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

[Bradley Morgan <brads@mainlining.org>]

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