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 <[email protected]> > > --- > 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
