Merge tag 'v2023.10-rc4' into next

Prepare v2023.10-rc4

12 files changed, 220 insertions, 134 deletions

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.