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

struct global_data: global data structure

Definition

struct global_data {
  struct bd_info *bd;
  struct global_data *new_gd;
  const void *fdt_blob;
  struct udevice *cur_serial_dev;
#ifndef CONFIG_XPL_BUILD;
  struct jt_funcs *jt;
  struct board_f *boardf;
#endif;
  phys_size_t ram_size;
  phys_addr_t ram_top;
  unsigned long flags;
  unsigned long cpu_clk;
#if CONFIG_IS_ENABLED(ENV_SUPPORT);
  unsigned long env_addr;
#endif ;
  unsigned long ram_base;
  unsigned long relocaddr;
  unsigned long irq_sp;
  unsigned long start_addr_sp;
  unsigned long reloc_off;
  unsigned int bus_clk;
  unsigned int mem_clk;
  unsigned int mon_len;
  unsigned int baudrate;
#if CONFIG_IS_ENABLED(ENV_SUPPORT);
  unsigned short env_has_init;
  unsigned char env_valid;
  char env_load_prio;
  char env_buf[32];
#endif ;
  enum fdt_source_t fdt_src;
  struct arch_global_data arch;
  struct list_head dmtag_list;
  unsigned int timebase_h;
  unsigned int timebase_l;
#if defined(CONFIG_POST);
  unsigned long post_log_word;
  unsigned long post_log_res;
  unsigned long post_init_f_time;
#endif;
#ifdef CONFIG_BOARD_TYPES;
  unsigned long board_type;
#endif;
#if CONFIG_IS_ENABLED(PRE_CONSOLE_BUFFER);
  long precon_buf_idx;
#endif;
#ifdef CONFIG_DM;
  struct udevice *dm_root;
  struct list_head uclass_root_s;
  struct list_head *uclass_root;
# if CONFIG_IS_ENABLED(OF_PLATDATA_DRIVER_RT);
  struct driver_rt *dm_driver_rt;
# endif;
#if CONFIG_IS_ENABLED(OF_PLATDATA_RT);
  struct udevice_rt *dm_udevice_rt;
  void *dm_priv_base;
# endif;
#endif;
#ifdef CONFIG_TIMER;
  struct udevice *timer;
#endif;
#if CONFIG_IS_ENABLED(OF_LIVE);
  struct device_node *of_root;
#endif;
#if CONFIG_IS_ENABLED(MULTI_DTB_FIT);
  const void *multi_dtb_fit;
#endif;
#ifdef CONFIG_TRACE;
  void *trace_buff;
#endif;
#if CONFIG_IS_ENABLED(SYS_I2C_LEGACY);
  int cur_i2c_bus;
#endif;
#if CONFIG_IS_ENABLED(CMD_BDINFO_EXTRA);
  unsigned long malloc_start;
#endif;
#if CONFIG_IS_ENABLED(SYS_MALLOC_F);
  unsigned long malloc_base;
  unsigned int malloc_limit;
  unsigned int malloc_ptr;
#endif;
#ifdef CONFIG_CONSOLE_RECORD;
  struct membuf console_out;
  struct membuf console_in;
#endif;
#if CONFIG_IS_ENABLED(VIDEO);
  ulong video_top;
  ulong video_bottom;
#endif;
#ifdef CONFIG_BOOTSTAGE;
  struct bootstage_data *bootstage;
#endif;
#ifdef CONFIG_LOG;
  struct list_head log_head;
  int log_drop_count;
  char default_log_level;
  char log_fmt;
  unsigned char logc_prev;
  unsigned char logl_prev;
  bool log_cont;
  bool processing_msg;
#endif;
#if CONFIG_IS_ENABLED(BLOBLIST);
  struct bloblist_hdr *bloblist;
#endif;
#if CONFIG_IS_ENABLED(HANDOFF);
  struct spl_handoff *spl_handoff;
#endif;
#if defined(CONFIG_TRANSLATION_OFFSET);
  fdt_addr_t translation_offset;
#endif;
#ifdef CONFIG_ACPI;
  struct acpi_ctx *acpi_ctx;
  ulong acpi_start;
#endif;
#if CONFIG_IS_ENABLED(GENERATE_SMBIOS_TABLE);
  char *smbios_version;
#endif;
#if CONFIG_IS_ENABLED(EVENT);
  struct event_state event_state;
#endif;
#if CONFIG_IS_ENABLED(CYCLIC);
  struct hlist_head cyclic_list;
#endif;
#if CONFIG_IS_ENABLED(UPL);
  struct upl *upl;
#endif;
};

Members

bd

board information

new_gd

pointer to relocated global data

fdt_blob

U-Boot’s own device tree, NULL if none

cur_serial_dev

current serial device

jt

jump table

The jump table contains pointers to exported functions. A pointer to the jump table is passed to standalone applications.

boardf

information only used before relocation

ram_size

RAM size in bytes

ram_top

top address of RAM used by U-Boot

flags

global data flags

See enum gd_flags

cpu_clk

CPU clock rate in Hz

env_addr

address of environment structure

env_addr contains the address of the structure holding the environment variables.

ram_base

base address of RAM used by U-Boot

relocaddr

start address of U-Boot in RAM

After relocation this field indicates the address to which U-Boot has been relocated. It can be displayed using the bdinfo command. Its value is needed to display the source code when debugging with GDB using the ‘add-symbol-file u-boot <relocaddr>’ command.

irq_sp

IRQ stack pointer

start_addr_sp

initial stack pointer address

reloc_off

relocation offset

bus_clk

platform clock rate in Hz

mem_clk

memory clock rate in Hz

mon_len

monitor length in bytes

baudrate

baud rate of the serial interface

env_has_init

bit mask indicating environment locations

enum env_location defines which bit relates to which location

env_valid

environment is valid

See enum env_valid

env_load_prio

priority of the loaded environment

env_buf

buffer for env_get() before reloc

fdt_src

Source of FDT

arch

architecture-specific data

dmtag_list

List of DM tags

timebase_h

high 32 bits of timer

timebase_l

low 32 bits of timer

post_log_word

active POST tests

post_log_word is a bit mask defining which POST tests are recorded (see constants POST_*).

post_log_res

POST results

post_log_res is a bit mask with the POST results. A bit with value 1 indicates successful execution.

post_init_f_time

time in ms when post_init_f() started

board_type

board type

If a U-Boot configuration supports multiple board types, the actual board type may be stored in this field.

precon_buf_idx

pre-console buffer index

precon_buf_idx indicates the current position of the buffer used to collect output before the console becomes available. When negative, the pre-console buffer is temporarily disabled (used when the pre-console buffer is being written out, to prevent adding its contents to itself).

dm_root

root instance for Driver Model

uclass_root_s

head of core tree when uclasses are not in read-only memory.

When uclasses are in read-only memory, uclass_root_s is not used and uclass_root points to the root node generated by dtoc.

uclass_root

pointer to head of core tree, if uclasses are in read-only memory and cannot be adjusted to use uclass_root as a list head.

When not in read-only memory, uclass_root_s is used to hold the uclass root, and uclass_root points to the address of uclass_root_s.

dm_driver_rt

Dynamic info about the driver

dm_udevice_rt

Dynamic info about the udevice

dm_priv_base

Base address of the priv/plat region used when udevices and uclasses are in read-only memory. This is NULL if not used

timer

timer instance for Driver Model

of_root

root node of the live tree

multi_dtb_fit

pointer to uncompressed multi-dtb FIT image

trace_buff

trace buffer

When tracing function in U-Boot this field points to the buffer recording the function calls.

cur_i2c_bus

currently used I2C bus

malloc_start

start of malloc() region

malloc_base

base address of early malloc()

malloc_limit

maximum size of early malloc()

malloc_ptr

currently used bytes of early malloc()

console_out

output buffer for console recording

This buffer is used to collect output during console recording.

console_in

input buffer for console recording

If console recording is activated, this buffer can be used to emulate input.

video_top