1.. _RISC-V-System-emulator: 2 3RISC-V System emulator 4====================== 5 6QEMU can emulate both 32-bit and 64-bit RISC-V CPUs. Use the 7``qemu-system-riscv64`` executable to simulate a 64-bit RISC-V machine, 8``qemu-system-riscv32`` executable to simulate a 32-bit RISC-V machine. 9 10QEMU has generally good support for RISC-V guests. It has support for 11several different machines. The reason we support so many is that 12RISC-V hardware is much more widely varying than x86 hardware. RISC-V 13CPUs are generally built into "system-on-chip" (SoC) designs created by 14many different companies with different devices, and these SoCs are 15then built into machines which can vary still further even if they use 16the same SoC. 17 18For most boards the CPU type is fixed (matching what the hardware has), 19so typically you don't need to specify the CPU type by hand, except for 20special cases like the ``virt`` board. 21 22Choosing a board model 23---------------------- 24 25For QEMU's RISC-V system emulation, you must specify which board 26model you want to use with the ``-M`` or ``--machine`` option; 27there is no default. 28 29Because RISC-V systems differ so much and in fundamental ways, typically 30operating system or firmware images intended to run on one machine 31will not run at all on any other. This is often surprising for new 32users who are used to the x86 world where every system looks like a 33standard PC. (Once the kernel has booted, most user space software 34cares much less about the detail of the hardware.) 35 36If you already have a system image or a kernel that works on hardware 37and you want to boot with QEMU, check whether QEMU lists that machine 38in its ``-machine help`` output. If it is listed, then you can probably 39use that board model. If it is not listed, then unfortunately your image 40will almost certainly not boot on QEMU. (You might be able to 41extract the file system and use that with a different kernel which 42boots on a system that QEMU does emulate.) 43 44If you don't care about reproducing the idiosyncrasies of a particular 45bit of hardware, such as small amount of RAM, no PCI or other hard 46disk, etc., and just want to run Linux, the best option is to use the 47``virt`` board. This is a platform which doesn't correspond to any 48real hardware and is designed for use in virtual machines. You'll 49need to compile Linux with a suitable configuration for running on 50the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and 51large amounts of RAM. It also supports 64-bit CPUs. 52 53Board-specific documentation 54---------------------------- 55 56Unfortunately many of the RISC-V boards QEMU supports are currently 57undocumented; you can get a complete list by running 58``qemu-system-riscv64 --machine help``, or 59``qemu-system-riscv32 --machine help``. 60 61.. 62 This table of contents should be kept sorted alphabetically 63 by the title text of each file, which isn't the same ordering 64 as an alphabetical sort by filename. 65 66.. toctree:: 67 :maxdepth: 1 68 69 riscv/microchip-icicle-kit 70 riscv/shakti-c 71 riscv/sifive_u 72 riscv/virt 73 74RISC-V CPU firmware 75------------------- 76 77When using the ``sifive_u`` or ``virt`` machine there are three different 78firmware boot options: 79 80* ``-bios default`` 81 82This is the default behaviour if no ``-bios`` option is included. This option 83will load the default OpenSBI firmware automatically. The firmware is included 84with the QEMU release and no user interaction is required. All a user needs to 85do is specify the kernel they want to boot with the ``-kernel`` option 86 87* ``-bios none`` 88 89QEMU will not automatically load any firmware. It is up to the user to load all 90the images they need. 91 92* ``-bios <file>`` 93 94Tells QEMU to load the specified file as the firmware. 95