1 SiFive HiFive Unleashed (``sifive_u``)
2 ======================================
4 SiFive HiFive Unleashed Development Board is the ultimate RISC-V development
5 board featuring the Freedom U540 multi-core RISC-V processor.
10 The ``sifive_u`` machine supports the following devices:
13 * Up to 4 U54 / U34 cores
14 * Core Level Interruptor (CLINT)
15 * Platform-Level Interrupt Controller (PLIC)
16 * Power, Reset, Clock, Interrupt (PRCI)
17 * L2 Loosely Integrated Memory (L2-LIM)
18 * DDR memory controller
20 * 1 GEM Ethernet controller
22 * 1 One-Time Programmable (OTP) memory with stored serial number
25 * 1 ISSI 25WP256 flash
26 * 1 SD card in SPI mode
28 Please note the real world HiFive Unleashed board has a fixed configuration of
29 1 E51 core and 4 U54 core combination and the RISC-V core boots in 64-bit mode.
30 With QEMU, one can create a machine with 1 E51 core and up to 4 U54 cores. It
31 is also possible to create a 32-bit variant with the same peripherals except
32 that the RISC-V cores are replaced by the 32-bit ones (E31 and U34), to help
33 testing of 32-bit guest software.
35 Hardware configuration information
36 ----------------------------------
38 The ``sifive_u`` machine automatically generates a device tree blob ("dtb")
39 which it passes to the guest. This provides information about the addresses,
40 interrupt lines and other configuration of the various devices in the system.
41 Guest software should discover the devices that are present in the generated
42 DTB instead of using a DTB for the real hardware, as some of the devices are
43 not modeled by QEMU and trying to access these devices may cause unexpected
49 The ``sifive_u`` machine can start using the standard -kernel functionality
50 for loading a Linux kernel, a VxWorks kernel, a modified U-Boot bootloader
51 (S-mode) or ELF executable with the default OpenSBI firmware image as the
52 -bios. It also supports booting the unmodified U-Boot bootloader using the
53 standard -bios functionality.
55 Machine-specific options
56 ------------------------
58 The following machine-specific options are supported:
62 The board serial number. When not given, the default serial number 1 is used.
64 SiFive reserves the first 1 KiB of the 16 KiB OTP memory for internal use.
65 The current usage is only used to store the serial number of the board at
66 offset 0xfc. U-Boot reads the serial number from the OTP memory, and uses
67 it to generate a unique MAC address to be programmed to the on-chip GEM
68 Ethernet controller. When multiple QEMU ``sifive_u`` machines are created
69 and connected to the same subnet, they all have the same MAC address hence
70 it creates an unusable network. In such scenario, user should give different
71 values to serial= when creating different ``sifive_u`` machines.
75 When given, QEMU's ROM codes jump to QSPI memory-mapped flash directly.
76 Otherwise QEMU will jump to DRAM or L2LIM depending on the msel= value.
77 When not given, it defaults to direct DRAM booting.
81 Mode Select (MSEL[3:0]) pins value, used to control where to boot from.
83 The FU540 SoC supports booting from several sources, which are controlled
84 using the Mode Select pins on the chip. Typically, the boot process runs
85 through several stages before it begins execution of user-provided programs.
86 These stages typically include the following:
88 1. Zeroth Stage Boot Loader (ZSBL), which is contained in an on-chip mask
89 ROM and provided by QEMU. Note QEMU implemented ROM codes are not the
90 same as what is programmed in the hardware. The QEMU one is a simplified
91 version, but it provides the same functionality as the hardware.
92 2. First Stage Boot Loader (FSBL), which brings up PLLs and DDR memory.
94 3. Second Stage Boot Loader (SSBL), which further initializes additional
95 peripherals as needed. This is U-Boot proper combined with an OpenSBI
96 fw_dynamic firmware image.
98 msel=6 means FSBL and SSBL are both on the QSPI flash. msel=11 means FSBL
99 and SSBL are both on the SD card.
104 Linux mainline v5.10 release is tested at the time of writing. To build a
105 Linux mainline kernel that can be booted by the ``sifive_u`` machine in
106 64-bit mode, simply configure the kernel using the defconfig configuration:
111 $ export CROSS_COMPILE=riscv64-linux-
115 To boot the newly built Linux kernel in QEMU with the ``sifive_u`` machine:
119 $ qemu-system-riscv64 -M sifive_u -smp 5 -m 2G \
120 -display none -serial stdio \
121 -kernel arch/riscv/boot/Image \
122 -initrd /path/to/rootfs.ext4 \
123 -append "root=/dev/ram"
125 To build a Linux mainline kernel that can be booted by the ``sifive_u`` machine
126 in 32-bit mode, use the rv32_defconfig configuration. A patch is required to
127 fix the 32-bit boot issue for Linux kernel v5.10.
132 $ export CROSS_COMPILE=riscv64-linux-
133 $ curl https://patchwork.kernel.org/project/linux-riscv/patch/20201219001356.2887782-1-atish.patra@wdc.com/mbox/ > riscv.patch
135 $ make rv32_defconfig
138 Replace ``qemu-system-riscv64`` with ``qemu-system-riscv32`` in the command
139 line above to boot the 32-bit Linux kernel. A rootfs image containing 32-bit
140 applications shall be used in order for kernel to boot to user space.
142 Running VxWorks kernel
143 ----------------------
145 VxWorks 7 SR0650 release is tested at the time of writing. To build a 64-bit
146 VxWorks mainline kernel that can be booted by the ``sifive_u`` machine, simply
147 create a VxWorks source build project based on the sifive_generic BSP, and a
148 VxWorks image project to generate the bootable VxWorks image, by following the
149 BSP documentation instructions.
151 A pre-built 64-bit VxWorks 7 image for HiFive Unleashed board is available as
152 part of the VxWorks SDK for testing as well. Instructions to download the SDK:
156 $ wget https://labs.windriver.com/downloads/wrsdk-vxworks7-sifive-hifive-1.01.tar.bz2
157 $ tar xvf wrsdk-vxworks7-sifive-hifive-1.01.tar.bz2
158 $ ls bsps/sifive_generic_1_0_0_0/uboot/uVxWorks
160 To boot the VxWorks kernel in QEMU with the ``sifive_u`` machine, use:
164 $ qemu-system-riscv64 -M sifive_u -smp 5 -m 2G \
165 -display none -serial stdio \
166 -nic tap,ifname=tap0,script=no,downscript=no \
167 -kernel /path/to/vxWorks \
168 -append "gem(0,0)host:vxWorks h=192.168.200.1 e=192.168.200.2:ffffff00 u=target pw=vxTarget f=0x01"
170 It is also possible to test 32-bit VxWorks on the ``sifive_u`` machine. Create
171 a 32-bit project to build the 32-bit VxWorks image, and use exact the same
172 command line options with ``qemu-system-riscv32``.
177 U-Boot mainline v2021.01 release is tested at the time of writing. To build a
178 U-Boot mainline bootloader that can be booted by the ``sifive_u`` machine, use
179 the sifive_fu540_defconfig with similar commands as described above for Linux:
183 $ export CROSS_COMPILE=riscv64-linux-
184 $ export OPENSBI=/path/to/opensbi-riscv64-generic-fw_dynamic.bin
185 $ make sifive_fu540_defconfig
187 You will get spl/u-boot-spl.bin and u-boot.itb file in the build tree.
189 To start U-Boot using the ``sifive_u`` machine, prepare an SPI flash image, or
190 SD card image that is properly partitioned and populated with correct contents.
191 genimage_ can be used to generate these images.
193 A sample configuration file for a 128 MiB SD card image is:
197 $ cat genimage_sdcard.cfg
205 partition u-boot-spl {
206 image = "u-boot-spl.bin"
208 partition-type-uuid = 5B193300-FC78-40CD-8002-E86C45580B47
214 partition-type-uuid = 2E54B353-1271-4842-806F-E436D6AF6985
218 SPI flash image has slightly different partition offsets, and the size has to
219 be 32 MiB to match the ISSI 25WP256 flash on the real board:
223 $ cat genimage_spi-nor.cfg
231 partition u-boot-spl {
232 image = "u-boot-spl.bin"
234 partition-type-uuid = 5B193300-FC78-40CD-8002-E86C45580B47
240 partition-type-uuid = 2E54B353-1271-4842-806F-E436D6AF6985
244 Assume U-Boot binaries are put in the same directory as the config file,
245 we can generate the image by:
249 $ genimage --config genimage_<boot_src>.cfg --inputpath .
251 Boot U-Boot from SD card, by specifying msel=11 and pass the SD card image
252 to QEMU ``sifive_u`` machine:
256 $ qemu-system-riscv64 -M sifive_u,msel=11 -smp 5 -m 8G \
257 -display none -serial stdio \
258 -bios /path/to/u-boot-spl.bin \
259 -drive file=/path/to/sdcard.img,if=sd
261 Changing msel= value to 6, allows booting U-Boot from the SPI flash:
265 $ qemu-system-riscv64 -M sifive_u,msel=6 -smp 5 -m 8G \
266 -display none -serial stdio \
267 -bios /path/to/u-boot-spl.bin \
268 -drive file=/path/to/spi-nor.img,if=mtd
270 Note when testing U-Boot, QEMU automatically generated device tree blob is
271 not used because U-Boot itself embeds device tree blobs for U-Boot SPL and
272 U-Boot proper. Hence the number of cores and size of memory have to match
273 the real hardware, ie: 5 cores (-smp 5) and 8 GiB memory (-m 8G).
275 Above use case is to run upstream U-Boot for the SiFive HiFive Unleashed
276 board on QEMU ``sifive_u`` machine out of the box. This allows users to
277 develop and test the recommended RISC-V boot flow with a real world use
278 case: ZSBL (in QEMU) loads U-Boot SPL from SD card or SPI flash to L2LIM,
279 then U-Boot SPL loads the combined payload image of OpenSBI fw_dynamic
280 firmware and U-Boot proper. However sometimes we want to have a quick test
281 of booting U-Boot on QEMU without the needs of preparing the SPI flash or
282 SD card images, an alternate way can be used, which is to create a U-Boot
283 S-mode image by modifying the configuration of U-Boot:
289 then manually select the following configuration in U-Boot:
291 Device Tree Control > Provider of DTB for DT Control > Prior Stage bootloader DTB
293 This lets U-Boot to use the QEMU generated device tree blob. During the build,
294 a build error will be seen below:
299 ./tools/mkimage: Can't open arch/riscv/dts/hifive-unleashed-a00.dtb: No such file or directory
300 ./tools/mkimage: failed to build FIT
301 make: *** [Makefile:1440: u-boot.img] Error 1
303 The above errors can be safely ignored as we don't run U-Boot SPL under QEMU
304 in this alternate configuration.
306 Boot the 64-bit U-Boot S-mode image directly:
310 $ qemu-system-riscv64 -M sifive_u -smp 5 -m 2G \
311 -display none -serial stdio \
312 -kernel /path/to/u-boot.bin
314 It's possible to create a 32-bit U-Boot S-mode image as well.
318 $ export CROSS_COMPILE=riscv64-linux-
319 $ make sifive_fu540_defconfig
322 then manually update the following configuration in U-Boot:
324 Device Tree Control > Provider of DTB for DT Control > Prior Stage bootloader DTB
325 RISC-V architecture > Base ISA > RV32I
326 Boot images > Text Base > 0x80400000
328 Use the same command line options to boot the 32-bit U-Boot S-mode image:
332 $ qemu-system-riscv32 -M sifive_u -smp 5 -m 2G \
333 -display none -serial stdio \
334 -kernel /path/to/u-boot.bin
336 .. _genimage: https://github.com/pengutronix/genimage