* [PATCH v3 0/3] doc: global data pointer
@ 2020-10-05 6:30 Heinrich Schuchardt
2020-10-05 6:30 ` [PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum Heinrich Schuchardt
` (2 more replies)
0 siblings, 3 replies; 9+ messages in thread
From: Heinrich Schuchardt @ 2020-10-05 6:30 UTC (permalink / raw)
To: u-boot
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum
2020-10-05 6:30 [PATCH v3 0/3] doc: global data pointer Heinrich Schuchardt
@ 2020-10-05 6:30 ` Heinrich Schuchardt
2020-10-14 17:43 ` Tom Rini
2020-10-05 6:30 ` [PATCH v3 2/3] global_data.h: add Sphinx documentation Heinrich Schuchardt
2020-10-05 6:30 ` [PATCH v3 3/3] doc: global data pointer Heinrich Schuchardt
2 siblings, 1 reply; 9+ messages in thread
From: Heinrich Schuchardt @ 2020-10-05 6:30 UTC (permalink / raw)
To: u-boot
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 <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
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(-)
diff --git a/include/asm-generic/global_data.h b/include/asm-generic/global_data.h
index d4a4e2215d..e4a68e0d91 100644
--- a/include/asm-generic/global_data.h
+++ b/include/asm-generic/global_data.h
@@ -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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH v3 2/3] global_data.h: add Sphinx documentation
2020-10-05 6:30 [PATCH v3 0/3] doc: global data pointer Heinrich Schuchardt
2020-10-05 6:30 ` [PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum Heinrich Schuchardt
@ 2020-10-05 6:30 ` Heinrich Schuchardt
2020-10-12 3:34 ` Simon Glass
2020-10-14 17:43 ` Tom Rini
2020-10-05 6:30 ` [PATCH v3 3/3] doc: global data pointer Heinrich Schuchardt
2 siblings, 2 replies; 9+ messages in thread
From: Heinrich Schuchardt @ 2020-10-05 6:30 UTC (permalink / raw)
To: u-boot
Add the missing Sphinx documentation for struct global_data and
gd_board_type().
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
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(-)
diff --git a/include/asm-generic/global_data.h b/include/asm-generic/global_data.h
index e4a68e0d91..ebb740d34f 100644
--- a/include/asm-generic/global_data.h
+++ b/include/asm-generic/global_data.h
@@ -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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH v3 3/3] doc: global data pointer
2020-10-05 6:30 [PATCH v3 0/3] doc: global data pointer Heinrich Schuchardt
2020-10-05 6:30 ` [PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum Heinrich Schuchardt
2020-10-05 6:30 ` [PATCH v3 2/3] global_data.h: add Sphinx documentation Heinrich Schuchardt
@ 2020-10-05 6:30 ` Heinrich Schuchardt
2020-10-14 17:43 ` Tom Rini
2 siblings, 1 reply; 9+ messages in thread
From: Heinrich Schuchardt @ 2020-10-05 6:30 UTC (permalink / raw)
To: u-boot
Add the description of the global data pointer to the generated HTML
documentation.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
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
diff --git a/doc/develop/global_data.rst b/doc/develop/global_data.rst
new file mode 100644
index 0000000000..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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH v3 2/3] global_data.h: add Sphinx documentation
2020-10-05 6:30 ` [PATCH v3 2/3] global_data.h: add Sphinx documentation Heinrich Schuchardt
@ 2020-10-12 3:34 ` Simon Glass
2020-10-14 17:43 ` Tom Rini
1 sibling, 0 replies; 9+ messages in thread
From: Simon Glass @ 2020-10-12 3:34 UTC (permalink / raw)
To: u-boot
On Mon, 5 Oct 2020 at 00:35, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> Add the missing Sphinx documentation for struct global_data and
> gd_board_type().
>
> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> ---
> 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(-)
Reviewed-by: Simon Glass <sjg@chromium.org>
Would it be OK to use single-line comments in some cases?
/** this is a test */
Regards,
Simon
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum
2020-10-05 6:30 ` [PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum Heinrich Schuchardt
@ 2020-10-14 17:43 ` Tom Rini
0 siblings, 0 replies; 9+ messages in thread
From: Tom Rini @ 2020-10-14 17:43 UTC (permalink / raw)
To: u-boot
On Mon, Oct 05, 2020 at 08:30:08AM +0200, Heinrich Schuchardt wrote:
> 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 <xypron.glpk@gmx.de>
> Reviewed-by: Simon Glass <sjg@chromium.org>
Applied to u-boot/master, thanks!
--
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>
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v3 2/3] global_data.h: add Sphinx documentation
2020-10-05 6:30 ` [PATCH v3 2/3] global_data.h: add Sphinx documentation Heinrich Schuchardt
2020-10-12 3:34 ` Simon Glass
@ 2020-10-14 17:43 ` Tom Rini
1 sibling, 0 replies; 9+ messages in thread
From: Tom Rini @ 2020-10-14 17:43 UTC (permalink / raw)
To: u-boot
On Mon, Oct 05, 2020 at 08:30:09AM +0200, Heinrich Schuchardt wrote:
> Add the missing Sphinx documentation for struct global_data and
> gd_board_type().
>
> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> Reviewed-by: Simon Glass <sjg@chromium.org>
Applied to u-boot/master, thanks!
--
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>
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v3 3/3] doc: global data pointer
2020-10-05 6:30 ` [PATCH v3 3/3] doc: global data pointer Heinrich Schuchardt
@ 2020-10-14 17:43 ` Tom Rini
0 siblings, 0 replies; 9+ messages in thread
From: Tom Rini @ 2020-10-14 17:43 UTC (permalink / raw)
To: u-boot
On Mon, Oct 05, 2020 at 08:30:10AM +0200, Heinrich Schuchardt wrote:
> Add the description of the global data pointer to the generated HTML
> documentation.
>
> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> Reviewed-by: Simon Glass <sjg@chromium.org>
Applied to u-boot/master, thanks!
--
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>
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v3 0/3] doc: global data pointer
@ 2020-09-27 12:36 Heinrich Schuchardt
0 siblings, 0 replies; 9+ messages in thread
From: Heinrich Schuchardt @ 2020-09-27 12:36 UTC (permalink / raw)
To: u-boot
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:
x86 uses register fs for global data pointer
v2:
enum gd_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 | 460 +++++++++++++++++++++++++-----
3 files changed, 446 insertions(+), 68 deletions(-)
create mode 100644 doc/develop/global_data.rst
--
2.28.0
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2020-10-14 17:43 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-05 6:30 [PATCH v3 0/3] doc: global data pointer Heinrich Schuchardt
2020-10-05 6:30 ` [PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum Heinrich Schuchardt
2020-10-14 17:43 ` Tom Rini
2020-10-05 6:30 ` [PATCH v3 2/3] global_data.h: add Sphinx documentation Heinrich Schuchardt
2020-10-12 3:34 ` Simon Glass
2020-10-14 17:43 ` Tom Rini
2020-10-05 6:30 ` [PATCH v3 3/3] doc: global data pointer Heinrich Schuchardt
2020-10-14 17:43 ` Tom Rini
-- strict thread matches above, loose matches on Subject: below --
2020-09-27 12:36 [PATCH v3 0/3] " Heinrich Schuchardt
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.