Merge pull request #276 from jcmvbkbc/xtensa-doc

Xtensa docs update

config/arch/xtensa.in

@@ -13,7 +13,7 @@
 ## help    a configuration specific 'overlay' file.
 ## help
 ## help    For a custom configuration, select the XTENSA_CUSTOM option and
-## help    provide the name of the overlay file through the
+## help    provide the name of the processor configuration through the
 ## help    CT_ARCH_XTENSA_CUSTOM_NAME option.
 ## help
 ## help    The default option (ARCH_xtensa_fsf) uses a built-in configuration,

config/arch/xtensa.in.2

@@ -10,15 +10,17 @@ config ARCH_xtensa_fsf
 endchoice
 
 config ARCH_XTENSA_CUSTOM_NAME
-	string "Custom Xtensa process configuration file name"
+	string "Custom Xtensa processor configuration name"
 	depends on XTENSA_CUSTOM
 	default ""
 	help
-	  Enter the name of the custom processor configuration
-	  overlay file or leave blank to use the default 'xtensa-overlay.tar'.
+	  Enter the name of the custom processor configuration.
+	  Overlay file for that configuration must be called
+	  'xtensa_<CUSTOM_NAME>.tar'.
+	  Leave blank to use the default 'xtensa-overlay.tar'.
 	  For more information about this option, please also consult
-	  the 'help' section of the 'Target Architecture Variant'
-	  option above.
+	  section 'Using crosstool-NG to build Xtensa toolchains' in the
+	  docs/C - Misc. tutorials.txt
 
 config ARCH_XTENSA_CUSTOM_OVERLAY_LOCATION
 	string "Full path to custom Xtensa processor configurations"

docs/C - Misc. tutorials.txt

@@ -359,3 +359,45 @@ MinGW-w64 as host.
 4. collect2.exe will attempt to run ld which is a shell script that runs either
    ld.exe or gold.exe so you need to make sure that a working shell is in your path.
    Eventually I will replace this with a native program for MinGW-w64 host.
+
+Using crosstool-NG to build Xtensa toolchains |
+----------------------------------------------+
+
+Contributed by: Max Filippov
+
+Xtensa cores are highly configurable: endianness, instruction set, register set
+of a core is chosen at processor configuration time. New registers and
+instructions may be added by designers, making each core configuration unique.
+Toolchain components cannot know about features of each individual core and
+need to be configured in order to be compatible with particular architecture
+variant. This configuration includes:
+- definitions of instruction formats, names and properties for assembler,
+  disassembler and debugger;
+- definitions of register names and properties for assembler, disassembler and
+  debugger;
+- selection of predefined features, such as endianness, presence of certain
+  processor options or instructions for compiler, debugger C library and OS
+  kernels;
+- macros with instruction sequences for saving and restoring special, user or
+  coprocessor registers for OS kernels.
+
+This configuration is provided in form of source files, that must replace
+corresponding files in binutils, gcc, gdb or newlib source trees or be added
+to OS kernel source tree. This set of files is usually distributed as archive
+known as Xtensa configuration overlay.
+
+Tensilica provides such an overlay as part of the processor download, however,
+it needs to be reformatted to match the specific format required by the
+crosstool-NG. For a script to convert the overlay file, and additional
+information, please see
+  http://wiki.linux-xtensa.org/index.php/Toolchain_Overlay_File
+
+The current version of crosstool-NG requires that the overlay file name has the
+format xtensa_<CORE_NAME>.tar, where CORE_NAME can be any user selected name.
+To make crosstool-NG use overlay file located at <PATH>/xtensa_<CORE_NAME>.tar
+select XTENSA_CUSTOM, set config parameter CT_ARCH_XTENSA_CUSTOM_NAME to
+CORE_NAME and CT_ARCH_XTENSA_CUSTOM_OVERLAY_LOCATION to PATH.
+
+The fsf target architecture variant is the configuration provided by toolchain
+components by default. It is present only for build-testing toolchain
+components and is in no way special or universal.