mirror of
https://github.com/u-boot/u-boot.git
synced 2025-04-22 04:44:46 +00:00
cafaa1a17f
Update the documentation to provide a bit more information about how to use global data. Signed-off-by: Simon Glass <sjg@chromium.org>
83 lines
3 KiB
ReStructuredText
83 lines
3 KiB
ReStructuredText
.. 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 |
|
|
+------------+----------+
|
|
| Nios II | gp |
|
|
+------------+----------+
|
|
| PowerPC | r2 |
|
|
+------------+----------+
|
|
| RISC-V | gp (x3) |
|
|
+------------+----------+
|
|
| SuperH | r13 |
|
|
+------------+----------+
|
|
| x86 32bit | fs |
|
|
+------------+----------+
|
|
|
|
The sandbox, x86_64, and Xtensa are notable exceptions.
|
|
|
|
Current implementation uses a register for the GD pointer because this results
|
|
in smaller code. However, using plain global data for the GD pointer would be
|
|
possible too (and simpler, as it does not require the reservation of a specific
|
|
register for it), but the resulting code is bigger.
|
|
|
|
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.
|
|
|
|
Guidelines
|
|
----------
|
|
|
|
The global_data structure is placed in some memory which is available very early
|
|
after boot to allow for a minimum set of global variables during system
|
|
initialisation (until the memory controller is set up and RAM can be used). It
|
|
is the primary data structure passed from pre-relocation U-Boot to
|
|
post-relocation, i.e. ``from board_init_f()`` ``to board_init_r()``.
|
|
|
|
The global_data struct exists for the lifetime of U-Boot. Since the struct is
|
|
used by all architectures, fields added should be useful for most architectures.
|
|
Fields which are only needed on one or two architectures can be placed in the
|
|
architecture-specific ``struct arch_global_data``.
|
|
|
|
In any case the struct should be kept small, since it uses precious SRAM on
|
|
many boards.
|
|
|
|
SPL also uses global data, as well as U-Boot proper, so take care to avoid
|
|
adding fields to SPL which are not actually used by SPL. You can create
|
|
access functions or macros in the header file to avoid filling the C code with
|
|
#ifdefs.
|
|
|
|
A flags word is available, which provides a convenient means to track the state
|
|
of various initialisation phases within U-Boot.
|
|
|
|
Global data structure
|
|
---------------------
|
|
|
|
.. kernel-doc:: include/asm-generic/global_data.h
|
|
:internal:
|