From: Bin Meng Date: Thu, 18 Jul 2019 07:34:34 +0000 (-0700) Subject: doc: arch: Convert README.xtensa to reST X-Git-Tag: v2019.10-rc1~16^2~1 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=e1c1364f3c22bd97bec315bc53161017f701a15a;p=oweals%2Fu-boot.git doc: arch: Convert README.xtensa to reST Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Bin Meng --- diff --git a/doc/README.xtensa b/doc/README.xtensa deleted file mode 100644 index 406858226f..0000000000 --- a/doc/README.xtensa +++ /dev/null @@ -1,97 +0,0 @@ -U-Boot for the Xtensa Architecture -================================== - -Xtensa Architecture and Diamond Cores -------------------------------------- - -Xtensa is a configurable processor architecture from Tensilica, Inc. -Diamond Cores are pre-configured instances available for license and -SoC cores in the same manner as ARM, MIPS, etc. - -Xtensa licensees create their own Xtensa cores with selected features -and custom instructions, registers and co-processors. The custom core -is configured with Tensilica tools and built with Tensilica's Xtensa -Processor Generator. - -There are an effectively infinite number of CPUs in the Xtensa -architecture family. It is, however, not feasible to support individual -Xtensa CPUs in U-Boot. Therefore, there is only a single 'xtensa' CPU -in the cpu tree of U-Boot. - -In the same manner as the Linux port to Xtensa, U-Boot adapts to an -individual Xtensa core configuration using a set of macros provided with -the particular core. This is part of what is known as the hardware -abstraction layer (HAL). For the purpose of U-Boot, the HAL consists only -of a few header files. These provide CPP macros that customize sources, -Makefiles, and the linker script. - - -Adding support for an additional processor configuration --------------------------------------------------------- - -The header files for one particular processor configuration are inside -a variant-specific directory located in the arch/xtensa/include/asm -directory. The name of that directory starts with 'arch-' followed by -the name for the processor configuration, for example, arch-dc233c for -the Diamond DC233 processor. - - core.h Definitions for the core itself. - -The following files are part of the overlay but not used by U-Boot. - - tie.h Co-processors and custom extensions defined - in the Tensilica Instruction Extension (TIE) - language. - tie-asm.h Assembly macros to access custom-defined registers - and states. - - -Global Data Pointer, Exported Function Stubs, and the ABI ---------------------------------------------------------- - -To support standalone applications launched with the "go" command, -U-Boot provides a jump table of entrypoints to exported functions -(grep for EXPORT_FUNC). The implementation for Xtensa depends on -which ABI (or function calling convention) is used. - -Windowed ABI presents unique difficulties with the approach based on -keeping global data pointer in dedicated register. Because the register -window rotates during a call, there is no register that is constantly -available for the gd pointer. Therefore, on xtensa gd is a simple -global variable. Another difficulty arises from the requirement to have -an 'entry' at the beginning of a function, which rotates the register -file and reserves a stack frame. This is an integral part of the -windowed ABI implemented in hardware. It makes using a jump table to an -arbitrary (separately compiled) function a bit tricky. Use of a simple -wrapper is also very tedious due to the need to move all possible -register arguments and adjust the stack to handle arguments that cannot -be passed in registers. The most efficient approach is to have the jump -table perform the 'entry' so as to pretend it's the start of the real -function. This requires decoding the target function's 'entry' -instruction to determine the stack frame size, and adjusting the stack -pointer accordingly, then jumping into the target function just after -the 'entry'. Decoding depends on the processor's endianness so uses the -HAL. The implementation (12 instructions) is in examples/stubs.c. - - -Access to Invalid Memory Addresses ----------------------------------- - -U-Boot does not check if memory addresses given as arguments to commands -such as "md" are valid. There are two possible types of invalid -addresses: an area of physical address space may not be mapped to RAM -or peripherals, or in the presence of MMU an area of virtual address -space may not be mapped to physical addresses. - -Accessing first type of invalid addresses may result in hardware lockup, -reading of meaningless data, written data being ignored or an exception, -depending on the CPU wiring to the system. Accessing second type of -invalid addresses always ends with an exception. - -U-Boot for Xtensa provides a special memory exception handler that -reports such access attempts and resets the board. - - ------------------------------------------------------------------------------- -Chris Zankel -Ross Morley diff --git a/doc/arch/index.rst b/doc/arch/index.rst index 2980b77dec..369d8eeb6d 100644 --- a/doc/arch/index.rst +++ b/doc/arch/index.rst @@ -15,3 +15,4 @@ Architecture-specific doc sandbox sh x86 + xtensa diff --git a/doc/arch/xtensa.rst b/doc/arch/xtensa.rst new file mode 100644 index 0000000000..176410d96b --- /dev/null +++ b/doc/arch/xtensa.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Xtensa +====== + +Xtensa Architecture and Diamond Cores +------------------------------------- + +Xtensa is a configurable processor architecture from Tensilica, Inc. +Diamond Cores are pre-configured instances available for license and +SoC cores in the same manner as ARM, MIPS, etc. + +Xtensa licensees create their own Xtensa cores with selected features +and custom instructions, registers and co-processors. The custom core +is configured with Tensilica tools and built with Tensilica's Xtensa +Processor Generator. + +There are an effectively infinite number of CPUs in the Xtensa +architecture family. It is, however, not feasible to support individual +Xtensa CPUs in U-Boot. Therefore, there is only a single 'xtensa' CPU +in the cpu tree of U-Boot. + +In the same manner as the Linux port to Xtensa, U-Boot adapts to an +individual Xtensa core configuration using a set of macros provided with +the particular core. This is part of what is known as the hardware +abstraction layer (HAL). For the purpose of U-Boot, the HAL consists only +of a few header files. These provide CPP macros that customize sources, +Makefiles, and the linker script. + + +Adding support for an additional processor configuration +-------------------------------------------------------- + +The header files for one particular processor configuration are inside +a variant-specific directory located in the arch/xtensa/include/asm +directory. The name of that directory starts with 'arch-' followed by +the name for the processor configuration, for example, arch-dc233c for +the Diamond DC233 processor. + +core.h: + Definitions for the core itself. + +The following files are part of the overlay but not used by U-Boot. + +tie.h: + Co-processors and custom extensions defined in the Tensilica Instruction + Extension (TIE) language. +tie-asm.h: + Assembly macros to access custom-defined registers and states. + + +Global Data Pointer, Exported Function Stubs, and the ABI +--------------------------------------------------------- + +To support standalone applications launched with the "go" command, +U-Boot provides a jump table of entrypoints to exported functions +(grep for EXPORT_FUNC). The implementation for Xtensa depends on +which ABI (or function calling convention) is used. + +Windowed ABI presents unique difficulties with the approach based on +keeping global data pointer in dedicated register. Because the register +window rotates during a call, there is no register that is constantly +available for the gd pointer. Therefore, on xtensa gd is a simple +global variable. Another difficulty arises from the requirement to have +an 'entry' at the beginning of a function, which rotates the register +file and reserves a stack frame. This is an integral part of the +windowed ABI implemented in hardware. It makes using a jump table to an +arbitrary (separately compiled) function a bit tricky. Use of a simple +wrapper is also very tedious due to the need to move all possible +register arguments and adjust the stack to handle arguments that cannot +be passed in registers. The most efficient approach is to have the jump +table perform the 'entry' so as to pretend it's the start of the real +function. This requires decoding the target function's 'entry' +instruction to determine the stack frame size, and adjusting the stack +pointer accordingly, then jumping into the target function just after +the 'entry'. Decoding depends on the processor's endianness so uses the +HAL. The implementation (12 instructions) is in examples/stubs.c. + + +Access to Invalid Memory Addresses +---------------------------------- + +U-Boot does not check if memory addresses given as arguments to commands +such as "md" are valid. There are two possible types of invalid +addresses: an area of physical address space may not be mapped to RAM +or peripherals, or in the presence of MMU an area of virtual address +space may not be mapped to physical addresses. + +Accessing first type of invalid addresses may result in hardware lockup, +reading of meaningless data, written data being ignored or an exception, +depending on the CPU wiring to the system. Accessing second type of +invalid addresses always ends with an exception. + +U-Boot for Xtensa provides a special memory exception handler that +reports such access attempts and resets the board. + + +.. Chris Zankel +.. Ross Morley