[PATCH v2] doc: spacemit: add K1 SPL build and test guide
Guodong Xu
guodong at riscstar.com
Fri Mar 27 09:14:18 CET 2026
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 <guodong at riscstar.com>
---
Changes in v2:
- Update vendor U-Boot repo from bianbu-linux to spacemit-buildroot,
and specify the k1-bl-v2.2.y branch
- Fix fsbl.json path to board/spacemit/k1-x/configs/
- Add mkdir -p for spl_bin directory in fsbl.sh
- Replace verbose DDR training log with concise SPL boot output
- Update expected output notes for SPI NOR availability
doc/board/spacemit/index.rst | 1 +
doc/board/spacemit/k1-spl.rst | 196 ++++++++++++++++++++++++++++++++++
2 files changed, 197 insertions(+)
create mode 100644 doc/board/spacemit/k1-spl.rst
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..6192cbe32b0
--- /dev/null
+++ b/doc/board/spacemit/k1-spl.rst
@@ -0,0 +1,196 @@
+.. 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.
+
+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**
+
+Connect a 3.3V USB-to-UART cable to the **J25** header on the BPI-F3.
+Remove all other cables first, then attach UART::
+
+ 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 J15 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. Build SPL**
+
+.. code-block:: console
+
+ $ export CROSS_COMPILE=riscv64-linux-gnu-
+ $ export ARCH=riscv
+ $ export DDR_FW_FILE=$(pwd)/ddr_fw.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.
+
+**3. 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
+
+ cp ${MAINLINE_UBOOT_IMG_PATH}/u-boot-spl-ddr.bin ${FSBL_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. Disconnect USB Type-C cable from J15 (power off)
+2. **Press and hold** the FDL button (see board layout above)
+3. Reconnect USB Type-C cable while holding the FDL button
+4. Release the FDL button
+
+The serial console should show a BootROM prompt indicating it is ready to
+accept an image via USB.
+
+On the host:
+
+.. code-block:: console
+
+ $ sudo fastboot stage FSBL.bin
+ $ sudo fastboot continue
+
+Expected Output
+~~~~~~~~~~~~~~~~
+
+After successful SPL boot with DDR initialization, the serial console displays::
+
+ U-Boot SPL 2026.04-rc4-00543-g2ba03a569e61 (Mar 26 2026 - 16:48:44 +0100)
+ Fail to detect board:-2
+ vdd_core, value:900000
+ vdd_1v8, value:1800000
+ vdd_1v8_mmc, value:500000
+ DDR firmware: [0xc08159c0]: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
+
+.. note::
+
+ After DDR init succeeds, SPL proceeds to load U-Boot proper. Since
+ SPI NOR storage driver support is not yet available, SPL cannot
+ transition into U-Boot proper. When U-Boot stage support is ready,
+ this document will be updated.
+
+If SPL hangs before printing DDR messages, verify that ``DDR_FW_FILE`` was set
+during build and that ``ddr_fw.bin`` is not empty.
+
+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
More information about the U-Boot
mailing list