docs/system: Add RISC-V documentation

Add RISC-V system emulator documentation for generic information.
`Board-specific documentation` and `RISC-V CPU features` are only
a placeholder and will be added in the future.

Signed-off-by: Bin Meng <bin.meng@windriver.com>
Reviewed-by: Alistair Francis <alistair.francis@wdc.com>
Message-id: 20210126060007.12904-9-bmeng.cn@gmail.com
Signed-off-by: Alistair Francis <alistair.francis@wdc.com>
This commit is contained in:
Bin Meng 2021-01-26 14:00:06 +08:00 committed by Alistair Francis
parent 1921e4276d
commit d6d9896814
2 changed files with 63 additions and 0 deletions

View File

@ -0,0 +1,62 @@
.. _RISC-V-System-emulator:
RISC-V System emulator
======================
QEMU can emulate both 32-bit and 64-bit RISC-V CPUs. Use the
``qemu-system-riscv64`` executable to simulate a 64-bit RISC-V machine,
``qemu-system-riscv32`` executable to simulate a 32-bit RISC-V machine.
QEMU has generally good support for RISC-V guests. It has support for
several different machines. The reason we support so many is that
RISC-V hardware is much more widely varying than x86 hardware. RISC-V
CPUs are generally built into "system-on-chip" (SoC) designs created by
many different companies with different devices, and these SoCs are
then built into machines which can vary still further even if they use
the same SoC.
For most boards the CPU type is fixed (matching what the hardware has),
so typically you don't need to specify the CPU type by hand, except for
special cases like the ``virt`` board.
Choosing a board model
----------------------
For QEMU's RISC-V system emulation, you must specify which board
model you want to use with the ``-M`` or ``--machine`` option;
there is no default.
Because RISC-V systems differ so much and in fundamental ways, typically
operating system or firmware images intended to run on one machine
will not run at all on any other. This is often surprising for new
users who are used to the x86 world where every system looks like a
standard PC. (Once the kernel has booted, most user space software
cares much less about the detail of the hardware.)
If you already have a system image or a kernel that works on hardware
and you want to boot with QEMU, check whether QEMU lists that machine
in its ``-machine help`` output. If it is listed, then you can probably
use that board model. If it is not listed, then unfortunately your image
will almost certainly not boot on QEMU. (You might be able to
extract the file system and use that with a different kernel which
boots on a system that QEMU does emulate.)
If you don't care about reproducing the idiosyncrasies of a particular
bit of hardware, such as small amount of RAM, no PCI or other hard
disk, etc., and just want to run Linux, the best option is to use the
``virt`` board. This is a platform which doesn't correspond to any
real hardware and is designed for use in virtual machines. You'll
need to compile Linux with a suitable configuration for running on
the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and
large amounts of RAM. It also supports 64-bit CPUs.
Board-specific documentation
----------------------------
Unfortunately many of the RISC-V boards QEMU supports are currently
undocumented; you can get a complete list by running
``qemu-system-riscv64 --machine help``, or
``qemu-system-riscv32 --machine help``.
RISC-V CPU features
-------------------

View File

@ -19,6 +19,7 @@ Contents:
target-m68k
target-mips
target-ppc
target-riscv
target-rx
target-s390x
target-sparc