[PATCH 2/3] doc: arch/powerpc: document the mpc85xx boot images

[Bradley Morgan <brads@mainlining.org>]

Boards boot from NOR, through a PBL image the BootROM runs, or with a
TPL and SPL pair out of NAND, and the image layout changes with each.
Write the layouts and the config options that control them down so
nobody has to figure it out from the linker scripts again.

Signed-off-by: Bradley Morgan <brads@mainlining.org>
---
 doc/arch/powerpc/boot.rst    | 57 ++++++++++++++++++++++++++++++++++++
 doc/arch/powerpc/index.rst   |  1 +
 doc/arch/powerpc/powerpc.rst |  4 ++-
 3 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 doc/arch/powerpc/boot.rst

diff --git a/doc/arch/powerpc/boot.rst b/doc/arch/powerpc/boot.rst
new file mode 100644
index 00000000000..dd01588db18
--- /dev/null
+++ b/doc/arch/powerpc/boot.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2026, Bradley Morgan <brads@mainlining.org>
+
+Boot images on MPC85xx
+======================
+
+There are two boot models and the image layout tells you which one you
+are dealing with.
+
+NOR flash
+---------
+
+U-Boot is linked for CONFIG_TEXT_BASE and u-boot.bin goes straight to
+flash. If the SoC has a boot page (CONFIG_MPC85XX_HAVE_RESET_VECTOR),
+the reset vector sits at the top of the 4K page, 0xfffffffc.
+
+With CONFIG_OF_SEPARATE, binman glues u-boot-dtb.bin together using
+arch/powerpc/dts/u-boot.dtsi. For a RAM image without a reset vector,
+CONFIG_SYS_MPC85XX_NO_RESETVEC throws .resetvec away and moves .bootpg
+up.
+
+RAMBOOT
+-------
+
+RAMBOOT means the BootROM loads the image for you. Depending on the
+board that is SD, SPI or NAND, and the defconfig name says which:
+
+* P2041RDB_SDCARD_defconfig, P2041RDB_SPIFLASH_defconfig
+* T1024RDB_SDCARD_defconfig, T1024RDB_SPIFLASH_defconfig,
+  T1024RDB_NAND_defconfig
+* T2080RDB_SDCARD_defconfig, T2080RDB_SPIFLASH_defconfig,
+  T2080RDB_NAND_defconfig
+
+These select CONFIG_RAMBOOT_PBL and build a PBL image instead of a plain
+u-boot.bin:
+
+* u-boot.pbl, when U-Boot proper is the only stage
+* u-boot-with-spl-pbl.bin, when CONFIG_SPL_FSL_PBL is set and an SPL runs
+  first
+
+NAND
+----
+
+Some P1010 and P1020 boards boot from NAND with a TPL in L2 SRAM that
+sets up DDR, then an SPL that loads U-Boot proper. That is the
+CONFIG_TPL and CONFIG_SPL_INIT_MINIMAL setup in the _NAND defconfigs.
+
+SPL builds in general also produce u-boot-with-spl.bin, which is SPL
+plus U-Boot proper padded to CONFIG_SPL_PAD_TO.
+
+SD and SPI, the other way
+-------------------------
+
+The BootROM also handles raw SD and SPI images that carry their own boot
+sector. Either let CONFIG_FSL_PREPBL_ESDHC_BOOT_SECTOR prepend one for
+eSDHC, or use the external boot_format tool. See
+doc/README.mpc85xx-sd-spi-boot and doc/README.ramboot-ppc85xx.
diff --git a/doc/arch/powerpc/index.rst b/doc/arch/powerpc/index.rst
index bf0c46b9408..bfeeb1ed2bb 100644
--- a/doc/arch/powerpc/index.rst
+++ b/doc/arch/powerpc/index.rst
@@ -8,3 +8,4 @@ PowerPC
    :maxdepth: 2
 
    powerpc
+   boot
diff --git a/doc/arch/powerpc/powerpc.rst b/doc/arch/powerpc/powerpc.rst
index 102943383de..1bc5f629ce3 100644
--- a/doc/arch/powerpc/powerpc.rst
+++ b/doc/arch/powerpc/powerpc.rst
@@ -130,7 +130,8 @@ MPC85xx:
   See doc/README.mpc85xx-spin-table.
 
 * CONFIG_MPC85XX_HAVE_RESET_VECTOR, CONFIG_SYS_MPC85XX_NO_RESETVEC and
-  CONFIG_FSL_PREPBL_ESDHC_BOOT_SECTOR are the image layout knobs.
+  CONFIG_FSL_PREPBL_ESDHC_BOOT_SECTOR are the image layout knobs, they
+  are explained in :doc:`/arch/powerpc/boot`.
 
 Device trees
 ------------
@@ -157,6 +158,7 @@ No magic here, other architectures do the same.
 More reading
 ------------
 
+* :doc:`/arch/powerpc/boot`
 * doc/README.pblimage
 * doc/README.ramboot-ppc85xx
 * doc/README.mpc85xx-sd-spi-boot
-- 
2.47.3