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 <[email protected]> --- doc/arch/powerpc/boot.rst | 2 + doc/arch/powerpc/index.rst | 1 + doc/arch/powerpc/pbl.rst | 145 +++++++++++++++++++++++++++++++++++ doc/arch/powerpc/powerpc.rst | 1 + 4 files changed, 149 insertions(+) create mode 100644 doc/arch/powerpc/pbl.rst diff --git a/doc/arch/powerpc/boot.rst b/doc/arch/powerpc/boot.rst index f72ed8d8304..48f044a3f78 100644 --- a/doc/arch/powerpc/boot.rst +++ b/doc/arch/powerpc/boot.rst @@ -40,6 +40,8 @@ to the build: * 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..a533969d5e6 --- /dev/null +++ b/doc/arch/powerpc/pbl.rst @@ -0,0 +1,145 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2026, Bradley Morgan <[email protected]> + +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 text files that live next to the board code. The +RCW file is a pile of 32 bit words with the preamble and header first, +PBI is a list of address data pairs. 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 672 + +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 0f1f0148252..8ce28569ebe 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
