[PATCH 3/3] doc: global data pointer

[Daniel Schwierzeck]

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 at 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
> 
-- 
- Daniel