jcs.org
"Das U-Boot" Source Tree
1.. SPDX-License-Identifier: GPL-2.0+
2
3Global data
4===========
5
6Globally required fields are held in the global data structure. A pointer to the
7structure is available as symbol gd. The symbol is made available by the macro
8%DECLARE_GLOBAL_DATA_PTR.
9
10Register pointing to global data
11--------------------------------
12
13On most architectures the global data pointer is stored in a register.
14
15+------------+----------+
16| ARC | r25 |
17+------------+----------+
18| ARM 32bit | r9 |
19+------------+----------+
20| ARM 64bit | x18 |
21+------------+----------+
22| M68000 | d7 |
23+------------+----------+
24| MicroBlaze | r31 |
25+------------+----------+
26| Nios II | gp |
27+------------+----------+
28| PowerPC | r2 |
29+------------+----------+
30| RISC-V | gp (x3) |
31+------------+----------+
32| SuperH | r13 |
33+------------+----------+
34| x86 32bit | fs |
35+------------+----------+
36
37The sandbox, x86_64, and Xtensa are notable exceptions.
38
39Current implementation uses a register for the GD pointer because this results
40in smaller code. However, using plain global data for the GD pointer would be
41possible too (and simpler, as it does not require the reservation of a specific
42register for it), but the resulting code is bigger.
43
44Clang for ARM does not support assigning a global register. When using Clang
45gd is defined as an inline function using assembly code. This adds a few bytes
46to the code size.
47
48Binaries called by U-Boot are not aware of the register usage and will not
49conserve gd. UEFI binaries call the API provided by U-Boot and may return to
50U-Boot. The value of gd has to be saved every time U-Boot is left and restored
51whenever U-Boot is reentered. This is also relevant for the implementation of
52function tracing. For setting the value of gd function set_gd() can be used.
53
54Guidelines
55----------
56
57The global_data structure is placed in some memory which is available very early
58after boot to allow for a minimum set of global variables during system
59initialisation (until the memory controller is set up and RAM can be used). It
60is the primary data structure passed from pre-relocation U-Boot to
61post-relocation, i.e. ``from board_init_f()`` ``to board_init_r()``.
62
63The global_data struct exists for the lifetime of U-Boot. Since the struct is
64used by all architectures, fields added should be useful for most architectures.
65Fields which are only needed on one or two architectures can be placed in the
66architecture-specific ``struct arch_global_data``.
67
68In any case the struct should be kept small, since it uses precious SRAM on
69many boards.
70
71SPL also uses global data, as well as U-Boot proper, so take care to avoid
72adding fields to SPL which are not actually used by SPL. You can create
73access functions or macros in the header file to avoid filling the C code with
74#ifdefs.
75
76A flags word is available, which provides a convenient means to track the state
77of various initialisation phases within U-Boot.
78
79Global data structure
80---------------------
81
82.. kernel-doc:: include/asm-generic/global_data.h
83 :internal: