Merge tag 'efi-2026-04-rc1-2' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request efi-2026-04-rc1-2

CI: https://source.denx.de/u-boot/custodians/u-boot-efi/-/pipelines/29050

Documentation:

* Update StarFive JH7110 common description
* Add TI AM62D documentation
* Update urllib3 version for building
* Update links to doc/develop/falcon.rst
* Describe QEMU networking
* kdoc: handle the obsolescensce of docutils.ErrorString()
* Fix typo "addtional" -> "additional" in pflash section.

UEFI:

* Fix boot failure from FIT with compressed EFI binary

Others:

* cmd/meminfo: Correct displaying addresses above 4 GiB
* test:
  - Consider configuration in meminfo test
  - Consider initf_malloc is only traced with EARLY_TRACE
  - Clean up test_trace.py code

23 files changed, 1019 insertions, 758 deletions

diff --git a/boot/bootm_os.c b/boot/bootm_os.c
index 88f7c183867..ae20b555f5c 100644
--- a/boot/bootm_os.c
+++ b/boot/bootm_os.c
@@ -509,11 +509,11 @@ static int do_bootm_efi(int flag, struct bootm_info *bmi)
 	/* We expect to return */
 	images->os.type = IH_TYPE_STANDALONE;
 
-	image_buf = map_sysmem(images->os.image_start, images->os.image_len);
+	image_buf = map_sysmem(images->os.load, images->os.image_len);
 
 	/* Run EFI image */
 	printf("## Transferring control to EFI (at address %08lx) ...\n",
-	       images->os.image_start);
+	       images->os.load);
 	bootstage_mark(BOOTSTAGE_ID_RUN_OS);
 
 	ret = efi_binary_run(image_buf, images->os.image_len,
diff --git a/cmd/Kconfig b/cmd/Kconfig
index 595ac49da41..20df068d55c 100644
--- a/cmd/Kconfig
+++ b/cmd/Kconfig
@@ -620,7 +620,7 @@ config CMD_SPL
 	help
 	  Falcon mode allows booting directly from SPL into an Operating
 	  System such as Linux, thus skipping U-Boot proper. See
-	  doc/README.falcon for full information about how to use this
+	  doc/develop/falcon.rst for full information about how to use this
 	  command.
 
 config CMD_SPL_NAND_OFS
@@ -629,7 +629,7 @@ config CMD_SPL_NAND_OFS
 	default 0x0
 	help
 	  This provides the offset of the command line arguments for Linux
-	  when booting from NAND in Falcon mode.  See doc/README.falcon
+	  when booting from NAND in Falcon mode.  See doc/develop/falcon.rst
 	  for full information about how to use this option (and also see
 	  board/gateworks/gw_ventana/README for an example).
 
diff --git a/cmd/meminfo.c b/cmd/meminfo.c
index aa3b5bafe17..b731280d106 100644
--- a/cmd/meminfo.c
+++ b/cmd/meminfo.c
@@ -23,9 +23,9 @@ static void print_region(const char *name, ulong base, ulong size, ulong *uptop)
 {
 	ulong end = base + size;
 
-	printf("%-12s %8lx %8lx %8lx", name, base, size, end);
+	printf("%-12s %13lx %13lx %13lx", name, base, size, end);
 	if (*uptop)
-		printf(" %8lx", *uptop - end);
+		printf(" %13lx", *uptop - end);
 	putc('\n');
 	*uptop = base;
 }
@@ -64,9 +64,9 @@ static int do_meminfo(struct cmd_tbl *cmdtp, int flag, int argc,
 
 	arch_dump_mem_attrs();
 
-	printf("\n%-12s %8s %8s %8s %8s\n", "Region", "Base", "Size", "End",
+	printf("\n%-12s %13s %13s %13s %13s\n", "Region", "Base", "Size", "End",
 	       "Gap");
-	printf("------------------------------------------------\n");
+	printf("--------------------------------------------------------------------\n");
 	upto = 0;
 	if (IS_ENABLED(CONFIG_VIDEO))
 		print_region("video", gd_video_bottom(),
diff --git a/common/spl/Kconfig b/common/spl/Kconfig
index c7db88345b4..e456d02dc8b 100644
--- a/common/spl/Kconfig
+++ b/common/spl/Kconfig
@@ -1211,7 +1211,7 @@ config SPL_OS_BOOT
 	depends on ARM || MICROBLAZE || PPC
 	help
 	  Enable booting directly to an OS from SPL.
-	  for more info read doc/README.falcon
+	  for more info read doc/develop/falcon.rst
 
 config SPL_OS_BOOT_SECURE
 	bool "Allow Falcon Mode on secure devices"
diff --git a/doc/board/emulation/index.rst b/doc/board/emulation/index.rst
index f8908166276..896f44c8087 100644
--- a/doc/board/emulation/index.rst
+++ b/doc/board/emulation/index.rst
@@ -8,6 +8,7 @@ Emulation
 
    acpi
    blkdev
+   network
    qemu-arm
    qemu-mips
    qemu-ppce500
diff --git a/doc/board/emulation/network.rst b/doc/board/emulation/network.rst
new file mode 100644
index 00000000000..e997265c297
--- /dev/null
+++ b/doc/board/emulation/network.rst
@@ -0,0 +1,152 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Emulation of network devices
+============================
+
+Networking types
+----------------
+
+QEMU can emulate different types of networks:
+
+User networking
+'''''''''''''''
+
+User networking is the easiest to use. QEMU provides NAT translation and a DHCP
+server.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0 \
+    -device virtio-net,netdev=eth0
+
+Port forwarding
+~~~~~~~~~~~~~~~
+
+The emulated device can access the outside network but cannot be reached from
+outside by default. Forwarding rules can be added.
+
+In the example the SSH port 22 of the default interface of the emulated device
+is forwarded to port 2222 of the loopback interface of the host.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0,hostfwd=tcp:127.0.0.1:2222-:22 \
+    -device virtio-net,netdev=eth0
+
+TFTP
+~~~~
+
+A TFTP server can be added by specifying a file path.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0,tftp=/path/to/tftpdir \
+    -device virtio-net,netdev=eth0
+
+Bridge networking
+'''''''''''''''''
+
+The emulated NIC is connected to an existing bridge device.
+
+.. code-block:: bash
+
+    -netdev bridge,id=eth0,br=virbr0 \
+    -device virtio-net,netdev=eth0
+
+The emulated device becomes part of the same local network as the bridge.
+
+Tap networking
+''''''''''''''
+
+With tap networking a tap device is created on the host.
+
+.. code-block:: bash
+
+    -netdev tap,id=eth0 \
+    -device virtio-net,netdev=eth0
+
+Emulated network interface controllers
+--------------------------------------
+
+QEMU can emulate different NICs. For best performance choose ``virtio-net``.
+
+Intel E1000
+'''''''''''
+
+U-Boot's E1000 driver supports a number of Intel PCI NICs. This includes the
+QEMU devices ``e1000``, ``e1000-82544gc``, and ``e1000-82545em``.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0 \
+    -device e1000,netdev=eth0
+
+Configuration:
+
+* CONFIG_PCI=y
+* CONFIG_E1000=y
+
+Realtek RTL8139
+'''''''''''''''
+
+The RTL8139 is a PCI network card.
+The U-Boot driver only supports the i386 archtitecture.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0 \
+    -device rtl8139,netdev=eth0
+
+Configuration:
+
+* CONFIG_PCI=y
+* CONFIG_NET_RANDOM_ETHADDR=y
+* CONFIG_RTL8139
+
+Virtio
+''''''
+
+U-Boot's virtio network driver supports ``virtio-net``, ``virtio-net-device``,
+and ``virtio-net-pci`` devices. ``virtio-net-device`` uses MMIO, while
+``virtio-net-pci`` uses PCI.
+
+For best performance use ``virtio-net``.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0 \
+    -device virtio-net,netdev=eth0
+
+Configuration:
+
+* CONFIG_PCI=y (only for ``virtio-net-pci``)
+* CONFIG_NET_VIRTIO=y
+
+Network device options
+----------------------
+
+The network adapters provide different configuration parameters.
+Here are some common ones.
+
+mac
+    set MAC address
+
+    .. code-block:: bash
+
+        -netdev user,id=eth0 \
+        -device virtio-net-pci,netdev=eth0,mac=00:00:00:00:01:01
+
+romfile
+    provide the ROM file of the NIC
+
+    .. code-block:: bash
+
+        -netdev user,id=eth0 \
+        -device virtio-net-pci,netdev=eth0,romfile=pxe-virtio.rom
+
+    or provide none
+
+    .. code-block:: bash
+
+        -netdev user,id=eth0 \
+        -device virtio-net-pci,netdev=eth0,romfile=
diff --git a/doc/board/emulation/qemu-riscv.rst b/doc/board/emulation/qemu-riscv.rst
index b5948d9affc..229a7700ac7 100644
--- a/doc/board/emulation/qemu-riscv.rst
+++ b/doc/board/emulation/qemu-riscv.rst
@@ -43,7 +43,7 @@ qemu-riscv64_smode_defconfig instead. Note that U-Boot running in supervisor
 mode requires a supervisor binary interface (SBI), such as RISC-V OpenSBI.
 
 To create a U-Boot binary that can be utilized with a pflash device in QEMU
-apply these addtional settings to qemu-riscv64_smode_defconfig:
+apply these additional settings to qemu-riscv64_smode_defconfig:
 
 ::
 
diff --git a/doc/board/starfive/deepcomputing_fml13v01.rst b/doc/board/starfive/deepcomputing_fml13v01.rst
index 5d9612483b4..9777f4c6303 100644
--- a/doc/board/starfive/deepcomputing_fml13v01.rst
+++ b/doc/board/starfive/deepcomputing_fml13v01.rst
@@ -9,38 +9,6 @@ The DeepComputing Framework motherboard (FLM13V01) can be combined with a
 U-Boot for the board uses the same binaries as the VisionFive 2 board.
 Currently only serial console output is supported by mainline U-Boot.
 
-Building
---------
-
-Setup the cross compilation environment variable:
-
-.. code-block:: bash
-
-   export CROSS_COMPILE=riscv64-linux-gnu-
-
-The M-mode software OpenSBI provides the supervisor binary interface (SBI) and
-is responsible for the switch to S-Mode. It is a prerequisite for building
-U-Boot. Support for the JH7110 was introduced in OpenSBI 1.2. It is recommended
-to use a current release.
-
-.. code-block:: bash
-
-    git clone https://github.com/riscv/opensbi.git
-    cd opensbi
-    make PLATFORM=generic FW_TEXT_START=0x40000000 FW_OPTIONS=0
-    export OPENSBI="$(pwd)/build/platform/generic/firmware/fw_dynamic.bin"
-
-Now build U-Boot SPL and main U-Boot.
-
-.. code-block:: bash
-
-    cd <U-Boot-dir>
-    make starfive_visionfive2_defconfig
-    make
-
-This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well
-as the FIT image (u-boot.itb) with OpenSBI, U-Boot, and device-trees.
-
 Device-tree selection
 ---------------------
 
diff --git a/doc/board/starfive/jh7110_common.rst b/doc/board/starfive/jh7110_common.rst
index 4a8058ee5da..77102fcc189 100644
--- a/doc/board/starfive/jh7110_common.rst
+++ b/doc/board/starfive/jh7110_common.rst
@@ -1,103 +1,562 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
+.. |arrowin| unicode:: U+2190
+.. |arrowout| unicode:: U+2192
+.. |degreecelsius| unicode:: U+2103
+.. _U74-MC Core Complex: https://www.starfivetech.com/uploads/u74mc_core_complex_manual_21G1.pdf
+.. _JH-7110 Technical Reference Manual: https://doc-en.rvspace.org/JH7110/TRM/
+.. _JH-7110 Boot User Guide BootROM: https://doc-en.rvspace.org/VisionFive2/Boot_UG/JH7110_SDK/bootrom.html
+.. _JH-7110 Datasheet: https://doc-en.rvspace.org/JH7110/PDF/JH7110_DS.pdf
+.. _JH-7110I Datasheet: https://doc-en.rvspace.org/JH7110/PDF/JH7110I_DS.pdf
+.. _Description of StarFive loader: https://lore.kernel.org/u-boot/ZQ2PR01MB1307E9F46803F18B2B9D5394E6C22@ZQ2PR01MB1307.CHNPR01.prod.partner.outlook.cn/
+.. _SYS SYSCON: https://doc-en.rvspace.org/JH7110/TRM/JH7110_TRM/sys_syscon.html
 
-Boot source selection
----------------------
+StarFive JH-7110 RISC-V SoC
+---------------------------
 
-The board provides DIP switches to select the device for loading the boot
-firmware.
+* JH-7110 working frequency 1.5GHz
+  ambient operating temperature range -20 |degreecelsius| to +85 |degreecelsius|
+  (`JH-7110 Datasheet`_)
 
-=========== === ===
-Boot source SW1 SW2
-=========== === ===
-UART        OFF OFF
-SD-card     ON  OFF
-eMMC        OFF ON
-SPI flash   ON  ON
-=========== === ===
+* JH-7110I working frequency 1.5GHz
+  ambient operating temperature range -40 |degreecelsius| to +85 |degreecelsius|
+  (`JH-7110I Datasheet`_)
 
-Flashing a new U-Boot version
------------------------------
+* JH-7110S working frequency 1.25GHz
 
-U-Boot SPL is provided as file spl/u-boot-spl.bin.normal.out. Main U-Boot is
-in file u-boot.itb.
+JH-7110 is a 4+1 core RISC-V System on Chip:
 
-Assuming your new U-Boot version is on partition 1 of an SD-card you could
-install it to the SPI flash with:
+* `U74-MC Core Complex`_
 
-.. code-block:: console
+  * S7 monitor core RV64IMAC
+
+    * Physical Memory Protection
+    * 16KB L1 Instruction cache
+    * 8KB Data Tightly-Integrated Memory
+
+  * U74 application core RV64GC (x4)
+
+    * Sv39 Memory Management Unit
+    * Floating Point Unit
+    * 32KB L1 Instruction cache
+    * 32KB L1 Data cache
+    * Physical Memory Protection
+
+  * Core-Local INTerruptor
+  * Platform-Level Interrupt Controller
+  * Debug
+  * Bus Matrix
+
+    * 2MB L2 cache
+
+      * Memory Port |arrowout| 128-bit AXI4
+
+    * System Port |arrowout| 64-bit AXI4
+    * Peripheral Port |arrowout| 64-bit AXI4
+    * Front Port |arrowin| 64-bit AXI4
+
+* Block
+
+  * RV32IMAFCB E24 co-processor
+
+    * 16KB Instruction cache
+    * 32KB Tightly-Integrated Memory "A"
+    * 32KB Tightly-Integrated Memory "B"
+
+  * Mailbox
+  * SGDMA
+
+* Network-on-Chip/AXI bus
+* Memory
+
+  * SRAM 256KB/BootROM 32KB
+  * LPDDR4/DDR4/LPDDR3/DDR3 32-bit 2800 Mbps (2133 Mbps supported working speed)
+  * QSPI Flash Controller
+
+* Interfaces
+
+  * PCIe2.0 1-lane x2
+  * Ethernet MAC 10/100/1000 Mbps x2
+  * USB 2.0 Host/Device
+  * SDIO3.0 x2
+  * CAN2.0B x2
+
+* Audio
+
+  * Cadence Tensilica HiFi-4 Audio DSP defined by U74MC or E24
+
+    * 4x 32x32-bit MACs
+    * some 72-bit accumulators
+    * limited support for 8x 32x16-bit MACs
+    * fourth VLIW slot
+    * two 64-bit loads per cycle
+    * optional floating point unit for four single-precision MACs per cycle
+
+  * I2S/PCM-TDM
+  * I2S/PCM
+  * PDM x4
+  * SPDIF
+
+* Graphics
+
+  * Epicsemi ISP
+  * IMG BXE-4-32 Integrated GPU with 3D Acceleration
+  * 12-bit DVP
+  * MIPI-CSI
+
+* Cryptographic function
+
+  * TRNG
+  * OTP
+  * Security HW Engine AES/DES/3DES/HASH/PKA
+
+* Block
+
+  * PAD_SHARE used for reset
+  * Power Management Unit Clock Reset Generator
+  * PLL x3
+  * JTAG
+  * RTC
+  * Temperature Sensor
+
+Supported SoC drivers:
+
+* ns16550 UART
+* StarFive JH-7110 clock
+* StarFive JH-7110 reset
+* Cadence QSPI controller
+* DesignWare MMC for eMMC/SD support
+* PLDA PCIe controller
+* Cadence USB2.0/3.0 controller
+
+Supported common peripherals:
+
+* AXP15060 Power Management Unit
+* LPDDR4 2GB / 4GB / 8GB DRAM memory
+* AT24C04F 4K bits (512 x 8) EEPROM
+* QSPI NOR Flash 16M or SoC ROM UART loader for boot (selectable by GPIO)
+
+Extra supported peripherals present on some boards:
+
+* Motorcomm YT8531C Gigabit Ethernet PHY
+* On-board VL805 PCIE-USB controller driver
+* Status LED RGPIO3
+
+Build U-Boot
+------------
+
+1.  Add a RISC-V toolchain to your PATH.
+2.  Set cross compilation environment variable if needed:
+
+    .. code-block:: none
+
+       export CROSS_COMPILE=<riscv64 toolchain prefix>
+
+3.  U-Boot for JH-7110 requires OpenSBI v1.5+ generic platform object
+    fw_dynamic.bin to be included in the Flattened Image Tree blob. OpenSBI may
+    first be built as below:
+
+    .. code-block:: console
+
+       # clone and/or update OpenSBI sources
+       git clone https://github.com/riscv/opensbi.git opensbi.git
+       git -C opensbi.git checkout v1.7
+       # always clean build directory when building OpenSBI due to incomplete
+       # dependency tracking
+       make -C opensbi.git -O opensbi clean
+       make -C opensbi.git -O opensbi PLATFORM=generic
+
+4.  Now build the First Stage BootLoader (U-Boot Secondary Program Loader) and
+    Second Boot Loader (OpenSBI + U-Boot Main):
+
+    .. code-block:: console
+
+       git clone https://source.denx.de/u-boot/u-boot.git u-boot.git
+       make -C u-boot.git -O u-boot starfive_visionfive2_defconfig
+       export OPENSBI=opensbi/build/platform/generic/firmware/fw_dynamic.bin
+       make -C u-boot.git -O u-boot
+
+    This will generate the U-Boot SPL image object post-processed with StarFive
+    SPL headers (u-boot/spl/u-boot-spl.bin.normal.out) as well as the FIT image
+    (u-boot/u-boot.itb) of OpenSBI and U-Boot Main.
+
+    Note: Debug UART is not available from U-Boot SPL when U-Boot Main uses the
+    SBI interface for this. Add the following configuration changes above to
+    enable early debug UART in U-Boot SPL::
+
+        u-boot.git/scripts/config --file u-boot/.config \
+         --set-val DEBUG_UART_BASE 0x10000000 \
+         --set-val DEBUG_UART_CLOCK 24000000 \
+         --enable DEBUG_UART_NS16550 \
+         --disable DEBUG_SBI_CONSOLE \
+         --set-val SPL_DEBUG_UART_BASE 0x10000000 \
+         --set-val DEBUG_UART_SHIFT 2
+
+        make -C u-boot.git -O u-boot olddefconfig
+
+Boot description
+----------------
+
+JH-7110 reset vectors (one 36-bit address per each of four U7 cores) are located
+split into four pairs of `SYS SYSCON`_ registers. The default value for all four
+reset vectors is 2a000000.
+
+Execute-in-place BootROM code located at 2a000000 is not published by StarFive
+however may be generally described as deciding based on [RGPIO2:RGPIO0] state
+where to transfer SPL data from, verify headers and CRC, and then jump to code
+execution in L2 LIM.
+
+Zero Stage Program Loader
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+====== =========== =============
+RGPIO2 Boot Vector ZSPL function
+====== =========== =============
+0      0x2A00_0000 On-chip 32KB BootROM
+1      0x2100_0000 QSPI XIP Flash (256mb)
+====== =========== =============
+
+JH-7110 ZSPL functionally consists of the selection of reset vector register
+defaults at chip-design time in concert with BootROM code at 2a000000. `JH-7110
+Technical Reference Manual`_ says "if XIP flash is disabled in OTP
+configuration, system cannot boot from XIP flash". Presumably there is some OTP
+configuration involved but there is no documentation available with which to
+expand on that topic.
+
+Zero Stage BootLoader
+^^^^^^^^^^^^^^^^^^^^^
+
+JH-7110 ZSBL is typically StarFive loader code in BootROM selected by RGPIO2
+pull-down.
+
+====== ====== ======================================
+RGPIO1 RGPIO0 StarFive loader function @ 0x2A00_0000
+====== ====== ======================================
+0      0      1-bit QSPI Flash offset 0x0
+0      1      SDIO3.0 *(deprecated)*
+1      0      eMMC5.0 or eMMC5.1 *(deprecated)*
+1      1      UART Serial XMODEM loader
+====== ====== ======================================
+
+According to `JH-7110 Boot User Guide BootROM`_ the StarFive loader code reads
+content to SRAM @ 0x0800_0000 from different media selected by [RGPIO1,RGPIO0].
+
+`Description of StarFive loader`_ by the StarFive VisionFive2 board maintainer:
+
+    The SD card boot mode is supported but the mmc driver of BootROM is not
+    compatible with a few SD cards. If you can't boot from a SD card, you can
+    change another card for a try.
+
+    The eMMC boot mode loads SPL from sector 0, while the SD card boot mode
+    loads GPT header from sector 1 and then finds the partition whose GUID is
+    2E54B353-1271-4842-806F-E436D6AF6985 to load SPL. So if we try to use GPT
+    partition in eMMC, it will fail to boot and report CRC (stored at 0x290)
+    failure. The workaround is using the backup load address. After the CRC
+    failure happens, it will try to load the SPL from the backup address
+    (stored at 0x4~0x7). That is why we write 0x00100000 to 0x4~0x7. But this
+    workaround is not a standard process and may destroy the partition
+    information stored in sector 0.
+
+There are additional unexplained GUID references in the JH-7110 MaskROM so the
+description given is not complete. Attribution and modifications to the GPL2.0+
+source code used in StarFive loader have not been published as of this writing.
+Due to the lack of verifiable documentation the upstream Linux devicetree does
+not contain hints for mmc0 and mmc1 interfaces to be included in U-Boot SPL. As
+of U-Boot release v2025.10 and newer the U-Boot specific devicetree override of
+hints for mmc0 and mmc1 interfaces that are required for the deprecated modes
+have been dropped marking the deprecation of these boot modes in U-Boot.
+
+Supported modes in U-Boot SPL are QSPI Flash and UART Serial XMODEM loader as
+accepted by upstream Linux Kernel for StarFive JH-7110 common devicetree.
+
+First Stage BootLoader
+^^^^^^^^^^^^^^^^^^^^^^
+
+JH-7110 FSBL is typically U-Boot SPL or any vendor flash programming tool.
+
+U-Boot SPL initializes DRAM and configures PLLs needed by CPU and peripherals.
+
+====== ====== ===================
+RGPIO1 RGPIO0 U-Boot SPL function
+====== ====== ===================
+0      0      BOOT_DEVICE_SPI @ offset 0x100000 (CONFIG_ENV_OFFSET + CONFIG_ENV_SIZE)
+0      1      BOOT_DEVICE_MMC2 @ CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION
+1      0      BOOT_DEVICE_MMC1 @ CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION
+1      1      BOOT_DEVICE_UART @ YMODEM
+====== ====== ===================
+
+U-Boot SPL function is selected by configuration of [RGPIO1:RGPIO0] then copies
+data to the start of DRAM and executes.
+
+=========== ===========
+Address     Description
+=========== ===========
+0x040000000 start of DRAM
+0x240000000 uncached alias of DRAM
+=========== ===========
+
+Note: The largest DRAM size with JH7110 is 8GB because the uncached alias of
+DRAM begins at +8GB following the start of DRAM.
+
+Second Stage BootLoader (OpenSBI fw_dynamic.bin + U-Boot Main)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+U-Boot Main is supported in S-mode and depends on prior stage M-mode SBI runtime
+services provided by OpenSBI FW_DYNAMIC firmware.
+
+Loading U-Boot
+--------------
+
+Vendored versions of U-Boot (as pre-installed on supported boards) are generally
+capable in U-Boot console of UART data transfer and updating QSPI Flash.
+Additionally there may be a vendor Board Support Package using the deprecated
+SDIO3.0 / eMMC5.0 boot modes. It is not documented here how to update U-Boot in
+vendor BSP data images, nor use of the deprecated boot modes. The recommended
+upgrade path is to update QSPI Flash in U-Boot console or from GNU/Linux OS.
+
+============ ============================ ===========
+Flash offset Length                       Data source
+============ ============================ ===========
+0x000000     0x0f0000 (CONFIG_ENV_OFFSET) u-boot/spl/u-boot-spl.bin.normal.out
+0x0f0000     0x010000 (CONFIG_ENV_SIZE)   runtime generated defaults if bad CRC
+0x100000     0xf00000                     u-boot/u-boot.itb
+============ ============================ ===========
+
+Recovery U-Boot console
+^^^^^^^^^^^^^^^^^^^^^^^
+
+With UART serial USB adapter and tio serial terminal::
+
+    tio /dev/ttyUSB0 -o 1
+        tio 3.9
+        Press ctrl-t q to quit
+        Connected to /dev/ttyUSB0
+
+    # Power on the board with [RGPIO1:RGPI0]=3
+        (C)StarFive
+        CC
+        (C)StarFive
+        CCC
+
+    (Control-t-x)
+        Please enter which X modem protocol to use:
+         (0) XMODEM-1K send
+         (1) XMODEM-CRC send
+         (2) XMODEM-CRC receive
+
+    0
+        Send file with XMODEM-1K
+        Enter file name:
+
+    u-boot/spl/u-boot-spl.bin.normal.out
+        Sending file 'u-boot/spl/u-boot-spl.bin.normal.out'
+        Press any key to abort transfer
+        ...|
+        Done
+
+    # U-Boot SPL on the board with [RGPIO1:RGPI0]=3
+        U-Boot SPL 2025.10 (Oct 23 2025 - 17:01:49 -0700)
+        DDR version: dc2e84f0.
+        Trying to boot from UART
+        CCC
+
+    (Control-t-y)
+        Send file with YMODEM
+        Enter file name:
+
+    u-boot/u-boot.itb
+        Sending file 'u-boot/u-boot.itb'
+        Press any key to abort transfer
+        ...|
+        Done
+        Loaded 3122637 bytes
+
+        OpenSBI v1.7
+           ____                    _____ ____ _____
+          / __ \                  / ____|  _ \_   _|
+         | |  | |_ __   ___ _ __ | (___ | |_) || |
+         | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
+         | |__| | |_) |  __/ | | |____) | |_) || |_
+          \____/| .__/ \___|_| |_|_____/|____/_____|
+                | |
+                |_|
+
+        Platform Name               : Pine64 Star64
+        Platform Features           : medeleg
+        Platform HART Count         : 4
+        Platform IPI Device         : aclint-mswi
+        Platform Timer Device       : aclint-mtimer @ 4000000Hz
+        Platform Console Device     : uart8250
+        Platform HSM Device         : ---
+        Platform PMU Device         : ---
+        Platform Reboot Device      : pm-reset
+        Platform Shutdown Device    : pm-reset
+        Platform Suspend Device     : ---
+        Platform CPPC Device        : ---
+        Firmware Base               : 0x40000000
+        Firmware Size               : 353 KB
+        Firmware RW Offset          : 0x40000
+        Firmware RW Size            : 97 KB
+        Firmware Heap Offset        : 0x4c000
+        Firmware Heap Size          : 49 KB (total), 3 KB (reserved), 12 KB (used), 33 KB (free)
+        Firmware Scratch Size       : 4096 B (total), 400 B (used), 3696 B (free)
+        Runtime SBI Version         : 3.0
+        Standard SBI Extensions     : time,rfnc,ipi,base,hsm,srst,pmu,dbcn,fwft,legacy,dbtr,sse
+        Experimental SBI Extensions : none
+
+        Domain0 Name                : root
+        Domain0 Boot HART           : 4
+        Domain0 HARTs               : 1*,2*,3*,4*
+        Domain0 Region00            : 0x0000000010000000-0x0000000010000fff M: (I,R,W) S/U: (R,W)
+        Domain0 Region01            : 0x0000000002000000-0x000000000200ffff M: (I,R,W) S/U: ()
+        Domain0 Region02            : 0x0000000040040000-0x000000004005ffff M: (R,W) S/U: ()
+        Domain0 Region03            : 0x0000000040000000-0x000000004003ffff M: (R,X) S/U: ()
+        Domain0 Region04            : 0x000000000c000000-0x000000000fffffff M: (I,R,W) S/U: (R,W)
+        Domain0 Region05            : 0x0000000000000000-0xffffffffffffffff M: () S/U: (R,W,X)
+        Domain0 Next Address        : 0x0000000040200000
+        Domain0 Next Arg1           : 0x0000000042200000
+        Domain0 Next Mode           : S-mode
+        Domain0 SysReset            : yes
+        Domain0 SysSuspend          : yes
+
+        Boot HART ID                : 4
+        Boot HART Domain            : root
+        Boot HART Priv Version      : v1.11
+        Boot HART Base ISA          : rv64imafdcbx
+        Boot HART ISA Extensions    : zihpm,sdtrig
+        Boot HART PMP Count         : 8
+        Boot HART PMP Granularity   : 12 bits
+        Boot HART PMP Address Bits  : 34
+        Boot HART MHPM Info         : 2 (0x00000018)
+        Boot HART Debug Triggers    : 8 triggers
+        Boot HART MIDELEG           : 0x0000000000000222
+        Boot HART MEDELEG           : 0x000000000000b109
+
+
+        U-Boot 2025.10 (Oct 23 2025 - 17:01:49 -0700)
+
+        CPU:   sifive,u74-mc
+        Model: Pine64 Star64
+        DRAM:  4 GiB
+        Core:  160 devices, 29 uclasses, devicetree: board
+        WDT:   Not starting watchdog@13070000
+        MMC:   mmc@16010000: 0, mmc@16020000: 1
+        Loading Environment from SPIFlash...
+        SF: Detected gd25lq128 with page size 256 Bytes, erase size 4 KiB, total 16 MiB
+        *** Warning - bad CRC, using default environment
+
+        StarFive EEPROM format v2
+
+        --------EEPROM INFO--------
+        Vendor : PINE64
+        Product full SN: STAR64V1-2310-D004E000-0000xxxx
+        data version: 0x2
+        PCB revision: 0xc1
+        BOM revision: A
+        Ethernet MAC0 address: 6c:cf:39:00:xx:xx
+        Ethernet MAC1 address: 6c:cf:39:00:xx:xx
+        --------EEPROM INFO--------
+
+        starfive_7110_pcie pcie@9c0000000: Starfive PCIe bus probed.
+        In:    serial@10000000
+        Out:   serial@10000000
+        Err:   serial@10000000
+        Net:   eth0: ethernet@16030000, eth1: ethernet@16040000
+        starting USB...
+        Register 2000820 NbrPorts 2
+        Starting the controller
+        USB XHCI 1.00
+        Bus usb@0: 4 USB Device(s) found
+               scanning usb for storage devices... 0 Storage Device(s) found
+        Working FDT set to ff717fe0
+        Hit any key to stop autoboot: 2 1 0
+
+    (enter)
+        StarFive #
+
+Update QSPI Flash using U-Boot console
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With UART serial USB adapter and tio serial terminal::
+
+    tio /dev/ttyUSB0 -o 1
+        tio 3.9
+        Press ctrl-t q to quit
+        Connected to /dev/ttyUSB0
+
+    (enter)
+        StarFive #
 
     sf probe
-    load mmc 1:1 $kernel_addr_r u-boot-spl.bin.normal.out
-    sf update $kernel_addr_r 0 $filesize
-    load mmc 1:1 $kernel_addr_r u-boot.itb
-    sf update $kernel_addr_r 0x100000 $filesize
+        StarFive # sf probe
+        SF: Detected gd25lq128 with page size 256 Bytes, erase size 4 KiB, total 16 MiB
 
-For loading the files from a TFTP server refer to the dhcp and tftpboot
-commands.
+    loady && sf update $loadaddr 0 $filesize
+        StarFive # loady && sf update $loadaddr 0 $filesize
+        ## Ready for binary (ymodem) download to 0x82000000 at 115200 bps...
+        CCC
 
-After updating U-Boot you may want to erase a saved environment and reboot.
+    (Control-t-y)
+        Send file with YMODEM
+        Enter file name:
 
-.. code-block:: console
+    u-boot/spl/u-boot-spl.bin.normal.out
+        Sending file 'u-boot/spl/u-boot-spl.bin.normal.out'
+        Press any key to abort transfer
+        ...|
+        Done
+        ## Total Size      = 0x00024eb7 = 151223 Bytes
+        ## Start Addr      = 0x82000000
+        device 0 offset 0x0, size 0x24eb7
+        151223 bytes written, 0 bytes skipped in 0.634s, speed 243096 B/s
+        StarFive #
 
     env erase
-    reset
-
-Booting from SD-Card
---------------------
-
-The device boot ROM loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
-partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
-to choose any partition number.
-
-With the default configuration U-Boot SPL loads the U-Boot FIT image
-(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
-When formatting it is recommended to use GUID
-BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
-
-Booting from eMMC
------------------
-
-The device boot ROM tries to load U-Boot SPL (u-boot-spl.bin.normal.out) from
-sector 0 of the eMMC's main hardware partition. But this conflicts with GPT
-partitioning. Fortunately eMMC can alternatively load U-Boot SPL from a backup
-position.
-
-For U-Boot SPL (u-boot-spl.bin.normal.out) starting at sector 2048 (position
-0x100000) write the following bytes to the eMMC device after GPT partitioning:
-
-======= ========================
-Address Bytes
-======= ========================
-0x0000  40 02 00 00  00 00 10 00
-0x0290  40 02 00 00  00 00 10 00
-======= ========================
-
-With the default configuration U-Boot SPL loads the U-Boot FIT image
-(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
-When formatting it is recommended to use GUID
-BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
-
-Booting from UART
------------------
-
-The boot ROM supports the X-modem protocol to upload
-spl/u-boot-spl.bin.normal.out. U-Boot SPL support loading the FIT image
-u-boot.itb via the Y-modem protocol.
-
-Due to restrictions of the boot ROM not all X-modem implementations are
-compatible. The package tio (https://github.com/tio/tio) has been found to be
-usable.
-
-Debug UART
-----------
-
-By default the SBI interface is used for the debug UART. But this only works
-in main U-Boot. To enable the debug UART in SPL, too, use the following
-settings::
-
-    CONFIG_DEBUG_UART=y
-    CONFIG_DEBUG_UART_NS16550=y
-    CONFIG_DEBUG_UART_BASE=0x10000000
-    CONFIG_SPL_DEBUG_UART_BASE=0x10000000
-    CONFIG_DEBUG_UART_CLOCK=24000000
-    CONFIG_DEBUG_UART_SHIFT=2
+        StarFive # env erase
+        Erasing Environment on SPIFlash... OK
+        StarFive #
+
+    loady && sf update $loadaddr 100000 $filesize
+        StarFive # loady $loadaddr && sf update $loadaddr 100000 $filesize
+        ## Ready for binary (ymodem) download to 0x82000000 at 115200 bps...
+        CCC
+
+    (Control-t-y)
+        Send file with YMODEM
+        Enter file name:
+
+    u-boot/u-boot.itb
+        Sending file 'u-boot/u-boot.itb'
+        Press any key to abort transfer
+        ...|
+        Done
+        ## Total Size      = 0x002fa5cd = 3122637 Bytes
+        ## Start Addr      = 0x82000000
+        device 0 offset 0x100000, size 0x2fa5cd
+        3122637 bytes written, 0 bytes skipped in 18.137s, speed 176272 B/s
+        StarFive #
+
+Update QSPI Flash from GNU/Linux OS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With mtd-utils::
+
+    cat /proc/mtd
+        dev:    size   erasesize  name
+        mtd0: 000f0000 00001000 "spl"
+        mtd1: 00010000 00001000 "uboot-env"
+        mtd2: 00f00000 00001000 "uboot"
+
+    flashcp --verbose u-boot/spl/u-boot-spl.bin.normal.out /dev/mtd0
+        Erasing blocks: 37/37 (100%)
+        Writing data: 147k/147k (100%)
+        Verifying data: 147k/147k (100%)
+
+    flashcp --verbose --erase-all /dev/zero /dev/mtd1
+        Erasing blocks: 16/16 (100%)
+        Writing data: 0k/0k (100%)
+        Verifying data: 0k/0k (100%)
+
+    flashcp --verbose u-boot/u-boot.itb /dev/mtd2
+        Erasing blocks: 763/763 (100%)
+        Writing data: 3049k/3049k (100%)
+        Verifying data: 3049k/3049k (100%)
diff --git a/doc/board/starfive/milk-v_mars.rst b/doc/board/starfive/milk-v_mars.rst
index ce4539a46f1..0dbc500b734 100644
--- a/doc/board/starfive/milk-v_mars.rst
+++ b/doc/board/starfive/milk-v_mars.rst
@@ -7,38 +7,6 @@ U-Boot for the Milk-V Mars uses the same U-Boot binaries as the VisionFive 2
 board. In U-Boot SPL the actual board is detected and the device-tree patched
 accordingly.
 
-Building
---------
-
-1. Add the RISC-V toolchain to your PATH.
-2. Setup ARCH & cross compilation environment variable:
-
-.. code-block:: none
-
-   export CROSS_COMPILE=<riscv64 toolchain prefix>
-
-The M-mode software OpenSBI provides the supervisor binary interface (SBI) and
-is responsible for the switch to S-Mode. It is a prerequisite to build U-Boot.
-Support for the JH7110 was introduced in OpenSBI 1.2. It is recommended to use
-a current release.
-
-.. code-block:: console
-
-	git clone https://github.com/riscv/opensbi.git
-	cd opensbi
-	make PLATFORM=generic FW_TEXT_START=0x40000000 FW_OPTIONS=0
-
-Now build the U-Boot SPL and U-Boot proper.
-
-.. code-block:: console
-
-	cd <U-Boot-dir>
-	make starfive_visionfive2_defconfig
-	make OPENSBI=$(opensbi_dir)/build/platform/generic/firmware/fw_dynamic.bin
-
-This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well
-as the FIT image (u-boot.itb) with OpenSBI and U-Boot.
-
 Device-tree selection
 ---------------------
 
@@ -57,45 +25,4 @@ environment
 or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to set to
 provide a default value.
 
-Preparing the SD-Card
----------------------
-
-The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
-partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
-to choose any partition number.
-
-With the default configuration U-Boot SPL loads the U-Boot FIT image
-(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
-When formatting it is recommended to use GUID
-BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
-
-The FIT image (u-boot.itb) is a combination of OpenSBI's fw_dynamic.bin,
-u-boot-nodtb.bin and the device tree blob.
-
-Format the SD card (make sure the disk has GPT, otherwise use gdisk to switch)
-
-.. code-block:: bash
-
-	sudo sgdisk --clear \
-	  --set-alignment=2 \
-	  --new=1:4096:8191 --change-name=1:spl --typecode=1:2E54B353-1271-4842-806F-E436D6AF6985\
-	  --new=2:8192:16383 --change-name=2:uboot --typecode=2:BC13C2FF-59E6-4262-A352-B275FD6F7172  \
-	  --new=3:16384:1654784 --change-name=3:system --typecode=3:EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 \
-	  /dev/sdb
-
-Copy U-Boot to the SD card
-
-.. code-block:: bash
-
-	sudo dd if=u-boot-spl.bin.normal.out of=/dev/sdb1
-	sudo dd if=u-boot.itb of=/dev/sdb2
-
-	sudo mount /dev/sdb3 /mnt/
-	sudo cp u-boot-spl.bin.normal.out /mnt/
-	sudo cp u-boot.itb /mnt/
-	sudo cp Image.gz /mnt/
-	sudo cp initramfs.cpio.gz /mnt/
-	sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
-	sudo umount /mnt
-
 .. include:: jh7110_common.rst
diff --git a/doc/board/starfive/pine64_star64.rst b/doc/board/starfive/pine64_star64.rst
index d1752c452da..78a330be455 100644
--- a/doc/board/starfive/pine64_star64.rst
+++ b/doc/board/starfive/pine64_star64.rst
@@ -7,38 +7,6 @@ U-Boot for the Star64 uses the same U-Boot binaries as the VisionFive 2 board.
 In U-Boot SPL the actual board is detected and the device-tree patched
 accordingly.
 
-Building
---------
-
-1. Add the RISC-V toolchain to your PATH.
-2. Setup ARCH & cross compilation environment variable:
-
-.. code-block:: none
-
-   export CROSS_COMPILE=<riscv64 toolchain prefix>
-
-The M-mode software OpenSBI provides the supervisor binary interface (SBI) and
-is responsible for the switch to S-Mode. It is a prerequisite to build U-Boot.
-Support for the JH7110 was introduced in OpenSBI 1.2. It is recommended to use
-a current release.
-
-.. code-block:: console
-
-	git clone https://github.com/riscv/opensbi.git
-	cd opensbi
-	make PLATFORM=generic FW_TEXT_START=0x40000000
-
-Now build the U-Boot SPL and U-Boot proper.
-
-.. code-block:: console
-
-	cd <U-Boot-dir>
-	make starfive_visionfive2_defconfig
-	make OPENSBI=$(opensbi_dir)/build/platform/generic/firmware/fw_dynamic.bin
-
-This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well
-as the FIT image (u-boot.itb) with OpenSBI and U-Boot.
-
 Device-tree selection
 ---------------------
 
@@ -55,49 +23,6 @@ environment
 or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to set to
 provide a default value.
 
-Preparing the SD-Card
----------------------
-
-The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
-partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
-to choose any partition number.
-
-With the default configuration U-Boot SPL loads the U-Boot FIT image
-(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
-When formatting it is recommended to use GUID
-BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
-
-The FIT image (u-boot.itb) is a combination of OpenSBI's fw_dynamic.bin,
-u-boot-nodtb.bin and the device tree blob.
-
-Format the SD card (make sure the disk has GPT, otherwise use gdisk to switch)
-
-.. code-block:: bash
-
-	sudo sgdisk --clear \
-	  --set-alignment=2 \
-	  --new=1:4096:8191 --change-name=1:spl --typecode=1:2E54B353-1271-4842-806F-E436D6AF6985\
-	  --new=2:8192:16383 --change-name=2:uboot --typecode=2:BC13C2FF-59E6-4262-A352-B275FD6F7172  \
-	  --new=3:16384:1654784 --change-name=3:system --typecode=3:EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 \
-	  /dev/sdb
-
-Copy U-Boot to the SD card
-
-.. code-block:: bash
-
-	sudo dd if=u-boot-spl.bin.normal.out of=/dev/sdb1
-	sudo dd if=u-boot.itb of=/dev/sdb2
-
-	sudo mount /dev/sdb3 /mnt/
-	sudo cp u-boot-spl.bin.normal.out /mnt/
-	sudo cp u-boot.itb /mnt/
-	sudo cp Image.gz /mnt/
-	sudo cp initramfs.cpio.gz /mnt/
-	sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
-	sudo umount /mnt
-
-.. include:: jh7110_common.rst
-
 Serial Number and MAC address issues
 ------------------------------------
 
@@ -183,3 +108,5 @@ The MAC addresses may be "set" as follows by writing as a custom config to SPI
 	env set eth1addr 6c:cf:39:ce:64:5a
 	env save
 	reset
+
+.. include:: jh7110_common.rst
diff --git a/doc/board/starfive/visionfive2.rst b/doc/board/starfive/visionfive2.rst
index 11121a1751a..c92ea16f91b 100644
--- a/doc/board/starfive/visionfive2.rst
+++ b/doc/board/starfive/visionfive2.rst
@@ -3,74 +3,9 @@
 StarFive VisionFive2
 ====================
 
-JH7110 RISC-V SoC
------------------
-
-The JH7110 is 4+1 64-bit RISC-V SoC from StarFive.
-
 The StarFive VisionFive2 development platform is based on JH7110 and capable
 of running Linux.
 
-Mainline support
-----------------
-
-The support for following drivers are already enabled:
-
-1. ns16550 UART Driver.
-2. StarFive JH7110 clock Driver.
-3. StarFive JH7110 reset Driver.
-4. Cadence QSPI controller Driver.
-5. MMC SPI Driver for MMC/SD support.
-6. PLDA PCIE controller driver.
-7. On-board VL805 PCIE-USB controller driver.
-
-Booting from MMC using U-Boot SPL
----------------------------------
-
-The current U-Boot port is supported in S-mode only and loaded from DRAM.
-
-A prior stage M-mode firmware/bootloader (e.g OpenSBI) is required to
-boot the u-boot.itb in S-mode and provide M-mode runtime services.
-
-Currently, the u-boot.itb is used as a dynamic of the OpenSBI FW_DYNAMIC
-firmware with the latest.
-
-Building
---------
-
-1. Add the RISC-V toolchain to your PATH.
-2. Setup ARCH & cross compilation environment variable:
-
-.. code-block:: none
-
-   export CROSS_COMPILE=<riscv64 toolchain prefix>
-
-Before building U-Boot SPL, OpenSBI must be built first. OpenSBI can be
-cloned and built for JH7110 as below:
-
-.. code-block:: console
-
-	git clone https://github.com/riscv/opensbi.git
-	cd opensbi
-	make PLATFORM=generic FW_TEXT_START=0x40000000 FW_OPTIONS=0
-
-The VisionFive 2 support for OpenSBI was introduced after the v1.2 release.
-
-More detailed description of steps required to build FW_DYNAMIC firmware
-is beyond the scope of this document. Please refer OpenSBI documenation.
-(Note: OpenSBI git repo is at https://github.com/riscv/opensbi.git)
-
-Now build the U-Boot SPL and U-Boot proper
-
-.. code-block:: console
-
-	cd <U-Boot-dir>
-	make starfive_visionfive2_defconfig
-	make OPENSBI=$(opensbi_dir)/opensbi/build/platform/generic/firmware/fw_dynamic.bin
-
-This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well
-as the FIT image (u-boot.itb) with OpenSBI and U-Boot.
-
 Device-tree selection
 ---------------------
 
@@ -89,388 +24,4 @@ environment
 or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to provide
 a default value.
 
-Flashing
---------
-
-The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
-partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
-to choose any partition number.
-
-With the default configuration U-Boot SPL loads the U-Boot FIT image
-(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
-When formatting it is recommended to use GUID
-BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
-
-The FIT image (u-boot.itb) is a combination of OpenSBI's fw_dynamic.bin,
-u-boot-nodtb.bin and the device tree blob
-(jh7110-starfive-visionfive-2-v1.3b.dtb or
-jh7110-starfive-visionfive-2-v1.2a.dtb).
-
-Format the SD card (make sure the disk has GPT, otherwise use gdisk to switch)
-
-.. code-block:: bash
-
-	sudo sgdisk --clear \
-	  --set-alignment=2 \
-	  --new=1:4096:8191 --change-name=1:spl --typecode=1:2E54B353-1271-4842-806F-E436D6AF6985\
-	  --new=2:8192:16383 --change-name=2:uboot --typecode=2:BC13C2FF-59E6-4262-A352-B275FD6F7172  \
-	  --new=3:16384:1654784 --change-name=3:system --typecode=3:EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 \
-	  /dev/sdb
-	sudo mkfs.vfat -F32 /dev/sdb3
-
-Program the SD card
-
-.. code-block:: bash
-
-	sudo dd if=u-boot-spl.bin.normal.out of=/dev/sdb1
-	sudo dd if=u-boot.itb of=/dev/sdb2
-
-	sudo mount /dev/sdb3 /mnt/
-	sudo cp u-boot-spl.bin.normal.out /mnt/
-	sudo cp u-boot.itb /mnt/
-	sudo cp Image.gz /mnt/
-	sudo cp initramfs.cpio.gz /mnt/
-	sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
-	sudo umount /mnt
-
 .. include:: jh7110_common.rst
-
-Sample boot log from StarFive VisionFive2 board
------------------------------------------------
-
-.. code-block:: none
-
-
-	U-Boot SPL 2023.04-rc2-00055-gfc43b9c51a-dirty (Mar 02 2023 - 10:51:39 +0800)
-	DDR version: dc2e84f0.
-	Trying to boot from MMC2
-
-	OpenSBI v1.2-80-g4b28afc
-	  ____                    _____ ____ _____
-	 / __ \                  / ____|  _ \_   _|
-	| |  | |_ __   ___ _ __ | (___ | |_) || |
-	| |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
-	| |__| | |_) |  __/ | | |____) | |_) || |_
-	 \____/| .__/ \___|_| |_|_____/|____/_____|
-	       | |
-	       |_|
-
-	Platform Name             : StarFive VisionFive 2 v1.3B
-	Platform Features         : medeleg
-	Platform HART Count       : 5
-	Platform IPI Device       : aclint-mswi
-	Platform Timer Device     : aclint-mtimer @ 4000000Hz
-	Platform Console Device   : uart8250
-	Platform HSM Device       : ---
-	Platform PMU Device       : ---
-	Platform Reboot Device    : ---
-	Platform Shutdown Device  : ---
-	Platform Suspend Device   : ---
-	Firmware Base             : 0x40000000
-	Firmware Size             : 264 KB
-	Firmware RW Offset        : 0x20000
-	Runtime SBI Version       : 1.0
-
-	Domain0 Name              : root
-	Domain0 Boot HART         : 2
-	Domain0 HARTs             : 0*,1*,2*,3*,4*
-	Domain0 Region00          : 0x0000000002000000-0x000000000200ffff M: (I,R,W) S/U: ()
-	Domain0 Region01          : 0x0000000040000000-0x000000004001ffff M: (R,X) S/U: ()
-	Domain0 Region02          : 0x0000000040000000-0x000000004007ffff M: (R,W) S/U: ()
-	Domain0 Region03          : 0x0000000000000000-0xffffffffffffffff M: (R,W,X) S/U: (R,W,X)
-	Domain0 Next Address      : 0x0000000040200000
-	Domain0 Next Arg1         : 0x0000000040287970
-	Domain0 Next Mode         : S-mode
-	Domain0 SysReset          : yes
-	Domain0 SysSuspend        : yes
-
-	Boot HART ID              : 2
-	Boot HART Domain          : root
-	Boot HART Priv Version    : v1.11
-	Boot HART Base ISA        : rv64imafdcbx
-	Boot HART ISA Extensions  : none
-	Boot HART PMP Count       : 8
-	Boot HART PMP Granularity : 4096
-	Boot HART PMP Address Bits: 34
-	Boot HART MHPM Count      : 2
-	Boot HART MIDELEG         : 0x0000000000000222
-	Boot HART MEDELEG         : 0x000000000000b109
-
-
-	U-Boot 2023.04-rc2-00055-gfc43b9c51a-dirty (Mar 02 2023 - 10:51:39 +0800)
-
-	CPU:   rv64imac_zba_zbb
-	Model: StarFive VisionFive 2 v1.3B
-	DRAM:  8 GiB
-	Core:  107 devices, 18 uclasses, devicetree: separate
-	MMC:   mmc@16010000: 0, mmc@16020000: 1
-	Loading Environment from nowhere... OK
-	In:    serial@10000000
-	Out:   serial@10000000
-	Err:   serial@10000000
-	Net:   No ethernet found.
-	Working FDT set to ff74a340
-	Hit any key to stop autoboot:  0
-	StarFive #
-	StarFive # version
-	U-Boot 2023.04-rc2-00055-gfc43b9c51a-dirty (Mar 02 2023 - 10:51:39 +0800)
-
-	riscv64-buildroot-linux-gnu-gcc.br_real (Buildroot VF2_515_v1.0.0_rc4) 10.3.0
-	GNU ld (GNU Binutils) 2.36.1
-	StarFive #
-	StarFive # mmc dev 1
-	switch to partitions #0, OK
-	mmc1 is current device
-	StarFive # mmc info
-	Device: mmc@16020000
-	Manufacturer ID: 9f
-	OEM: 5449
-	Name: SD64G
-	Bus Speed: 50000000
-	Mode: SD High Speed (50MHz)
-	Rd Block Len: 512
-	SD version 3.0
-	High Capacity: Yes
-	Capacity: 58.3 GiB
-	Bus Width: 4-bit
-	Erase Group Size: 512 Bytes
-	StarFive #
-	StarFive # mmc part
-
-	Partition Map for MMC device 1  --   Partition Type: EFI
-
-	Part    Start LBA       End LBA         Name
-			Attributes
-			Type GUID
-			Partition GUID
-	1     0x00001000      0x00001fff      "spl"
-			attrs:  0x0000000000000000
-			type:   2e54b353-1271-4842-806f-e436d6af6985
-					(2e54b353-1271-4842-806f-e436d6af6985)
-			guid:   d5ee2056-3020-475b-9a33-25b4257c9f12
-	2     0x00002000      0x00003fff      "uboot"
-			attrs:  0x0000000000000000
-			type:   bc13c2ff-59e6-4262-a352-b275fd6f7172
-					(bc13c2ff-59e6-4262-a352-b275fd6f7172)
-			guid:   379ab7fe-fd0c-4149-b758-960c1cbfc0cc
-	3     0x00004000      0x00194000      "system"
-			attrs:  0x0000000000000000
-			type:   ebd0a0a2-b9e5-4433-87c0-68b6b72699c7
-					(data)
-			guid:   539a6df9-4655-4953-8541-733ca36eb1db
-	StarFive #
-	StarFive # fatls mmc 1:3
-	6429424   Image.gz
-	717705   u-boot.itb
-	125437   u-boot-spl.bin.normal.out
-	152848495   initramfs.cpio.gz
-		11285   jh7110-starfive-visionfive-2-v1.3b.dtb
-
-	5 file(s), 0 dir(s)
-
-	StarFive # fatload mmc 1:3 ${kernel_addr_r} Image.gz
-	6429424 bytes read in 394 ms (15.6 MiB/s)
-	StarFive # fatload mmc 1:3 ${fdt_addr_r} jh7110-starfive-visionfive-2.dtb
-	11285 bytes read in 5 ms (2.2 MiB/s)
-	StarFive # fatload mmc 1:3 ${ramdisk_addr_r} initramfs.cpio.gz
-	152848495 bytes read in 9271 ms (15.7 MiB/s)
-	StarFive # booti ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}
-	Uncompressing Kernel Image
-	## Flattened Device Tree blob at 46000000
-	Booting using the fdt blob at 0x46000000
-	Working FDT set to 46000000
-	Loading Ramdisk to f5579000, end fe73d86f ... OK
-	Loading Device Tree to 00000000f5573000, end 00000000f5578c14 ... OK
-	Working FDT set to f5573000
-
-	Starting kernel ...
-
-
-	] Linux version 6.2.0-starfive-00026-g11934a315b67 (wyh@wyh-VirtualBox) (riscv64-linux-gnu-gcc (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0, GNU ld (GNU Binutils for Ubuntu) 2.30) #1 SMP Thu Mar  2 14:51:36 CST 2023
-	[    0.000000] OF: fdt: Ignoring memory range 0x40000000 - 0x40200000
-	[    0.000000] Machine model: StarFive VisionFive 2 v1.3B
-	[    0.000000] efi: UEFI not found.
-	[    0.000000] Zone ranges:
-	[    0.000000]   DMA32    [mem 0x0000000040200000-0x00000000ffffffff]
-	[    0.000000]   Normal   [mem 0x0000000100000000-0x000000013fffffff]
-	[    0.000000] Movable zone start for each node
-	[    0.000000] Early memory node ranges
-	[    0.000000]   node   0: [mem 0x0000000040200000-0x000000013fffffff]
-	[    0.000000] Initmem setup node 0 [mem 0x0000000040200000-0x000000013fffffff]
-	[    0.000000] On node 0, zone DMA32: 512 pages in unavailable ranges
-	[    0.000000] SBI specification v1.0 detected
-	[    0.000000] SBI implementation ID=0x1 Version=0x10002
-	[    0.000000] SBI TIME extension detected
-	[    0.000000] SBI IPI extension detected
-	[    0.000000] SBI RFENCE extension detected
-	[    0.000000] SBI HSM extension detected
-	[    0.000000] CPU with hartid=0 is not available
-	[    0.000000] CPU with hartid=0 is not available
-	[    0.000000] CPU with hartid=0 is not available
-	[    0.000000] riscv: base ISA extensions acdfim
-	[    0.000000] riscv: ELF capabilities acdfim
-	[    0.000000] percpu: Embedded 18 pages/cpu s35960 r8192 d29576 u73728
-	[    0.000000] pcpu-alloc: s35960 r8192 d29576 u73728 alloc=18*4096
-	[    0.000000] pcpu-alloc: [0] 0 [0] 1 [0] 2 [0] 3
-	[    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 1031688
-	[    0.000000] Kernel command line: console=ttyS0,115200 debug rootwait earlycon=sbi
-	[    0.000000] Dentry cache hash table entries: 524288 (order: 10, 4194304 bytes, linear)
-	[    0.000000] Inode-cache hash table entries: 262144 (order: 9, 2097152 bytes, linear)
-	[    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
-	[    0.000000] software IO TLB: area num 4.
-	[    0.000000] software IO TLB: mapped [mem 0x00000000f1573000-0x00000000f5573000] (64MB)
-	[    0.000000] Virtual kernel memory layout:
-	[    0.000000]       fixmap : 0xffffffc6fee00000 - 0xffffffc6ff000000   (2048 kB)
-	[    0.000000]       pci io : 0xffffffc6ff000000 - 0xffffffc700000000   (  16 MB)
-	[    0.000000]      vmemmap : 0xffffffc700000000 - 0xffffffc800000000   (4096 MB)
-	[    0.000000]      vmalloc : 0xffffffc800000000 - 0xffffffd800000000   (  64 GB)
-	[    0.000000]      modules : 0xffffffff0136a000 - 0xffffffff80000000   (2028 MB)
-	[    0.000000]       lowmem : 0xffffffd800000000 - 0xffffffd8ffe00000   (4094 MB)
-	[    0.000000]       kernel : 0xffffffff80000000 - 0xffffffffffffffff   (2047 MB)
-	[    0.000000] Memory: 3867604K/4192256K available (8012K kernel code, 4919K rwdata, 4096K rodata, 2190K init, 476K bss, 324652K reserved, 0K cma-reserved)
-	[    0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1
-	[    0.000000] rcu: Hierarchical RCU implementation.
-	[    0.000000] rcu:     RCU restricting CPUs from NR_CPUS=64 to nr_cpu_ids=4.
-	[    0.000000] rcu:     RCU debug extended QS entry/exit.
-	[    0.000000]  Tracing variant of Tasks RCU enabled.
-	[    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 25 jiffies.
-	[    0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4
-	[    0.000000] NR_IRQS: 64, nr_irqs: 64, preallocated irqs: 0
-	[    0.000000] CPU with hartid=0 is not available
-	[    0.000000] riscv-intc: unable to find hart id for /cpus/cpu@0/interrupt-controller
-	[    0.000000] riscv-intc: 64 local interrupts mapped
-	[    0.000000] plic: interrupt-controller@c000000: mapped 136 interrupts with 4 handlers for 9 contexts.
-	[    0.000000] rcu: srcu_init: Setting srcu_struct sizes based on contention.
-	[    0.000000] riscv-timer: riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [4]
-	[    0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 881590404240 ns
-	[    0.000003] sched_clock: 64 bits at 4MHz, resolution 250ns, wraps every 2199023255500ns
-	[    0.000437] Console: colour dummy device 80x25
-	[    0.000568] Calibrating delay loop (skipped), value calculated using timer frequency.. 8.00 BogoMIPS (lpj=16000)
-	[    0.000602] pid_max: default: 32768 minimum: 301
-	[    0.000752] LSM: initializing lsm=capability,integrity
-	[    0.001071] Mount-cache hash table entries: 8192 (order: 4, 65536 bytes, linear)
-	[    0.001189] Mountpoint-cache hash table entries: 8192 (order: 4, 65536 bytes, linear)
-	[    0.004201] CPU node for /cpus/cpu@0 exist but the possible cpu range is :0-3
-	[    0.007426] cblist_init_generic: Setting adjustable number of callback queues.
-	[    0.007457] cblist_init_generic: Setting shift to 2 and lim to 1.
-	[    0.007875] riscv: ELF compat mode unsupported
-	[    0.007902] ASID allocator disabled (0 bits)
-	[    0.008405] rcu: Hierarchical SRCU implementation.
-	[    0.008426] rcu:     Max phase no-delay instances is 1000.
-	[    0.009247] EFI services will not be available.
-	[    0.010738] smp: Bringing up secondary CPUs ...
-	[    0.018358] smp: Brought up 1 node, 4 CPUs
-	[    0.021776] devtmpfs: initialized
-	[    0.027337] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns
-	[    0.027389] futex hash table entries: 1024 (order: 4, 65536 bytes, linear)
-	[    0.027888] pinctrl core: initialized pinctrl subsystem
-	[    0.029881] NET: Registered PF_NETLINK/PF_ROUTE protocol family
-	[    0.030401] audit: initializing netlink subsys (disabled)
-	[    0.031041] audit: type=2000 audit(0.028:1): state=initialized audit_enabled=0 res=1
-	[    0.031943] cpuidle: using governor menu
-	[    0.043011] HugeTLB: registered 2.00 MiB page size, pre-allocated 0 pages
-	[    0.043033] HugeTLB: 0 KiB vmemmap can be freed for a 2.00 MiB page
-	[    0.044943] iommu: Default domain type: Translated
-	[    0.044965] iommu: DMA domain TLB invalidation policy: strict mode
-	[    0.046089] SCSI subsystem initialized
-	[    0.046733] libata version 3.00 loaded.
-	[    0.047231] usbcore: registered new interface driver usbfs
-	[    0.047315] usbcore: registered new interface driver hub
-	[    0.047420] usbcore: registered new device driver usb
-	[    0.049770] vgaarb: loaded
-	[    0.050277] clocksource: Switched to clocksource riscv_clocksource
-	[    0.084690] NET: Registered PF_INET protocol family
-	[    0.085561] IP idents hash table entries: 65536 (order: 7, 524288 bytes, linear)
-	[    0.093010] tcp_listen_portaddr_hash hash table entries: 2048 (order: 4, 65536 bytes, linear)
-	[    0.093152] Table-perturb hash table entries: 65536 (order: 6, 262144 bytes, linear)
-	[    0.093224] TCP established hash table entries: 32768 (order: 6, 262144 bytes, linear)
-	[    0.093821] TCP bind hash table entries: 32768 (order: 9, 2097152 bytes, linear)
-	[    0.117880] TCP: Hash tables configured (established 32768 bind 32768)
-	[    0.118500] UDP hash table entries: 2048 (order: 5, 196608 bytes, linear)
-	[    0.118881] UDP-Lite hash table entries: 2048 (order: 5, 196608 bytes, linear)
-	[    0.119675] NET: Registered PF_UNIX/PF_LOCAL protocol family
-	[    0.121749] RPC: Registered named UNIX socket transport module.
-	[    0.121776] RPC: Registered udp transport module.
-	[    0.121784] RPC: Registered tcp transport module.
-	[    0.121791] RPC: Registered tcp NFSv4.1 backchannel transport module.
-	[    0.121816] PCI: CLS 0 bytes, default 64
-	[    0.124101] Unpacking initramfs...
-	[    0.125468] workingset: timestamp_bits=46 max_order=20 bucket_order=0
-	[    0.128372] NFS: Registering the id_resolver key type
-	[    0.128498] Key type id_resolver registered
-	[    0.128525] Key type id_legacy registered
-	[    0.128625] nfs4filelayout_init: NFSv4 File Layout Driver Registering...
-	[    0.128649] nfs4flexfilelayout_init: NFSv4 Flexfile Layout Driver Registering...
-	[    0.129358] 9p: Installing v9fs 9p2000 file system support
-	[    0.130179] NET: Registered PF_ALG protocol family
-	[    0.130499] Block layer SCSI generic (bsg) driver version 0.4 loaded (major 247)
-	[    0.130544] io scheduler mq-deadline registered
-	[    0.130556] io scheduler kyber registered
-	[    0.416754] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
-	[    0.420857] SuperH (H)SCI(F) driver initialized
-	[    0.443735] loop: module loaded
-	[    0.448605] e1000e: Intel(R) PRO/1000 Network Driver
-	[    0.448627] e1000e: Copyright(c) 1999 - 2015 Intel Corporation.
-	[    0.450716] usbcore: registered new interface driver uas
-	[    0.450832] usbcore: registered new interface driver usb-storage
-	[    0.451638] mousedev: PS/2 mouse device common for all mice
-	[    0.453465] sdhci: Secure Digital Host Controller Interface driver
-	[    0.453487] sdhci: Copyright(c) Pierre Ossman
-	[    0.453584] sdhci-pltfm: SDHCI platform and OF driver helper
-	[    0.454140] usbcore: registered new interface driver usbhid
-	[    0.454174] usbhid: USB HID core driver
-	[    0.454833] riscv-pmu-sbi: SBI PMU extension is available
-	[    0.454920] riscv-pmu-sbi: 16 firmware and 4 hardware counters
-	[    0.454942] riscv-pmu-sbi: Perf sampling/filtering is not supported as sscof extension is not available
-	[    0.457071] NET: Registered PF_INET6 protocol family
-	[    0.460627] Segment Routing with IPv6
-	[    0.460821] In-situ OAM (IOAM) with IPv6
-	[    0.461005] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver
-	[    0.462712] NET: Registered PF_PACKET protocol family
-	[    0.462933] 9pnet: Installing 9P2000 support
-	[    0.463141] Key type dns_resolver registered
-	[    0.463168] start plist test
-	[    0.469261] end plist test
-	[    0.506774] debug_vm_pgtable: [debug_vm_pgtable         ]: Validating architecture page table helpers
-	[    0.553683] gpio gpiochip0: Static allocation of GPIO base is deprecated, use dynamic allocation.
-	[    0.554741] starfive-jh7110-sys-pinctrl 13040000.pinctrl: StarFive GPIO chip registered 64 GPIOs
-	[    0.555900] gpio gpiochip1: Static allocation of GPIO base is deprecated, use dynamic allocation.
-	[    0.556772] starfive-jh7110-aon-pinctrl 17020000.pinctrl: StarFive GPIO chip registered 4 GPIOs
-	[    0.559454] printk: console [ttyS0] disabled
-	[    0.579948] 10000000.serial: ttyS0 at MMIO 0x10000000 (irq = 3, base_baud = 1500000) is a 16550A
-	[    0.580082] printk: console [ttyS0] enabled
-	[   13.642680] Freeing initrd memory: 149264K
-	[   13.651051] Freeing unused kernel image (initmem) memory: 2188K
-	[   13.666431] Run /init as init process
-	[   13.670116]   with arguments:
-	[   13.673168]     /init
-	[   13.675488]   with environment:
-	[   13.678668]     HOME=/
-	[   13.681038]     TERM=linux
-	Starting syslogd: OK
-	Starting klogd: OK
-	Running sysctl: OK
-	Populating /dev using udev: [   14.145944] udevd[93]: starting version 3.2.10
-	[   15.214287] random: crng init done
-	[   15.240816] udevd[94]: starting eudev-3.2.10
-	done
-	Saving random seed: OK
-	Starting system message bus: dbus[122]: Unknown username "pulse" in message bus configuration file
-	done
-	Starting rpcbind: OK
-	Starting iptables: OK
-	Starting bluetoothd: OK
-	Starting network: Waiting for interface eth0 to appear............... timeout!
-	run-parts: /etc/network/if-pre-up.d/wait_iface: exit status 1
-	FAIL
-	Starting dropbear sshd: OK
-	Starting NFS statd: OK
-	Starting NFS services: OK
-	Starting NFS daemon: rpc.nfsd: Unable to access /proc/fs/nfsd errno 2 (No such file or directory).
-	Please try, as root, 'mount -t nfsd nfsd /proc/fs/nfsd' and then restart rpc.nfsd to correct the problem
-	FAIL
-	Starting NFS mountd: OK
-	Starting DHCP server: FAIL
-
-	Welcome to Buildroot
-	buildroot login:
diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
index 40e144948a3..b14ba41917e 100644
--- a/doc/board/ti/am335x_evm.rst
+++ b/doc/board/ti/am335x_evm.rst
@@ -274,7 +274,7 @@ into memory, then written to NAND.
 Falcon Mode
 -----------
 
-The default build includes "Falcon Mode" (see doc/README.falcon) via NAND,
+The default build includes :ref:`falcon-mode` via NAND,
 eMMC (or raw SD cards) and FAT SD cards.  Our default behavior currently is
 to read a 'c' on the console while in SPL at any point prior to loading the
 OS payload (so as soon as possible) to opt to booting full U-Boot.  Also
diff --git a/doc/board/ti/am62dx_evm.rst b/doc/board/ti/am62dx_evm.rst
new file mode 100644
index 00000000000..2d66241ce68
--- /dev/null
+++ b/doc/board/ti/am62dx_evm.rst
@@ -0,0 +1,256 @@
+.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
+.. sectionauthor:: Paresh Bhagat <[email protected]>
+
+AM62D Platforms
+===============
+
+Introduction:
+-------------
+The AM62D2 SoC belongs to the K3 Multicore SoC architecture with DSP core
+targeted for applications needing high-performance Digital Signal
+Processing. It is used in applications like automotive audio systems,
+professional sound equipment, radar and radio for aerospace, sonar in
+marine devices, and ultrasound in medical imaging. It also supports
+precise signal analysis in test and measurement tools.
+
+Some highlights of AM62D2 SoC are:
+
+* Quad-Cortex-A53s (running up to 1.4GHz) in a single cluster. Dual/Single
+  core variants are provided in the same package to allow HW compatible
+  designs.
+* One Device manager Cortex-R5F for system power and resource management,
+  and one Cortex-R5F for Functional Safety or general-purpose usage.
+* DSP with Matrix Multiplication Accelerator(MMA) (up to 2 TOPS) based on
+  single core C7x.
+* 3x Multichannel Audio Serial Ports (McASP) Up to 4/6/16 Serial Data Pins
+  which can Transmit and Receive Clocks up to 50MHz, with multi-channel I2S
+  and TDM Audio inputs and outputs.
+* Integrated Giga-bit Ethernet switch supporting up to a total of two
+  external ports with TSN capable to enable audio networking features such
+  as, Ethernet Audio Video Bridging (eAVB) and Dante.
+* 9xUARTs, 5xSPI, 6xI2C, 2xUSB2, 3xCAN-FD, 3x eMMC and SD, OSPI memory
+  controller, 1x CSI-RX-4L for Camera, eCAP/eQEP, ePWM, among other
+  peripherals.
+* Dedicated Centralized Hardware Security Module with support for secure
+  boot, debug security and crypto acceleration and trusted execution
+  environment.
+* One 32 bit DDR Subsystem that supports LPDDR4, DDR4 memory types.
+* Low power mode support: Partial IO support for CAN/GPIO/UART wakeup.
+
+This SoC is of part K3 AM62x family, which includes the AM62A and AM62P
+variants. While the AM62A and AM62D are largely similar, the AM62D is
+specifically targeted for general-purpose DSP applications, whereas the
+AM62A focuses on edge AI workloads. A key distinction is that the AM62D
+does not include multimedia components such as the video encoder/decoder,
+MJPEG encoder, Vision Processing Accelerator (VPAC) for image signal
+processing, or the display subsystem. Additionally, the AM62D has a
+different pin configuration compared to the AM62A, which impacts
+embedded software development.
+
+More details can be found in the Technical Reference Manual:
+https://www.ti.com/lit/pdf/sprujd4
+
+Platform information:
+
+* https://www.ti.com/tool/AUDIO-AM62D-EVM
+
+Boot Flow:
+----------
+Below is the pictorial representation of boot flow:
+
+.. image:: img/boot_diagram_am62.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.
+
+Sources:
+--------
+
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_boot_sources
+    :end-before: .. k3_rst_include_end_boot_sources
+
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_boot_firmwares
+    :end-before: .. k3_rst_include_end_tifsstub
+
+Build procedure:
+----------------
+0. Setup the environment variables:
+
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_desc
+    :end-before: .. k3_rst_include_end_common_env_vars_desc
+
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_board_env_vars_desc
+    :end-before: .. k3_rst_include_end_board_env_vars_desc
+
+Set the variables corresponding to this platform:
+
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_defn
+    :end-before: .. k3_rst_include_end_common_env_vars_defn
+.. prompt:: bash
+
+   export UBOOT_CFG_CORTEXR=am62dx_evm_r5_defconfig
+   export UBOOT_CFG_CORTEXA=am62dx_evm_a53_defconfig
+   export TFA_BOARD=lite
+   # we dont use any extra TFA parameters
+   unset TFA_EXTRA_ARGS
+   export OPTEE_PLATFORM=k3-am62ax
+   # we dont use any extra OPTEE parameters
+   unset OPTEE_EXTRA_ARGS
+
+1. Trusted Firmware-A:
+
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_tfa
+    :end-before: .. k3_rst_include_end_build_steps_tfa
+
+2. OP-TEE:
+
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_optee
+    :end-before: .. k3_rst_include_end_build_steps_optee
+
+3. U-Boot:
+
+* 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
+
+* 3.2 A53:
+
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_uboot
+    :end-before: .. k3_rst_include_end_build_steps_uboot
+
+Target Images
+--------------
+In order to boot we need tiboot3.bin, tispl.bin and u-boot.img.  Each SoC
+variant (HS-FS, HS-SE) requires a different source for these files.
+
+ - HS-FS
+
+        * tiboot3-am62ax-hs-fs-evm.bin from step 3.1
+        * tispl.bin, u-boot.img from step 3.2
+
+ - HS-SE
+
+        * tiboot3-am62ax-hs-evm.bin from step 3.1
+        * tispl.bin, u-boot.img from step 3.2
+
+Image formats:
+--------------
+
+- tiboot3.bin
+
+.. image:: img/multi_cert_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
+
+- tispl.bin
+
+.. image:: img/tifsstub_dm_tispl.bin.svg
+  :alt: tispl.bin image format
+
+Switch Setting for Boot Mode
+----------------------------
+
+Boot Mode pins provide means to select the boot mode and options before the
+device is powered up. After every POR, they are the main source to populate
+the Boot Parameter Tables.
+
+The following table shows some common boot modes used on AM62D platform. More
+details can be found in the Technical Reference Manual:
+https://www.ti.com/lit/pdf/sprujd4 under the `Boot Mode Pins` section.
+
+.. list-table:: Boot Modes
+   :widths: 16 16 16
+   :header-rows: 1
+
+   * - Switch Label
+     - SW2: 12345678
+     - SW3: 12345678
+
+   * - SD
+     - 01000000
+     - 11000010
+
+   * - OSPI
+     - 00000000
+     - 11001110
+
+   * - EMMC
+     - 00000000
+     - 11010010
+
+   * - UART
+     - 00000000
+     - 11011100
+
+   * - USB DFU
+     - 00000000
+     - 11001010
+
+For SW2 and SW1, the switch state in the "ON" position = 1.
+
+Falcon Mode
+-----------
+
+Falcon Mode on AM62dx platforms bypasses the A53 SPL and U-Boot with the overall
+boot flow as below:
+
+.. include:: am62x_sk.rst
+    :start-after: .. am62x_evm_falcon_start_boot_flow
+    :end-before: .. am62x_evm_falcon_end_boot_flow
+
+Build Process
+^^^^^^^^^^^^^
+
+.. include:: am62x_sk.rst
+    :start-after: .. am62x_evm_falcon_start_build_process
+    :end-before: .. am62x_evm_falcon_end_build_process
+
+Usage
+^^^^^
+
+.. include:: am62x_sk.rst
+    :start-after: .. am62x_evm_falcon_start_usage
+    :end-before: .. am62x_evm_falcon_end_usage
+
+R5 SPL Memory Map
+^^^^^^^^^^^^^^^^^
+
+.. include:: am62x_sk.rst
+    :start-after: .. am62x_evm_falcon_start_r5_memory_map
+    :end-before: .. am62x_evm_falcon_end_r5_memory_map
+
+Debugging U-Boot
+----------------
+
+See :ref:`Common Debugging environment - OpenOCD<k3_rst_refer_openocd>`: for
+detailed setup information.
+
+.. warning::
+
+  **AM62A**: OpenOCD support since August 2023 (git master)
+
+  **AM62D**: Uses AM62A configuration (compatible due to same core architecture)
+
+  Until the next stable release of OpenOCD is available in your development
+  environment's distribution, it might be necessary to build OpenOCD `from the
+  source <https://github.com/openocd-org/openocd>`_.
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_openocd_connect_XDS110
+    :end-before: .. k3_rst_include_end_openocd_connect_XDS110
+
+To start OpenOCD and connect to the board
+
+.. prompt:: bash
+
+  openocd -f board/ti/am62a7evm.cfg
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
index 913cdd7d09e..ed04a57c167 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -31,6 +31,7 @@ K3 Based SoCs
    :maxdepth: 1
 
    am62ax_sk
+   am62dx_evm
    am62x_sk
    am62px_sk
    am6254atl_sk
diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst
index 528a9c389bf..3fc23f65c45 100644
--- a/doc/develop/falcon.rst
+++ b/doc/develop/falcon.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
+.. _falcon-mode:
 
 Falcon Mode
 ===========
diff --git a/doc/sphinx/kernel_abi.py b/doc/sphinx/kernel_abi.py
index 32c50e496b5..930e9273b16 100644
--- a/doc/sphinx/kernel_abi.py
+++ b/doc/sphinx/kernel_abi.py
@@ -44,7 +44,9 @@ from os import path
 from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import directives, Directive
-from docutils.utils.error_reporting import ErrorString
+
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
 
 #
 # AutodocReporter is only good up to Sphinx 1.7
diff --git a/doc/sphinx/kernel_feat.py b/doc/sphinx/kernel_feat.py
index 2fee04f1ded..cca48f6f1a4 100644
--- a/doc/sphinx/kernel_feat.py
+++ b/doc/sphinx/kernel_feat.py
@@ -41,7 +41,9 @@ from os import path
 from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import directives, Directive
-from docutils.utils.error_reporting import ErrorString
+
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
 
 #
 # AutodocReporter is only good up to Sphinx 1.7
diff --git a/doc/sphinx/kernel_include.py b/doc/sphinx/kernel_include.py
index f523aa68a36..6522de9dd69 100755
--- a/doc/sphinx/kernel_include.py
+++ b/doc/sphinx/kernel_include.py
@@ -34,11 +34,13 @@ u"""
 import os.path
 
 from docutils import io, nodes, statemachine
-from docutils.utils.error_reporting import SafeString, ErrorString
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
 from docutils.parsers.rst.directives.misc import Include
 
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
+
 __version__  = '1.0'
 
 # ==============================================================================
@@ -109,7 +111,7 @@ class KernelInclude(Include):
             raise self.severe('Problems with "%s" directive path:\n'
                               'Cannot encode input file path "%s" '
                               '(wrong locale?).' %
-                              (self.name, SafeString(path)))
+                              (self.name, path))
         except IOError as error:
             raise self.severe('Problems with "%s" directive path:\n%s.' %
                       (self.name, ErrorString(error)))
diff --git a/doc/sphinx/maintainers_include.py b/doc/sphinx/maintainers_include.py
index 13557d3d3c2..ab79a74dc0c 100755
--- a/doc/sphinx/maintainers_include.py
+++ b/doc/sphinx/maintainers_include.py
@@ -22,10 +22,12 @@ import re
 import os.path
 
 from docutils import statemachine
-from docutils.utils.error_reporting import ErrorString
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst.directives.misc import Include
 
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
+
 __version__  = '1.0'
 
 def setup(app):
diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt
index dd433e2bb15..e313e4f0946 100644
--- a/doc/sphinx/requirements.txt
+++ b/doc/sphinx/requirements.txt
@@ -24,4 +24,4 @@ sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==2.0.0
-urllib3==2.6.0
+urllib3==2.6.3
diff --git a/test/cmd/meminfo.c b/test/cmd/meminfo.c
index 40c3520496e..d91fa6fcead 100644
--- a/test/cmd/meminfo.c
+++ b/test/cmd/meminfo.c
@@ -15,24 +15,34 @@ static int cmd_test_meminfo(struct unit_test_state *uts)
 {
 	ut_assertok(run_command("meminfo", 0));
 	ut_assert_nextlinen("DRAM:  ");
+
+	if (!IS_ENABLED(CMD_MEMINFO_MAP))
+		return 0;
+
 	ut_assert_nextline_empty();
 
-	ut_assert_nextline("Region           Base     Size      End      Gap");
+	ut_assert_nextline("Region                Base          Size           End           Gap");
 	ut_assert_nextlinen("-");
 
 	/* For now we don't worry about checking the values */
-	ut_assert_nextlinen("video");
+	if (IS_ENABLED(CONFIG_VIDEO))
+		ut_assert_nextlinen("video");
+	if (IS_ENABLED(CONFIG_TRACE))
+		ut_assert_nextlinen("trace");
 	ut_assert_nextlinen("code");
 	ut_assert_nextlinen("malloc");
 	ut_assert_nextlinen("board_info");
 	ut_assert_nextlinen("global_data");
 	ut_assert_nextlinen("devicetree");
-	ut_assert_nextlinen("bootstage");
-	ut_assert_nextlinen("bloblist");
+	if (IS_ENABLED(CONFIG_BOOTSTAGE))
+		ut_assert_nextlinen("bootstage");
+	if (IS_ENABLED(CONFIG_BLOBLIST))
+		ut_assert_nextlinen("bloblist");
 	ut_assert_nextlinen("stack");
 
 	/* we expect at least one lmb line, but don't know how many */
-	ut_assert_nextlinen("lmb");
+	if (IS_ENABLED(CONFIG_LMB))
+		ut_assert_nextlinen("lmb");
 	ut_assert_skip_to_linen("free");
 
 	ut_assert_console_end();
diff --git a/test/py/tests/test_trace.py b/test/py/tests/test_trace.py
index fcdcbe2c6db..36a3c4e8fe9 100644
--- a/test/py/tests/test_trace.py
+++ b/test/py/tests/test_trace.py
@@ -2,9 +2,11 @@
 # Copyright 2022 Google LLC
 # Written by Simon Glass <[email protected]>
 
+"""Tests for the function trace facility"""
+
 import os
-import pytest
 import re
+import pytest
 
 import utils
 
@@ -159,7 +161,8 @@ def check_function(ubman, fname, proftool, map_fname, trace_dat):
             base = timestamp
 
     # Check for some expected functions
-    assert 'initf_malloc' in vals.keys()
+    if ubman.config.buildconfig.get('config_trace_early'):
+        assert 'initf_malloc' in vals.keys()
     assert 'initr_watchdog' in vals.keys()
     assert 'initr_dm' in vals.keys()
 
@@ -182,26 +185,25 @@ def check_funcgraph(ubman, fname, proftool, map_fname, trace_dat):
     """
 
     # Generate the funcgraph format
-    out = utils.run_and_log(
-        ubman, [proftool, '-t', fname, '-o', trace_dat, '-m', map_fname,
-               'dump-ftrace', '-f', 'funcgraph'])
+    utils.run_and_log(ubman, [proftool, '-t', fname, '-o', trace_dat, '-m',
+                      map_fname, 'dump-ftrace', '-f', 'funcgraph'])
 
     # Check that the trace has what we expect
     cmd = f'trace-cmd report -l {trace_dat} |head -n 70'
     out = utils.run_and_log(ubman, ['sh', '-c', cmd])
 
     # First look for this:
-    #  u-boot-1     0.....   282.101360: funcgraph_entry:        0.004 us   |    initf_malloc();
+    #  u-boot-1     0.....   282.101360: funcgraph_entry:   0.004 us   |    initf_malloc();
     # ...
-    #  u-boot-1     0.....   282.101369: funcgraph_entry:                   |    initf_bootstage() {
-    #  u-boot-1     0.....   282.101369: funcgraph_entry:                   |      bootstage_init() {
-    #  u-boot-1     0.....   282.101369: funcgraph_entry:                   |        dlmalloc() {
+    #  u-boot-1     0.....   282.101369: funcgraph_entry:              |    initf_bootstage() {
+    #  u-boot-1     0.....   282.101369: funcgraph_entry:              |      bootstage_init() {
+    #  u-boot-1     0.....   282.101369: funcgraph_entry:              |        dlmalloc() {
     # ...
-    #  u-boot-1     0.....   282.101375: funcgraph_exit:         0.001 us   |        }
+    #  u-boot-1     0.....   282.101375: funcgraph_exit:    0.001 us   |        }
     # Then look for this:
-    #  u-boot-1     0.....   282.101375: funcgraph_exit:         0.006 us   |      }
+    #  u-boot-1     0.....   282.101375: funcgraph_exit:    0.006 us   |      }
     # Then check for this:
-    #  u-boot-1     0.....   282.101375: funcgraph_entry:        0.000 us   |    event_init();
+    #  u-boot-1     0.....   282.101375: funcgraph_entry:   0.000 us   |    event_init();
 
     expected_indent = None
     found_start = False
@@ -217,7 +219,7 @@ def check_funcgraph(ubman, fname, proftool, map_fname, trace_dat):
             if found_end:
                 upto = func
                 break
-            elif func == 'initf_bootstage() ':
+            if func == 'initf_bootstage() ':
                 found_start = True
                 expected_indent = indent + '  '
             elif found_start and indent == expected_indent and brace == '}':
@@ -267,9 +269,8 @@ def check_flamegraph(ubman, fname, proftool, map_fname, trace_fg):
     """
 
     # Generate the flamegraph format
-    out = utils.run_and_log(
-        ubman, [proftool, '-t', fname, '-o', trace_fg, '-m', map_fname,
-               'dump-flamegraph'])
+    utils.run_and_log(ubman, [proftool, '-t', fname, '-o', trace_fg, '-m', map_fname,
+                      'dump-flamegraph'])
 
     # We expect dm_timer_init() to be called twice: once before relocation and
     # once after
@@ -290,16 +291,15 @@ def check_flamegraph(ubman, fname, proftool, map_fname, trace_fg):
 
     # Add up all the time spend in initf_dm() and its children
     total = 0
-    with open(trace_fg, 'r') as fd:
+    with open(trace_fg, 'r', encoding='utf-8') as fd:
         for line in fd:
             line = line.strip()
             if line.startswith('initf_dm'):
-                func, val = line.split()
+                _, val = line.split()
                 count = int(val)
                 total += count
     return total
 
-check_flamegraph
 @pytest.mark.slow
 @pytest.mark.boardspec('sandbox')
 @pytest.mark.buildconfigspec('trace')