Merge tag 'v2023.10-rc4' into next

Prepare v2023.10-rc4

24 files changed, 854 insertions, 140 deletions

diff --git a/doc/api/event.rst b/doc/api/event.rst
new file mode 100644
index 00000000000..8a57d438322
--- /dev/null
+++ b/doc/api/event.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Events
+======
+
+The concept of events is decribed :doc:`here <../develop/event>`.
+
+.. kernel-doc:: include/event.h
+   :internal:
diff --git a/doc/api/index.rst b/doc/api/index.rst
index 3a80ae0635a..2f0218c47a3 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -10,6 +10,7 @@ U-Boot API documentation
    dfu
    dm
    efi
+   event
    getopt
    linker_lists
    lmb
diff --git a/doc/board/qualcomm/sdm845.rst b/doc/board/qualcomm/sdm845.rst
index 71879c2a6e3..d3f218e835e 100644
--- a/doc/board/qualcomm/sdm845.rst
+++ b/doc/board/qualcomm/sdm845.rst
@@ -38,9 +38,10 @@ and FIT image instead of ``initramfs``. Android bootloader expect gzipped kernel
 with appended dtb, so let's mimic linux to satisfy stock bootloader.
 
 Boards
-------------
+------
+
 starqlte
-^^^^^^^^^^^^
+^^^^^^^^
 
 The starqltechn is a production board for Samsung S9 (SM-G9600) phone,
 based on the Qualcomm SDM845 SoC.
@@ -149,7 +150,11 @@ Steps:
 	mkbootimg --kernel u-boot.bin.gz-dtb --ramdisk db845c.itb \
 	--output boot.img --pagesize 4096 --base 0x80000000
 
-- Flash boot.img using db845c fastboot method.
+- Flash boot.img using db845c fastboot method:
+
+  .. code-block:: bash
+
+      sudo fastboot flash boot boot.img
 
 More information can be found on the `DragonBoard 845c page`_.
 
diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
index 5ed17c0a3a5..d7437c6d22f 100644
--- a/doc/board/ti/am62x_sk.rst
+++ b/doc/board/ti/am62x_sk.rst
@@ -47,6 +47,7 @@ Boot Flow:
 Below is the pictorial representation of boot flow:
 
 .. image:: img/boot_diagram_k3_current.svg
+  :alt: Boot flow diagram
 
 - Here TIFS acts as master and provides all the critical services. R5/A53
   requests TIFS to get these services done as shown in the above diagram.
@@ -102,13 +103,13 @@ Set the variables corresponding to this platform:
 
 3. U-Boot:
 
-* 4.1 R5:
+* 3.1 R5:
 
 .. include::  ../ti/k3.rst
     :start-after: .. k3_rst_include_start_build_steps_spl_r5
     :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
-* 4.2 A53:
+* 3.2 A53:
 
 .. include::  ../ti/k3.rst
     :start-after: .. k3_rst_include_start_build_steps_uboot
@@ -141,10 +142,12 @@ Image formats:
 - tiboot3.bin
 
 .. image:: img/multi_cert_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
 
 - tispl.bin
 
 .. image:: img/dm_tispl.bin.svg
+  :alt: tispl.bin image format
 
 A53 SPL DDR Memory Layout
 -------------------------
diff --git a/doc/board/ti/am65x_evm.rst b/doc/board/ti/am65x_evm.rst
index 5f3c46cf9f9..7cebb1ca62d 100644
--- a/doc/board/ti/am65x_evm.rst
+++ b/doc/board/ti/am65x_evm.rst
@@ -46,6 +46,7 @@ applications. This should happen before running Linux.
 instead use Falcon boot flow to reduce boot time.
 
 .. image:: img/boot_diagram_am65.svg
+  :alt: Boot flow diagram
 
 - Here DMSC acts as master and provides all the critical services. R5/A53
   requests DMSC to get these services done as shown in the above diagram.
@@ -102,13 +103,13 @@ Set the variables corresponding to this platform:
 
 3. U-Boot:
 
-* 4.1 R5:
+* 3.1 R5:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_spl_r5
     :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
-* 4.2 A53:
+* 3.2 A53:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_uboot
@@ -122,13 +123,13 @@ Each SoC variant (GP and HS) requires a different source for these files.
 
 - GP
 
-        * tiboot3-am65x_sr2-gp-evm.bin, sysfw-am65x_sr2-gp-evm.itb from step 4.1
-        * tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
+        * tiboot3-am65x_sr2-gp-evm.bin, sysfw-am65x_sr2-gp-evm.itb from step 3.1
+        * tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
 
 - HS
 
-        * tiboot3-am65x_sr2-hs-evm.bin, sysfw-am65x_sr2-hs-evm.itb from step 4.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tiboot3-am65x_sr2-hs-evm.bin, sysfw-am65x_sr2-hs-evm.itb from step 3.1
+        * tispl.bin, u-boot.img from step 3.2
 
 Image formats:
 --------------
@@ -136,14 +137,17 @@ Image formats:
 - tiboot3.bin
 
 .. image:: img/no_multi_cert_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
 
 - tispl.bin
 
 .. image:: img/nodm_tispl.bin.svg
+  :alt: tispl.bin image format
 
 - sysfw.itb
 
 .. image:: img/sysfw.itb.svg
+  :alt: sysfw.itb image format
 
 eMMC:
 -----
@@ -185,6 +189,7 @@ used:
 eMMC layout:
 
 .. image:: img/emmc_am65x_evm_boot0.svg
+  :alt: emmc boot partition layout
 
 Kernel image and DT are expected to be present in the /boot folder of rootfs.
 To boot kernel from eMMC, use the following commands:
@@ -220,6 +225,7 @@ addresses.
 Flash layout for OSPI:
 
 .. image:: img/ospi_sysfw.svg
+  :alt: OSPI flash partition layout
 
 Kernel Image and DT are expected to be present in the /boot folder of UBIFS
 ospi.rootfs just like in SD card case. U-Boot looks for UBI volume named
diff --git a/doc/board/ti/j7200_evm.rst b/doc/board/ti/j7200_evm.rst
index 2e60e22ba15..bcf8dc1c5f0 100644
--- a/doc/board/ti/j7200_evm.rst
+++ b/doc/board/ti/j7200_evm.rst
@@ -35,6 +35,7 @@ Boot Flow:
 Below is the pictorial representation of boot flow:
 
 .. image:: img/boot_diagram_k3_current.svg
+  :alt: Boot flow diagram
 
 - Here DMSC acts as master and provides all the critical services. R5/A72
   requests DMSC to get these services done as shown in the above diagram.
@@ -91,13 +92,13 @@ Set the variables corresponding to this platform:
 
 3. U-Boot:
 
-* 4.1 R5:
+* 3.1 R5:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_spl_r5
     :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
-* 4.2 A72:
+* 3.2 A72:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_uboot
@@ -111,18 +112,18 @@ variant (GP, HS-FS, HS-SE) requires a different source for these files.
 
  - GP
 
-        * tiboot3-j7200-gp-evm.bin from step 4.1
-        * tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
+        * tiboot3-j7200-gp-evm.bin from step 3.1
+        * tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
 
  - HS-FS
 
-        * tiboot3-j7200_sr2-hs-fs-evm.bin from step 4.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tiboot3-j7200_sr2-hs-fs-evm.bin from step 3.1
+        * tispl.bin, u-boot.img from step 3.2
 
  - HS-SE
 
-        * tiboot3-j7200_sr2-hs-evm.bin from step 4.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tiboot3-j7200_sr2-hs-evm.bin from step 3.1
+        * tispl.bin, u-boot.img from step 3.2
 
 Image formats:
 --------------
@@ -130,12 +131,12 @@ Image formats:
 - tiboot3.bin
 
 .. image:: img/j7200_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
 
 - tispl.bin
 
 .. image:: img/dm_tispl.bin.svg
-
-
+  :alt: tispl.bin image format
 
 Switch Setting for Boot Mode
 ----------------------------
@@ -191,6 +192,7 @@ Size of u-boot.img is taken 4MB for refernece,
 But this is subject to change depending upon atf, optee size
 
 .. image:: img/emmc_j7200_evm_boot01.svg
+  :alt: Traditional eMMC boot partition layout
 
 In case of UDA FS mode booting, following is layout.
 
@@ -198,6 +200,7 @@ All boot images tiboot3.bin, tispl and u-boot should be written to
 fat formatted UDA FS as file.
 
 .. image:: img/emmc_j7200_evm_udafs.svg
+  :alt: eMMC UDA boot partition layout
 
 In case of booting from eMMC, write above images into raw or UDA FS.
 and set mmc partconf accordingly.
diff --git a/doc/board/ti/j721e_evm.rst b/doc/board/ti/j721e_evm.rst
index d2a214fb33f..cadaac01781 100644
--- a/doc/board/ti/j721e_evm.rst
+++ b/doc/board/ti/j721e_evm.rst
@@ -40,6 +40,7 @@ Boot flow is similar to that of AM65x SoC and extending it with remoteproc
 support. Below is the pictorial representation of boot flow:
 
 .. image:: img/boot_diagram_j721e.svg
+  :alt: Boot flow diagram
 
 - Here DMSC acts as master and provides all the critical services. R5/A72
   requests DMSC to get these services done as shown in the above diagram.
@@ -96,13 +97,13 @@ Set the variables corresponding to this platform:
 
 3. U-Boot:
 
-* 4.1 R5:
+* 3.1 R5:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_spl_r5
     :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
-* 4.2 A72:
+* 3.2 A72:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_uboot
@@ -117,18 +118,18 @@ files.
 
  - GP
 
-        * tiboot3-j721e-gp-evm.bin, sysfw-j721e-gp-evm.itb from step 4.1
-        * tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
+        * tiboot3-j721e-gp-evm.bin, sysfw-j721e-gp-evm.itb from step 3.1
+        * tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
 
  - HS-FS
 
-        * tiboot3-j721e_sr2-hs-fs-evm.bin, sysfw-j721e_sr2-hs-fs-evm.itb from step 4.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tiboot3-j721e_sr2-hs-fs-evm.bin, sysfw-j721e_sr2-hs-fs-evm.itb from step 3.1
+        * tispl.bin, u-boot.img from step 3.2
 
  - HS-SE
 
-        * tiboot3-j721e_sr2-hs-evm.bin, sysfw-j721e_sr2-hs-evm.itb from step 4.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tiboot3-j721e_sr2-hs-evm.bin, sysfw-j721e_sr2-hs-evm.itb from step 3.1
+        * tispl.bin, u-boot.img from step 3.2
 
 Image formats:
 --------------
@@ -136,14 +137,17 @@ Image formats:
 - tiboot3.bin
 
 .. image:: img/no_multi_cert_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
 
 - tispl.bin
 
 .. image:: img/dm_tispl.bin.svg
+  :alt: tispl.bin image format
 
 - sysfw.itb
 
 .. image:: img/sysfw.itb.svg
+  :alt: sysfw.itb image format
 
 R5 Memory Map:
 --------------
@@ -213,6 +217,7 @@ addresses.
 Flash layout for OSPI:
 
 .. image:: img/ospi_sysfw.svg
+  :alt: OSPI flash partition layout
 
 Firmwares:
 ----------
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
index 5f9bd4dfcbe..95cdb366252 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -48,6 +48,7 @@ including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump
 to after it has finished loading everything into internal SRAM.
 
 .. image:: img/boot_flow_01.svg
+  :alt: Boot flow up to wakeup domain SPL
 
 The wakeup SPL, running on a wakeup domain core, will initialize DDR and
 any peripherals needed load the larger binaries inside the `tispl.bin`
@@ -57,6 +58,7 @@ starting with Trusted Firmware-A (TF-A), before moving on to start
 OP-TEE and the main domain's U-Boot SPL.
 
 .. image:: img/boot_flow_02.svg
+  :alt: Boot flow up to main domain SPL
 
 The main domain's SPL, running on a 64bit application core, has
 virtually unlimited space (billions of bytes now that DDR is working) to
@@ -65,6 +67,7 @@ which loads more firmware into the micro-controller & wakeup domains and
 finally prepare the main domain to run Linux.
 
 .. image:: img/boot_flow_03.svg
+  :alt: Complete boot flow up to Linux
 
 This is the typical boot flow for all K3 based SoCs, however this flow
 offers quite a lot in the terms of flexibility, especially on High
@@ -121,11 +124,30 @@ online
   | **source:** https://github.com/OP-TEE/optee_os.git
   | **branch:** master
 
-* **TI Firmware (TIFS, DM, DSMC)**
+* **TI Firmware (TIFS, DM, SYSFW)**
 
   | **source:** https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
   | **branch:** ti-linux-firmware
 
+.. note::
+
+  The TI Firmware required for functionality of the system can be
+  one of the following combination (see platform specific boot diagram for
+  further information as to which component runs on which processor):
+
+  * **TIFS** - TI Foundational Security Firmware - Consists of purely firmware
+    meant to run on the security enclave.
+  * **DM** - Device Management firmware also called TI System Control Interface
+    server (TISCI Server) - This component purely plays the role of managing
+    device resources such as power, clock, interrupts, dma etc. This firmware
+    runs on a dedicated or multi-use microcontroller outside the security
+    enclave.
+
+ OR
+
+  * **SYSFW** - System firmware - consists of both TIFS and DM both running on
+    the security enclave.
+
 .. k3_rst_include_end_boot_sources
 
 Build Procedure
@@ -173,13 +195,13 @@ All of that to say you will need both a 32bit and 64bit cross compiler
 .. k3_rst_include_end_common_env_vars_desc
 
 .. k3_rst_include_start_common_env_vars_defn
-.. code-block:: bash
+.. prompt:: bash
 
- $ export CC32=arm-linux-gnueabihf-
- $ export CC64=aarch64-linux-gnu-
- $ export LNX_FW_PATH=path/to/ti-linux-firmware
- $ export TFA_PATH=path/to/trusted-firmware-a
- $ export OPTEE_PATH=path/to/optee_os
+ export CC32=arm-linux-gnueabihf-
+ export CC64=aarch64-linux-gnu-
+ export LNX_FW_PATH=path/to/ti-linux-firmware
+ export TFA_PATH=path/to/trusted-firmware-a
+ export OPTEE_PATH=path/to/optee_os
 .. k3_rst_include_end_common_env_vars_defn
 
 We will also need some common environment variables set up for the various
@@ -223,11 +245,11 @@ Building tiboot3.bin
    uses the split binary flow)
 
 .. k3_rst_include_start_build_steps_spl_r5
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXR
- $ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
+ # inside u-boot source
+ make $UBOOT_CFG_CORTEXR
+ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
 .. k3_rst_include_end_build_steps_spl_r5
 
 At this point you should have all the needed binaries to boot the wakeup
@@ -259,11 +281,11 @@ firmware if your device using a split firmware.
    application cores on the main domain.
 
 .. k3_rst_include_start_build_steps_tfa
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside trusted-firmware-a source
- $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
-        TARGET_BOARD=$TFA_BOARD
+ # inside trusted-firmware-a source
+ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
+      TARGET_BOARD=$TFA_BOARD
 .. k3_rst_include_end_build_steps_tfa
 
 Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
@@ -275,11 +297,11 @@ use the `lite` option.
    using the TrustZone technology built into the core.
 
 .. k3_rst_include_start_build_steps_optee
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside optee_os source
- $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
-         PLATFORM=$OPTEE_PLATFORM
+ # inside optee_os source
+ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
+       PLATFORM=$OPTEE_PLATFORM
 .. k3_rst_include_end_build_steps_optee
 
 4. Finally, after TF-A has initialized the main domain and OP-TEE has
@@ -287,11 +309,11 @@ use the `lite` option.
    64bit core in the main domain.
 
 .. k3_rst_include_start_build_steps_uboot
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXA
- $ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
+ # inside u-boot source
+ make $UBOOT_CFG_CORTEXA
+ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
         BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \
         TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
 .. k3_rst_include_end_build_steps_uboot
@@ -386,14 +408,14 @@ and the same can be extended to other platforms
   be passing to mkimage for signing the fitImage and embedding the key in
   the u-boot dtb.
 
-  .. code-block:: bash
+  .. prompt:: bash
 
     mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
     $UBOOT_PATH/build/a72/dts/dt.dtb
 
   For signing a secondary platform, pass the -K parameter to that DTB
 
-  .. code-block:: bash
+  .. prompt:: bash
 
     mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
     $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb
@@ -452,10 +474,11 @@ then the saveenv command and can be used across various bootmodes too.
 
 **Writing to MMC/EMMC**
 
-.. code-block::
+.. prompt:: bash
+  :prompts: =>
 
-  => env export -t $loadaddr <list of variables>
-  => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
+  env export -t $loadaddr <list of variables>
+  fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
 
 **Reading from MMC/EMMC**
 
@@ -465,10 +488,11 @@ mmcdev) and set the environments.
 If manually needs to be done then the environment can be read from the
 filesystem and then imported
 
-.. code-block::
+.. prompt:: bash
+  :prompts: =>
 
-  => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
-  => env import -t ${loadaddr} ${filesize}
+  fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
+  env import -t ${loadaddr} ${filesize}
 
 .. _k3_rst_refer_openocd:
 
@@ -486,6 +510,7 @@ generation device.
 The overall structure of this setup is in the following figure.
 
 .. image:: img/openocd-overview.svg
+  :alt: Overview of OpenOCD setup.
 
 .. note::
 
@@ -524,7 +549,7 @@ Refer to the release notes corresponding to the `OpenOCD version
   box support by OpenOCD. The board-specific documentation will
   cover the details and any adapter/dongle recommendations.
 
-.. code-block:: bash
+.. prompt:: bash
 
  openocd -v
 
@@ -542,21 +567,21 @@ systems, but equivalent instructions should exist for systems with
 other package managers. Please refer to the `OpenOCD Documentation
 <https://openocd.org/>`_ for more recent installation steps.
 
-.. code-block:: bash
+.. prompt:: bash
 
-  $ # Check the packages to be installed: needs deb-src in sources.list
-  $ sudo apt build-dep openocd
-  $ # The following list is NOT complete - please check the latest
-  $ sudo apt-get install libtool pkg-config texinfo libusb-dev \
+  # Check the packages to be installed: needs deb-src in sources.list
+  sudo apt build-dep openocd
+  # The following list is NOT complete - please check the latest
+  sudo apt-get install libtool pkg-config texinfo libusb-dev \
     libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
-  $ git clone https://github.com/openocd-org/openocd.git openocd
-  $ cd openocd
-  $ git submodule init
-  $ git submodule update
-  $ ./bootstrap
-  $ ./configure --prefix=/usr/local/
-  $ make -j`nproc`
-  $ sudo make install
+  git clone https://github.com/openocd-org/openocd.git openocd
+  cd openocd
+  git submodule init
+  git submodule update
+  ./bootstrap
+  ./configure --prefix=/usr/local/
+  make -j`nproc`
+  sudo make install
 
 .. note::
 
@@ -572,28 +597,28 @@ The step is not necessary if the distribution supports the OpenOCD, but
 if building from a source, ensure that the udev rules are installed
 correctly to ensure a sane system.
 
-.. code-block:: bash
+.. prompt:: bash
 
   # Go to the OpenOCD source directory
-  $ cd openocd
-  # Copy the udev rules to the correct system location
-  $ sudo cp ./contrib/60-openocd.rules \
-      ./src/JTAG/drivers/libjaylink/contrib/99-libjaylink.rules \
+  cd openocd
+  Copy the udev rules to the correct system location
+  sudo cp ./contrib/60-openocd.rules \
+      ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
       /etc/udev/rules.d/
   # Get Udev to load the new rules up
-  $ sudo udevadm control --reload-rules
+  sudo udevadm control --reload-rules
   # Use the new rules on existing connected devices
-  $ sudo udevadm trigger
+  sudo udevadm trigger
 
 Step 2: Setup GDB
 ^^^^^^^^^^^^^^^^^
 
 Most systems come with gdb-multiarch package.
 
-.. code-block:: bash
+.. prompt:: bash
 
   # Install gdb-multiarch package
-  $ sudo apt-get install gdb-multiarch
+  sudo apt-get install gdb-multiarch
 
 Though using GDB natively is normal, developers with interest in using IDE
 may find a few of these interesting:
@@ -769,7 +794,7 @@ Code modification
   In this example, we will debug ``board_init_f`` inside
   ``arch/arm/mach-k3/{soc}_init.c``. Since some sections of U-Boot
   will be executed multiple times during the bootup process of K3
-  devices, we will need to include either ``CONFIG_CPU_ARM64`` or
+  devices, we will need to include either ``CONFIG_ARM64`` or
   ``CONFIG_CPU_V7R`` to catch the CPU at the desired place during the
   bootup process (Main or Wakeup domains). For example, modify the
   file as follows (depending on need):
@@ -787,7 +812,7 @@ Code modification
       }
       ...
       /* Code to run on the ARMV8 (Main Domain) */
-      if (IS_ENABLED(CONFIG_CPU_ARM64)) {
+      if (IS_ENABLED(CONFIG_ARM64)) {
           volatile int x = 1;
           while(x) {};
       }
@@ -806,7 +831,7 @@ Startup OpenOCD to debug the platform as follows:
 
 .. k3_rst_include_start_openocd_cfg_XDS110
 
-.. code-block:: bash
+.. prompt:: bash
 
   openocd -f board/{board_of_choice}.cfg
 
@@ -820,7 +845,7 @@ Startup OpenOCD to debug the platform as follows:
   <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_
   to decide if the SoC is supported or not.
 
-.. code-block:: bash
+.. prompt:: bash
 
   openocd -f openocd_connect.cfg
 
@@ -895,7 +920,7 @@ To debug using this server, use GDB directly or your preferred
 GDB-based IDE. To start up GDB in the terminal, run the following
 command.
 
-.. code-block:: bash
+.. prompt:: bash
 
   gdb-multiarch
 
diff --git a/doc/board/toradex/apalis-imx8.rst b/doc/board/toradex/apalis-imx8.rst
index 849b1172bd4..ffc4c7d222a 100644
--- a/doc/board/toradex/apalis-imx8.rst
+++ b/doc/board/toradex/apalis-imx8.rst
@@ -1,7 +1,11 @@
-.. SPDX-License-Identifier: GPL-2.0+
+.. SPDX-License-Identifier: GPL-2.0-or-later
+.. sectionauthor:: Marcel Ziswiler <marcel.ziswiler@toradex.com>
 
-Apalis iMX8QM V1.0B Module
-==========================
+Apalis iMX8 Module
+==================
+
+- SoM: https://www.toradex.com/computer-on-modules/apalis-arm-family/nxp-imx-8
+- Carrier board: https://www.toradex.com/products/carrier-board/apalis-evaluation-board
 
 Quick Start
 -----------
@@ -49,6 +53,7 @@ Copy the following firmware to the U-Boot folder:
 
 Build U-Boot
 ------------
+
 .. code-block:: bash
 
     $ make apalis-imx8_defconfig
@@ -61,8 +66,8 @@ Get the latest version of the universal update utility (uuu) aka ``mfgtools 3.0`
 
 https://community.nxp.com/external-link.jspa?url=https%3A%2F%2Fgithub.com%2FNXPmicro%2Fmfgtools%2Freleases
 
-Put the module into USB recovery aka serial downloader mode, connect USB device
-to your host and execute uuu:
+Put the module into USB recovery aka serial downloader mode, connect the USB
+device to your host and execute ``uuu``:
 
 .. code-block:: bash
 
@@ -80,3 +85,10 @@ partition and boot:
     setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
     mmc dev 0 1
     mmc write ${loadaddr} 0x0 ${blkcnt}
+
+As a convenience, instead of the last three commands, one may also use the
+update U-Boot wrapper:
+
+.. code-block:: bash
+
+    > run update_uboot
diff --git a/doc/board/toradex/colibri-imx8x.rst b/doc/board/toradex/colibri-imx8x.rst
index 545568c844a..9e61d98c6b1 100644
--- a/doc/board/toradex/colibri-imx8x.rst
+++ b/doc/board/toradex/colibri-imx8x.rst
@@ -1,7 +1,11 @@
-.. SPDX-License-Identifier: GPL-2.0+
+.. SPDX-License-Identifier: GPL-2.0-or-later
+.. sectionauthor:: Marcel Ziswiler <marcel.ziswiler@toradex.com>
 
-Colibri iMX8QXP V1.0D Module
-============================
+Colibri iMX8X Module
+====================
+
+- SoM: https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-imx-8x
+- Carrier board: https://www.toradex.com/products/carrier-board/colibri-evaluation-board
 
 Quick Start
 -----------
@@ -23,18 +27,19 @@ Get and Build the ARM Trusted Firmware
 
 Get scfw_tcm.bin and ahab-container.img
 ---------------------------------------
+
 .. code-block:: bash
 
     $ wget https://github.com/toradex/i.MX-System-Controller-Firmware/raw/master/src/scfw_export_mx8qx_b0/build_mx8qx_b0/mx8qx-colibri-scfw-tcm.bin
-    $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-seco-3.7.4.bin
-    $ sh imx-seco-3.7.4.bin --auto-accept
+    $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-seco-3.8.1.bin
+    $ sh imx-seco-3.8.1.bin --auto-accept
 
 Copy the following firmware to the U-Boot folder:
 
 .. code-block:: bash
 
     $ cp imx-atf/build/imx8qx/release/bl31.bin .
-    $ cp imx-seco-3.7.4/firmware/seco/mx8qxc0-ahab-container.img mx8qx-ahab-container.img
+    $ cp imx-seco-3.8.1/firmware/seco/mx8qxc0-ahab-container.img mx8qx-ahab-container.img
 
 Build U-Boot
 ------------
@@ -51,8 +56,8 @@ Get the latest version of the universal update utility (uuu) aka ``mfgtools 3.0`
 
 https://community.nxp.com/external-link.jspa?url=https%3A%2F%2Fgithub.com%2FNXPmicro%2Fmfgtools%2Freleases
 
-Put the module into USB recovery aka serial downloader mode, connect USB device
-to your host and execute ``uuu``:
+Put the module into USB recovery aka serial downloader mode, connect the USB
+device to your host and execute ``uuu``:
 
 .. code-block:: bash
 
@@ -61,7 +66,8 @@ to your host and execute ``uuu``:
 Flash the U-Boot Binary into the eMMC
 -------------------------------------
 
-Burn the ``u-boot-dtb.imx`` binary to the primary eMMC hardware boot area partition:
+Burn the ``u-boot-dtb.imx`` binary to the primary eMMC hardware boot area
+partition and boot:
 
 .. code-block:: bash
 
@@ -69,3 +75,10 @@ Burn the ``u-boot-dtb.imx`` binary to the primary eMMC hardware boot area partit
     setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
     mmc dev 0 1
     mmc write ${loadaddr} 0x0 ${blkcnt}
+
+As a convenience, instead of the last three commands, one may also use the
+update U-Boot wrapper:
+
+.. code-block:: bash
+
+    > run update_uboot
diff --git a/doc/board/toradex/colibri_imx7.rst b/doc/board/toradex/colibri_imx7.rst
index a30e721379e..6532878932c 100644
--- a/doc/board/toradex/colibri_imx7.rst
+++ b/doc/board/toradex/colibri_imx7.rst
@@ -1,7 +1,11 @@
-.. SPDX-License-Identifier: GPL-2.0+
+.. SPDX-License-Identifier: GPL-2.0-or-later
+.. sectionauthor:: Igor Opaniuk <igor.opaniuk@toradex.com>
 
-Colibri iMX7
-============
+Colibri iMX7 Modules
+====================
+
+- SoM: https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-freescale-imx7
+- Carrier board: https://www.toradex.com/products/carrier-board/colibri-evaluation-board
 
 Quick Start
 -----------
@@ -21,11 +25,11 @@ Build U-Boot
     $ make colibri_imx7_emmc_defconfig # For NAND: colibri_imx7_defconfig
     $ make
 
-After build succeeds, you will obtain final ``u-boot-dtb.imx`` IMX specific
-image, ready for flashing (but check next section for additional
+After the build succeeds, you will obtain the final ``u-boot-dtb.imx`` IMX
+specific image, ready for flashing (but check next section for additional
 adjustments).
 
-Final IMX program image includes (section ``6.6.7`` from `IMX7DRM
+The final IMX program image includes (section ``6.6.7`` from `IMX7DRM
 <https://www.nxp.com/webapp/Download?colCode=IMX7DRM>`_):
 
 * **Image vector table** (IVT) for BootROM
@@ -34,21 +38,20 @@ Final IMX program image includes (section ``6.6.7`` from `IMX7DRM
 * **Device configuration data**
 * **User image**: U-Boot image (``u-boot-dtb.bin``)
 
-
 IMX image adjustments prior to flashing
 ---------------------------------------
 
 1. U-Boot for both Colibri iMX7 NAND and eMMC versions
 is built with HABv4 support (`AN4581.pdf
 <https://www.nxp.com/docs/en/application-note/AN4581.pdf>`_)
-enabled by default, which requires to generate a proper
+enabled by default, which requires generating a proper
 Command Sequence File (CSF) by srktool from NXP (not included in the
 U-Boot tree, check additional details in introduction_habv4.txt)
 and concatenate it to the final ``u-boot-dtb.imx``.
 
-2. In case if you don't want to generate a proper ``CSF`` (for any reason),
-you still need to pad the IMX image so i has the same size as specified in
-in **Boot Data** section of IMX image.
+2. In case you don't want to generate a proper ``CSF`` (for any reason),
+you still need to pad the IMX image so it has the same size as specified in
+the **Boot Data** section of the IMX image.
 To obtain this value, run:
 
 .. code-block:: bash
@@ -78,11 +81,11 @@ and then pad the image:
     $ objcopy -I binary -O binary --pad-to 0xa7c60 --gap-fill=0x00 \
         u-boot-dtb.imx u-boot-dtb.imx.zero-padded
 
-3. Also, according to requirement from ``6.6.7.1``, the final image
-should have ``0x400`` offset for initial IVT table.
+3. Also, according to the requirement from ``6.6.7.1``, the final image
+should have ``0x400`` offset for the initial IVT table.
 
-For eMMC setup we handle this by flashing it to ``0x400``, howewer
-for NAND setup we adjust the image prior to flashing, adding padding in the
+For eMMC setup we handle this by flashing it to ``0x400``, however
+for NAND setup we adjust the image prior to flashing, adding padding at the
 beginning of the image.
 
 .. code-block:: bash
@@ -97,7 +100,6 @@ boot area partition:
 
 .. code-block:: bash
 
-
     => load mmc 1:1 $loadaddr u-boot-dtb.imx.zero-padded
     => setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
     => mmc dev 0 1
@@ -117,8 +119,8 @@ Flash U-Boot IMX image to NAND
 Using update_uboot script
 -------------------------
 
-You can also usb U-Boot env update_uboot script,
-which wraps all eMMC/NAND specific command invocation:
+You can also use U-Boot env update_uboot script,
+which wraps all eMMC/NAND specific command invocations:
 
 .. code-block:: bash
 
diff --git a/doc/board/toradex/verdin-am62.rst b/doc/board/toradex/verdin-am62.rst
index 36db149cda0..e8d90273288 100644
--- a/doc/board/toradex/verdin-am62.rst
+++ b/doc/board/toradex/verdin-am62.rst
@@ -24,12 +24,14 @@ For an overview of the TI AM62 SoC boot flow please head over to:
 
 Sources:
 --------
+
 .. include::  ../ti/k3.rst
     :start-after: .. k3_rst_include_start_boot_sources
     :end-before: .. k3_rst_include_end_boot_sources
 
 Build procedure:
 ----------------
+
 0. Setup the environment variables:
 
 .. include::  ../ti/k3.rst
@@ -50,7 +52,7 @@ Set the variables corresponding to this platform:
  $ export UBOOT_CFG_CORTEXR=verdin-am62_r5_defconfig
  $ export UBOOT_CFG_CORTEXA=verdin-am62_a53_defconfig
  $ export TFA_BOARD=lite
- $ # we dont use any extra TFA parameters
+ $ # we don't use any extra TFA parameters
  $ unset TFA_EXTRA_ARGS
  $ export OPTEE_PLATFORM=k3-am62x
  $ export OPTEE_EXTRA_ARGS="CFG_WITH_SOFTWARE_PRNG=y"
@@ -72,12 +74,24 @@ Flash to eMMC
     => fatload mmc 1 ${loadaddr} u-boot.img
     => mmc write ${loadaddr} 0x1400 0x2000
 
+As a convenience, instead of having to remember all those addresses and sizes,
+one may also use the update U-Boot wrappers:
+
+.. code-block:: bash
+
+    > tftpboot ${loadaddr} tiboot3-am62x-gp-verdin.bin
+    > run update_tiboot3
+
+    > tftpboot ${loadaddr} tispl.bin
+    > run update_tispl
+
+    > tftpboot ${loadaddr} u-boot.img
+    > run update_uboot
+
 Boot
 ----
 
-Output:
-
-.. code-block:: none
+Output::
 
   U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:14 +0200)
   SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)')
diff --git a/doc/board/toradex/verdin-imx8mm.rst b/doc/board/toradex/verdin-imx8mm.rst
index cc39030450f..6e150e9aec7 100644
--- a/doc/board/toradex/verdin-imx8mm.rst
+++ b/doc/board/toradex/verdin-imx8mm.rst
@@ -46,6 +46,7 @@ Get the DDR Firmware
 
 Build U-Boot
 ------------
+
 .. code-block:: bash
 
     $ export CROSS_COMPILE=aarch64-linux-gnu-
@@ -61,7 +62,7 @@ Flash to eMMC
     > setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
     > mmc dev 0 1 && mmc write ${loadaddr} 0x2 ${blkcnt}
 
-As a convenience, instead of the last two commands one may also use the update
+As a convenience, instead of the last two commands, one may also use the update
 U-Boot wrapper:
 
 .. code-block:: bash
@@ -71,16 +72,14 @@ U-Boot wrapper:
 Boot
 ----
 
-ATF, U-Boot proper and u-boot.dtb images are packed into FIT image,
+ATF, U-Boot proper and u-boot.dtb images are packed into a FIT image,
 which is loaded and parsed by SPL.
 
 Boot sequence is:
 
 * SPL ---> ATF (TF-A) ---> U-Boot proper
 
-Output:
-
-.. code-block:: none
+Output::
 
   U-Boot SPL 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200)
   Normal Boot
diff --git a/doc/board/toradex/verdin-imx8mp.rst b/doc/board/toradex/verdin-imx8mp.rst
index bdc4d0c2cb5..9ee605f64d5 100644
--- a/doc/board/toradex/verdin-imx8mp.rst
+++ b/doc/board/toradex/verdin-imx8mp.rst
@@ -46,6 +46,7 @@ Get the DDR Firmware
 
 Build U-Boot
 ------------
+
 .. code-block:: bash
 
     $ export CROSS_COMPILE=aarch64-linux-gnu-
@@ -61,7 +62,7 @@ Flash to eMMC
     > setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
     > mmc dev 2 1 && mmc write ${loadaddr} 0x0 ${blkcnt}
 
-As a convenience, instead of the last two commands one may also use the update
+As a convenience, instead of the last two commands, one may also use the update
 U-Boot wrapper:
 
 .. code-block:: bash
@@ -71,16 +72,14 @@ U-Boot wrapper:
 Boot
 ----
 
-ATF, U-Boot proper and u-boot.dtb images are packed into FIT image,
+ATF, U-Boot proper and u-boot.dtb images are packed into a FIT image,
 which is loaded and parsed by SPL.
 
 Boot sequence is:
 
 * SPL ---> ATF (TF-A) ---> U-Boot proper
 
-Output:
-
-.. code-block:: none
+Output::
 
   U-Boot SPL 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100)
   Quad die, dual rank failed, attempting dual die, single rank configuration.
diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
index 011cd34a57c..20b0fefa2d8 100644
--- a/doc/build/documentation.rst
+++ b/doc/build/documentation.rst
@@ -5,6 +5,17 @@ Building documentation
 
 The U-Boot documentation is based on the Sphinx documentation generator.
 
+In addition to the Python packages listed in ``doc/sphinx/requirements.txt``,
+the following dependencies are needed to build the documentation:
+
+* fontconfig
+
+* graphviz
+
+* imagemagick
+
+* texinfo (if building the `Infodoc documentation`_)
+
 HTML documentation
 ------------------
 
diff --git a/doc/conf.py b/doc/conf.py
index 00f24136647..5e2ff1c8f5e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -39,7 +39,7 @@ needs_sphinx = '2.4.4'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat', 'sphinx-prompt']
 
 #
 # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst
index c01e0971dc8..e8b90752f08 100644
--- a/doc/develop/bootstd.rst
+++ b/doc/develop/bootstd.rst
@@ -132,6 +132,9 @@ above bootdev scanning.
 Controlling ordering
 --------------------
 
+By default, faster bootdevs (or those which are assumed to be faster) are used
+first, since they are more likely to be able to boot the device quickly.
+
 Several options are available to control the ordering of boot scanning:
 
 
@@ -151,6 +154,10 @@ bootdevs and their sequence numbers.
 bootmeths
 ~~~~~~~~~
 
+By default bootmeths are checked in name order. Use `bootmeth list` to see the
+ordering. Note that the `extlinux` and `script` bootmeth is first, to preserve the behaviour
+used by the old distro scripts.
+
 This environment variable can be used to control the list of bootmeths used and
 their ordering for example::
 
@@ -164,7 +171,6 @@ controlled by aliases.
 The :ref:`usage/cmd/bootmeth:bootmeth command` (`bootmeth order`) operates in
 the same way as setting this variable.
 
-
 Bootdev uclass
 --------------
 
diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst
index 50d33df4211..346cf29ef39 100644
--- a/doc/develop/release_cycle.rst
+++ b/doc/develop/release_cycle.rst
@@ -70,7 +70,7 @@ For the next scheduled release, release candidates were made on::
 
 * U-Boot v2023.10-rc3 was released on Mon 21 August 2023.
 
-.. * U-Boot v2023.10-rc4 was released on Mon 04 September 2023.
+* U-Boot v2023.10-rc4 was released on Mon 04 September 2023.
 
 .. * U-Boot v2023.10-rc5 was released on Mon 18 September 2023.
 
diff --git a/doc/develop/uefi/u-boot_on_efi.rst b/doc/develop/uefi/u-boot_on_efi.rst
index acad6397e81..0d4927807ca 100644
--- a/doc/develop/uefi/u-boot_on_efi.rst
+++ b/doc/develop/uefi/u-boot_on_efi.rst
@@ -254,6 +254,90 @@ This shows running with serial enabled (see `include/configs/efi-x86_app.h`)::
 
    => QEMU: Terminated
 
+Run on VirtualBox (x86_64)
+--------------------------
+
+Enable EFI
+~~~~~~~~~~
+At settings for virtual machine the flag at **System->Motherboard->Enable EFI
+(special OSes only)** has to be enabled.
+
+Installation
+~~~~~~~~~~~~
+Provide the preinstalled Linux system as a Virtual Disk Image (VDI) and assign
+it to a SATA controller (type AHCI) using the settings for the virtual machine
+at menu item **System->Storage->Controller:SATA**.
+
+For the following description three GPT partitions are assumed:
+
+- Partition 1: formatted as FAT file-system and marked as EFI system partition
+  (partition type 0xEF00) used for the U-Boot EFI binary. (If VirtualBox is UEFI
+  compliant, it should recognize the ESP as the boot partition.)
+
+- Partition 2: formatted as **ext4**, used for root file system
+
+Create an extlinux.conf or a boot script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Following files are assumed to be located at system for boot configuration::
+
+ Partition  File                    Comment
+ 1          EFI/BOOT/BOOTX64.efi    # renamed U-Boot EFI image
+ 1          Image                   # Linux image
+ 1          Initrd                  # Initramfs of Linux
+
+**EFI/BOOT/BOOTX64.efi** is a renamed build result **u-boot-payload.efi**, built with
+**efi-x86_payload64_defconfig** configuration.
+
+Boot script
+~~~~~~~~~~~
+
+The boot script **boot.scr** is assumed to be located at::
+
+ Partition  File        Comment
+ 1          boot.scr    # Boot script, generated with mkimage from template
+
+Content of **boot.scr**:
+
+.. code-block:: bash
+
+  ext4load ${devtype} ${devnum}:${distro_bootpart} ${kernel_addr_r} ${prefix}Image
+  setenv kernel_size ${filesize}
+  ext4load ${devtype} ${devnum}:${distro_bootpart} ${ramdisk_addr_r} ${prefix}Initrd
+  setenv initrd_size ${filesize}
+  zboot  ${kernel_addr_r} ${kernel_size} ${ramdisk_addr_r} ${initrd_size}
+
+Extlinux configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively a configuration **extlinux.conf** can be used. **extlinux.conf**
+is assumed to be located at::
+
+ Partition  File                        Comment
+ 1          extlinux/extlinux.conf      # Extlinux boot configuration
+
+Content of **extlinux.conf**:
+
+.. code-block:: bash
+
+  default l0
+  menu title U-Boot menu
+  prompt 0
+  timeout 50
+
+  label l0
+    menu label Linux
+    linux /Image
+    initrd /Initrd
+
+
+Additionally something like (sda is assumed as disk device):
+
+.. code-block:: bash
+
+	append  root=/dev/sda2 console=tty0 console=ttyS0,115200n8 rootwait rw
+
+
 
 Future work
 -----------
diff --git a/doc/learn/talks.rst b/doc/learn/talks.rst
index 33bac483e17..0bb44aeabe5 100644
--- a/doc/learn/talks.rst
+++ b/doc/learn/talks.rst
@@ -3,9 +3,18 @@
 U-Boot Talks
 ============
 
-U-Boot is a topic at various conferences each year. These talkes might help you
-learn a bit about U-Boot.
+U-Boot is a topic at various conferences each year. These talks might help you
+learn a bit about U-Boot:
 
-See elinux_talks_ for a list.
+* `Tutorial: Introduction to the Embedded Boot Loader U-boot - Behan Webster,
+  Converse in Code <https://www.youtube.com/watch?v=INWghYZH3hI>`__
+  from Embedded Linux Conference 2020
+  (`slides <https://cm.e-ale.org/2020/ELC2020/intro-to-u-boot/intro-to-u-boot-2020.pdf>`__).
+
+* `Recent Advances in U-Boot - Simon Glass, Google Inc.
+  <https://www.youtube.com/watch?v=YlJBsVZJkDI>`__
+  from Embedded Linux Conference 2023.
+
+See elinux_talks_ for a more comprehensive list.
 
 .. _elinux_talks: https://elinux.org/Boot_Loaders#U-Boot
diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt
index 4f411f78d03..6ccbe527ee7 100644
--- a/doc/sphinx/requirements.txt
+++ b/doc/sphinx/requirements.txt
@@ -15,6 +15,7 @@ requests==2.31.0
 six==1.16.0
 snowballstemmer==2.2.0
 Sphinx==3.4.3
+sphinx-prompt==1.5.0
 sphinx-rtd-theme==1.0.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
diff --git a/doc/usage/cmd/gpt.rst b/doc/usage/cmd/gpt.rst
new file mode 100644
index 00000000000..6387c8116fe
--- /dev/null
+++ b/doc/usage/cmd/gpt.rst
@@ -0,0 +1,184 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+gpt command
+===========
+
+Synopsis
+--------
+
+::
+
+    gpt enumerate <interface> <dev>
+    gpt guid <interface> <dev> [<varname>]
+    gpt read <interface> <dev> [<varname>]
+    gpt rename <interface> <dev> <part> <name>
+    gpt repair <interface> <dev>
+    gpt setenv <interface> <dev> <partition name>
+    gpt swap <interface> <dev> <name1> <name2>
+    gpt verify <interface> <dev> [<partition string>]
+    gpt write <interface> <dev> <partition string>
+
+Description
+-----------
+
+The gpt command lets users read, create, modify, or verify the GPT (GUID
+Partition Table) partition layout.
+
+Common arguments:
+
+interface
+    interface for accessing the block device (mmc, sata, scsi, usb, ....)
+
+dev
+    device number
+
+partition string
+    Describes the GPT partition layout for a disk.  The syntax is similar to
+    the one used by the :doc:`mbr command <mbr>` command. The string contains
+    one or more partition descriptors, each separated by a ";". Each descriptor
+    contains one or more fields, with each field separated by a ",". Fields are
+    either of the form "key=value" to set a specific value, or simple "flag" to
+    set a boolean flag
+
+    The first descriptor can optionally be used to describe parameters for the
+    whole disk with the following fields:
+
+    * uuid_disk=UUID - Set the UUID for the disk
+
+    Partition descriptors can have the following fields:
+
+    * name=<NAME> - The partition name, required
+    * start=<BYTES> - The partition start offset in bytes, required
+    * size=<BYTES> - The partition size in bytes or "-" to expand it to the whole free area
+    * bootable - Set the legacy bootable flag
+    * uuid=<UUID> - The partition UUID, optional if CONFIG_RANDOM_UUID=y is enabled
+    * type=<UUID> - The partition type GUID, requires CONFIG_PARTITION_TYPE_GUID=y
+
+
+    If 'uuid' is not specified, but CONFIG_RANDOM_UUID is enabled, a random UUID
+    will be generated for the partition
+
+gpt enumerate
+~~~~~~~~~~~~~
+
+Sets the variable 'gpt_partition_list' to be a list of all the partition names
+on the device.
+
+gpt guid
+~~~~~~~~
+
+Report the GUID of a disk. If 'varname' is specified, the command will set the
+variable to the GUID, otherwise it will be printed out.
+
+gpt read
+~~~~~~~~
+
+Prints the current state of the GPT partition table. If 'varname' is specified,
+the variable will be filled with a partition string in the same format as a
+'<partition string>', suitable for passing to other 'gpt' commands.  If the
+argument is omitted, a human readable description is printed out.
+CONFIG_CMD_GPT_RENAME=y is required.
+
+gpt rename
+~~~~~~~~~~
+
+Renames all partitions named 'part' to be 'name'. CONFIG_CMD_GPT_RENAME=y is
+required.
+
+gpt repair
+~~~~~~~~~~
+
+Repairs the GPT partition tables if it they become corrupted.
+
+gpt setenv
+~~~~~~~~~~
+
+The 'gpt setenv' command will set a series of environment variables with
+information about the partition named '<partition name>'. The variables are:
+
+gpt_partition_addr
+    the starting offset of the partition in blocks as a hexadecimal number
+
+gpt_partition_size
+    the size of the partition in blocks as a hexadecimal number
+
+gpt_partition_name
+    the name of the partition
+
+gpt_partition_entry
+    the partition number in the table, e.g. 1, 2, 3, etc.
+
+gpt swap
+~~~~~~~~
+
+Changes the names of all partitions that are named 'name1' to be 'name2', and
+all partitions named 'name2' to be 'name1'. CONFIG_CMD_GPT_RENAME=y is
+required.
+
+gpt verify
+~~~~~~~~~~
+
+Sets return value $? to 0 (true) if the partition layout on the
+specified disk matches the one in the provided partition string, and 1 (false)
+if it does not match. If no partition string is specified, the command will
+check if the disk is partitioned or not.
+
+gpt write
+~~~~~~~~~
+
+(Re)writes the partition table on the disk to match the provided
+partition string. It returns 0 on success or 1 on failure.
+
+Configuration
+-------------
+
+To use the 'gpt' command you must specify CONFIG_CMD_GPT=y. To enable 'gpt
+read', 'gpt swap' and 'gpt rename', you must specify CONFIG_CMD_GPT_RENAME=y.
+
+Examples
+~~~~~~~~
+Create 6 partitions on a disk::
+
+    => setenv gpt_parts 'uuid_disk=bec9fc2a-86c1-483d-8a0e-0109732277d7;
+        name=boot,start=4M,size=128M,bootable,type=ebd0a0a2-b9e5-4433-87c0-68b6b72699c7,
+        name=rootfs,size=3072M,type=0fc63daf-8483-4772-8e79-3d69d8477de4;
+        name=system-data,size=512M,type=0fc63daf-8483-4772-8e79-3d69d8477de4;
+        name=[ext],size=-,type=0fc63daf-8483-4772-8e79-3d69d8477de4;
+        name=user,size=-,type=0fc63daf-8483-4772-8e79-3d69d8477de4;
+        name=modules,size=100M,type=0fc63daf-8483-4772-8e79-3d69d8477de4;
+        name=ramdisk,size=8M,type=0fc63daf-8483-4772-8e79-3d69d8477de4
+    => gpt write mmc 0 $gpt_parts
+
+
+Verify that the device matches the partition layout described in the variable
+$gpt_parts::
+
+    => gpt verify mmc 0 $gpt_parts
+
+
+Get the information about the partition named 'rootfs'::
+
+    => gpt setenv mmc 0 rootfs
+    => echo ${gpt_partition_addr}
+    2000
+    => echo ${gpt_partition_size}
+    14a000
+    => echo ${gpt_partition_name}
+    rootfs
+    => echo ${gpt_partition_entry}
+    2
+
+Get the list of partition names on the disk::
+
+    => gpt enumerate
+    => echo gpt_partition_list
+    boot rootfs system-data [ext] user modules ramdisk
+
+
+Get the GUID for a disk::
+
+    => gpt guid mmc 0
+    bec9fc2a-86c1-483d-8a0e-0109732277d7
+    => gpt guid mmc gpt_disk_uuid
+    => echo ${gpt_disk_uuid}
+    bec9fc2a-86c1-483d-8a0e-0109732277d7
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 3326ec82fff..fa702920faa 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -4,6 +4,7 @@ Use U-Boot
 .. toctree::
    :maxdepth: 1
 
+   spl_boot
    blkmap
    dfu
    environment
@@ -65,6 +66,7 @@ Shell commands
    cmd/for
    cmd/fwu_mdata
    cmd/gpio
+   cmd/gpt
    cmd/host
    cmd/imxtract
    cmd/load
diff --git a/doc/usage/spl_boot.rst b/doc/usage/spl_boot.rst
new file mode 100644
index 00000000000..93419f158af
--- /dev/null
+++ b/doc/usage/spl_boot.rst
@@ -0,0 +1,321 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Booting from TPL/SPL
+====================
+
+The main U-Boot binary may be too large to be loaded directly by the Boot ROM.
+This was the original driver for splitting up U-Boot into multiple boot stages.
+
+U-Boot typically goes through the following boot phases where TPL, VPL, and SPL
+are optional. While many boards use SPL only few use TPL.
+
+TPL
+   Tertiary Program Loader. Very early init, as tiny as possible. This loads SPL
+   (or VPL if enabled).
+
+VPL
+   Verifying Program Loader. Optional verification step, which can select one of
+   several SPL binaries, if A/B verified boot is enabled. Implementation of the
+   VPL logic is work-in-progress. For now it just boots into SPL.
+
+SPL
+   Secondary Program Loader. Sets up SDRAM and loads U-Boot proper. It may also
+   load other firmware components.
+
+U-Boot
+   U-Boot proper. This is the only stage containing command. It also implements
+   logic to load an operating system, e.g. via UEFI.
+
+.. note::
+
+   The naming convention on the PowerPC architecture deviates from the other
+   archtitectures. Here the boot sequence is SPL->TPL->U-Boot.
+
+Further usages for U-Boot SPL comprise:
+
+* launching BL31 of ARM Trusted Firmware which invokes U-Boot as BL33
+* launching EDK II
+* launching Linux, e.g. :doc:`Falcon Mode <../develop/falcon>`
+* launching RISC-V OpenSBI which invokes main U-Boot
+
+Target binaries
+---------------
+
+Binaries loaded by SPL/TPL can be:
+
+* raw binaries where the entry address equals the start address. This is the
+  only binary format supported by TPL.
+* :doc:`FIT <fit/index>` images
+* legacy U-Boot images
+
+Configuration
+~~~~~~~~~~~~~
+
+Raw images are only supported in SPL if CONFIG_SPL_RAW_IMAGE_SUPPORT=y.
+
+CONFIG_SPL_FIT=y and CONFIG_SPL_LOAD_FIT=y are needed to load FIT images.
+
+CONFIG_SPL_LEGACY_IMAGE_FORMAT=y is needed to load legacy U-Boot images.
+CONFIG_SPL_LEGACY_IMAGE_CRC_CHECK=y enables checking the CRC32 of legacy U-Boot
+images.
+
+Image load methods
+------------------
+
+The image boot methods available for a board must be defined in two places:
+
+The board code implements a function board_boot_order() enumerating up to
+five boot methods and the sequence in which they are tried. (The maximum
+number of boot methods is currently hard coded as variable spl_boot_list[]).
+If there is only one boot method function, spl_boot_device() may be implemented
+instead.
+
+The configuration controls which of these boot methods are actually available.
+
+Loading from block devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MMC1, MMC2, MMC2_2
+    These methods read an image from SD card or eMMC. The first digit after
+    'MMC' indicates the device number. Required configuration settings include:
+
+    * CONFIG_SPL_MMC=y or CONFIG_TPL_MMC=y
+
+    To use a PCI connected MMC controller you need to additionally specify:
+
+    * CONFIG_SPL_PCI=y
+
+    * CONFIG_SPL_PCI_PNP=y
+
+    * CONFIG_MMC=y
+
+    * CONFIG_MMC_PCI=y
+
+    * CONFIG_MMC_SDHCI=y
+
+    To load from a file system use:
+
+    * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y
+
+    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>"
+
+NVMe
+    This methods load the image from an NVMe drive.
+    Required configuration settings include:
+
+    * CONFIG_SPL_PCI=y
+
+    * CONFIG_SPL_PCI_PNP=y
+
+    * CONFIG_SPL_NVME=y
+
+    * CONFIG_SPL_NVME_PCI=y
+
+    * CONFIG_SPL_NVME_BOOT_DEVICE (number of the NVMe device)
+
+    * CONFIG_SYS_NVME_BOOT_PARTITION (partition to read from)
+
+    To load from a file system use:
+
+    * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y
+
+    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>"
+
+SATA
+    This method reads an image from a SATA drive.
+    Required configuration settings include:
+
+    * CONFIG_SPL_SATA=y or CONFIG_TPL_SATA=y
+
+    To use a PCIe connecte SATA controller you additionally need:
+
+    * CONFIG_SPL_PCI=y
+
+    * CONFIG_SPL_SATA=y
+
+    * CONFIG_SPL_AHCI_PCI=y
+
+    * CONFIG_SPL_PCI_PNP=y
+
+    To load from a file system use:
+
+    * CONFIG_SPL_FS_FAT=y
+
+    * CONFIG_SYS_SATA_FAT_BOOT_PARTITION=<partition number>
+
+    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>"
+
+USB
+    The USB method loads an image from a USB block device.
+    Required configuration settings include:
+
+    * CONFIG_SPL_USB_HOST=y
+
+    * CONFIG_SPL_USB_STORAGE=y
+
+    To use a PCI connected USB 3.0 controller you additionally need:
+
+    * CONFIG_SPL_FS_FAT=y
+
+    * CONFIG_SPL_PCI=y
+
+    * CONFIG_SPL_PCI_PNP=y
+
+    * CONFIG_USB=y
+
+    * CONFIG_USB_XHCI_HCD=y
+
+    * CONFIG_USB_XHCI_PCI=y
+
+    To load from a file system use:
+
+    * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y
+
+    * CONFIG_SYS_USB_FAT_BOOT_PARTITION=<partition number>
+
+    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>"
+
+Loading from raw flash devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+NAND
+    This method loads the image from NAND flash. To read from raw NAND the
+    following configuration settings are required:
+
+    * CONFIG_SPL_NAND_SUPPORT=y or CONFIG_TPL_NAND_SUPPORT=y
+
+    If CONFIG_SPL_NAND_RAW_ONLY=y only raw images can be loaded.
+
+    For using UBI (Unsorted Block Images) volumes to read from NAND the
+    following configuration settings are required:
+
+    * CONFIG_SPL_UBI=y or CONFIG_TPL_UBI=y
+
+    The UBI volume to read can either be specified
+
+    * by name using CONFIG_SPL_UBI_LOAD_BY_VOLNAME or
+
+    * by number using CONFIG_SPL_UBI_LOAD_MONITOR_ID.
+
+NOR
+    This method loads the image from NOR flash.
+    Required configuration settings include:
+
+    * CONFIG_SPL_NOR_SUPPORT=y or CONFIG_TPL_NOR_SUPPORT=y
+
+OneNAND
+    This methods loads the image from a OneNAND device. To read from raw OneNAND
+    the following configuration settings are required:
+
+    * CONFIG_SPL_ONENAND_SUPPORT=y or CONFIG_TPL_ONENAND_SUPPORT=y
+
+    For using the Ubi file system to read from NAND the following configuration
+    settings are required:
+
+    * CONFIG_SPL_UBI=y or CONFIG_TPL_UBI=y
+
+SPI
+    This method loads an image form SPI NOR flash.
+    Required configuration settings include:
+
+    * CONFIG_SPL_DM_SPI=y
+
+    * CONFIG_SPL_SPI_FLASH=y
+
+    * CONFIG_SPI_LOAD=y or CONFIG_TPL_SPI_LOAD=y
+
+
+Sunxi SPI
+    This method which is specific to Allwinner SoCs loads an image form SPI NOR
+    flash. Required configuration settings include:
+
+    * CONFIG_SPL_SPI_SUNXI=y
+
+Loading from other devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+BOOTROM
+    The binary is loaded by the boot ROM.
+    Required configuration settings include:
+
+    * CONFIG_SPL_BOOTROM_SUPPORT=y or CONFIG_TPL_BOOTROM_SUPPORT=y
+
+DFU
+    :doc:`Device Firmware Upgrade <dfu>` is used to load the binary into RAM.
+    Required configuration settings include:
+
+    * CONFIG_DFU=y
+
+    * CONFIG_SPL_RAM_SUPPORT=y or CONFIG TPL_RAM_SUPPORT=y
+
+Ethernet
+    This method loads an image over Ethernet. The BOOTP protocol is used to find
+    a TFTP server and binary name. The binary is downloaded via the TFTP
+    protocol. Required configuration settings include:
+
+    * CONFIG_SPL_NET=y or CONFIG_TPL_NET=y
+
+    * CONFIG_SPL_ETH_DEVICE=y or CONFIG_DM_USB_GADGET=y
+
+FEL
+    This method does not actually load an image for U-Boot.
+    FEL is a routine contained in the boot ROM of Allwinner SoCs which serves
+    for the initial programming or recovery via USB
+
+RAM
+    This method uses an image preloaded into RAM.
+    Required configuration settings include:
+
+    * CONFIG_SPL_RAM_SUPPORT=y or CONFIG_TPL_RAM_SUPPORT=y
+
+    * CONFIG_RAM_DEVICE=y
+
+Sandbox file
+    On the sandbox this method loads an image from the host file system.
+
+Sandbox image
+    On the sandbox this method loads an image from the host file system.
+
+Semihosting
+    When running in an ARM or RISC-V virtual machine the semihosting method can
+    be used to load an image from the host file system.
+    Required configuration settings include:
+
+    * CONFIG_SPL_SEMIHOSTING=y
+
+    * CONFIG_SPL_SEMIHOSTING_FALLBACK=y
+
+    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME=<path to file>
+
+UART
+    This method loads an image via the Y-Modem protocol from the UART.
+    Required configuration settings include:
+
+    * CONFIG_SPL_YMODEM_SUPPORT=y or CONFIG_TPL_YMODEM_SUPPORT=y
+
+USB SDP
+    This method loads the image using the Serial Download Protocol as
+    implemented by the boot ROM of the i.MX family of SoCs.
+
+    Required configuration settings include:
+
+    * CONFIG_SPL_SERIAL=y
+
+    * CONFIG_SPL_USB_SDP_SUPPORT=y or CONFIG_TPL_USB_SDP_SUPPORT
+
+VBE Simple
+    This method is used by the VPL stage to extract the next stage image from
+    the loaded image.
+
+    Required configuration settings include:
+
+    * CONFIG_VPL=y
+
+    * CONFIG_SPL_BOOTMETH_VBE_SIMPLE_FW=y or CONFIG_TPL_BOOTMETH_VBE_SIMPLE_FW=y
+
+XIP
+    This method executes an image in place.
+
+    Required configuration settings include:
+
+    * CONFIG_SPL_XIP_SUPPORT