From patchwork Sun Sep 27 12:36:07 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1372043 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=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=Ps8/vi0+; 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) server-digest SHA256) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4BzlWv2ynHz9sPB for ; Sun, 27 Sep 2020 22:36:43 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 7D24182374; Sun, 27 Sep 2020 14:36:28 +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="Ps8/vi0+"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 040AE82377; Sun, 27 Sep 2020 14:36:25 +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.18]) (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 647708235C for ; Sun, 27 Sep 2020 14:36:22 +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=1601210179; bh=meut2PDpoQoCqbAhzTy274uXCTxItxYvO8jUYxkGYTI=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=Ps8/vi0+sEYfYvMXDlR5wqxNkYZhJCCEpVHoWm5ow+IkxZ1IL6gC7P9x136GpxiJ5 f8+F8dq8w20A1PuAiEAQwft2ejuOpClWOH96jV2jz3qzxdUT5NYupeamjNNIawMm09 tGxbNfiyxy9UVtyhRyvo+rYy6goqgsJ6j2BBYOBU= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from LT02.fritz.box ([178.202.41.107]) by mail.gmx.com (mrgmx004 [212.227.17.184]) with ESMTPSA (Nemesis) id 1MbzyP-1kzhU41s35-00dYvH; Sun, 27 Sep 2020 14:36:19 +0200 From: Heinrich Schuchardt To: Tom Rini Cc: Simon Glass , Ilias Apalodimas , Peng Fan , Bin Meng , Masahiro Yamada , Baruch Siach , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH v3 1/3] global_data.h: convert GD_FLG_* to enum Date: Sun, 27 Sep 2020 14:36:07 +0200 Message-Id: <20200927123609.37517-2-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200927123609.37517-1-xypron.glpk@gmx.de> References: <20200927123609.37517-1-xypron.glpk@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:sBeLNt2hE1ioZprZb+wAN6gOc8vDw4eXf4+rljxAb2qbFNlWrNZ xRlQzqnsp7StAfWz9hTNQCVkiowkxe9b3MEdi99nwAs2kVvcFyz8Jpi0H03xApa9fLH0B+L VCqbP512E+nya6E8DDDo6aWW/I0rcsgQY1w0nlRbGpGE5ljEkhK7jkRn1Xz/ls+X72VdRyp gK4KlH/ore9S8uynu7H5Q== X-UI-Out-Filterresults: notjunk:1;V03:K0:atQLNda5CL0=:HDRF2UPo6UMlqlme2SbhLx Lg6gidxyodMCgTDdIskRIr8R36YZf9OK6nL/uy2Z4k1EOYPPFC18E5fXmi4tMRKrj7leQcVip mkpU0SrtX+4Pc2wY/NgomvUKYF97HNqUHLIFqWe6u6fdemAVXa3i1RVoAsHyP3nkWOAC/n2WI 8nqWNTI0mRj/9MWIUiBs2JVYVk4GRvdlHMX7MbaQGPkyM/GtJJ4OTK/Eisw2CWZwUfqhbSX0T 7F7BNswLc6u80afc1u1ommsmI9GPXcn/n5DcYN1mOlQo3GWSA50Ycy+2/yUdyWl9vkHK3SXQ3 ScbD0N8sOWU/FJsFJrWDCAq3ouWadxO94nnMmLsfdxOwCIwkvkQKfyKlmUY0JLW+40mREDqD0 2A0q3VoMFH+0zQsHhcBrrUc5NdUSAkdbYhZDI5VeGwosSshfWSTAVnw6pvUuI4lnXiJF78TdG nOXYkHZ7MUydrUnf7EUhLcZ5Ophbj4igKRxK8LeBkCUkROQOHilH3h+y9e68Gp9+sDQ9cvgbQ ZiRqvre/7RqeRCloxFKift0+yHTROQg0caT9+2yntpKwB2orEKeRlPTW/FLQrVwCmsBQ/PgYR Y2XTOJ8cAJWRdr4U1TpiWVeqaBkDBRlpJzLiWPHAG6rWAw/N5Sv+MiH8pPL46raC1p9tG/1zI 7sXIkPljrTo4b//a5riaOBJnkqVaqCR9LrmEHyeLmOESj/fnZ2yPrr4BWum6BeScOnX1yFnUg 2HwmDhCqSvkUuQz9jcKkEjdbAFVq5G3hLwSDHzsfAXv1FWJ4IpoOPLgJ0T2i+DyCm7ahchHlY mFl/Yp/SbGnMS7nJ3YGEbvLtlSbMkVQLYWp6cC75CETlriRSqqvvwQIUcZZSv4N9KkUBtlgsP +bdjI+aCLekeCxnDIN5noz3bS9UjhWOJaTpOAAo8gyF4l0Kn7rblOm7wLgRlaOI3/9QVeKhf2 a4ZLy1fFPENFkqyAoBD28+Hm+zi98RI3Cx8zZnyx6Ud0z4xyrywT5bz4jwun7Mtztxr7qaGL3 TBgj2QqJt6nKHi24EGRACF5ezhjDom/WMXlmHqM3JvFVAD5mf8DS5JZJbD2La8SzvOGQhqsMD PjK6nVciCJLZtF/i/ihrV539u7+I/ukJIVYHT9MZ9m68QXsHfjnsFTsiz8Xla9jbBdC/tYLW6 ZusPPmgBaIVk0JOWcO18h5uItnjy4fwjp85ocBYpgAW4scf5a32FNDggbo/+owwCw8mA0GiR2 AQWsheXu5QzPyEu2wt0cLAGJFL2Y60qnnYkItPg== 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 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 Reviewed-by: Simon Glass --- 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(-) -- 2.28.0 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 */ From patchwork Sun Sep 27 12:36:08 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1372045 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=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=k7ld0jmL; 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 4BzlXH6WYWz9sSG for ; Sun, 27 Sep 2020 22:37:03 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 21B0C823AF; Sun, 27 Sep 2020 14:36:35 +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="k7ld0jmL"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id E2A4182384; Sun, 27 Sep 2020 14:36:27 +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 5B24C82374 for ; Sun, 27 Sep 2020 14:36: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=1601210180; bh=zk+6+JvAzIg7Q5FNQp4IwCwf7x8NYiXkfmGFWddEMOY=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=k7ld0jmLZNbmJDwmeUBIqiBo7XLM5cZaCvwg8gtu89AsKB3RBNNw/0YGb1vTtQdV2 aj005K5XhSbxinSvhcAsEY5IxRZxdGp75LlgDX1PMTgwBNprJiAStzcYGetOiTdB0v 1GBnDUaKtQnyGp3OFe95KKe+ywxI9X6Ti+kp0dpQ= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from LT02.fritz.box ([178.202.41.107]) by mail.gmx.com (mrgmx004 [212.227.17.184]) with ESMTPSA (Nemesis) id 1M9o1v-1kJV703gQv-005uCL; Sun, 27 Sep 2020 14:36:20 +0200 From: Heinrich Schuchardt To: Tom Rini Cc: Simon Glass , Ilias Apalodimas , Peng Fan , Bin Meng , Masahiro Yamada , Baruch Siach , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH v3 2/3] global_data.h: add Sphinx documentation Date: Sun, 27 Sep 2020 14:36:08 +0200 Message-Id: <20200927123609.37517-3-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200927123609.37517-1-xypron.glpk@gmx.de> References: <20200927123609.37517-1-xypron.glpk@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:5+FayWhTgHNbOP9b1ltPVIf8J+nQzOZ+Q1rY2LEWwkiNLtwHCfX 5RdFjABiCOGd9dzKPz+h+nha+/ioINrzH2Sp+7uxd3+dPKydQjANAuFdKPX3i/irF5281/2 kdRwFSS4QKeSnHzx5n+CzSBjPXvfhw5xZfPq9gPIb1240rzxmgpK/+vghKJFeAVAKlcq22G MhTDNPWMedffVI9P1IMGA== X-UI-Out-Filterresults: notjunk:1;V03:K0:X7Xy1jprhTg=:BOsXoEPMMWPAv3E1dPPQYv BxwsJKnCc3hwSVPba/Ed96zzDg9b1QXqsRjWK9K0Su9igJXy1MO4HOP+UHFgVkEjXTkhYog7x iYkoXFGSoKFX8WOYeQ3/naQvoJiWN1IujbH6No16B/LPECDetglFbT1Qe5pcYCOLfKdu74CXK NMvvkvGHJnoIsSFpIFhidWBk4bxV04pqQ2Udi0YR6aYN0BN4MlSQMZRTxTsI5PnBPZvVkkinP HVlVDImd4mseqlFTxizvmk8ZBPiGyOXr9wu0vZUiOYhj9w/AoPN04u9nztahduB+JspU/mthr UJwYmVP+2nizdOxD1fcyDp62obA9XjAUR4bejbMIE93NAvnUOmHeNanJ7lKys5DN7su543W9u 0cVeYelW3qsDaqEbrNATLXiOs9BzkbJNcY8DX9OQr9VmNiUXRLtRVKug9SlW2c5tX/AWprw5a ThEn02lCHi1dwWKSSUI7c7Zt0e2team92upfxBTyBqYbCa36EsvH65Cc0A6tO/LgmXnd2FyY4 dpjGB8gA1I7KHDejfxxbDDs4j7yf8HuLDGBq966f9vpsV81SW5SvFVR+GmnvlmGtTdL4Or02l FtT47xCwP51w11HychNeyaJAYGhdxjWBPpi3i3WsNFGy+mRaPYSWa1S7bx0v+kh0jschX3n+4 jMdmpCmQlMJ2qWy/he6aZM60l0LgyZ6ISWfiz/AUdRp7h87dpGKimRn2+cWq/a9RhRQZ3gIOh NeQ28RtftOdtDMrXFxTROYrCLRM73oicT416U4Bk/iN9Mj2JVtuI8I+NHYtMDI2JsW9KiZRCZ ygW/TisIAQ7QhvCeY8xpScbUVK2g9oS8xuscMYhuUwzsmHLSKIQ2atY6hoTdn1WkwONezVm7W Kblpz5i8go3lmGdX+u21UCyZeWvldX8ZzB9Udbc9ZKbDJ+spEKuiq3BmQ05AwV80XN31X32kA gZrPtfxll203+r1r6v8+FlYSjd/80m1iMJ3CxMJwLrBsdETvBmwGDQGSjTEMcMZZXD6yZIJm0 pyN7LtpGhNKade7z+tfmJP/vbL9f01TRGjR/ZEzVC2JBnfiaBvUPbBpPvQ65VaKK9edImzK1R B5nWSRq8nHVmPFrXMPPtxSouF6RDx6fwl1vjUMtiG6edN6UTvfqaUya+t0UNuy01y+aeaKK0d WLXEAF6EJqc+tlUS1Q2otUnCucuYh+eyvAZtqRDZuhslFQLOLku5tqOeSTd9ft391ORKExSsD Xplp9uXp+GL8YRilWlvodUwjJUWajCFrGx7bMkQ== 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: no change v2: no change --- include/asm-generic/global_data.h | 354 ++++++++++++++++++++++++++---- 1 file changed, 308 insertions(+), 46 deletions(-) -- 2.28.0 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 #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; +}; +/** + * gd_board_type() - retrieve board type + * + * Return: global board type + */ #ifdef CONFIG_BOARD_TYPES #define gd_board_type() gd->board_type #else From patchwork Sun Sep 27 12:36: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: 1372044 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=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=SVAArHrI; 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 4BzlX468phz9sPB for ; Sun, 27 Sep 2020 22:36:52 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id B5D41823A2; Sun, 27 Sep 2020 14:36:29 +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="SVAArHrI"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 29D6F82393; Sun, 27 Sep 2020 14:36:27 +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.19]) (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 AEBCB82369 for ; Sun, 27 Sep 2020 14:36:22 +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=1601210180; bh=9ayRznRXOQMq/oNL66J+YafbUsD2unRcD4DnkBhgrhA=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=SVAArHrIzdoDg1dbltLc9BDNowfqaBOj2Ull/gEzG4S/oI1nCWQkMMkIRduy1Jsdr lXCl7MO3nUAfQ3HIPUz2o3b7YmstCICNhMlf8iw3hOaT+o/tBEOj4iwMJ09TM6XPNM 4OlPGuPjFYb7/7dx/ubyx6Kvzi+MvR0GY5E+umYk= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from LT02.fritz.box ([178.202.41.107]) by mail.gmx.com (mrgmx004 [212.227.17.184]) with ESMTPSA (Nemesis) id 1M4s4r-1kOQmx1E7b-0022JL; Sun, 27 Sep 2020 14:36:20 +0200 From: Heinrich Schuchardt To: Tom Rini Cc: Simon Glass , Ilias Apalodimas , Peng Fan , Bin Meng , Masahiro Yamada , Baruch Siach , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH v3 3/3] doc: global data pointer Date: Sun, 27 Sep 2020 14:36:09 +0200 Message-Id: <20200927123609.37517-4-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200927123609.37517-1-xypron.glpk@gmx.de> References: <20200927123609.37517-1-xypron.glpk@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:lsCJhvgtNioLqjNHwW52v+kpEnRrwH+f9frW5Tcn5csWJRjlv7q S4NytVwwK5dsUPmPIGD2wa8J5+Wjs1Sd2rmugMIwZGoRnLc/SHHXVtAEMiJQkJrAPvt9y4V vxyUoIDgB22osXDR3vPP91WVFhJRG1Sn6ybyTig1xyzLTRRfVfca4coz0Y529JbBaFG/SrW /Qh2houHXJApH6yzPZuew== X-UI-Out-Filterresults: notjunk:1;V03:K0:HZz78rSCB2M=:xLdt6h3QRq+X6QlxL9aVWB 9SL7AP2kdNiVQWc8gLBWnvr8BXcpQ/EBRdChfEWSe39d5W0IG+fVIAMSXvsAAWm6LyPjWWmIZ rLFUp/pEmhSH5maJcJ3X1xiDTWoD2Cn+bG5MJKvnU4kgDaOohTlgJmlmWroIaidtcAy/6rVVQ lPSj87LFTtLzvNemxarcwS9+J49wdbSLFaAhqzKnHzmLK3O96ryruv/VUSkLJDks7pgvddZg9 b41BMPR0eqy6qmqUOBf/sgR8Vcytd8aFsLNdAjaVMJJro696N8aJ2mU73NhBG9dq5222OCQPk nK1c6yzmkxqC9V0501hi8o2CYokuKfr/JnbBbSP4eKNQcTG+7VteFH2HJxjg9PDrZB7J9k1eG KE+cwTCVtemync5UyeJQOqPCLD2A2BQ8Ddq9G0MqfrCnl76rxLVQncONjKRgyKCNCK3YqQHCD cFasyp0YdJAVoJTRLaAmMnfQgIOKxa6kDQ4ujg3OSR1RJ26G1htEnJ56CIB/ME+oLcGvPshba dqdhyqhJCwOC5f9XMSxLm7uZCwPkDW0lIoHInGfw2RZ+jp9afmrZmzA6mZ3+dQccJDAgSYcZY q0bLK4ybuzhbkg5C9Nyz/WCnIU3VSqMw0s7ZtnAw6pqcL1HXUA0/fOOMqez/zIR2TzrSTFm1F twmfXpgVIhx/t0FQ+6DJYliHHvs83JXrGfppdDaO0E6HRWxVFKLBEAstJvpv1yjazJAdKZ/tU ng7V7NweZkSmiw7WfSEqx2G6yAmerHmNWmWy10mkPtA8k2nG8caPq15aUX/s+8S4wLVZOmD1+ VzXQ7PePhp/4svaJXctlkAJ5YGgnTHLnIFL+sB6MwIdjvosXECjg3KjhHeuILSoarnBXMjHOJ rd+pNotvP73NZur2eMedK1GEDm3Ow7jcooGXp5dXCsJ9T9Rk1F7OFPs7M4uJ0ocLxkmvtZzhz sujRdesTO596INKem+T3t50/w+DoCL7kWfKvirKccsjVcN5wT4/1dxQgVnJNO9b2m5VWpjwQY 7Lo0jy1Q93aq+g07Nd/zMEVa/Jlff/ucTO8MykEpDInm5oCesd+dwr037LQcWBdaum9RBpCbE tWkPjIMzQ1XF/gkjAb0tc/myj+NeNa6d4PCMezCZAON00mMOhY/4wGlYHvpnm3p8gE3PGCwUP GAfx0/X/oGxJY0tjggoKCx5obVkQSelLIc5o3QDC0A48sSnEYxCqT27TqCJlKmb+5Ax++1Bof MaEPtnnQoiLC6pWSpvGVvIC/e9eHKSXPzRkvLnQ== 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 description of the global data pointer to the generated HTML documentation. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- v3: x86 uses register fs for global data pointer 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 -- 2.28.0 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