[PATCH 3/3] doc: arch/powerpc: add a PBL guide

[Bradley Morgan <brads@mainlining.org>]

The PBL side is the fun part and most of it lives in people's heads.
Explain what the RCW and PBI files are, how to build and flash the
image, what to watch out for before somebody bricks their board, and
what it takes to add PBL support for a new one.

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

diff --git a/doc/arch/powerpc/boot.rst b/doc/arch/powerpc/boot.rst
index dd01588db18..f56ce6b1712 100644
--- a/doc/arch/powerpc/boot.rst
+++ b/doc/arch/powerpc/boot.rst
@@ -38,6 +38,8 @@ u-boot.bin:
 * u-boot-with-spl-pbl.bin, when CONFIG_SPL_FSL_PBL is set and an SPL runs
   first
 
+Poking at those images has its own page, see :doc:`/arch/powerpc/pbl`.
+
 NAND
 ----
 
diff --git a/doc/arch/powerpc/index.rst b/doc/arch/powerpc/index.rst
index bfeeb1ed2bb..0663b305af3 100644
--- a/doc/arch/powerpc/index.rst
+++ b/doc/arch/powerpc/index.rst
@@ -9,3 +9,4 @@ PowerPC
 
    powerpc
    boot
+   pbl
diff --git a/doc/arch/powerpc/pbl.rst b/doc/arch/powerpc/pbl.rst
new file mode 100644
index 00000000000..6a4ca5c8fc1
--- /dev/null
+++ b/doc/arch/powerpc/pbl.rst
@@ -0,0 +1,144 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2026, Bradley Morgan <brads@mainlining.org>
+
+Playing with PBL images
+=======================
+
+What this thing is
+------------------
+
+PBL (pre boot loader) is what the QorIQ BootROM deals with on the way to
+U-Boot. The image starts with a PBL preamble, then the RCW (reset
+configuration word), then a list of PBI (pre boot initialization)
+commands, then U-Boot itself. The BootROM applies the RCW and the PBI
+commands, then jumps into U-Boot.
+
+The RCW and PBI are just text files full of "address data" pairs and
+they live next to the board code. For example:
+
+* board/nxp/p2041rdb/p2041rdb_rcw_sd.cfg and board/nxp/p2041rdb/pbi.cfg
+* board/nxp/t102xrdb/t1024_sd_rcw.cfg and board/nxp/t102xrdb/t1024_pbi.cfg
+* board/nxp/t208xrdb/t2080_sd_rcw.cfg and board/nxp/t208xrdb/t2080_pbi.cfg
+
+The RCW file kicks off with the preamble and a header, then the RCW
+words:
+
+.. code-block:: none
+
+   #PBL preamble and RCW header for T1024RDB
+   aa55aa55 010e0100
+   #SerDes Protocol: 0x95
+   #Core/DDR: 1400Mhz/1600MT/s with single source clock
+   0810000c 00000000 00000000 00000000
+   4a800003 80000012 6c027000 21000000
+
+PBI is a straight list of register writes:
+
+.. code-block:: none
+
+   #PBI commands
+   #Configure CPC1 as 256KB SRAM
+   09010100 00000000
+   09010104 fffc0007
+
+Building one
+------------
+
+The defconfig points at both files:
+
+.. code-block:: none
+
+   CONFIG_SYS_FSL_PBL_RCW="board/nxp/p2041rdb/p2041rdb_rcw_sd.cfg"
+   CONFIG_SYS_FSL_PBL_PBI="board/nxp/p2041rdb/pbi.cfg"
+
+and a normal build takes it from there:
+
+.. code-block:: console
+
+   $ make P2041RDB_SDCARD_defconfig
+   $ make
+
+You get u-boot.pbl. On boards that build an SPL too, CONFIG_SPL_FSL_PBL
+switches the output to u-boot-with-spl-pbl.bin: the SPL runs first and
+sets up DDR, then U-Boot proper comes along. With secure boot
+(CONFIG_NXP_ESBC) u-boot.pbl is not built automatically, that image has
+to be built and signed separately.
+
+Flashing it
+-----------
+
+The offsets people actually use:
+
+SPI flash, offset 0:
+
+.. code-block:: none
+
+   => tftp 1000000 u-boot.pbl
+   => sf probe 0
+   => sf erase 0 100000
+   => sf write 1000000 0 $filesize
+
+SD/MMC, offset 0x1000, which is block 8:
+
+.. code-block:: none
+
+   => tftp 1000000 u-boot.pbl
+   => mmc info
+   => mmc write 1000000 8 441
+
+NAND, offset 0:
+
+.. code-block:: none
+
+   => tftp 1000000 u-boot.pbl
+   => nand erase 0 100000
+   => nand write 1000000 0 $filesize
+
+The block count for mmc write and the erase sizes depend on the image
+size and the flash geometry, adjust them for your board. The board
+README files have working numbers, for example
+board/nxp/p2041rdb/README.rst.
+
+Having fun with it
+------------------
+
+Things worth knowing before poking at the RCW:
+
+* The RCW sets the SerDes protocols and the clock setup. Change it wrong
+  and the board comes up dead with no console to tell you why. Keep a way
+  back in, either a boot switch to another medium or JTAG.
+
+* PBI is just register writes, so setting up an extra LAW or bringing an
+  I2C device out of reset before U-Boot starts is a one liner. Watch the
+  addresses, a stray write can take the boot down just as fast.
+
+* Try the image from RAM first. tftp it and run it from an already
+  running U-Boot, or load it over JTAG. A dead SPI flash is a lot less
+  fun than a dead RAM image.
+
+* No board at hand? qemu-ppce500 runs U-Boot fine, no PBL involved, see
+  :doc:`/board/emulation/qemu-ppce500`.
+
+Adding PBL support for a board
+------------------------------
+
+* copy the RCW and PBI files from a board with the same SoC and boot
+  medium into board/<vendor>/<board>/
+
+* set CONFIG_SYS_FSL_PBL_RCW and CONFIG_SYS_FSL_PBL_PBI in the defconfig
+  to point at them
+
+* turn on CONFIG_RAMBOOT_PBL and pick the boot medium in the defconfig
+
+* decide if you want an SPL stage. Without CONFIG_SPL_FSL_PBL the image
+  is a single u-boot.pbl and U-Boot runs from whatever memory the PBI
+  set up. With it, u-boot-with-spl-pbl.bin has the SPL doing DDR init and
+  U-Boot proper running from DDR.
+
+* check CONFIG_TEXT_BASE. Do not just copy it from another board, the
+  single image case usually runs from on chip SRAM.
+
+* try it over JTAG or tftp before writing it to the real medium
+
+doc/README.pblimage has the image format details and the older flashing
+examples.
diff --git a/doc/arch/powerpc/powerpc.rst b/doc/arch/powerpc/powerpc.rst
index 1bc5f629ce3..c058d519dd0 100644
--- a/doc/arch/powerpc/powerpc.rst
+++ b/doc/arch/powerpc/powerpc.rst
@@ -159,6 +159,7 @@ More reading
 ------------
 
 * :doc:`/arch/powerpc/boot`
+* :doc:`/arch/powerpc/pbl`
 * doc/README.pblimage
 * doc/README.ramboot-ppc85xx
 * doc/README.mpc85xx-sd-spi-boot
-- 
2.47.3