[v2] doc: spacemit: add K1 SPL build and test guide

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@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

On 3/27/26 09:14, Guodong Xu wrote:
> 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@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.

Thanks a lot for providing this documentation.

> +
> +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.

Isn't this documentation meant to apply to all K1 boards?

How about:

Connect a 3.3V USB-to-UART cable to the board's UART header (J25 on the 
BPI-F3).

> +Remove all other cables first, then attach UART::

This sentence should precede before "Connect a 3.3V ....".

> +
> +    BPI-F3 top view
> +    +--------------------------------------------------+
> +    |                                                  |
> +    |   J15: USB-C [====]     [FDL] [PWR] [RST]       |
> +    |                                                  |
> +    |                                                  |
> +    |                              J25 (UART header)   |
> +    |                              [TXD] [RXD] [GND]  |
> +    +--------------------------------------------------+

I guess the ragged right border is not intentional.

> +
> +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)

J15 is only the designation on the BPI-F3. A more generic term may be 
needed.

How about:

Power of the board by disconnecting the OTG port (J15 on BPI-F3) and any 
additional power supply (12 V on BPI-F3).

> +2. **Press and hold** the FDL button (see board layout above)
> +3. Reconnect USB Type-C cable while holding the FDL button

How about:

While holding the FDL button use an USB cable to connect the OTG port to 
your host. This cable will be used by fastboot to upload the firmware.

The OTG USB should be detected as

361c:1001 DFU USB download gadget


> +4. Release the FDL button

https://docs.banana-pi.org/en/BPI-F3/GettingStarted_BPI-F3 has additionally:

(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)

> +
> +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

Maybe a minimum tested version of fastboot should be indicated, cf.
https://gist.github.com/orangecms/8624aa82bab4931f787b5eee572f7668

> +   $ sudo fastboot continue
> +
> +Expected Output
> +~~~~~~~~~~~~~~~~
> +
> +After successful SPL boot with DDR initialization, the serial console displays::

At least the first line will be different.

%s/After/During/
%s/displays/shows output like/

> +
> +    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.

Please, move the note to the top of the document so that reader does not 
discover at the end of the process that their board does not boot anymore.

Best regards

Heinrich

> +
> +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>`_

Hi Heinrich, Guodong Xu,

On 3/27/26 10:32, Heinrich Schuchardt wrote:
> Thanks a lot for providing this documentation. 

Yes, I also add my thanks. This is very useful to 
help passing-by random-joe-testers.

>> +Hardware Setup
>> +~~~~~~~~~~~~~~
>> +
>> +**1. UART Connection**
>> +
>> +Connect a 3.3V USB-to-UART cable to the **J25** header on the BPI-F3.
>
> Isn't this documentation meant to apply to all K1 boards?
>
> How about:
>
> Connect a 3.3V USB-to-UART cable to the board's UART header (J25 on 
> the BPI-F3). 


I'd even go a step further, i.e. keep this doc completely board-agnostic

and keep board-specific parts for their own pages. That would mean moving

the "Deploying via USB Fastboot" section out of this document.


This is only IMHO, don't take my personal preference as the maintainers one.


>> +Deploying via USB Fastboot
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +To enter BootROM fastboot mode:
>> +
>> +1. Disconnect USB Type-C cable from J15 (power off)
>
> J15 is only the designation on the BPI-F3. A more generic term may be 
> needed.
>
> How about:
>
> Power of the board by disconnecting the OTG port (J15 on BPI-F3) and 
> any additional power supply (12 V on BPI-F3). 


Maybe just: "Power off the board by unplugging its power supply."


>> +2. **Press and hold** the FDL button (see board layout above)


The FDL button is also probably BPI-F3 specific information, I see picture

of the OrangePi RV2 having a "Boot Key", which may be the equivalent one.


>> +.. 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.
>
> Please, move the note to the top of the document so that reader does 
> not discover at the end of the process that their board does not boot 
> anymore.


Yes, I agree. I missed it, probably out of haste, but still.

Thanks again