From: Simon Glass <sjg@chromium.org>
Date: Wed, 21 Aug 2024 16:19:27 +0000 (-0600)
Subject: doc: Add some guidelines about global data
X-Git-Url: http://git.dujemihanovic.xyz/html/%7B%7B%20.Permalink%20%7D%7D?a=commitdiff_plain;h=cafaa1a17f765e684e3a5b52448d495c0e1da83d;p=u-boot.git

doc: Add some guidelines about global data

Update the documentation to provide a bit more information about how to
use global data.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

diff --git a/doc/develop/global_data.rst b/doc/develop/global_data.rst
index d143f27eed..2863154ea4 100644
--- a/doc/develop/global_data.rst
+++ b/doc/develop/global_data.rst
@@ -51,6 +51,31 @@ 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.
 
+Guidelines
+----------
+
+The global_data structure is placed in some memory which is available very early
+after boot to allow for a minimum set of global variables during system
+initialisation (until the memory controller is set up and RAM can be used). It
+is the primary data structure passed from pre-relocation U-Boot to
+post-relocation, i.e. ``from board_init_f()`` ``to board_init_r()``.
+
+The global_data struct exists for the lifetime of U-Boot. Since the struct is
+used by all architectures, fields added should be useful for most architectures.
+Fields which are only needed on one or two architectures can be placed in the
+architecture-specific ``struct arch_global_data``.
+
+In any case the struct should be kept small, since it uses precious SRAM on
+many boards.
+
+SPL also uses global data, as well as U-Boot proper, so take care to avoid
+adding fields to SPL which are not actually used by SPL. You can create
+access functions or macros in the header file to avoid filling the C code with
+#ifdefs.
+
+A flags word is available, which provides a convenient means to track the state
+of various initialisation phases within U-Boot.
+
 Global data structure
 ---------------------