On Wed, Jul 29, 2026 at 11:33 PM Yao Zi <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> > > > > > > > > > > > > --- > > > > > > 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. > > 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. 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. 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. > > 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
