1.. SPDX-License-Identifier: GPL-2.0+
2
3Xtensa
4======
5
6Xtensa Architecture and Diamond Cores
7-------------------------------------
8
9Xtensa is a configurable processor architecture from Tensilica, Inc.
10Diamond Cores are pre-configured instances available for license and
11SoC cores in the same manner as ARM, MIPS, etc.
12
13Xtensa licensees create their own Xtensa cores with selected features
14and custom instructions, registers and co-processors. The custom core
15is configured with Tensilica tools and built with Tensilica's Xtensa
16Processor Generator.
17
18There are an effectively infinite number of CPUs in the Xtensa
19architecture family. It is, however, not feasible to support individual
20Xtensa CPUs in U-Boot. Therefore, there is only a single 'xtensa' CPU
21in the cpu tree of U-Boot.
22
23In the same manner as the Linux port to Xtensa, U-Boot adapts to an
24individual Xtensa core configuration using a set of macros provided with
25the particular core. This is part of what is known as the hardware
26abstraction layer (HAL). For the purpose of U-Boot, the HAL consists only
27of a few header files. These provide CPP macros that customize sources,
28Makefiles, and the linker script.
29
30
31Adding support for an additional processor configuration
32--------------------------------------------------------
33
34The header files for one particular processor configuration are inside
35a variant-specific directory located in the arch/xtensa/include/asm
36directory. The name of that directory starts with 'arch-' followed by
37the name for the processor configuration, for example, arch-dc233c for
38the Diamond DC233 processor.
39
40core.h:
41  Definitions for the core itself.
42
43The following files are part of the overlay but not used by U-Boot.
44
45tie.h:
46  Co-processors and custom extensions defined in the Tensilica Instruction
47  Extension (TIE) language.
48tie-asm.h:
49  Assembly macros to access custom-defined registers and states.
50
51
52Global Data Pointer, Exported Function Stubs, and the ABI
53---------------------------------------------------------
54
55To support standalone applications launched with the "go" command,
56U-Boot provides a jump table of entrypoints to exported functions
57(grep for EXPORT_FUNC). The implementation for Xtensa depends on
58which ABI (or function calling convention) is used.
59
60Windowed ABI presents unique difficulties with the approach based on
61keeping global data pointer in dedicated register. Because the register
62window rotates during a call, there is no register that is constantly
63available for the gd pointer. Therefore, on xtensa gd is a simple
64global variable. Another difficulty arises from the requirement to have
65an 'entry' at the beginning of a function, which rotates the register
66file and reserves a stack frame. This is an integral part of the
67windowed ABI implemented in hardware. It makes using a jump table to an
68arbitrary (separately compiled) function a bit tricky. Use of a simple
69wrapper is also very tedious due to the need to move all possible
70register arguments and adjust the stack to handle arguments that cannot
71be passed in registers. The most efficient approach is to have the jump
72table perform the 'entry' so as to pretend it's the start of the real
73function. This requires decoding the target function's 'entry'
74instruction to determine the stack frame size, and adjusting the stack
75pointer accordingly, then jumping into the target function just after
76the 'entry'. Decoding depends on the processor's endianness so uses the
77HAL. The implementation (12 instructions) is in examples/stubs.c.
78
79
80Access to Invalid Memory Addresses
81----------------------------------
82
83U-Boot does not check if memory addresses given as arguments to commands
84such as "md" are valid. There are two possible types of invalid
85addresses: an area of physical address space may not be mapped to RAM
86or peripherals, or in the presence of MMU an area of virtual address
87space may not be mapped to physical addresses.
88
89Accessing first type of invalid addresses may result in hardware lockup,
90reading of meaningless data, written data being ignored or an exception,
91depending on the CPU wiring to the system. Accessing second type of
92invalid addresses always ends with an exception.
93
94U-Boot for Xtensa provides a special memory exception handler that
95reports such access attempts and resets the board.
96
97
98.. Chris Zankel
99.. Ross Morley
100