Re: [PATCH v2 6/6] hw/riscv: microchip_pfsoc: Rework documentation

[Alistair Francis <alistair23@gmail.com>]

On Tue, Feb 25, 2025 at 10:55 AM Sebastian Huber
<sebastian.huber@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.huber@embedded-brains.de>

Acked-by: Alistair Francis <alistair.francis@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
>