1Microchip PolarFire SoC Icicle Kit (``microchip-icicle-kit``)
2=============================================================
3
4Microchip PolarFire SoC Icicle Kit integrates a PolarFire SoC, with one
5SiFive's E51 plus four U54 cores and many on-chip peripherals and an FPGA.
6
7For more details about Microchip PolarFire SoC, please see:
8https://www.microsemi.com/product-directory/soc-fpgas/5498-polarfire-soc-fpga
9
10The Icicle Kit board information can be found here:
11https://www.microsemi.com/existing-parts/parts/152514
12
13Supported devices
14-----------------
15
16The ``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
29Boot options
30------------
31
32The ``microchip-icicle-kit`` machine can start using the standard -bios
33functionality for loading its BIOS image, aka Hart Software Services (HSS_).
34HSS loads the second stage bootloader U-Boot from an SD card. Then a kernel
35can 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
37boot is used, the OpenSBI fw_dynamic BIOS image is used to boot a payload
38like U-Boot or OS kernel directly.
39
40The 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
48QEMU 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
58The memory is set to 1537 MiB by default which is the minimum required high
59memory size by HSS. A sanity check on ram size is performed in the machine
60init routine to prompt user to increase the RAM size to > 1537 MiB when less
61than 1537 MiB ram is detected.
62
63Running HSS
64-----------
65
66HSS 2020.12 release is tested at the time of writing. To build an HSS image
67that can be booted by the ``microchip-icicle-kit`` machine, type the following
68in 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
76Download the official SD card image released by Microchip and prepare it for
77QEMU 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
85Then 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
97With above command line, current terminal session will be used for the first
98serial port. Open another terminal window, and use ``minicom`` to connect the
99second serial port.
100
101.. code-block:: bash
102
103  $ minicom -D unix\#serial1.sock
104
105HSS output is on the first serial port (stdio) and U-Boot outputs on the
106second serial port. U-Boot will automatically load the Linux kernel from
107the SD card image.
108
109Direct Kernel Boot
110------------------
111
112Sometimes we just want to test booting a new kernel, and transforming the
113kernel image to the format required by the HSS bootflow is tedious. We can
114use '-kernel' for direct kernel booting just like other RISC-V machines do.
115
116In this mode, the OpenSBI fw_dynamic BIOS image for 'generic' platform is
117used to boot an S-mode payload like U-Boot or OS kernel directly.
118
119For example, the following commands show building a U-Boot image from U-Boot
120mainline 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
127Then 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
139CAVEATS:
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
150