From patchwork Mon Oct 5 06:30:09 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1376610 X-Patchwork-Delegate: trini@ti.com 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=2a01:238:438b:c500:173d:9f52:ddab:ee01; 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=I2SEsp5p; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (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 4C4W2K2wmlz9sSn for ; Mon, 5 Oct 2020 17:31:05 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id E4D5382361; Mon, 5 Oct 2020 08:30:33 +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="I2SEsp5p"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 0F2F482339; Mon, 5 Oct 2020 08:30:30 +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.15.15]) (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 06C3D822C8 for ; Mon, 5 Oct 2020 08:30:23 +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=1601879420; bh=aDbTrK2rwkIQNKoErdVTMOBKVSLn5yVab5opQ6kjw94=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=I2SEsp5pOlX/zPdfwS0mHNodD4ogS03DrsXj22WdhEFSs2QIRQGd5NplUdZZA042O 4fuk15LGQtq3CRQXiqMn77E8BUPC0n7LDCxX0OEl89iaX6JKEOK+YYEt2r3SVWy/T+ 3sxWHwSZ0PgKNlV3FTvhb5/fumHWaAXFKjxpD6gQ= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from workstation4.fritz.box ([178.202.41.107]) by mail.gmx.com (mrgmx004 [212.227.17.184]) with ESMTPSA (Nemesis) id 1MD9X9-1kGlI23s5h-0099Yl; Mon, 05 Oct 2020 08:30:20 +0200 From: Heinrich Schuchardt To: Tom Rini Cc: Simon Glass , Ilias Apalodimas , Bin Meng , Peng Fan , Wolfgang Wallner , Baruch Siach , Masahiro Yamada , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH v3 2/3] global_data.h: add Sphinx documentation Date: Mon, 5 Oct 2020 08:30:09 +0200 Message-Id: <20201005063010.8439-3-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201005063010.8439-1-xypron.glpk@gmx.de> References: <20201005063010.8439-1-xypron.glpk@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:qYb3SWRg6hJvE95/WehNDwNrW2hf4m/MNqkYfuKsxUmef4tBJwf 8+988MxFha6R8t5Mf0qPohgSXG45aL4yl5okimPSkrcKFQ9GjlcXRUdHZq21QMfHLc5q4KG TDDudFK1NTmQg0T1/g/hHaQJIXYKGCtCvN3N2yAzbjK3s+GZrtjbyqI18WEG5pVL49WK14K We1VYiee6Ynh/gSwZypoA== X-UI-Out-Filterresults: notjunk:1;V03:K0:D24ic/nJSLw=:m9PyMzeYOOCVOpx5eDuXHT aVjCV2A98WsZI+SWULCHKJCR7qiP6IHMu2nHymeqs9mT3KaenQQ3vlfzGCUFKzdxW4T+Fli8w XVsBsSyfsQVe+agO9cwk1td7QpVi1W9THGNBhAsqxaY5xxwYFJMzMo8TicCTknUvVd5raQHlM 1V+jcIJd9faj+X/tFI2E4YdpfwwpmIyaFYAlYse5rUUJl46jN8Olr2qAx1zrkSBICauX67t9D KW+iHdc0SEC8CeF6nN2WGWKMO1NnFKBd7fbPw+Pa+CpbmKqGwePCVRWK+vjHuDgo8rp1Ma3Qb ieqtMjW/Z7DzlNj9jUf23vE8WNBiMx7gs523wkhTJJVWmuDZVCJDB8pn2QalZ5PAmqOYm2top WaJfbpYIxV7D88xFLt+UoLp1wgvPgz4UpHKH+yGzlulmg50/npe/3EKJ2wu51i192BNBR3wWo civ2rwmTr+VMbvN3c4XCBUi80K6QW/EZBVJkcnyt3QzSBUalHz6gLbtNV8YOjSU+UeN3m3510 NMmKDkaT4aI4BjqcPm52pA5LxxLsc5MVL2A6/QeVQxCjPwUUVq3HDCSSjuBR8I+i6Lx7KsSYV cLB8YvZ8gxwf7CBBYrOVdlTB33Lo0d5QrPQvyJBTopFATxx9i17LsWveVlDUdd0wNRyT74bb8 g1rYH95rLZGXpxuwb0V7duxQzVGzGG2YdSu82QBTPA+nYCXHlDtEJvA38lfkGaEQsyESR35Ry aT1hQKQnSxrud8oFO97HrF8kxYURv7wrWBF3wOnMg1xFwQpeI6IA+WZ4AyUIW3eHr3AntK0gQ 8mJI+dCe6y5kNV2M9EUZ63Xvj4LcXcSEI7gRd1+mVw7dDriiV5qxcVcPgpmsYC4lKNqavrxAV 0S5t3IXYbED/wfeeex0+HQeZiBMk42y2L+gukQUCFaeYRlQAhemdd8g3wrT8GqKeyDhxZSsV8 ehmBx2FLZYUmW4Of5xBMWnL2h/rDre6L6pXYt4Ri8f0YWno9yIlVGdpcIZEDnqVWXG12IR6Nv uJveLbsiBfVcACLqpZ/s7TQn8HV83EE5XUbHXKNaVVIfQyTQkuUgqpboYWSPZDh3AYjJtjKYr /8NjvdEEuqL7PGj5e8/jUTdK2X2jXiO3P3fu9DK5/V9ZvX+uGXNv5ZRTO3qVoUMGOWpqK7ZSJ MB/9/C/5lgF2m6G7R3kP3P0k67BMKI6gvSxzOCJtM5yIhLzDvQlGQ74S4/BEoq/OdlRs72CWC ItcM6gXlQEDtabH8MAglBSQ05aTUYPcRs3ZnCHw== 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 --- 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(-) -- 2.28.0 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 #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) - 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 ' 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