7 files changed, 200 insertions, 16 deletions
diff --git a/doc/develop/commands.rst b/doc/develop/commands.rst
index 5ad4e59c838..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, UT_TESTF_SCAN_PDATA | UT_TESTF_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 e3c13b93afd..de1d3045b44 100644
--- a/doc/develop/release_cycle.rst
+++ b/doc/develop/release_cycle.rst
@@ -55,7 +55,7 @@ Current Status
 
 * The Merge Window for the next release (v2024.10) is **closed**.
 
-* The next branch is now **closed**.
+* The next branch is now **open**.
 
 * Release "v2024.10" is scheduled for 07 October 2024.
 
@@ -69,11 +69,11 @@ For the next scheduled release, release candidates were made on::
 
 * U-Boot v2024.10-rc1 was released on Mon 22 July 2024.
 
-.. * U-Boot v2024.10-rc2 was released on Mon 05 August 2024.
+* U-Boot v2024.10-rc2 was released on Mon 05 August 2024.
 
-.. * U-Boot v2024.10-rc3 was released on Mon 19 August 2024.
+* 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 44b544fa78b..a328ebfef33 100644
--- a/doc/develop/tests_writing.rst
+++ b/doc/develop/tests_writing.rst
@@ -81,7 +81,7 @@ The best of both worlds is sometimes to have a Python test set things up and
 perform some operations, with a 'checker' C unit test doing the checks
 afterwards. This can be achieved with these steps:
 
-- Add the `UT_TESTF_MANUAL` flag to the checker test so that the `ut` command
+- Add the `UTF_MANUAL` flag to the checker test so that the `ut` command
   does not run it by default
 - Add a `_norun` suffix to the name so that pytest knows to skip it too
 
@@ -95,7 +95,7 @@ test to run it, e.g.::
    # Run the checker to make sure that everything worked
    ut -f bootstd vbe_test_fixup_norun
 
-Note that apart from the `UT_TESTF_MANUAL` flag, the code in a 'manual' C test
+Note that apart from the `UTF_MANUAL` flag, the code in a 'manual' C test
 is just like any other C test. It still uses ut_assert...() and other such
 constructs, in this case to check that the expected things happened in the
 Python test.
@@ -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("--");
@@ -167,7 +166,7 @@ There is no exactly equivalent C test, but here is a similar one that tests 'ms'
 
       return 0;
    }
-   MEM_TEST(mem_test_ms_b, UT_TESTF_CONSOLE_REC);
+   MEM_TEST(mem_test_ms_b, UTF_CONSOLE);
 
 This runs the command directly in U-Boot, then checks the console output, also
 directly in U-Boot. If run by itself this takes 100ms. For 1000 runs it takes
@@ -226,14 +225,17 @@ Declare the test with::
 
       return 0;
    }
-   DM_TEST(dm_test_uclassname_what, UT_TESTF_SCAN_FDT);
+   DM_TEST(dm_test_uclassname_what, UTF_SCAN_FDT);
+
+Note that the convention is to NOT add a blank line before the macro, so that
+the function it relates to is more obvious.
 
 Replace 'uclassname' with the name of your uclass, if applicable. Replace 'what'
 with what you are testing.
 
 The flags for DM_TEST() are defined in test/test.h and you typically want
-UT_TESTF_SCAN_FDT so that the devicetree is scanned and all devices are bound
-and ready for use. The DM_TEST macro adds UT_TESTF_DM automatically so that
+UTF_SCAN_FDT so that the devicetree is scanned and all devices are bound
+and ready for use. The DM_TEST macro adds UTF_DM automatically so that
 the test runner knows it is a driver model test.
 
 Driver model tests are special in that the entire driver model state is
@@ -263,7 +265,7 @@ with the suite. For example, to add a new mem_search test::
 
          return 0;
    }
-   MEM_TEST(mem_test_ms_new_thing, UT_TESTF_CONSOLE_REC);
+   MEM_TEST(mem_test_ms_new_thing, UTF_CONSOLE);
 
 Note that the MEM_TEST() macros is defined at the top of the file.