docs/system/riscv/microchip-icicle-kit.rst

   1 Microchip PolarFire SoC Icicle Kit (``microchip-icicle-kit``)
   2 =============================================================
   3
   4 Microchip PolarFire SoC Icicle Kit integrates a PolarFire SoC, with one
   5 SiFive's E51 plus four U54 cores and many on-chip peripherals and an FPGA.
   6
   7 For more details about Microchip PolarFire SoC, please see:
   8 https://www.microsemi.com/product-directory/soc-fpgas/5498-polarfire-soc-fpga
   9
  10 The Icicle Kit board information can be found here:
  11 https://www.microsemi.com/existing-parts/parts/152514
  12
  13 Supported devices
  14 -----------------
  15
  16 The ``microchip-icicle-kit`` machine supports the following devices:
  17
  18 * 1 E51 core
  19 * 4 U54 cores
  20 * Core Level Interruptor (CLINT)
  21 * Platform-Level Interrupt Controller (PLIC)
  22 * L2 Loosely Integrated Memory (L2-LIM)
  23 * DDR memory controller
  24 * 5 MMUARTs
  25 * 1 DMA controller
  26 * 2 GEM Ethernet controllers
  27 * 1 SDHC storage controller
  28
  29 Boot options
  30 ------------
  31
  32 The ``microchip-icicle-kit`` machine can start using the standard -bios
  33 functionality for loading its BIOS image, aka Hart Software Services (HSS_).
  34 HSS loads the second stage bootloader U-Boot from an SD card. Then a kernel
  35 can be loaded from U-Boot. It also supports direct kernel booting via the
  36 -kernel option along with the device tree blob via -dtb. When direct kernel
  37 boot is used, the OpenSBI fw_dynamic BIOS image is used to boot a payload
  38 like U-Boot or OS kernel directly.
  39
  40 The user provided DTB should have the following requirements:
  41
  42 * The /cpus node should contain at least one subnode for E51 and the number
  43   of subnodes should match QEMU's ``-smp`` option
  44 * The /memory reg size should match QEMU’s selected ram_size via ``-m``
  45 * Should contain a node for the CLINT device with a compatible string
  46   "riscv,clint0"
  47
  48 QEMU follows below truth table to select which payload to execute:
  49
  50 ===== ========== ========== =======
  51 -bios    -kernel       -dtb payload
  52 ===== ========== ========== =======
  53     N          N don't care     HSS
  54     Y don't care don't care     HSS
  55     N          Y          Y  kernel
  56 ===== ========== ========== =======
  57
  58 The memory is set to 1537 MiB by default which is the minimum required high
  59 memory size by HSS. A sanity check on ram size is performed in the machine
  60 init routine to prompt user to increase the RAM size to > 1537 MiB when less
  61 than 1537 MiB ram is detected.
  62
  63 Running HSS
  64 -----------
  65
  66 HSS 2020.12 release is tested at the time of writing. To build an HSS image
  67 that can be booted by the ``microchip-icicle-kit`` machine, type the following
  68 in the HSS source tree:
  69
  70 .. code-block:: bash
  71
  72   $ export CROSS_COMPILE=riscv64-linux-
  73   $ cp boards/mpfs-icicle-kit-es/def_config .config
  74   $ make BOARD=mpfs-icicle-kit-es
  75
  76 Download the official SD card image released by Microchip and prepare it for
  77 QEMU usage:
  78
  79 .. code-block:: bash
  80
  81   $ wget ftp://ftpsoc.microsemi.com/outgoing/core-image-minimal-dev-icicle-kit-es-sd-20201009141623.rootfs.wic.gz
  82   $ gunzip core-image-minimal-dev-icicle-kit-es-sd-20201009141623.rootfs.wic.gz
  83   $ qemu-img resize core-image-minimal-dev-icicle-kit-es-sd-20201009141623.rootfs.wic 4G
  84
  85 Then we can boot the machine by:
  86
  87 .. code-block:: bash
  88
  89   $ qemu-system-riscv64 -M microchip-icicle-kit -smp 5 \
  90       -bios path/to/hss.bin -sd path/to/sdcard.img \
  91       -nic user,model=cadence_gem \
  92       -nic tap,ifname=tap,model=cadence_gem,script=no \
  93       -display none -serial stdio \
  94       -chardev socket,id=serial1,path=serial1.sock,server=on,wait=on \
  95       -serial chardev:serial1
  96
  97 With above command line, current terminal session will be used for the first
  98 serial port. Open another terminal window, and use ``minicom`` to connect the
  99 second serial port.
 100
 101 .. code-block:: bash
 102
 103   $ minicom -D unix\#serial1.sock
 104
 105 HSS output is on the first serial port (stdio) and U-Boot outputs on the
 106 second serial port. U-Boot will automatically load the Linux kernel from
 107 the SD card image.
 108
 109 Direct Kernel Boot
 110 ------------------
 111
 112 Sometimes we just want to test booting a new kernel, and transforming the
 113 kernel image to the format required by the HSS bootflow is tedious. We can
 114 use '-kernel' for direct kernel booting just like other RISC-V machines do.
 115
 116 In this mode, the OpenSBI fw_dynamic BIOS image for 'generic' platform is
 117 used to boot an S-mode payload like U-Boot or OS kernel directly.
 118
 119 For example, the following commands show building a U-Boot image from U-Boot
 120 mainline v2021.07 for the Microchip Icicle Kit board:
 121
 122 .. code-block:: bash
 123
 124   $ export CROSS_COMPILE=riscv64-linux-
 125   $ make microchip_mpfs_icicle_defconfig
 126
 127 Then we can boot the machine by:
 128
 129 .. code-block:: bash
 130
 131   $ qemu-system-riscv64 -M microchip-icicle-kit -smp 5 -m 2G \
 132       -sd path/to/sdcard.img \
 133       -nic user,model=cadence_gem \
 134       -nic tap,ifname=tap,model=cadence_gem,script=no \
 135       -display none -serial stdio \
 136       -kernel path/to/u-boot/build/dir/u-boot.bin \
 137       -dtb path/to/u-boot/build/dir/u-boot.dtb
 138
 139 CAVEATS:
 140
 141 * Check the "stdout-path" property in the /chosen node in the DTB to determine
 142   which serial port is used for the serial console, e.g.: if the console is set
 143   to the second serial port, change to use "-serial null -serial stdio".
 144 * The default U-Boot configuration uses CONFIG_OF_SEPARATE hence the ELF image
 145   ``u-boot`` cannot be passed to "-kernel" as it does not contain the DTB hence
 146   ``u-boot.bin`` has to be used which does contain one. To use the ELF image,
 147   we need to change to CONFIG_OF_EMBED or CONFIG_OF_PRIOR_STAGE.
 148
 149 .. _HSS: https://github.com/polarfire-soc/hart-software-services