On Fri, Sep 04, 2026 at 11:57:39PM +0800, Bin Meng wrote: > With all previous changes, the Icicle Kit model is now able to boot > HSS v2024.06 through a Buildroot 2026.05 SD image to U-Boot and Linux. > > Document the tested source versions and exact commands to build HSS > and Buildroot. Include the sparse resize and GPT relocation steps > needed to make the generated SD image usable by QEMU. > > Also describe the RAM and serial setup, boot stages, and remaining > model limitations. > > Signed-off-by: Bin Meng <[email protected]> > --- > > (no changes since v1) > > docs/system/riscv/microchip-icicle-kit.rst | 101 +++++++++++++++++++-- > 1 file changed, 95 insertions(+), 6 deletions(-) > > diff --git a/docs/system/riscv/microchip-icicle-kit.rst > b/docs/system/riscv/microchip-icicle-kit.rst > index 38352cc62b..eeb4ff938c 100644 > --- a/docs/system/riscv/microchip-icicle-kit.rst > +++ b/docs/system/riscv/microchip-icicle-kit.rst > @@ -19,12 +19,15 @@ The ``microchip-icicle-kit`` machine supports the > following devices: > * 4 U54 cores > * Core Level Interruptor (CLINT) > * Platform-Level Interrupt Controller (PLIC) > -* L2 Loosely Integrated Memory (L2-LIM) > +* Loosely Integrated Memory (L2-LIM) > +* L2 cache controller (L2CC) > * DDR memory controller > +* System controller and system services mailbox > * 5 MMUARTs > * 1 DMA controller > * 2 GEM Ethernet controllers > * 1 SDHC storage controller > +* 1 Real-Time Clock > > The machine has a fixed 2 GiB of RAM. Other memory sizes are rejected. > The machine always exposes all five harts. Other CPU counts are rejected. > @@ -101,10 +104,96 @@ CAVEATS: > Running HSS > ----------- > > -The machine ``microchip-icicle-kit`` used to run the Hart Software Services > -(HSS_), however, the HSS development progressed and the QEMU machine > -implementation lacks behind. Currently, running the HSS no longer works. > -There is missing support in the clock and memory controller devices. In > -particular, reading from the SD card does not work. > +The ``microchip-icicle-kit`` machine can boot the Hart Software Services > +(HSS_), which then loads an HSS payload containing U-Boot from an SD card. > +The following flow was tested with HSS v2024.06 and Buildroot 2026.05. > + > +Configure HSS for the ``mpfs-icicle-kit-es`` board using its default > +configuration. QEMU provides the software-visible registers and deterministic > +status consumed by the HSS v2024.06 DDR initialization and training flow; > +it does not model the electrical properties of DDR training. HSS requires > +the RISC-V bare-metal toolchain supplied by Microchip SoftConsole to be > +available in ``PATH``. Build the tested HSS version with: > + > +.. code-block:: bash > + > + $ git clone https://github.com/polarfire-soc/hart-software-services.git > + $ cd hart-software-services > + $ git checkout v2024.06 > + $ make BOARD=mpfs-icicle-kit-es defconfig > + $ make -j$(nproc) BOARD=mpfs-icicle-kit-es > + > +The HSS build creates both the raw wrapper and an eNVM programming image. > QEMU > +needs the complete eNVM image, including the 256-byte boot header added by > the > +Microchip boot mode programmer. Convert the generated Intel HEX file to a raw > +binary image, for example: > + > +.. code-block:: bash > + > + $ riscv64-unknown-elf-objcopy -I ihex -O binary \ > + build/hss-envm-wrapper.mpfs-icicle-kit-es.hex build/hss.bin > + > +Do not pass ``build/hss-envm-wrapper.bin`` directly to QEMU. That file starts > +at eNVM offset 0x100 and does not contain the boot header with the image size > +and per-hart reset vectors. > + > +Build the SD card image with the tested Buildroot version: > + > +.. code-block:: bash > + > + $ git clone https://gitlab.com/buildroot.org/buildroot.git > + $ cd buildroot > + $ git checkout 2026.05 > + $ make microchip_mpfs_icicle_defconfig > + $ make > + > +This produces ``output/images/sdcard.img`` with three GPT partitions: > + > +* An HSS ``payload.bin`` containing U-Boot. > +* A FAT partition containing ``boot.scr`` and the kernel FIT image. > +* An ext4 Linux root filesystem. > + > +The QEMU SD card model requires a power-of-two image size. Make a sparse > +4 GiB working copy and relocate its backup GPT to the new end of the image: > + > +.. code-block:: bash > + > + $ cp --reflink=auto output/images/sdcard.img sdcard.img > + $ truncate -s 4G sdcard.img > + $ sgdisk -e sdcard.img > + $ sgdisk -v sdcard.img > + > +The Icicle Kit firmware device tree in the FIT image describes 2 GiB of RAM, > +matching the machine's fixed RAM size. The command below keeps ``-m 2G`` > +explicit. Attach the image as an SD card and route both board serial ports: > + > +.. code-block:: bash > + > + $ qemu-system-riscv64 \ > + -M microchip-icicle-kit -smp 5 -m 2G \ > + -bios path/to/hss/build/hss.bin \ > + -drive if=sd,file=path/to/sdcard.img,format=raw \ > + -display none \ > + -serial file:hss.log \ > + -serial stdio \ > + -no-reboot > + > +HSS writes to MMUART0, which the command records in ``hss.log``. U-Boot and > +Linux use MMUART1, which remains connected to the terminal. A successful > +boot proceeds through HSS payload loading, U-Boot, the Linux kernel, and the > +login prompt from the root filesystem on the third partition. > + > +Known limitations > +----------------- > + > +* The tested HSS v2024.06 flow contains 2 separate multi-hart startup races > + issues which is still not fixed as of the latest v2026.04 release. A boot > + may therefore stall at the very beginning or after successful DDR training > + during the OpenSBI/U-Boot handoff.
Some symptoms would be nice, so as to differentiate between the known issues and other potential problems. > +* The SD card model requires the raw image size to be a power of two. Keep > + the backup GPT header at the end when resizing the image. > +* The machine does not generate an Icicle Kit device tree. Firmware boot must > + provide one in its payload or FIT image; There's 3 options actually. Either the HSS has one itself, there's one in the HSS payload or the software brings it - be that in a fit image or part of a U-Boot binary. > direct kernel boot must use > + ``-dtb`` as described above. > > .. _HSS: https://github.com/polarfire-soc/hart-software-services > -- > 2.53.0 > >
signature.asc
Description: PGP signature
