[PATCH v3 0/3] doc: global data pointer

[PATCH v3 0/3] doc: global data pointer

[Heinrich Schuchardt]

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

[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 <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

[PATCH v3 2/3] global_data.h: add Sphinx documentation

[Heinrich Schuchardt]

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

[PATCH v3 3/3] doc: global data pointer

[Heinrich Schuchardt]

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

[PATCH v3 2/3] global_data.h: add Sphinx documentation

[Simon Glass]

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

[PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum

[Tom Rini]

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>

[PATCH v3 2/3] global_data.h: add Sphinx documentation

[Tom Rini]

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>

[PATCH v3 3/3] doc: global data pointer

[Tom Rini]

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>

[PATCH v3 2/3] global_data.h: add Sphinx documentation

[Heinrich Schuchardt]

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>
---
v3:
	no change
v2:
	no change
---
 include/asm-generic/global_data.h | 354 ++++++++++++++++++++++++++----
 1 file changed, 308 insertions(+), 46 deletions(-)

diff --git a/include/asm-generic/global_data.h b/include/asm-generic/global_data.h
index e4a68e0d91..7222fa1241 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)
+	/**
+	 * @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;	/* 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_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
+	/**
+	 * @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;	/* serial_init() was called */
 #if CONFIG_IS_ENABLED(PRE_CONSOLE_BUFFER)
+	/**
+	 * @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;	/* Pre-Console buffer index */
 #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 */
+	/**
+	 * @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;		/* Top 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.
+	 */
 	unsigned long relocaddr;	/* Start address of U-Boot in RAM */
-	phys_size_t ram_size;		/* RAM size */
-	unsigned long mon_len;		/* monitor len */
+	/**
+	 * @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;		/* irq stack pointer */
-	unsigned long start_addr_sp;	/* start_addr_stackpointer */
+	/**
+	 * @start_addr_sp: initial stack pointer address
+	 */
+	unsigned long start_addr_sp;
+	/**
+	 * @reloc_off: relocation offset
+	 */
 	unsigned long reloc_off;
+	/**
+	 * @new_gd: pointer to relocated global data
+	 */
 	struct global_data *new_gd;	/* relocated global data */

 #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 */
+	/**
+	 * @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;			/* Mask containing log format info */
 #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)
+	/**
+	 * @translation_offset: optional translation offset
+	 *
+	 * See CONFIG_TRANSLATION_OFFSET.
+	 */
 	fdt_addr_t translation_offset;	/* optional 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