Am Samstag, den 19.09.2020, 18:03 +0200 schrieb Heinrich Schuchardt:
Add the description of the global data pointer to the generated HTML documentation.
Signed-off-by: Heinrich Schuchardt xypron.glpk@gmx.de
doc/develop/global_data.rst | 53 +++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 54 insertions(+) create mode 100644 doc/develop/global_data.rst
diff --git a/doc/develop/global_data.rst b/doc/develop/global_data.rst new file mode 100644 index 0000000000..9e7c8a24da --- /dev/null +++ b/doc/develop/global_data.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GPL-2.0+
+Global data +===========
+Globally required fields are held in the global data structure. A pointer to the +structure is available as symbol gd. The symbol is made available by the macro +%DECLARE_GLOBAL_DATA_PTR.
+Register pointing to global data +--------------------------------
+On most architectures the global data pointer is stored in a register.
++------------+----------+ +| ARC | r25 | ++------------+----------+ +| ARM 32bit | r9 | ++------------+----------+ +| ARM 64bit | x18 | ++------------+----------+ +| M68000 | d7 | ++------------+----------+ +| MicroBlaze | r31 | ++------------+----------+ +| NDS32 | r10 | ++------------+----------+ +| Nios II | gp | ++------------+----------+ +| PowerPC | r2 | ++------------+----------+ +| RISC-V | gp (x3) | ++------------+----------+ +| SuperH | r13 | ++------------+----------+
if you want to add MIPS to the list, the register is: $26 (k0)
+The sandbox, x86, and Xtensa are notable exceptions.
+Clang for ARM does not support assigning a global register. When using Clang +gd is defined as an inline function using assembly code. This adds a few bytes +to the code size.
+Binaries called by U-Boot are not aware of the register usage and will not +conserve gd. UEFI binaries call the API provided by U-Boot and may return to +U-Boot. The value of gd has to be saved every time U-Boot is left and restored +whenever U-Boot is reentered. This is also relevant for the implementation of +function tracing. For setting the value of gd function set_gd() can be used.
+Global data structure +---------------------
+.. kernel-doc:: include/asm-generic/global_data.h
- :internal:
diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 98a95ad434..89e80eab94 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -9,4 +9,5 @@ Develop U-Boot
coccinelle crash_dumps
- global_data logging
-- 2.28.0