1'virt' Generic Virtual Platform (``virt``) 2========================================== 3 4The `virt` board is a platform which does not correspond to any real hardware; 5it is designed for use in virtual machines. It is the recommended board type 6if you simply want to run a guest such as Linux and do not care about 7reproducing the idiosyncrasies and limitations of a particular bit of 8real-world hardware. 9 10Supported devices 11----------------- 12 13The ``virt`` machine supports the following devices: 14 15* Up to 8 generic RV32GC/RV64GC cores, with optional extensions 16* Core Local Interruptor (CLINT) 17* Platform-Level Interrupt Controller (PLIC) 18* CFI parallel NOR flash memory 19* 1 NS16550 compatible UART 20* 1 Google Goldfish RTC 21* 1 SiFive Test device 22* 8 virtio-mmio transport devices 23* 1 generic PCIe host bridge 24* The fw_cfg device that allows a guest to obtain data from QEMU 25 26Note that the default CPU is a generic RV32GC/RV64GC. Optional extensions 27can be enabled via command line parameters, e.g.: ``-cpu rv64,x-h=true`` 28enables the hypervisor extension for RV64. 29 30Hardware configuration information 31---------------------------------- 32 33The ``virt`` machine automatically generates a device tree blob ("dtb") 34which it passes to the guest, if there is no ``-dtb`` option. This provides 35information about the addresses, interrupt lines and other configuration of 36the various devices in the system. Guest software should discover the devices 37that are present in the generated DTB. 38 39If users want to provide their own DTB, they can use the ``-dtb`` option. 40These DTBs should have the following requirements: 41 42* The number of subnodes of the /cpus node should match QEMU's ``-smp`` option 43* The /memory reg size should match QEMU’s selected ram_size via ``-m`` 44* Should contain a node for the CLINT device with a compatible string 45 "riscv,clint0" if using with OpenSBI BIOS images 46 47Boot options 48------------ 49 50The ``virt`` machine can start using the standard -kernel functionality 51for loading a Linux kernel, a VxWorks kernel, an S-mode U-Boot bootloader 52with the default OpenSBI firmware image as the -bios. It also supports 53the recommended RISC-V bootflow: U-Boot SPL (M-mode) loads OpenSBI fw_dynamic 54firmware and U-Boot proper (S-mode), using the standard -bios functionality. 55 56Running Linux kernel 57-------------------- 58 59Linux mainline v5.12 release is tested at the time of writing. To build a 60Linux mainline kernel that can be booted by the ``virt`` machine in 6164-bit mode, simply configure the kernel using the defconfig configuration: 62 63.. code-block:: bash 64 65 $ export ARCH=riscv 66 $ export CROSS_COMPILE=riscv64-linux- 67 $ make defconfig 68 $ make 69 70To boot the newly built Linux kernel in QEMU with the ``virt`` machine: 71 72.. code-block:: bash 73 74 $ qemu-system-riscv64 -M virt -smp 4 -m 2G \ 75 -display none -serial stdio \ 76 -kernel arch/riscv/boot/Image \ 77 -initrd /path/to/rootfs.cpio \ 78 -append "root=/dev/ram" 79 80To build a Linux mainline kernel that can be booted by the ``virt`` machine 81in 32-bit mode, use the rv32_defconfig configuration. A patch is required to 82fix the 32-bit boot issue for Linux kernel v5.12. 83 84.. code-block:: bash 85 86 $ export ARCH=riscv 87 $ export CROSS_COMPILE=riscv64-linux- 88 $ curl https://patchwork.kernel.org/project/linux-riscv/patch/20210627135117.28641-1-bmeng.cn@gmail.com/mbox/ > riscv.patch 89 $ git am riscv.patch 90 $ make rv32_defconfig 91 $ make 92 93Replace ``qemu-system-riscv64`` with ``qemu-system-riscv32`` in the command 94line above to boot the 32-bit Linux kernel. A rootfs image containing 32-bit 95applications shall be used in order for kernel to boot to user space. 96 97Running U-Boot 98-------------- 99 100U-Boot mainline v2021.04 release is tested at the time of writing. To build an 101S-mode U-Boot bootloader that can be booted by the ``virt`` machine, use 102the qemu-riscv64_smode_defconfig with similar commands as described above for Linux: 103 104.. code-block:: bash 105 106 $ export CROSS_COMPILE=riscv64-linux- 107 $ make qemu-riscv64_smode_defconfig 108 109Boot the 64-bit U-Boot S-mode image directly: 110 111.. code-block:: bash 112 113 $ qemu-system-riscv64 -M virt -smp 4 -m 2G \ 114 -display none -serial stdio \ 115 -kernel /path/to/u-boot.bin 116 117To test booting U-Boot SPL which in M-mode, which in turn loads a FIT image 118that bundles OpenSBI fw_dynamic firmware and U-Boot proper (S-mode) together, 119build the U-Boot images using riscv64_spl_defconfig: 120 121.. code-block:: bash 122 123 $ export CROSS_COMPILE=riscv64-linux- 124 $ export OPENSBI=/path/to/opensbi-riscv64-generic-fw_dynamic.bin 125 $ make qemu-riscv64_spl_defconfig 126 127The minimal QEMU commands to run U-Boot SPL are: 128 129.. code-block:: bash 130 131 $ qemu-system-riscv64 -M virt -smp 4 -m 2G \ 132 -display none -serial stdio \ 133 -bios /path/to/u-boot-spl \ 134 -device loader,file=/path/to/u-boot.itb,addr=0x80200000 135 136To test 32-bit U-Boot images, switch to use qemu-riscv32_smode_defconfig and 137riscv32_spl_defconfig builds, and replace ``qemu-system-riscv64`` with 138``qemu-system-riscv32`` in the command lines above to boot the 32-bit U-Boot. 139