| Message ID | 20200919160335.40909-4-xypron.glpk@gmx.de |
|---|---|
| State | Superseded, archived |
| Headers | show |
| Series | doc: global data pointer | expand |
On Sat, 19 Sep 2020 at 10:10, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote: > > 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 > Reviewed-by: Simon Glass <sjg@chromium.org>
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 >
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 | ++------------+----------+ + +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
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 -- 2.28.0