On Tue, Feb 25, 2025 at 10:55 AM Sebastian Huber <sebastian.hu...@embedded-brains.de> wrote: > > Mention that running the HSS no longer works. Document the changed boot > options. Reorder documentation blocks. Update URLs. > > Signed-off-by: Sebastian Huber <sebastian.hu...@embedded-brains.de>
Acked-by: Alistair Francis <alistair.fran...@wdc.com> Alistair > --- > docs/system/riscv/microchip-icicle-kit.rst | 124 +++++++-------------- > 1 file changed, 43 insertions(+), 81 deletions(-) > > diff --git a/docs/system/riscv/microchip-icicle-kit.rst > b/docs/system/riscv/microchip-icicle-kit.rst > index 40798b1aae..9809e94b84 100644 > --- a/docs/system/riscv/microchip-icicle-kit.rst > +++ b/docs/system/riscv/microchip-icicle-kit.rst > @@ -5,10 +5,10 @@ Microchip PolarFire SoC Icicle Kit integrates a PolarFire > SoC, with one > SiFive's E51 plus four U54 cores and many on-chip peripherals and an FPGA. > > For more details about Microchip PolarFire SoC, please see: > -https://www.microsemi.com/product-directory/soc-fpgas/5498-polarfire-soc-fpga > +https://www.microchip.com/en-us/products/fpgas-and-plds/system-on-chip-fpgas/polarfire-soc-fpgas > > The Icicle Kit board information can be found here: > -https://www.microsemi.com/existing-parts/parts/152514 > +https://www.microchip.com/en-us/development-tool/mpfs-icicle-kit-es > > Supported devices > ----------------- > @@ -26,95 +26,48 @@ The ``microchip-icicle-kit`` machine supports the > following devices: > * 2 GEM Ethernet controllers > * 1 SDHC storage controller > > +The memory is set to 1537 MiB by default. A sanity check on RAM size is > +performed in the machine init routine to prompt user to increase the RAM size > +to > 1537 MiB when less than 1537 MiB RAM is detected. > + > Boot options > ------------ > > -The ``microchip-icicle-kit`` machine can start using the standard -bios > -functionality for loading its BIOS image, aka Hart Software Services (HSS_). > -HSS loads the second stage bootloader U-Boot from an SD card. Then a kernel > -can be loaded from U-Boot. It also supports direct kernel booting via the > --kernel option along with the device tree blob via -dtb. When direct kernel > -boot is used, the OpenSBI fw_dynamic BIOS image is used to boot a payload > -like U-Boot or OS kernel directly. > - > -The user provided DTB should have the following requirements: > - > -* The /cpus node should contain at least one subnode for E51 and the number > - of subnodes should match QEMU's ``-smp`` option > -* The /memory reg size should match QEMU’s selected ram_size via ``-m`` > -* Should contain a node for the CLINT device with a compatible string > - "riscv,clint0" > - > -QEMU follows below truth table to select which payload to execute: > - > -===== ========== ========== ======= > --bios -kernel -dtb payload > -===== ========== ========== ======= > - N N don't care HSS > - Y don't care don't care HSS > - N Y Y kernel > -===== ========== ========== ======= > - > -The memory is set to 1537 MiB by default which is the minimum required high > -memory size by HSS. A sanity check on ram size is performed in the machine > -init routine to prompt user to increase the RAM size to > 1537 MiB when less > -than 1537 MiB ram is detected. > - > -Running HSS > ------------ > - > -HSS 2020.12 release is tested at the time of writing. To build an HSS image > -that can be booted by the ``microchip-icicle-kit`` machine, type the > following > -in the HSS source tree: > - > -.. code-block:: bash > - > - $ export CROSS_COMPILE=riscv64-linux- > - $ cp boards/mpfs-icicle-kit-es/def_config .config > - $ make BOARD=mpfs-icicle-kit-es > - > -Download the official SD card image released by Microchip and prepare it for > -QEMU usage: > - > -.. code-block:: bash > - > - $ wget > ftp://ftpsoc.microsemi.com/outgoing/core-image-minimal-dev-icicle-kit-es-sd-20201009141623.rootfs.wic.gz > - $ gunzip > core-image-minimal-dev-icicle-kit-es-sd-20201009141623.rootfs.wic.gz > - $ qemu-img resize > core-image-minimal-dev-icicle-kit-es-sd-20201009141623.rootfs.wic 4G > - > -Then we can boot the machine by: > - > -.. code-block:: bash > - > - $ qemu-system-riscv64 -M microchip-icicle-kit -smp 5 \ > - -bios path/to/hss.bin -sd path/to/sdcard.img \ > - -nic user,model=cadence_gem \ > - -nic tap,ifname=tap,model=cadence_gem,script=no \ > - -display none -serial stdio \ > - -chardev socket,id=serial1,path=serial1.sock,server=on,wait=on \ > - -serial chardev:serial1 > +The ``microchip-icicle-kit`` machine provides some options to run a firmware > +(BIOS) or a kernel image. QEMU follows below truth table to select the > +firmware: > > -With above command line, current terminal session will be used for the first > -serial port. Open another terminal window, and use ``minicom`` to connect the > -second serial port. > +============= =========== ====================================== > +-bios -kernel firmware > +============= =========== ====================================== > +none N this is an error > +none Y the kernel image > +NULL, default N hss.bin > +NULL, default Y opensbi-riscv64-generic-fw_dynamic.bin > +other don't care the BIOS image > +============= =========== ====================================== > > -.. code-block:: bash > +Direct Kernel Boot > +------------------ > > - $ minicom -D unix\#serial1.sock > +Use the ``-kernel`` option to directly run a kernel image. When a direct > +kernel boot is requested, a device tree blob may be specified via the > ``-dtb`` > +option. Unlike other QEMU machines, this machine does not generate a device > +tree for the kernel. It shall be provided by the user. The user provided > DTB > +should meet the following requirements: > > -HSS output is on the first serial port (stdio) and U-Boot outputs on the > -second serial port. U-Boot will automatically load the Linux kernel from > -the SD card image. > +* The ``/cpus`` node should contain at least one subnode for E51 and the > number > + of subnodes should match QEMU's ``-smp`` option. > > -Direct Kernel Boot > ------------------- > +* The ``/memory`` reg size should match QEMU’s selected RAM size via the > ``-m`` > + option. > > -Sometimes we just want to test booting a new kernel, and transforming the > -kernel image to the format required by the HSS bootflow is tedious. We can > -use '-kernel' for direct kernel booting just like other RISC-V machines do. > +* It should contain a node for the CLINT device with a compatible string > + "riscv,clint0". > > -In this mode, the OpenSBI fw_dynamic BIOS image for 'generic' platform is > -used to boot an S-mode payload like U-Boot or OS kernel directly. > +When ``-bios`` is not specified or set to ``default``, the OpenSBI > +``fw_dynamic`` BIOS image for the ``generic`` platform is used to boot an > +S-mode payload like U-Boot or OS kernel directly. > > For example, the following commands show building a U-Boot image from U-Boot > mainline v2021.07 for the Microchip Icicle Kit board: > @@ -146,4 +99,13 @@ CAVEATS: > ``u-boot.bin`` has to be used which does contain one. To use the ELF image, > we need to change to CONFIG_OF_EMBED or CONFIG_OF_PRIOR_STAGE. > > +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. > + > .. _HSS: https://github.com/polarfire-soc/hart-software-services > -- > 2.43.0 >
