Re: [PATCH 3/3] doc: global data pointer
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 > --- > 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 00..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
Re: [PATCH 3/3] doc: global data pointer
On Sat, 19 Sep 2020 at 10:10, Heinrich Schuchardt wrote: > > Add the description of the global data pointer to the generated HTML > documentation. > > Signed-off-by: Heinrich Schuchardt > --- > 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
[PATCH 3/3] doc: global data pointer
Add the description of the global data pointer to the generated HTML documentation. Signed-off-by: Heinrich Schuchardt --- 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 00..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 -- 2.28.0
