docs/system/riscv/virt.rst

   1 'virt' Generic Virtual Platform (``virt``)
   2 ==========================================
   3
   4 The ``virt`` board is a platform which does not correspond to any real hardware;
   5 it is designed for use in virtual machines. It is the recommended board type
   6 if you simply want to run a guest such as Linux and do not care about
   7 reproducing the idiosyncrasies and limitations of a particular bit of
   8 real-world hardware.
   9
  10 Supported devices
  11 -----------------
  12
  13 The ``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
  26 Note that the default CPU is a generic RV32GC/RV64GC. Optional extensions
  27 can be enabled via command line parameters, e.g.: ``-cpu rv64,x-h=true``
  28 enables the hypervisor extension for RV64.
  29
  30 Hardware configuration information
  31 ----------------------------------
  32
  33 The ``virt`` machine automatically generates a device tree blob ("dtb")
  34 which it passes to the guest, if there is no ``-dtb`` option. This provides
  35 information about the addresses, interrupt lines and other configuration of
  36 the various devices in the system. Guest software should discover the devices
  37 that are present in the generated DTB.
  38
  39 If users want to provide their own DTB, they can use the ``-dtb`` option.
  40 These 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
  47 Boot options
  48 ------------
  49
  50 The ``virt`` machine can start using the standard -kernel functionality
  51 for loading a Linux kernel, a VxWorks kernel, an S-mode U-Boot bootloader
  52 with the default OpenSBI firmware image as the -bios. It also supports
  53 the recommended RISC-V bootflow: U-Boot SPL (M-mode) loads OpenSBI fw_dynamic
  54 firmware and U-Boot proper (S-mode), using the standard -bios functionality.
  55
  56 Machine-specific options
  57 ------------------------
  58
  59 The following machine-specific options are supported:
  60
  61 - aclint=[on|off]
  62
  63   When this option is "on", ACLINT devices will be emulated instead of
  64   SiFive CLINT. When not specified, this option is assumed to be "off".
  65
  66 Running Linux kernel
  67 --------------------
  68
  69 Linux mainline v5.12 release is tested at the time of writing. To build a
  70 Linux mainline kernel that can be booted by the ``virt`` machine in
  71 64-bit mode, simply configure the kernel using the defconfig configuration:
  72
  73 .. code-block:: bash
  74
  75   $ export ARCH=riscv
  76   $ export CROSS_COMPILE=riscv64-linux-
  77   $ make defconfig
  78   $ make
  79
  80 To boot the newly built Linux kernel in QEMU with the ``virt`` machine:
  81
  82 .. code-block:: bash
  83
  84   $ qemu-system-riscv64 -M virt -smp 4 -m 2G \
  85       -display none -serial stdio \
  86       -kernel arch/riscv/boot/Image \
  87       -initrd /path/to/rootfs.cpio \
  88       -append "root=/dev/ram"
  89
  90 To build a Linux mainline kernel that can be booted by the ``virt`` machine
  91 in 32-bit mode, use the rv32_defconfig configuration. A patch is required to
  92 fix the 32-bit boot issue for Linux kernel v5.12.
  93
  94 .. code-block:: bash
  95
  96   $ export ARCH=riscv
  97   $ export CROSS_COMPILE=riscv64-linux-
  98   $ curl https://patchwork.kernel.org/project/linux-riscv/patch/20210627135117.28641-1-bmeng.cn@gmail.com/mbox/ > riscv.patch
  99   $ git am riscv.patch
 100   $ make rv32_defconfig
 101   $ make
 102
 103 Replace ``qemu-system-riscv64`` with ``qemu-system-riscv32`` in the command
 104 line above to boot the 32-bit Linux kernel. A rootfs image containing 32-bit
 105 applications shall be used in order for kernel to boot to user space.
 106
 107 Running U-Boot
 108 --------------
 109
 110 U-Boot mainline v2021.04 release is tested at the time of writing. To build an
 111 S-mode U-Boot bootloader that can be booted by the ``virt`` machine, use
 112 the qemu-riscv64_smode_defconfig with similar commands as described above for Linux:
 113
 114 .. code-block:: bash
 115
 116   $ export CROSS_COMPILE=riscv64-linux-
 117   $ make qemu-riscv64_smode_defconfig
 118
 119 Boot the 64-bit U-Boot S-mode image directly:
 120
 121 .. code-block:: bash
 122
 123   $ qemu-system-riscv64 -M virt -smp 4 -m 2G \
 124       -display none -serial stdio \
 125       -kernel /path/to/u-boot.bin
 126
 127 To test booting U-Boot SPL which in M-mode, which in turn loads a FIT image
 128 that bundles OpenSBI fw_dynamic firmware and U-Boot proper (S-mode) together,
 129 build the U-Boot images using riscv64_spl_defconfig:
 130
 131 .. code-block:: bash
 132
 133   $ export CROSS_COMPILE=riscv64-linux-
 134   $ export OPENSBI=/path/to/opensbi-riscv64-generic-fw_dynamic.bin
 135   $ make qemu-riscv64_spl_defconfig
 136
 137 The minimal QEMU commands to run U-Boot SPL are:
 138
 139 .. code-block:: bash
 140
 141   $ qemu-system-riscv64 -M virt -smp 4 -m 2G \
 142       -display none -serial stdio \
 143       -bios /path/to/u-boot-spl \
 144       -device loader,file=/path/to/u-boot.itb,addr=0x80200000
 145
 146 To test 32-bit U-Boot images, switch to use qemu-riscv32_smode_defconfig and
 147 riscv32_spl_defconfig builds, and replace ``qemu-system-riscv64`` with
 148 ``qemu-system-riscv32`` in the command lines above to boot the 32-bit U-Boot.