@samitouri / QOSamiQemu
Code Commits Issues Pulls Sessions CI/CD
master
master
rst 128 lines 5.04 KB
Raw
1 .. _RISC-V-System-emulator:
2
3 RISC-V System emulator
4 ======================
5
6 QEMU 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
10 QEMU has generally good support for RISC-V guests. It has support for
11 several different machines. The reason we support so many is that
12 RISC-V hardware is much more widely varying than x86 hardware. RISC-V
13 CPUs are generally built into "system-on-chip" (SoC) designs created by
14 many different companies with different devices, and these SoCs are
15 then built into machines which can vary still further even if they use
16 the same SoC.
17
18 For most boards the CPU type is fixed (matching what the hardware has),
19 so typically you don't need to specify the CPU type by hand, except for
20 special cases like the ``virt`` board.
21
22 Choosing a board model
23 ----------------------
24
25 For QEMU's RISC-V system emulation, you must specify which board
26 model you want to use with the ``-M`` or ``--machine`` option;
27 there is no default.
28
29 Because RISC-V systems differ so much and in fundamental ways, typically
30 operating system or firmware images intended to run on one machine
31 will not run at all on any other. This is often surprising for new
32 users who are used to the x86 world where every system looks like a
33 standard PC. (Once the kernel has booted, most user space software
34 cares much less about the detail of the hardware.)
35
36 If you already have a system image or a kernel that works on hardware
37 and you want to boot with QEMU, check whether QEMU lists that machine
38 in its ``-machine help`` output. If it is listed, then you can probably
39 use that board model. If it is not listed, then unfortunately your image
40 will almost certainly not boot on QEMU. (You might be able to
41 extract the file system and use that with a different kernel which
42 boots on a system that QEMU does emulate.)
43
44 If you don't care about reproducing the idiosyncrasies of a particular
45 bit of hardware, such as small amount of RAM, no PCI or other hard
46 disk, 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
48 real hardware and is designed for use in virtual machines. You'll
49 need to compile Linux with a suitable configuration for running on
50 the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and
51 large amounts of RAM. It also supports 64-bit CPUs.
52
53 Board-specific documentation
54 ----------------------------
55
56 Unfortunately many of the RISC-V boards QEMU supports are currently
57 undocumented; 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/k230
70 riscv/microblaze-v-generic
71 riscv/microchip-icicle-kit
72 riscv/mips
73 riscv/shakti-c
74 riscv/sifive_u
75 riscv/tt_atlantis
76 riscv/virt
77 riscv/xiangshan-kunminghu
78
79 RISC-V CPU firmware
80 -------------------
81
82 When using the ``sifive_u`` or ``virt`` machine there are three different
83 firmware boot options:
84
85 * ``-bios default``
86
87 This is the default behaviour if no ``-bios`` option is included. This option
88 will load the default OpenSBI firmware automatically. The firmware is included
89 with the QEMU release and no user interaction is required. All a user needs to
90 do is specify the kernel they want to boot with the ``-kernel`` option
91
92 * ``-bios none``
93
94 QEMU will not automatically load any firmware. It is up to the user to load all
95 the images they need.
96
97 * ``-bios <file>``
98
99 Tells QEMU to load the specified file as the firmware.
100
101 RISC-V CPU endianness
102 ---------------------
103
104 The RISC-V ISA specifies that instruction fetches are always little-endian,
105 while data accesses can be either little-endian or big-endian under control
106 of the MSTATUS ``MBE``/``SBE``/``UBE`` bits (see section 3.1.6.5, "Memory
107 Endianness", in the RISC-V Privileged Specification).
108
109 QEMU implements the full data-endianness behaviour described by those bits.
110 In addition, the RISC-V CPU object exposes a ``big-endian`` boolean property
111 which models a big-endian-only hardware implementation, where the
112 ``MBE``/``SBE``/``UBE`` bits are hardwired to 1. When the property is set,
113 the CPU is reset with all three bits initialised to 1, so the guest starts
114 executing in big-endian data mode from the reset vector. The property is a
115 static, per-CPU hardware configuration option and is not meant to be toggled
116 at runtime.
117
118 The property does not model a mixed-endian implementation where software can
119 toggle ``MBE``/``SBE``/``UBE`` at runtime. QEMU's RISC-V CPUs treat these
120 fields as fixed by the CPU configuration: they are reset to 0 by default and
121 to 1 when ``big-endian`` is enabled.
122
123 The property can be enabled from the command line, for example::
124
125 -cpu <cpu>,big-endian=on
126
127 No upstream CPU model currently defaults to big-endian; the property is
128 provided so that big-endian-only RISC-V CPU variants can be modelled.