Nothing explains what runs between reset and the prompt, and porting a board is scattered over whatever README a sibling board happens to have. Add a page with the boot flow, booting a kernel and the file by file porting steps.
Signed-off-by: Bradley Morgan <[email protected]> --- doc/arch/powerpc/index.rst | 1 + doc/arch/powerpc/porting.rst | 78 ++++++++++++++++++++++++++++++++++++ doc/arch/powerpc/powerpc.rst | 4 +- 3 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 doc/arch/powerpc/porting.rst diff --git a/doc/arch/powerpc/index.rst b/doc/arch/powerpc/index.rst index 0663b305af3..66bffaa9270 100644 --- a/doc/arch/powerpc/index.rst +++ b/doc/arch/powerpc/index.rst @@ -10,3 +10,4 @@ PowerPC powerpc boot pbl + porting diff --git a/doc/arch/powerpc/porting.rst b/doc/arch/powerpc/porting.rst new file mode 100644 index 00000000000..de4c0e8f525 --- /dev/null +++ b/doc/arch/powerpc/porting.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2026, Bradley Morgan <[email protected]> + +Booting and porting +=================== + +How it boots +------------ + +On a NOR boot the CPU comes out of reset in the top 4K boot page, at +CFG_RESET_VECTOR_ADDRESS. That page holds .bootpg from start.S and +.resetvec from resetvec.S. From there: + +* start.S sets up the early TLB and a stack and calls cpu_init_f for the + early CPU and memory controller setup + +* board_init_f runs the init sequence, brings DRAM up (or just sizes it + on RAMBOOT) and picks where to relocate to, then calls relocate_code + +* U-Boot carries on from DDR, board_init_r brings up the rest and you get + a prompt + +On RAMBOOT boards the BootROM has already applied the RCW and the PBI and +loads the image for you, see :doc:`/arch/powerpc/pbl`. Where an SPL runs +first it brings DRAM up and loads U-Boot proper, and the P1010 and P1020 +NAND boards push the DDR init down into a TPL instead. The image layouts +are in :doc:`/arch/powerpc/boot`. + +Booting a kernel +---------------- + +Nothing special, the board READMEs have the usual recipe. P2041RDB: + +.. code-block:: console + + => tftp 1000000 uImage + => tftp 2000000 rootfs.ext2.gz.uboot + => tftp 3000000 p2041rdb.dtb + => bootm 1000000 2000000 3000000 + +The rest is normal U-Boot business, see :doc:`/usage/cmd/bootm` and +:doc:`/develop/bootstd/index`. + +Porting a board +--------------- + +Start from the board that is closest to yours, same SoC and same boot +medium, and clone the pieces: + +* a TARGET_FOO entry in arch/powerpc/cpu/<family>/Kconfig, with the + ARCH_MPCxxxx select for the SoC, SUPPORT_SPL or SUPPORT_TPL if you need + them, and a source line for the board Kconfig + +* board/<vendor>/<board>/ with a Kconfig (SYS_BOARD, SYS_VENDOR and + SYS_CONFIG_NAME), the Makefile, board code with board_early_init_f and + friends, and ddr.c + +* include/configs/<board>.h, or the shared one a sibling board uses, for + whatever has not moved to Kconfig yet + +* a defconfig in configs/: cp the closest one to configs/<board>_defconfig, + make <board>_defconfig, tweak it, make savedefconfig and copy the result + back + +* a dts in arch/powerpc/dts/, added to a dtb-$(CONFIG_TARGET_FOO) line in + the Makefile, with CONFIG_DEFAULT_DEVICE_TREE pointing at it + +The fiddly bits are CONFIG_TEXT_BASE, the DDR timings, the boot medium and +the RCW and SerDes protocol. Copy them from the evalkit board and only +change what the schematic says is different. + +First boot +---------- + +Do not flash until the image runs from RAM. Load it over JTAG, or tftp it +from a U-Boot that already works and run it, same as :doc:`/arch/powerpc/pbl` +says. If nothing comes out of the serial port, check the baud rate, the +boot switch, the RCW and the DDR setup, in that order. diff --git a/doc/arch/powerpc/powerpc.rst b/doc/arch/powerpc/powerpc.rst index 8ce28569ebe..8ee4f19870b 100644 --- a/doc/arch/powerpc/powerpc.rst +++ b/doc/arch/powerpc/powerpc.rst @@ -153,13 +153,15 @@ Four things: * a dts in arch/powerpc/dts/ if OF_CONTROL is used -No magic here, other architectures do the same. +No magic here, other architectures do the same. The long version, with +the files and the commands, is in :doc:`/arch/powerpc/porting`. More reading ------------ * :doc:`/arch/powerpc/boot` * :doc:`/arch/powerpc/pbl` +* :doc:`/arch/powerpc/porting` * doc/README.pblimage * doc/README.ramboot-ppc85xx * doc/README.mpc85xx-sd-spi-boot -- 2.47.3
