From patchwork Sat Sep 19 16:03:34 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1367613 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=85.214.62.61; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=gmx.de Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.a=rsa-sha256 header.s=badeba3b8450 header.b=fc0fHFGS; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4BtwY72lSRz9sT6 for ; Sun, 20 Sep 2020 02:06:01 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 2538582493; Sat, 19 Sep 2020 18:05:46 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=none (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.b="fc0fHFGS"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 6DC49824A0; Sat, 19 Sep 2020 18:05:42 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,FREEMAIL_FROM,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.2 Received: from mout.gmx.net (mout.gmx.net [212.227.17.21]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 49DC782476 for ; Sat, 19 Sep 2020 18:05:39 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=none (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=xypron.glpk@gmx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1600531535; bh=kprQ+Wyb11vpEWm5/ZvsvjNciTFa6Ul/8FKBqw1WAX0=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=fc0fHFGSHQIomgfYUTmMsFqPCyVPgArkYGFhzw26SeAjmeEn/D76AjbbS5TyKV32T /kDOMFRiVQXwv1rkg++C/zoL6PUIUurlP1Zkupbw+3PiSowk6thoM4rEva3ZF0RzfC jN7aIYtxxly5ONHf5t4I8kCmCvJGHmSL9AIVoDas= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from workstation4.fritz.box ([178.202.41.107]) by mail.gmx.com (mrgmx104 [212.227.17.174]) with ESMTPSA (Nemesis) id 1MBDj4-1kBN6f1WJS-00Cjd6; Sat, 19 Sep 2020 18:05:35 +0200 From: Heinrich Schuchardt To: Tom Rini Cc: Ilias Apalodimas , Simon Glass , Peng Fan , Bin Meng , Wolfgang Wallner , Baruch Siach , Masahiro Yamada , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH 2/3] global_data.h: add Sphinx documentation Date: Sat, 19 Sep 2020 18:03:34 +0200 Message-Id: <20200919160335.40909-3-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200919160335.40909-1-xypron.glpk@gmx.de> References: <20200919160335.40909-1-xypron.glpk@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:Ie0xqMWJY4PiW3lhSzWPS8qZ0pJjTLzzVIpPY6B34yGFblWTf1T CNygvLNRrIUoOLGvmMNHQ3ak2dzNEBpUPvTm5CqRczEyVNYJ0DQY3NTT6WdeKrlYt+OyY5V GWEWUqfx1F5skYoW6yUpwLK2aDCkRn49IWnNGOz4qxawsta4uVENLzNDlddCw56q48/+dAg C4dorJqLzt1+skcd+9v1g== X-UI-Out-Filterresults: notjunk:1;V03:K0:erNpsdQkEvI=:0DSTd3AwnEDY02ZgL734H3 ME708XvWhXSXW+RTn2r+ojScnmMR/jrMdjS3OSHWA88+9aDvGfcdI1W5y1lvQQgsQAC9FqHHe txM41IR+76F8DRoY3yXNaPRk5oBwujMzsWxIwSMjmBLjxVrrIpdfd6jOEwrFFvyP8UA1a+7QU 7iNyuHW5GQJiH4j/wPRHN6iILWxAl2vUmpYj+ZnbyF/S6Ap1yG9kI1mwtt8JcXeAWeeBNC3Hg a5gmJAf41P4jYevHZplrKCcIA2wmxuqlzgEZLofh+p4lrDHQxspQ/xDD532an7m7l1xk+1bEM lmkf05Yxnko6PC8rSLK0CM5mzlr2PcGdawQYMT/s9bQSJS+v0yY94VHqmfU3MmUvaBTHsXys0 dCpwm7cDOEzkj+1eAzicMvLi7OqAOx80NVxuVCgW4CXH9eOwmmVlR/h5pSA4MwNlgfrLMRJ3M jiyAYVpDppO36AKTotKbTcObxdVGmXQmzUmJ38rr2VjSVDWRDH3lEqVhbQCGKYBGvnjO+Wmwq 9eqh3So6HkiFIR7X5bN8UedEkD6pw0Q8DQb8SAjgG6CdaN5ynYIpVsi+5Rs9RsreXjMiFSsWn F5wGhLTMAXm5TrrypfsgKx5TPbFX1kJxq3Q7oge5237m08556gKwH7YFv+p0weLz7rwlNm4pm bA3ayjg4h+YJl0wqko+rqPTkJj0qj3KEFfR93BqxbfK0TGUFsxdU5acZIUs1MOFUkhKsWr/xB 6gqM/uo5odPor/778juhi0w7CLs7DOogWtWztwwQ6UWbS1J4QuUxHp3sJ16KMBk7iEh4uLnZF lEZ1y2f1gtEWKkLLh1jJSgBruH4hmzdyDJnssdX3iCboi48wLizryjF+Ho6FqWFeF0+dXraq2 OXlW+bhFgTzecw4eUo3y9AA1ECJYO0r9swO12VStTsLrAyJNO+EEAzECc4EAqpFVYGbjFlkW8 sMmQnLYgBXiE6r5Pu5tfgO8HyRreEAJbaSIFjNYI+WEw25Uy9pk40foMhqLUFyAscF9BgBUDD NBAD3HYrzLA9+DjsfKUKwbXg+vedP6ndbL2mGi/33eAHVARD0dHYl2uIPWl86nXDs39eUMO23 +Eg5QUPcMpSoXYulVSvs/mxmqenv0cIz0axQxk7ahyRL4p99JxxAOxd2LzYH+WgClJq4Cb0o7 PUTdv6e159u8b4f4ZaYYiDskB5lg3K/OH6gX6rfNvS5hHy8KLc2jfjSbX30CGn8w+wgmSJAby euz/9OdS1M6OkDjNBMksZRy9GgTwiVh+Tjw5dxQ== X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.102.3 at phobos.denx.de X-Virus-Status: Clean Add the missing Sphinx documentation for struct global_data and gd_board_type(). Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- include/asm-generic/global_data.h | 357 ++++++++++++++++++++++++++---- 1 file changed, 309 insertions(+), 48 deletions(-) -- 2.28.0 diff --git a/include/asm-generic/global_data.h b/include/asm-generic/global_data.h index 6859df4e1d..abbd64a619 100644 --- a/include/asm-generic/global_data.h +++ b/include/asm-generic/global_data.h @@ -24,122 +24,384 @@ #include #include -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 ' 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; -#endif +}; +#endif /* __ASSEMBLY__ */ +/** + * gd_board_type() - retrieve board type + * + * Return: global board type + */ #ifdef CONFIG_BOARD_TYPES #define gd_board_type() gd->board_type #else @@ -230,5 +492,4 @@ enum gd_flags { GD_FLG_SMP_READY = 0x40000, }; - #endif /* __ASM_GENERIC_GBL_DATA_H */