8 files changed, 214 insertions, 6 deletions
diff --git a/doc/develop/commands.rst b/doc/develop/commands.rst
index 6427844f143..77a7a4d9c02 100644
--- a/doc/develop/commands.rst
+++ b/doc/develop/commands.rst
@@ -197,7 +197,6 @@ Here is an example:
 
         ctx.current = buf;
         ut_assertok(acpi_fill_ssdt(&ctx));
-        console_record_reset();
         run_command("acpi items", 0);
         ut_assert_nextline("dev 'acpi-test', type 1, size 2");
         ut_assert_nextline("dev 'acpi-test2', type 1, size 2");
@@ -205,13 +204,11 @@ Here is an example:
 
         ctx.current = buf;
         ut_assertok(acpi_inject_dsdt(&ctx));
-        console_record_reset();
         run_command("acpi items", 0);
         ut_assert_nextline("dev 'acpi-test', type 2, size 2");
         ut_assert_nextline("dev 'acpi-test2', type 2, size 2");
         ut_assert_console_end();
 
-        console_record_reset();
         run_command("acpi items -d", 0);
         ut_assert_nextline("dev 'acpi-test', type 2, size 2");
         ut_assert_nextlines_are_dump(2);
@@ -223,4 +220,8 @@ Here is an example:
 
         return 0;
     }
-    DM_TEST(dm_test_acpi_cmd_items, UTF_SCAN_PDATA | UTF_SCAN_FDT);
+    DM_TEST(dm_test_acpi_cmd_items, UTF_SCAN_PDATA | UTF_SCAN_FDT | UTF_CONSOLE);
+
+Note that it is not necessary to call console_record_reset() unless you are
+trying to drop some unchecked output. Consider using ut_check_skip_to_line()
+instead.
diff --git a/doc/develop/global_data.rst b/doc/develop/global_data.rst
index d143f27eedd..2863154ea42 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
 ---------------------
 
diff --git a/doc/develop/historical/generic_board.rst b/doc/develop/historical/generic_board.rst
new file mode 100644
index 00000000000..12550a140e0
--- /dev/null
+++ b/doc/develop/historical/generic_board.rst
@@ -0,0 +1,136 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. (C) Copyright 2014 Google, Inc
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
+
+Generic board
+-------------
+
+U-Boot traditionally had a board.c file for each architecture. This introduced
+quite a lot of duplication, with each architecture tending to do
+initialisation slightly differently. To address this, a new 'generic board
+init' feature was introduced in March 2013 (further motivation is
+provided in the cover letter below).
+
+All boards and architectures have moved to this as of mid 2016.
+
+
+What has changed?
+~~~~~~~~~~~~~~~~~
+
+The main change is that the arch/<arch>/lib/board.c file is removed in
+favour of common/board_f.c (for pre-relocation init) and common/board_r.c
+(for post-relocation init).
+
+Related to this, the global_data and bd_info structures now have a core set of
+fields which are common to all architectures. Architecture-specific fields
+have been moved to separate structures.
+
+
+Further Background
+~~~~~~~~~~~~~~~~~~
+
+The full text of the original generic board series is reproduced below.
+
+--8<-------------
+
+This series creates a generic board.c implementation which contains
+the essential functions of the major arch/xxx/lib/board.c files.
+
+What is the motivation for this change?
+
+1. There is a lot of repeated code in the board.c files. Any change to
+things like setting up the baud rate requires a change in 10 separate
+places.
+
+2. Since there are 10 separate files, adding a new feature which requires
+initialisation is painful since it must be independently added in 10
+places.
+
+3. As time goes by the architectures naturally diverge since there is limited
+pressure to compare features or even CONFIG options against similar things
+in other board.c files.
+
+4. New architectures must implement all the features all over again, and
+sometimes in subtle different ways. This places an unfair burden on getting
+a new architecture fully functional and running with U-Boot.
+
+5. While it is a bit of a tricky change, I believe it is worthwhile and
+achievable. There is no requirement that all code be common, only that
+the code that is common should be located in common/board.c rather than
+arch/xxx/lib/board.c.
+
+All the functions of board_init_f() and board_init_r() are broken into
+separate function calls so that they can easily be included or excluded
+for a particular architecture. It also makes it easier to adopt Graeme's
+initcall proposal when it is ready.
+
+http://lists.denx.de/pipermail/u-boot/2012-January/114499.html
+
+This series removes the dependency on generic relocation. So relocation
+happens as one big chunk and is still completely arch-specific. See the
+relocation series for a proposed solution to this for ARM:
+
+http://lists.denx.de/pipermail/u-boot/2011-December/112928.html
+
+or Graeme's recent x86 series v2:
+
+http://lists.denx.de/pipermail/u-boot/2012-January/114467.html
+
+Instead of moving over a whole architecture, this series takes the approach
+of simply enabling generic board support for an architecture. It is then up
+to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board
+config file. If this is not done, then the code will be generated as
+before. This allows both sets of code to co-exist until we are comfortable
+with the generic approach, and enough boards run.
+
+ARM is a relatively large board.c file and one which I can test, therefore
+I think it is a good target for this series. On the other hand, x86 is
+relatively small and simple, but different enough that it introduces a
+few issues to be solved. So I have chosen both ARM and x86 for this series.
+After a suggestion from Wolfgang I have added PPC also. This is the
+largest and most feature-full board, so hopefully we have all bases
+covered in this RFC.
+
+A generic global_data structure is also required. This might upset a few
+people. Here is my basic reasoning: most fields are the same, all
+architectures include and need it, most global_data.h files already have
+#ifdefs to select fields for a particular SOC, so it is hard to
+see why architecures are different in this area. We can perhaps add a
+way to put architecture-specific fields into a separate header file, but
+for now I have judged that to be counter-productive.
+
+Similarly we need a generic bd_info structure, since generic code will
+be accessing it. I have done this in the same way as global_data and the
+same comments apply.
+
+There was dicussion on the list about passing gd_t around as a parameter
+to pre-relocation init functions. I think this makes sense, but it can
+be done as a separate change, and this series does not require it.
+
+While this series needs to stand on its own (as with the link script
+cleanup series and the generic relocation series) the goal is the
+unification of the board init code. So I hope we can address issues with
+this in mind, rather than focusing too narrowly on particular ARM, x86 or
+PPC issues.
+
+I have run-tested ARM on Tegra Seaboard only. To try it out, define
+CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on
+x86 and PPC at least it will hang, but if you are lucky it will print
+something first :-)
+
+I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all
+ARM, PPC and x86 boards. There are a few failures due to errors in
+the board config, which I have sent patches for. The main issue is
+just the difference between __bss_end and __bss_end__.
+
+Note: the first group of commits are required for this series to build,
+but could be separated out if required. I have included them here for
+convenience.
+
+------------->8--
+
+Simon Glass, sjg@chromium.org
+March 2014
+
+Updated after final removal, May 2016
+
diff --git a/doc/develop/historical/index.rst b/doc/develop/historical/index.rst
new file mode 100644
index 00000000000..e4462f5d2a7
--- /dev/null
+++ b/doc/develop/historical/index.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Historical Documents
+====================
+
+This section provides documentation about major changes in U-Boot over the
+years.
+
+.. toctree::
+   :maxdepth: 1
+
+   generic_board
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index c0107a783fc..0d0e60ab56c 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -99,3 +99,11 @@ Code quality
    :maxdepth: 1
 
    python_cq
+
+Historical documentation
+------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   historical/index
diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst
index 72863756a42..de1d3045b44 100644
--- a/doc/develop/release_cycle.rst
+++ b/doc/develop/release_cycle.rst
@@ -73,7 +73,7 @@ For the next scheduled release, release candidates were made on::
 
 * U-Boot v2024.10-rc3 was released on Mon 19 August 2024.
 
-.. * U-Boot v2024.10-rc4 was released on Mon 02 September 2024.
+* U-Boot v2024.10-rc4 was released on Mon 02 September 2024.
 
 .. * U-Boot v2024.10-rc5 was released on Mon 16 September 2024.
 
diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst
index 404d158ec40..a328ebfef33 100644
--- a/doc/develop/tests_writing.rst
+++ b/doc/develop/tests_writing.rst
@@ -151,7 +151,6 @@ There is no exactly equivalent C test, but here is a similar one that tests 'ms'
       buf[0x31] = 0x12;
       buf[0xff] = 0x12;
       buf[0x100] = 0x12;
-      ut_assertok(console_record_reset_enable());
       run_command("ms.b 1 ff 12", 0);
       ut_assert_nextline("00000030: 00 12 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ................");
       ut_assert_nextline("--");
diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
index d450b12bf80..94482758573 100644
--- a/doc/develop/uefi/uefi.rst
+++ b/doc/develop/uefi/uefi.rst
@@ -449,6 +449,33 @@ practice. Getting this information from the firmware itself is more
 secure, assuming the firmware has been verified by a previous stage
 boot loader.
 
+Dynamic Firmware Update GUIDs
+*****************************
+
+The image_type_id contains a GUID value which is specific to the image
+and board being updated, that is to say it should uniquely identify the
+board model (and revision if relevant) and image pair. Traditionally,
+these GUIDs are generated manually and hardcoded on a per-board basis,
+however this scheme makes it difficult to scale up to support many
+boards.
+
+To address this, v5 GUIDs can be used to generate board-specific GUIDs
+at runtime, based on the board's devicetree root compatible
+(e.g. "qcom,qrb5165-rb5").
+
+These strings are combined with the fw_image name to generate GUIDs for
+each image. Support for dynamic UUIDs can be enabled by generating a new
+namespace UUID and setting EFI_CAPSULE_NAMESPACE_GUID to it. Dynamic GUID
+generation is only enabled if the image_type_id property is unset for your
+firmware images, this is to avoid breaking existing boards with hardcoded
+GUIDs.
+
+The mkeficapsule tool can be used to determine the GUIDs for a particular
+board and image. It can be found in the tools directory.
+
+Firmware update images
+**********************
+
 The firmware images structure defines the GUID values, image index
 values and the name of the images that are to be updated through
 the capsule update feature. These values are to be defined as part of