On Wed, Sep 30, 2026 at 5:46 PM Conor Dooley <[email protected]> wrote: > > 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. >
Sure, will add in v3. > > +* 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. > ditto > > > direct kernel boot must use > > + ``-dtb`` as described above. > > > > .. _HSS: https://github.com/polarfire-soc/hart-software-services > > -- Regards, Bin
