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

[Yao Zi <me@ziyao.cc>]

On Thu, Jul 30, 2026 at 02:25:31PM +0800, Eric Chung wrote:
> On Wed, Jul 29, 2026 at 11:33 PM Yao Zi <me@ziyao.cc> wrote:
> >
> > 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 checked Rockchip or StarFive's documentation. And I can't find any mention of
> creating a bootable SD card.

Please grep SD in doc/rockchip/rockchip.rst. For StarFive, it seems
the process of creating bootable SDcards has been removed a little
earlier, but in section "Zero Stage BootLoader" of
doc/starfive/jh7110_common.rst, the BROM's behavior is still described.

> > > 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.
> 
> The flashing process must begin with a USB transfer. The vendor's
> proprietary tool is required to download the images to the target
> device. To maintain compatibility with this tool, I need to use the
> same partition table that it expects.

So please make it clear whether the proprietary tool is required for
creating SD-card images, or it's only required for downloading the image
to the SD card. The latter seems impossible since you described how to
flash an image to SD with dd in this documentation.

I'm really confused with your description.

> Currently, the SPL (Secondary Program Loader) only boots U-Boot; it
> has no other function in the boot flow.
> 
> >
> > 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?
> >
> 
> Oh, I missed it. I need to append SPL part.
> 
> > > 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.
> >
> 
> I’m required to use the vendor’s flashing tool, flashserver, for
> programming SD card images — mainly because it’s the only way I can
> properly program the RPMB partition.

But you don't do so in the documentation, dd is used. This wouldn't
program the RPMB partition AFAIK. And does it mean that K1 requires a
SDcard with RPMB support to boot? This doesn't match my experience with
the platform.

> The tool supports both eMMC and SD boot modes, and environment
> variables (ENV) can be stored on either medium. However, it would be
> unusual to boot from an SD card while loading the ENV from eMMC.
> Therefore, the simplest and most consistent approach is to keep the
> same partition layout across all critical components — including FSBL,
> ENV, and OpenSBI partitions — regardless of the boot medium.
> 
> > > 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.
> >
> 
> Mentioned above.

Please quote the text, you do provide an example partition table, but
there's no note describing which partitions are mandatory, and whether
their offsets could be changed.

If a user could only create their own SDcard images by trial and error,
this documentation loses its purpose. Please describe what is mandatory,
or only describe the mandatory parts like Rockchip's documentation.

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

Frankly, I'm really tired of this discussion, I don't think you
understand much of my questions, even though I tried to explain myself
once and once again. And your replies are self-contradictory.

Please make sure you understand my questions and reply with reasonable
answers. I wouldn't continue to review your patches before you resolve
questions in this thread.

Best regards,
Yao Zi