[PATCH 0/3] doc: arch/powerpc: add architecture documentation

[PATCH 0/3] doc: arch/powerpc: add architecture documentation

[Bradley Morgan]

There is no proper PowerPC page under doc/arch, everything is in the
README files scattered around the boards. Add an overview, the mpc85xx
boot image layouts and a PBL guide, with the PBL one covering the
practical bits like building, flashing and not bricking the board.

Bradley Morgan (3):
  doc: arch/powerpc: add an overview
  doc: arch/powerpc: document the mpc85xx boot images
  doc: arch/powerpc: add a PBL guide

 doc/arch/index.rst           |   1 +
 doc/arch/powerpc/boot.rst    |  59 ++++++++++++
 doc/arch/powerpc/index.rst   |  12 +++
 doc/arch/powerpc/pbl.rst     | 144 +++++++++++++++++++++++++++++
 doc/arch/powerpc/powerpc.rst | 169 +++++++++++++++++++++++++++++++++++
 5 files changed, 385 insertions(+)
 create mode 100644 doc/arch/powerpc/boot.rst
 create mode 100644 doc/arch/powerpc/index.rst
 create mode 100644 doc/arch/powerpc/pbl.rst
 create mode 100644 doc/arch/powerpc/powerpc.rst

-- 
2.47.3

[PATCH 1/3] doc: arch/powerpc: add an overview

[Bradley Morgan]

PowerPC support is split over three CPU families and the only bits
written down are in the README files next to the boards. Add an arch
page covering the families, the boards, how to build and the config
options people keep asking about.

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

diff --git a/doc/arch/index.rst b/doc/arch/index.rst
index 60c93b3b664..4602aac0571 100644
--- a/doc/arch/index.rst
+++ b/doc/arch/index.rst
@@ -12,6 +12,7 @@ Architecture-specific doc
    m68k
    mips
    nios2
+   powerpc/index
    riscv
    sandbox/index
    sh
diff --git a/doc/arch/powerpc/index.rst b/doc/arch/powerpc/index.rst
new file mode 100644
index 00000000000..bf0c46b9408
--- /dev/null
+++ b/doc/arch/powerpc/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2026, Bradley Morgan <brads@mainlining.org>
+
+PowerPC
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   powerpc
diff --git a/doc/arch/powerpc/powerpc.rst b/doc/arch/powerpc/powerpc.rst
new file mode 100644
index 00000000000..102943383de
--- /dev/null
+++ b/doc/arch/powerpc/powerpc.rst
@@ -0,0 +1,166 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2026, Bradley Morgan <brads@mainlining.org>
+
+PowerPC
+=======
+
+Overview
+--------
+
+U-Boot on PowerPC is always a 32 bit big endian binary, even on the SoCs
+with 64 bit cores (e5500, e6500). The build passes -m32 -melf32ppclinux
+and that is the end of the story.
+
+The port is split by CPU family under arch/powerpc/cpu/:
+
+``mpc8xx``
+   PowerQUICC I. MPC866 and MPC885, CPM and friends.
+
+``mpc83xx``
+   e300 core, which is a 603e derivative. MPC830x, MPC831x, MPC832x,
+   MPC834x, MPC836x and MPC837x.
+
+``mpc85xx``
+   The e500 family: e500v1/v2, e500mc, e5500 and e6500. MPC8544, P1010,
+   P1020, P2020, P2041, T1024, T2080, T4240, that whole crowd.
+
+Stuff shared between mpc83xx and mpc85xx (LAWs, local bus, serdes, I2C, SPI)
+lives in arch/powerpc/cpu/mpc8xxx/.
+
+The PowerPC port is the original one, it came over from PPCBoot. MPC86xx
+was removed in 2026, so patches for it go nowhere.
+
+Supported boards
+----------------
+
+Boards are picked with Kconfig. configs/ has the full list, here are the
+usual suspects:
+
+* MPC8xx: MCR3000 and CMPC885, both from CSSI.
+
+* MPC83xx: CMPCPRO, MPC837XERDB, gazerbeam, and a pile of Keymile boards
+  (kmcoge5ne, kmeter1, kmopti2, kmsupx5, kmtepr2, tuge1, tuxx1).
+
+* MPC85xx: socrates (MPC8544), P1010RDB, P1020RDB, P2041RDB, T1024RDB,
+  T2080QDS, T2080RDB, T4240RDB, Turris 1.x, and qemu-ppce500 if you want
+  to play without hardware.
+
+Some settings still live in include/configs/<board>.h, but the defconfig
+is what actually counts.
+
+Building
+--------
+
+The boring case:
+
+.. code-block:: console
+
+   $ export CROSS_COMPILE=powerpc-linux-gnu-
+   $ make P1020RDB-PC_defconfig
+   $ make
+
+All of them at once:
+
+.. code-block:: console
+
+   $ tools/buildman/buildman powerpc
+
+See :doc:`/build/buildman`. CI builds every PowerPC defconfig and runs the
+test suite on qemu-ppce500, so most breakage shows up there first. See
+:doc:`/develop/ci_testing`.
+
+Toolchains
+----------
+
+The kernel.org crosstool powerpc-linux-gnu toolchains work fine for the
+whole architecture. GCC older than 4.0 is refused by the build, which
+should not surprise anyone in 2026.
+
+CI uses the trini/u-boot-gitlab-ci-runner image.
+
+Configuration options
+---------------------
+
+The ones people actually ask about:
+
+``CONFIG_HIGH_BATS``
+   Turns on BAT registers 4 to 7 where the CPU has them.
+
+``CONFIG_SYS_INIT_RAM_LOCK``
+   Locks part of L1 used for the early stack (MPC83xx, MPC85xx).
+
+``CONFIG_FSL_LBC``
+   Freescale local bus, for SoCs without IFC.
+
+``CONFIG_SYS_SRIO`` and friends
+   Serial RapidIO and booting over it, with CONFIG_SRIO1, CONFIG_SRIO2 and
+   CONFIG_SRIO_PCIE_BOOT_MASTER for the details.
+
+``CONFIG_USE_UBOOTPATH``, ``CONFIG_UBOOTPATH``
+   Sets the default uboot env var, which the default environment scripts
+   use to name the tftp image.
+
+``CONFIG_CACHE_FLUSH_WATCHDOG_THRESHOLD``
+   How many bytes flush_cache() flushes between schedule() calls.
+
+MPC8xx has its own pile:
+
+* CONFIG_MPC866 and CONFIG_MPC885 pick the CPU model.
+
+* CONFIG_SYS_SIUMCR, CONFIG_SYS_SYPCR, CONFIG_SYS_TBSCR, CONFIG_SYS_PISCR,
+  CONFIG_SYS_PLPRCR, CONFIG_SYS_SCCR and CONFIG_SYS_DER set the system
+  interface registers at startup. Get these wrong and you get a very quiet
+  board.
+
+* CONFIG_USB_SOF_UCODE_PATCH and CONFIG_SMC_UCODE_PATCH load CPM
+  microcode, for the CPM15 erratum and parameter RAM relocation.
+
+* CONFIG_CMD_IMMAP adds siuinfo and memcinfo.
+
+MPC85xx:
+
+* CONFIG_CMD_ERRATA, on by default, adds the errata command, which prints
+  the workarounds enabled on the current board.
+
+* CONFIG_SYS_PPC_E500_USE_DEBUG_TLB and CONFIG_SYS_PPC_E500_DEBUG_TLB work
+  around the e500v1/v2 debugger limitations. See doc/README.mpc85xx.
+
+* CONFIG_PPC_SPINTABLE_COMPATIBLE keeps the old spin table around for
+  older OSes, spin_table_compat in the environment flips it at runtime.
+  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.
+
+Device trees
+------------
+
+Most boards use CONFIG_OF_CONTROL with the dts in arch/powerpc/dts/. The
+usual rules apply, see :doc:`/develop/devicetree/control`.
+
+Adding a board
+--------------
+
+Four things:
+
+* a TARGET_* entry in arch/powerpc/cpu/<family>/Kconfig (defconfig selects
+  it), with board specific options coming from board/<vendor>/<board>/Kconfig
+
+* a defconfig in configs/, make savedefconfig is your friend
+
+* board code in board/<vendor>/<board>/
+
+* a dts in arch/powerpc/dts/ if OF_CONTROL is used
+
+No magic here, other architectures do the same.
+
+More reading
+------------
+
+* doc/README.pblimage
+* doc/README.ramboot-ppc85xx
+* doc/README.mpc85xx-sd-spi-boot
+* doc/README.mpc85xx-spin-table
+* doc/README.mpc85xx
+* doc/README.mpc83xx.ddrecc
+* :doc:`/board/emulation/qemu-ppce500`
-- 
2.47.3

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

[Bradley Morgan]

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

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

[Bradley Morgan]

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

Re: [PATCH 0/3] doc: arch/powerpc: add architecture documentation

[Bradley Morgan]

On 30 October 2026 01:49:22 GMT, Bradley Morgan <brads@mainlining.org>
wrote:
>There is no proper PowerPC page under doc/arch, everything is in the
>README files scattered around the boards. Add an overview, the mpc85xx
>boot image layouts and a PBL guide, with the PBL one covering the
>practical bits like building, flashing and not bricking the board.
>
>Bradley Morgan (3):
>  doc: arch/powerpc: add an overview
>  doc: arch/powerpc: document the mpc85xx boot images
>  doc: arch/powerpc: add a PBL guide
>
> doc/arch/index.rst           |   1 +
> doc/arch/powerpc/boot.rst    |  59 ++++++++++++
> doc/arch/powerpc/index.rst   |  12 +++
> doc/arch/powerpc/pbl.rst     | 144 +++++++++++++++++++++++++++++
> doc/arch/powerpc/powerpc.rst | 169 +++++++++++++++++++++++++++++++++++
> 5 files changed, 385 insertions(+)
> create mode 100644 doc/arch/powerpc/boot.rst
> create mode 100644 doc/arch/powerpc/index.rst
> create mode 100644 doc/arch/powerpc/pbl.rst
> create mode 100644 doc/arch/powerpc/powerpc.rst

Self-NAK, wing it and do a V2 and add a new doc with it to make life
betterin the future :)

>
>

--- Thanks!