doc: global data pointer
v3 cover doc: global data pointer
Add the description of the global data pointer to the generated HTML documentation.
The first patch converts the GD_FLG_* constants to an enum. The second adds move Sphinx comments.
The third finally provides the HTML documentation.
v3:
do not duplicate comments
v2:
_flags must not be exposed to assembler code. This avoids a build failure on x86.
Heinrich Schuchardt (3):
global_data.h: convert GD_FLG_* to enum
global_data.h: add Sphinx documentation
doc: global data pointer
doc/develop/global_data.rst | 53 ++++ doc/develop/index.rst | 1 + include/asm-generic/global_data.h | 478 +++++++++++++++++++++++++----- 3 files changed, 455 insertions(+), 77 deletions(-) create mode 100644 doc/develop/global_data.rst
--
2.28.0
PATCH v3 1/3 global_data.h: convert GD_FLG_* to enum
Sphinx documentation is only available for enums not for #defines. Anyway it is better to keep related definitions in an enum.
---
v3:
no change
v2:
enum gd_flags must not be exposed to assembler code
--- include/asm-generic/global_data.h | 106 +++++++++++++++++++++++------- 1 file changed, 84 insertions(+), 22 deletions(-)
include/asm-generic/global_data.h +84 -22
@@ -138,7 +138,6 @@ typedef struct global_data {struct udevice *watchdog_dev;#endif } gd_t; -#endif #ifdef CONFIG_BOARD_TYPES #define gd_board_type () gd->board_type
@@ -146,27 +145,90 @@ typedef struct global_data {#define gd_board_type () 0#endif -/* -* Global Data Flags +/** +* enum gd_flags - global data flags +* +* See field flags of &struct global_data. */ -#define GD_FLG_RELOC 0x00001/* Code was relocated to RAM */ -#define GD_FLG_DEVINIT 0x00002/* Devices have been initialized */ -#define GD_FLG_SILENT 0x00004/* Silent mode */ -#define GD_FLG_POSTFAIL 0x00008/* Critical POST test failed */ -#define GD_FLG_POSTSTOP 0x00010/* POST seqeunce aborted */ -#define GD_FLG_LOGINIT 0x00020/* Log Buffer has been initialized */ -#define GD_FLG_DISABLE_CONSOLE 0x00040/* Disable console (in & out) */ -#define GD_FLG_ENV_READY 0x00080/* Env. imported into hash table */ -#define GD_FLG_SERIAL_READY 0x00100/* Pre-reloc serial console ready */ -#define GD_FLG_FULL_MALLOC_INIT 0x00200/* Full malloc() is ready */ -#define GD_FLG_SPL_INIT 0x00400/* spl_init() has been called */ -#define GD_FLG_SKIP_RELOC 0x00800/* Don't relocate */ -#define GD_FLG_RECORD 0x01000/* Record console */ -#define GD_FLG_ENV_DEFAULT 0x02000/* Default variable flag */ -#define GD_FLG_SPL_EARLY_INIT 0x04000/* Early SPL init is done */ -#define GD_FLG_LOG_READY 0x08000/* Log system is ready for use */ -#define GD_FLG_WDT_READY 0x10000/* Watchdog is ready for use */ -#define GD_FLG_SKIP_LL_INIT 0x20000/* Don't perform low-level init */ -#define GD_FLG_SMP_READY 0x40000/* SMP init is complete */ +enum gd_flags { +/** +* @GD_FLG_RELOC: code was relocated to RAM +*/ +GD_FLG_RELOC =0x00001 , +/** +* @GD_FLG_DEVINIT: devices have been initialized +*/ +GD_FLG_DEVINIT =0x00002 , +/** +* @GD_FLG_SILENT: silent mode +*/ +GD_FLG_SILENT =0x00004 , +/** +* @GD_FLG_POSTFAIL: critical POST test failed +*/ +GD_FLG_POSTFAIL =0x00008 , +/** +* @GD_FLG_POSTSTOP: POST sequence aborted +*/ +GD_FLG_POSTSTOP =0x00010 , +/** +* @GD_FLG_LOGINIT: log Buffer has been initialized +*/ +GD_FLG_LOGINIT =0x00020 , +/** +* @GD_FLG_DISABLE_CONSOLE: disable console (in & out) +*/ +GD_FLG_DISABLE_CONSOLE =0x00040 , +/** +* @GD_FLG_ENV_READY: environment imported into hash table +*/ +GD_FLG_ENV_READY =0x00080 , +/** +* @GD_FLG_SERIAL_READY: pre-relocation serial console ready +*/ +GD_FLG_SERIAL_READY =0x00100 , +/** +* @GD_FLG_FULL_MALLOC_INIT: full malloc() is ready +*/ +GD_FLG_FULL_MALLOC_INIT =0x00200 , +/** +* @GD_FLG_SPL_INIT: spl_init() has been called +*/ +GD_FLG_SPL_INIT =0x00400 , +/** +* @GD_FLG_SKIP_RELOC: don't relocate +*/ +GD_FLG_SKIP_RELOC =0x00800 , +/** +* @GD_FLG_RECORD: record console +*/ +GD_FLG_RECORD =0x01000 , +/** +* @GD_FLG_ENV_DEFAULT: default variable flag +*/ +GD_FLG_ENV_DEFAULT =0x02000 , +/** +* @GD_FLG_SPL_EARLY_INIT: early SPL initialization is done +*/ +GD_FLG_SPL_EARLY_INIT =0x04000 , +/** +* @GD_FLG_LOG_READY: log system is ready for use +*/ +GD_FLG_LOG_READY =0x08000 , +/** +* @GD_FLG_WDT_READY: watchdog is ready for use +*/ +GD_FLG_WDT_READY =0x10000 , +/** +* @GD_FLG_SKIP_LL_INIT: don't perform low-level initialization +*/ +GD_FLG_SKIP_LL_INIT =0x20000 , +/** +* @GD_FLG_SMP_READY: SMP initialization is complete +*/ +GD_FLG_SMP_READY =0x40000 , +}; + +#endif /* __ASSEMBLY__ */ #endif /* __ASM_GENERIC_GBL_DATA_H */
--
2.28.0
PATCH v3 1/3 global_data.h: convert GD_FLG_* to enum
Quoted 5 lines · Heinrich Schuchardt
Sphinx documentation is only available for enums not for #defines. Anyway it is better to keep related definitions in an enum.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>
Applied to u-boot/master, thanks!
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: <https://lists.denx.de/pipermail/u-boot/attachments/20201014/a23b3d89/attachment.sig>
PATCH v3 2/3 global_data.h: add Sphinx documentation
In reply to Heinrich SchuchardtAdd the missing Sphinx documentation for struct global_data and gd_board_type().
---
v3:
Avoid duplicate comments: comments replaced by Sphinx documentation should be removed.
v2:
no change
--- include/asm-generic/global_data.h | 372 +++++++++++++++++++++++++----- 1 file changed, 317 insertions(+), 55 deletions(-)
include/asm-generic/global_data.h +317 -55
@@ -24,121 +24,383 @@#include <membuff.h> #include <linux/list.h> -typedef struct global_data { +typedef struct global_data gd_t ; + +/** +* struct global_data - global data structure +*/ +struct global_data { +/** +* @bd: board information +*/ struct bd_info *bd; +/** +* @flags: global data flags +* +* See &enum gd_flags +*/ unsigned long flags; +/** +* @baudrate: baud rate of the serial interface +*/ unsigned int baudrate; -unsigned long cpu_clk;/* CPU clock in Hz! */ +/** +* @cpu_clk: CPU clock rate in Hz +*/ +unsigned long cpu_clk; +/** +* @bus_clk: platform clock rate in Hz +*/ unsigned long bus_clk; +/** +* @pci_clk: PCI clock rate in Hz +*/ /* We cannot bracket this with CONFIG_PCI due to mpc5xxx */ unsigned long pci_clk; +/** +* @mem_clk: memory clock rate in Hz +*/ unsigned long mem_clk;#if defined(CONFIG_LCD ) || defined(CONFIG_VIDEO ) || defined(CONFIG_DM_VIDEO ) -unsigned long fb_base;/* Base address of framebuffer mem */ +/** +* @fb_base: base address of frame buffer memory +*/ +unsigned long fb_base;#endif #if defined(CONFIG_POST ) -unsigned long post_log_word;/* Record POST activities */ -unsigned long post_log_res;/* success of POST test */ -unsigned long post_init_f_time;/* When post_init_f started */ +/** +* @post_log_word: active POST tests +* +* @post_log_word is a bit mask defining which POST tests are recorded +* (see constants POST_*). +*/ +unsigned long post_log_word; +/** +* @post_log_res: POST results +* +* @post_log_res is a bit mask with the POST results. A bit with value 1 +* indicates successful execution. +*/ +unsigned long post_log_res; +/** +* @post_init_f_time: time in ms when post_init_f() started +*/ +unsigned long post_init_f_time;#endif #ifdef CONFIG_BOARD_TYPES +/** +* @board_type: board type +* +* If a U-Boot configuration supports multiple board types, the actual +* board type may be stored in this field. +*/ unsigned long board_type;#endif -unsigned long have_console;/* serial_init() was called */ +/** +* @have_console: console is available +* +* A value of 1 indicates that serial_init() was called and a console +* is available. +* A value of 0 indicates that console input and output drivers shall +* not be called. +*/ +unsigned long have_console;#if CONFIG_IS_ENABLED (PRE_CONSOLE_BUFFER ) -unsigned long precon_buf_idx;/* Pre-Console buffer index */ +/** +* @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 +*/ +unsigned long precon_buf_idx;#endif -unsigned long env_addr;/* Address of Environment struct */ -unsigned long env_valid;/* Environment valid? enum env_valid */ -unsigned long env_has_init;/* Bitmask of boolean of struct env_location offsets */ -int env_load_prio;/* Priority of the loaded environment */ - -unsigned long ram_base;/* Base address of RAM used by U-Boot */ -unsigned long ram_top;/* Top address of RAM used by U-Boot */ -unsigned long relocaddr;/* Start address of U-Boot in RAM */ -phys_size_t ram_size;/* RAM size */ -unsigned long mon_len;/* monitor len */ -unsigned long irq_sp;/* irq stack pointer */ -unsigned long start_addr_sp;/* start_addr_stackpointer */ +/** +* @env_addr: address of environment structure +* +* @env_addr contains the address of the structure holding the +* environment variables. +*/ +unsigned long env_addr; +/** +* @env_valid: environment is valid +* +* See &enum env_valid +*/ +unsigned long env_valid; +/** +* @env_has_init: bit mask indicating environment locations +* +* &enum env_location defines which bit relates to which location +*/ +unsigned long env_has_init; +/** +* @env_load_prio: priority of the loaded environment +*/ +int env_load_prio; +/** +* @ram_base: base address of RAM used by U-Boot +*/ +unsigned long ram_base; +/** +* @ram_top: top address of RAM used by U-Boot +*/ +unsigned long ram_top; +/** +* @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. +*/ +unsigned long relocaddr; +/** +* @ram_size: RAM size in bytes +*/ +phys_size_t ram_size; +/** +* @mon_len: monitor length in bytes +*/ +unsigned long mon_len; +/** +* @irq_sp: IRQ stack pointer +*/ +unsigned long irq_sp; +/** +* @start_addr_sp: initial stack pointer address +*/ +unsigned long start_addr_sp; +/** +* @reloc_off: relocation offset +*/ unsigned long reloc_off; -struct global_data *new_gd;/* relocated global data */ +/** +* @new_gd: pointer to relocated global data +*/ +struct global_data *new_gd;#ifdef CONFIG_DM -struct udevice *dm_root;/* Root instance for Driver Model */ -struct udevice *dm_root_f;/* Pre-relocation root instance */ -struct list_head uclass_root;/* Head of core tree */ +/** +* @dm_root: root instance for Driver Model +*/ +struct udevice *dm_root; +/** +* @dm_root_f: pre-relocation root instance +*/ +struct udevice *dm_root_f; +/** +* @uclass_root: head of core tree +*/ +struct list_head uclass_root;#endif #ifdef CONFIG_TIMER -struct udevice *timer;/* Timer instance for Driver Model */ +/** +* @timer: timer instance for Driver Model +*/ +struct udevice *timer;#endif - -const void *fdt_blob;/* Our device tree, NULL if none */ -void *new_fdt;/* Relocated FDT */ -unsigned long fdt_size;/* Space reserved for relocated FDT */ +/** +* @fdt_blob: U-Boot's own device tree, NULL if none +*/ +const void *fdt_blob; +/** +* @new_fdt: relocated device tree +*/ +void *new_fdt; +/** +* @fdt_size: space reserved for relocated device space +*/ +unsigned long fdt_size;#ifdef CONFIG_OF_LIVE +/** +* @of_root: root node of the live tree +*/ struct device_node *of_root;#endif #if CONFIG_IS_ENABLED (MULTI_DTB_FIT ) -const void *multi_dtb_fit;/* uncompressed multi-dtb FIT image */ +/** +* @multi_dtb_fit: pointer to uncompressed multi-dtb FIT image +*/ +const void *multi_dtb_fit;#endif -struct jt_funcs *jt;/* jump table */ -char env_buf[32 ];/* buffer for env_get() before reloc. */ +/** +* @jt: jump table +* +* The jump table contains pointers to exported functions. A pointer to +* the jump table is passed to standalone applications. +*/ +struct jt_funcs *jt; +/** +* @env_buf: buffer for env_get() before reloc +*/ +char env_buf[32 ];#ifdef CONFIG_TRACE -void *trace_buff;/* The trace buffer */ +/** +* @trace_buff: trace buffer +* +* When tracing function in U-Boot this field points to the buffer +* recording the function calls. +*/ +void *trace_buff;#endif #if defined(CONFIG_SYS_I2C ) -int cur_i2c_bus;/* current used i2c bus */ +/** +* @cur_i2c_bus: currently used I2C bus +*/ +int cur_i2c_bus;#endif +/** +* @timebase_h: high 32 bits of timer +*/ unsigned int timebase_h; +/** +* @timebase_l: low 32 bits of timer +*/ unsigned int timebase_l;#if CONFIG_VAL (SYS_MALLOC_F_LEN ) -unsigned long malloc_base;/* base address of early malloc() */ -unsigned long malloc_limit;/* limit address */ -unsigned long malloc_ptr;/* current address */ +/** +* @malloc_base: base address of early malloc() +*/ +unsigned long malloc_base; +/** +* @malloc_limit: limit address of early malloc() +*/ +unsigned long malloc_limit; +/** +* @malloc_ptr: current address of early malloc() +*/ +unsigned long malloc_ptr;#endif #ifdef CONFIG_PCI -struct pci_controller *hose;/* PCI hose for early use */ -phys_addr_t pci_ram_top;/* top of region accessible to PCI */ +/** +* @hose: PCI hose for early use +*/ +struct pci_controller *hose; +/** +* @pci_ram_top: top of region accessible to PCI +*/ +phys_addr_t pci_ram_top;#endif #ifdef CONFIG_PCI_BOOTDELAY +/** +* @pcidelay_done: delay time before scanning of PIC hose expired +* +* If CONFIG_PCI_BOOTDELAY=y, pci_hose_scan() waits for the number of +* milliseconds defined by environment variable pcidelay before +* scanning. Once this delay has expired the flag @pcidelay_done +* is set to 1. +*/ int pcidelay_done;#endif -struct udevice *cur_serial_dev;/* current serial device */ -struct arch_global_data arch;/* architecture-specific data */ +/** +* @cur_serial_dev: current serial device +*/ +struct udevice *cur_serial_dev; +/** +* @arch: architecture-specific data +*/ +struct arch_global_data arch;#ifdef CONFIG_CONSOLE_RECORD -struct membuff console_out;/* console output */ -struct membuff console_in;/* console input */ +/** +* @console_out: output buffer for console recording +* +* This buffer is used to collect output during console recording. +*/ +struct membuff console_out; +/** +* @console_in: input buffer for console recording +* +* If console recording is activated, this buffer can be used to +* emulate input. +*/ +struct membuff console_in;#endif #ifdef CONFIG_DM_VIDEO -ulong video_top;/* Top of video frame buffer area */ -ulong video_bottom;/* Bottom of video frame buffer area */ +/** +* @video_top: top of video frame buffer area +*/ +ulong video_top; +/** +* @video_bottom: bottom of video frame buffer area +*/ +ulong video_bottom;#endif #ifdef CONFIG_BOOTSTAGE -struct bootstage_data *bootstage;/* Bootstage information */ -struct bootstage_data *new_bootstage;/* Relocated bootstage info */ +/** +* @bootstage: boot stage information +*/ +struct bootstage_data *bootstage; +/** +* @new_bootstage: relocated boot stage information +*/ +struct bootstage_data *new_bootstage;#endif #ifdef CONFIG_LOG -int log_drop_count;/* Number of dropped log messages */ -int default_log_level;/* For devices with no filters */ -struct list_head log_head;/* List of struct log_device */ -int log_fmt;/* Mask containing log format info */ +/** +* @log_drop_count: number of dropped log messages +* +* This counter is incremented for each log message which can not +* be processed because logging is not yet available as signaled by +* flag %GD_FLG_LOG_READY in @flags. +*/ +int log_drop_count; +/** +* @default_log_level: default logging level +* +* For logging devices without filters @default_log_level defines the +* logging level, cf. &enum log_level_t. +*/ +int default_log_level; +/** +* @log_head: list of logging devices +*/ +struct list_head log_head; +/** +* @log_fmt: bit mask for logging format +* +* The @log_fmt bit mask selects the fields to be shown in log messages. +* &enum log_fmt defines the bits of the bit mask. +*/ +int log_fmt;#endif #if CONFIG_IS_ENABLED (BLOBLIST ) -struct bloblist_hdr *bloblist;/* Bloblist information */ -struct bloblist_hdr *new_bloblist;/* Relocated blolist info */ +/** +* @bloblist: blob list information +*/ +struct bloblist_hdr *bloblist; +/** +* @new_bloblist: relocated blob list information +*/ +struct bloblist_hdr *new_bloblist;# ifdef CONFIG_SPL +/** +* @spl_handoff: SPL hand-off information +*/ struct spl_handoff *spl_handoff;# endif #endif #if defined(CONFIG_TRANSLATION_OFFSET ) -fdt_addr_t translation_offset;/* optional translation offset */ +/** +* @translation_offset: optional translation offset +* +* See CONFIG_TRANSLATION_OFFSET. +*/ +fdt_addr_t translation_offset;#endif #if CONFIG_IS_ENABLED (WDT ) +/** +* @watchdog_dev: watchdog device +*/ struct udevice *watchdog_dev;#endif -}gd_t ; +}; +/** +* gd_board_type() - retrieve board type +* +* Return: global board type +*/ #ifdef CONFIG_BOARD_TYPES #define gd_board_type () gd->board_type#else
--
2.28.0
PATCH v3 2/3 global_data.h: add Sphinx documentation
Quoted 11 lines · Heinrich Schuchardt
Add the missing Sphinx documentation for struct
global_dataandgd_board_type().Signed-off-by Heinrich Schuchardt <[email protected]>---
v3:
Avoid duplicate comments: comments replaced by Sphinx documentation should be removed.
v2:
no change
Quoted 3 lines
--- include/asm-generic/global_data.h | 372 +++++++++++++++++++++++++----- 1 file changed, 317 insertions(+), 55 deletions(-)
Would it be OK to use single-line comments in some cases?
/** this is a test */
Regards,
Simon
PATCH v3 2/3 global_data.h: add Sphinx documentation
In reply to Heinrich SchuchardtQuoted 5 lines · Heinrich Schuchardt
Add the missing Sphinx documentation for struct
global_dataandgd_board_type().Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>
Applied to u-boot/master, thanks!
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: <https://lists.denx.de/pipermail/u-boot/attachments/20201014/f17983e6/attachment.sig>
PATCH v3 3/3 doc: global data pointer
In reply to Heinrich SchuchardtAdd the description of the global data pointer to the generated HTML documentation.
---
v3:
no change
v2:
no change
--- doc/develop/global_data.rst | 53 +++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 54 insertions(+) create mode 100644 doc/develop/global_data.rst
doc/develop/global_data.rst new file +53 -0
@@ -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:
doc/develop/index.rst +1 -0
@@ -9,4 +9,5 @@ Develop U-Boot coccinelle crash_dumps + global_data logging
--
2.28.0
PATCH v3 3/3 doc: global data pointer
Quoted 5 lines · Heinrich Schuchardt
Add the description of the global data pointer to the generated HTML documentation.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>
Applied to u-boot/master, thanks!
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: <https://lists.denx.de/pipermail/u-boot/attachments/20201014/09f0e385/attachment.sig>