Re: [PATCH v12 6/7] doc: spacemit: flash on K1 SoC based boards

[Yao Zi <me@ziyao.cc>]

On Sun, Sep 06, 2026 at 05:11:08PM +0800, Eric Chung wrote:
> Add document on how to flash images into eMMC of K1 SoC based boards.
> 
> Signed-off-by: Eric Chung <eric.chung@riscstar.com>
> 
> ---
> v9:
> - Add to generate the partition table of SD card.
> v3:
> - Add document on how to flash images into SD card.
> ---
>  board/spacemit/k1/MAINTAINERS |   2 +-
>  doc/board/spacemit/index.rst  |   1 +
>  doc/board/spacemit/k1-mmc.rst | 271 ++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 273 insertions(+), 1 deletion(-)

...

> diff --git a/doc/board/spacemit/k1-mmc.rst b/doc/board/spacemit/k1-mmc.rst
> new file mode 100644
> index 000000000000..0be5d5fa1c39
> --- /dev/null
> +++ b/doc/board/spacemit/k1-mmc.rst

...

> +Chapter 2: SD Card Boot
> +=======================
> +
> +
> +SpacemiT K1 Bianbu SD Card Image Flashing and U-Boot Update Guide
> +==================================================================
> +
> +This guide explains how to prepare a bootable SD card with Bianbu OS for
> +SpacemiT K1 based boards and how to replace the U-Boot binary on the SD
> +card with a custom build.
> +
> +Prerequisites
> +~~~~~~~~~~~~~
> +
> +- A SpacemiT K1 based development board
> +- A microSD card (at least 4GB capacity recommended)
> +- A card reader for your host computer
> +- A Linux host system (for ``dd``, ``sgdisk``, ``lsblk`` commands)
> +- The Bianbu release package from
> +  <https://archive.spacemit.com/image/k1/version/bianbu/v2.3.3/Bianbu-Minimal-K1-V2.3.3-20260128183217.zip>
> +- A custom ``FSBL.bin`` and ``u-boot.itb`` file to be written to the U-Boot
> +  partition
> +
> +Prepare the SD Card & the image
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +**1. Obtain the release images**
> +
> +Unpack the release package to get the image files. Replace the ``FSBL.bin``
> +and ``u-boot.itb`` with your custom builds.
> +
> +**2. Identify the SD card device**
> +
> +Insert the microSD card into your card reader, then run:
> +
> +.. code-block:: console
> +
> +   $ lsblk
> +
> +Compare the output before and after inserting the card to identify
> +the new device. It will typically appear as ``/dev/sdb``, ``/dev/sdc``,
> +or ``/dev/mmcblk0``.
> +
> +**3. Write the image to the SD card**
> +
> +Run ``sgdisk`` to generate the partition table, then use ``dd`` to write
> +the images to the corresponding partitions.
> +
> +.. code-block:: console
> +
> +    $sudo sgdisk -o /dev/sdb
> +    $sudo sgdisk -a 128 \
> +        -n 1:256:767 -t 1:8300 \
> +        -n 2:768:895 -t 2:8300 \
> +        -n 3:2048:4095 -t 3:8300 \
> +        -n 4:4096:8191 -t 4:8300 \
> +        -n 5:8192:532479 -t 5:8300 \
> +        -n 6:532480:4726783 -t 6:8300 \
> +        /dev/sdb
> +    $sudo dd if=FSBL.bin of=/dev/sdb1 bs=512 seek=0 status=progress
> +    $sudo dd if=env.bin of=/dev/sdb2 bs=512 seek=0 status=progress
> +    $sudo dd if=fw_dynamic.itb of=/dev/sdb3 bs=512 seek=0 status=progress
> +    $sudo dd if=u-boot.itb of=/dev/sdb4 bs=512 seek=0 status=progress
> +    $sudo dd if=bootfs.img of=/dev/sdb5 bs=1M status=progress
> +    $sudo dd if=rootfs.ext4 of=/dev/sdb6 bs=1M status=progress

The bootfs/rootfs part aren't U-Boot-related stuff, so please omit them
from this documentation to keep it simplified.

Then the only binary we need to extract from the "SpacemiT release
package" is env.bin and fw_dynamic.bin.

For env.bin, I think this U-Boot port depends on no specific environment
setttings? If no, please omit it, too; otherwise please provide a .env
file in upstream U-Boot tree, and make it the default environment to
use.

For fw_dynamic.bin, I think SpacemiT K1 support has been landed in the
upstream OpenSBI tree? Please check if it works with upstream U-Boot.
If no, please try fixing it, and then it's okay to stick to the
downstream OpenSBI, but you need providing a guidance to build it from
source if possible.

Then you could fully omit the step of downloading the "SpacemiT release
package".

> +The SD card is now ready as a bootable system disk.
> +
> +Understanding the SD Card Partition Layout
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The role of each partition:
> +
> ++----------+----------+------------------------------------+
> +| Partition| Size     | Purpose                            |
> ++==========+==========+====================================+
> +| ``sdb1`` | 256 KB   | FSBL (First Stage Bootloader)      |
> ++----------+----------+------------------------------------+
> +| ``sdb2`` | 64 KB    | ENV                                |
> ++----------+----------+------------------------------------+
> +| ``sdb3`` | 1 MB     | OpenSBI                            |
> ++----------+----------+------------------------------------+
> +| ``sdb4`` | 2 MB     | U-Boot binary (``u-boot.itb``)     |
> ++----------+----------+------------------------------------+
> +| ``sdb5`` | 256 MB   | Boot partition (kernel)            |
> ++----------+----------+------------------------------------+
> +| ``sdb6`` | 2 GB     | Root filesystem (ext4)             |
> ++----------+----------+------------------------------------+

...

> +- If the board boots successfully, the new device tree or U-Boot image
> +  is compatible with your hardware.

This sentence looks extra, please drop it.

Best regards,
Yao Zi