The K1 SPL patchset requires DDR firmware integration and FSBL signing steps that are not covered by existing documentation. Add a SoC-level guide so reviewers and developers can build and test on hardware.
Signed-off-by: Guodong Xu <[email protected]> --- v4: - New in series. Folded from standalone v2 doc thread. --- doc/board/spacemit/index.rst | 1 + doc/board/spacemit/k1-spl.rst | 243 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 244 insertions(+) diff --git a/doc/board/spacemit/index.rst b/doc/board/spacemit/index.rst index e7d3d94e459..a5e35ee12ab 100644 --- a/doc/board/spacemit/index.rst +++ b/doc/board/spacemit/index.rst @@ -6,4 +6,5 @@ SpacemiT :maxdepth: 1 bananapi-f3 + k1-spl diff --git a/doc/board/spacemit/k1-spl.rst b/doc/board/spacemit/k1-spl.rst new file mode 100644 index 00000000000..187eed56e8e --- /dev/null +++ b/doc/board/spacemit/k1-spl.rst @@ -0,0 +1,243 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +SpacemiT K1 SPL Build and Test Guide +===================================== + +This guide explains how to build and test U-Boot SPL on SpacemiT K1 based +boards. It covers building SPL with DDR initialization, generating the signed +FSBL image, and deploying via USB fastboot. + +Tested boards: Banana Pi BPI-F3, MusePi Pro. + +.. note:: + + The procedure described here loads SPL into SRAM via USB fastboot and + does not modify the on-board flash, so a power cycle restores the + board's normal boot path. + + At this stage of the patchset, SPL initializes DDR and then halts with + "SPL: Unsupported Boot Device!" because SPI NOR storage support is not + yet available in U-Boot proper. This document will be updated when + U-Boot stage support is ready. + +Prerequisites +~~~~~~~~~~~~~ + +- A SpacemiT K1 board with USB Type-C and UART access +- USB-to-UART adapter (3.3V TTL) +- ``minicom`` or equivalent serial terminal, configured at 115200 8N1 +- ``fastboot`` tool on the host + +Hardware Setup +~~~~~~~~~~~~~~ + +**1. UART Connection** + +Remove all other cables first, then attach UART. Connect a 3.3V +USB-to-UART cable to the board's UART header (J25 on the BPI-F3):: + + BPI-F3 top view + +--------------------------------------------------+ + | | + | J15: USB-C [====] [FDL] [PWR] [RST] | + | | + | | + | J25 (UART header) | + | [TXD] [RXD] [GND] | + +--------------------------------------------------+ + +After UART is connected, attach the USB Type-C cable to the OTG port +(J15 on BPI-F3) to power on. + +**2. Serial Console** + +.. code-block:: console + + $ minicom -D /dev/ttyUSB0 + +Default baudrate: 115200. + +Building U-Boot SPL +~~~~~~~~~~~~~~~~~~~~ + +**1. Obtain the DDR training firmware** + +The DDR training firmware is a proprietary binary provided by SpacemiT. It is +not included in U-Boot and must be downloaded separately from: + +https://github.com/spacemit-com/spacemit-firmware/tree/master/k1/v0.2 + +Download ``ddr_fw.bin`` from that directory. + +This binary is integrated into the SPL image at build time via the binman +framework. When the SPL image is loaded to SRAM (e.g., via USB fastboot), +the SPL executes the DDR firmware from SRAM to perform DDR initialization. + +**2. Obtain OpenSBI fw_dynamic.bin** + +Any pre-built ``fw_dynamic.bin`` is sufficient. Upstream OpenSBI +sources are at https://github.com/riscv-software-src/opensbi if you +need to build one. + +At this stage of the patchset, SPL halts before invoking OpenSBI, +but U-Boot's binman still packages ``fw_dynamic.bin`` into +``u-boot.itb`` and the build fails if it is missing. + +**3. Build SPL** + +.. code-block:: console + + $ export CROSS_COMPILE=riscv64-linux-gnu- + $ export ARCH=riscv + $ export DDR_FW_FILE=$(pwd)/ddr_fw.bin + $ export OPENSBI=/path/to/fw_dynamic.bin + $ make spacemit_k1_defconfig + $ make + +Output: ``u-boot-spl-ddr.bin`` in the build directory. This image contains the +SPL code and the DDR firmware blob packaged together via binman. + +.. note:: + + If ``DDR_FW_FILE`` is not set, the build completes with an empty + placeholder. The resulting SPL will boot but cannot initialize DDR. + +**4. Generate signed FSBL image** + +The K1 BootROM requires a signed first-stage bootloader (FSBL). The signing +tool (``tools/build_binary_file.py``) is in SpacemiT's vendor U-Boot repository: + +.. code-block:: console + + $ git clone -b k1-bl-v2.2.y https://gitee.com/spacemit-buildroot/uboot-2022.10 + +The script uses ``fsbl_ddr.json`` which may not exist by default. If +``fsbl_ddr.json`` does not exist in +``uboot-2022.10/board/spacemit/k1-x/configs/``, +create it by copying ``fsbl.json`` and replacing the reference to +``u-boot-spl.bin`` with ``u-boot-spl-ddr.bin``: + +.. code-block:: console + + $ cd uboot-2022.10/board/spacemit/k1-x/configs + $ cp fsbl.json fsbl_ddr.json + $ sed -i 's/u-boot-spl\.bin/u-boot-spl-ddr.bin/g' fsbl_ddr.json + +Create the ``fsbl.sh`` script below in the ``uboot-2022.10`` directory. +Update the path variables to match your local setup: + +.. code-block:: bash + + #!/bin/sh + MAINLINE_UBOOT_IMG_PATH="{your path}/u-boot" + MAINLINE_SPL_IMG_PATH="{your path}/u-boot/spl" + FSBL_PATH="{your path}/uboot-2022.10/spl_bin" + KEY_TOOL_PATH="{your path}/uboot-2022.10/tools" + CONFIG_PATH="{your path}/uboot-2022.10/board/spacemit/k1-x/configs" + + mkdir -p ${FSBL_PATH} + echo "Clean binaries in ${FSBL_PATH}" + rm -f ${FSBL_PATH}/u-boot-spl-ddr.bin + rm -f ${FSBL_PATH}/u-boot-spl.bin + + if [ ! -d ${MAINLINE_SPL_IMG_PATH} ]; then + MAINLINE_UBOOT_IMG_PATH="{your path}/build" + MAINLINE_SPL_IMG_PATH="{your path}/build/spl" + fi + + # The signing tool reads u-boot-spl-ddr.bin from the path declared in + # fsbl_ddr.json's "source" field, which is resolved relative to the + # JSON file's directory -- i.e. one level up from CONFIG_PATH, not + # FSBL_PATH. Stage the unsigned binary there before signing. + cp ${MAINLINE_UBOOT_IMG_PATH}/u-boot-spl-ddr.bin ${CONFIG_PATH}/../ + python3 ${KEY_TOOL_PATH}/build_binary_file.py \ + -c ${CONFIG_PATH}/fsbl_ddr.json \ + -o ${FSBL_PATH}/FSBL.bin + +Then run: + +.. code-block:: console + + $ chmod +x fsbl.sh + $ ./fsbl.sh + +Output: ``FSBL.bin`` in the ``spl_bin`` directory, ready for deployment. + +Deploying via USB Fastboot +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enter BootROM fastboot mode: + +1. Power off the board by unplugging its power supply. +2. **Press and hold** the FDL button (called "Boot Key" on some boards; + see the board layout above for the BPI-F3). +3. While holding the button, use a USB cable to connect the OTG port to + your host. This cable is also used by fastboot to upload the firmware. +4. Release the button. + +On the host, ``fastboot devices`` should list the board:: + + dfu-device DFU download + +The serial console shows the BootROM's USB download handler trace, +including a line like:: + + usb2d_initialize : enter + +This indicates the board is ready to accept an image via USB. + +.. tip:: + + If you are worried about insufficient USB power, you can first plug + in the power, then release the button, and then plug in the USB + cable. + +On the host: + +.. code-block:: console + + $ sudo fastboot stage FSBL.bin + $ sudo fastboot continue + +Expected Output +~~~~~~~~~~~~~~~~ + +During successful SPL boot with DDR initialization, the serial console +shows output like:: + + <debug_uart> + + U-Boot SPL 2026.04-rc4-00430-g8b84b1ed8ea9 (May 08 2026 - 09:08:27 -0400) + Fail to detect board:-19 + vdd_core, value:900000 + vdd_1v8, value:1800000 + vdd_1v8_mmc, value:1800000 + DDR firmware: [0xc0815840]:0xf0227179, size:0x8d98 + DDR is ready + SPL: Unsupported Boot Device! + SPL: failed to boot from all boot devices + ### ERROR ### Please RESET the board ### + +To walk through the key lines: + +- ``DDR firmware: [...], size:0x8d98`` - DDR firmware loaded successfully +- ``DDR is ready`` - DDR initialization completed +- ``SPL: failed to boot from all boot devices`` - expected at this stage, + confirms that SPL with DDR init is working correctly + +If SPL hangs before printing DDR messages, verify that ``DDR_FW_FILE`` was set +during build and that ``ddr_fw.bin`` is not empty. + +.. tip:: + + To see verbose DDR training output from the DDR firmware (per-phase + training pass/fail logs), add ``#define DEBUG`` at the top of + ``board/spacemit/k1/spl.c`` and rebuild. SPL then passes ``puts`` as + the firmware's log callback; otherwise the callback is ``NULL`` and + the firmware runs silently. + +References +~~~~~~~~~~~ + +- `DDR firmware repository <https://github.com/spacemit-com/spacemit-firmware>`_ +- `SpacemiT vendor U-Boot (signing tool) <https://gitee.com/spacemit-buildroot/uboot-2022.10>`_ -- 2.43.0
