doc: global data pointer
Add the description of the global data pointer to the generated HTML
documentation.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
diff --git a/doc/develop/global_data.rst b/doc/develop/global_data.rst
new file mode 100644
index 0000000..9e7c8a2
--- /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 |
++------------+----------+
+
+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 98a95ad..89e80ea 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -9,4 +9,5 @@
coccinelle
crash_dumps
+ global_data
logging