Re: [PATCH v6 09/11] doc: spacemit: flash on K1 SoC based boards

[Yao Zi <me@ziyao.cc>]

On Wed, Jul 29, 2026 at 09:49:26PM +0800, Eric Chung wrote:
> On Tue, Jul 28, 2026 at 5:45 PM Yao Zi <me@ziyao.cc> wrote:
> >
> > On Tue, Jul 28, 2026 at 08:53:02AM +0800, Eric Chung wrote:
> > > On Tue, Jul 28, 2026 at 1:26 AM Yao Zi <me@ziyao.cc> wrote:
> > > >
> > > > On Mon, Jul 27, 2026 at 02:59:11PM +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>
> > > > >
> > > > > ---
> > > > > 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 | 320 ++++++++++++++++++++++++++++++++++++++++++
> > > > >  3 files changed, 322 insertions(+), 1 deletion(-)
> > > >
> > > > ...
> > > >
> > > > > diff --git a/doc/board/spacemit/k1-mmc.rst b/doc/board/spacemit/k1-mmc.rst
> > > > > new file mode 100644
> > > > > index 00000000000..b0fe78c75ce
> > > > > --- /dev/null
> > > > > +++ b/doc/board/spacemit/k1-mmc.rst
> > > > > @@ -0,0 +1,320 @@
> > > >
> > > > ...
> > > >
> > > > > +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 8 GB capacity recommended)
> > > > > +- A card reader for your host computer
> > > > > +- A Linux host system (for ``dd``, ``fdisk``, ``lsblk`` commands)
> > > > > +- The Bianbu SD card image from
> > > > > +   <https://spacemit.com/community/resources-download/Images%20Collects/K1/Bianbu>
> > > > > +- A custom ``u-boot.itb`` file (device tree blob or U-Boot FIT image) to be
> > > > > +  written to the U-Boot partition
> > > > > +
> > > > > +Prepare the SD Card & the image
> > > > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > > > +
> > > > > +**1. Download the image**
> > > > > +
> > > > > +Download the released package from the official SpacemiT website:
> > > > > +
> > > > > +<https://archive.spacemit.com/image/k1/version/bianbu/v2.3.5/Bianbu-Minimal-K1-sdcard-V2.3.5-20260601180942.img.zip>
> > > > > +
> > > > > +**2. Extract the image**
> > > > > +
> > > > > +.. code-block:: console
> > > > > +
> > > > > +   $ unzip Bianbu-Minimal-K1-sdcard-V2.3.5-20260601180942.img.zip
> > > > > +
> > > > > +**3. 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``.
> > > > > +
> > > > > +**4. Write the image to the SD card**
> > > > > +
> > > > > +.. code-block:: console
> > > > > +
> > > > > +   $ sudo dd if=./Bianbu-Minimal-K1-sdcard-V2.3.5-20260601180942.img of=/dev/sdb bs=1M status=progress
> > > > > +
> > > > > +The SD card is now ready as a bootable Bianbu system disk.
> > > >
> > > > This looks out of scope of describing how to create a bootable SD card
> > > > with U-Boot. In my opinion, you'd better describe the requirements of
> > > > parition layout and image position for SD-card booting, to allow readers
> > > > to create their own images/bootable medium from scratch more easily,
> > > > instead of sticking to the vendored image.
> > > >
> > >
> > > Creating a bootable SD card from scratch would be valuable, but I'll address
> > > it later due to time constraints.
> >
> > In case I didn't make myself clear enough, the documentation *SHOULD*
> > describe how to create bootable devices from scratch, instead of
> > alternating an existing OS image to use mainline U-Boot. I don't think
> > the current documentation helps much for downstream users/distributions
> > to adapt U-Boot for their own use cases, or at least it could be written
> > in a much more clear, vendor-neutral way.
> >
> > So here's my NAK for this patch. I'm not sure what you mean by "time
> > constraints", but please keep submitted patches in a good shape.
> >

In case that I still didn't make myself clear enough, by "bootable SD
card", I mean a minimal medium with only a bootable U-Boot, you could
refer to Rockchip or StarFive's documentation.

> I’m not sure why the documentation insists on walking users through creating a
> bootable SD card from scratch, especially when, at this stage, it
> still depends on
> the vendor’s tools.

Please explain which tools it depends on. Now U-Boot for your platform
already has its SPL ported, and according to your instructions of
replacing the vendor U-Boot, it seems no extra post-processing is
required for the SoC to identify it.

And after re-reading the documentation, it seems you don't make use of
the upstream SPL when creating the SD-card image, is this intended, and
why?

> In practice, we’re required to use the vendor’s
> flashing tool for
> both eMMC and SD devices,

Please explain the constraints, it's okay to depend on vendor's tools,
but for creating a SD-card image, I couldn't come up with a reason to
do so, at least by inferring from the current documentation.

> and we must adhere to the provided partition table.

Thus please clearly describe which part of the partition table must be
preserved for the SoC to boot.

> If users prefer to define their own partition layout, nothing prevents
> them from doing
> so on their own. That’s entirely up to them.
> 
> The default SD image already includes the vendor’s U-Boot. My
> instructions simply
> explain how to replace it with the upstream version—nothing more.

Best regards,
Yao Zi