On Thu, Dec 31, 2020 at 3:53 AM Bin Meng <bmeng...@gmail.com> wrote: > > From: Bin Meng <bin.m...@windriver.com> > > 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.m...@windriver.com>
This is great! Thanks! Reviewed-by: Alistair Francis <alistair.fran...@wdc.com> Alistair > --- > > docs/system/target-riscv.rst | 62 ++++++++++++++++++++++++++++++++++++ > docs/system/targets.rst | 1 + > 2 files changed, 63 insertions(+) > create mode 100644 docs/system/target-riscv.rst > > diff --git a/docs/system/target-riscv.rst b/docs/system/target-riscv.rst > new file mode 100644 > index 0000000000..978b96cbdb > --- /dev/null > +++ b/docs/system/target-riscv.rst > @@ -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 userspace 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 filesystem 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 > +------------------- > diff --git a/docs/system/targets.rst b/docs/system/targets.rst > index 564cea9a9b..75ed1087fd 100644 > --- a/docs/system/targets.rst > +++ b/docs/system/targets.rst > @@ -19,6 +19,7 @@ Contents: > target-m68k > target-mips > target-ppc > + target-riscv > target-rx > target-s390x > target-sparc > -- > 2.25.1 > >
