docs/system: openrisc: Add OpenRISC documentation

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Stafford Horne <shorne@gmail.com>
This commit is contained in:
Stafford Horne 2022-07-01 08:29:17 +09:00
parent c6fe3e6b4c
commit b14df228d7
6 changed files with 197 additions and 0 deletions

View File

@ -0,0 +1,15 @@
CPU Features
============
The QEMU emulation of the OpenRISC architecture provides following built in
features.
- Shadow GPRs
- MMU TLB with 128 entries, 1 way
- Power Management (PM)
- Programmable Interrupt Controller (PIC)
- Tick Timer
These features are on by default and the presence can be confirmed by checking
the contents of the Unit Presence Register (``UPR``) and CPU Configuration
Register (``CPUCFGR``).

View File

@ -0,0 +1,17 @@
OpenRISC 1000 CPU architecture support
======================================
QEMU's TCG emulation includes support for the OpenRISC or1200 implementation of
the OpenRISC 1000 cpu architecture.
The or1200 cpu also has support for the following instruction subsets:
- ORBIS32 (OpenRISC Basic Instruction Set)
- ORFPX32 (OpenRISC Floating-Point eXtension)
In addition to the instruction subsets the QEMU TCG emulation also has support
for most Class II (optional) instructions.
For information on all OpenRISC instructions please refer to the latest
architecture manual available on the OpenRISC website in the
`OpenRISC Architecture <https://openrisc.io/architecture>`_ section.

View File

@ -0,0 +1,43 @@
Or1ksim board
=============
The QEMU Or1ksim machine emulates the standard OpenRISC board simulator which is
also the standard SoC configuration.
Supported devices
-----------------
* 16550A UART
* ETHOC Ethernet controller
* SMP (OpenRISC multicore using ompic)
Boot options
------------
The Or1ksim machine can be started using the ``-kernel`` and ``-initrd`` options
to load a Linux kernel and optional disk image.
.. code-block:: bash
$ qemu-system-or1k -cpu or1220 -M or1k-sim -nographic \
-kernel vmlinux \
-initrd initramfs.cpio.gz \
-m 128
Linux guest kernel configuration
""""""""""""""""""""""""""""""""
The 'or1ksim_defconfig' for Linux openrisc kernels includes the right
drivers for the or1ksim machine. If you would like to run an SMP system
choose the 'simple_smp_defconfig' config.
Hardware configuration information
""""""""""""""""""""""""""""""""""
The ``or1k-sim`` board automatically generates a device tree blob ("dtb")
which it passes to the guest. This provides information about the
addresses, interrupt lines and other configuration of the various devices
in the system.
The location of the DTB will be passed in register ``r3`` to the guest operating
system.

View File

@ -0,0 +1,50 @@
'virt' generic virtual platform
===============================
The ``virt`` board is a platform which does not correspond to any
real hardware; it is designed for use in virtual machines.
It is the recommended board type if you simply want to run
a guest such as Linux and do not care about reproducing the
idiosyncrasies and limitations of a particular bit of real-world
hardware.
Supported devices
-----------------
* PCI/PCIe devices
* 8 virtio-mmio transport devices
* 16550A UART
* Goldfish RTC
* SiFive Test device for poweroff and reboot
* SMP (OpenRISC multicore using ompic)
Boot options
------------
The virt machine can be started using the ``-kernel`` and ``-initrd`` options
to load a Linux kernel and optional disk image. For example:
.. code-block:: bash
$ qemu-system-or1k -cpu or1220 -M or1k-sim -nographic \
-device virtio-net-device,netdev=user -netdev user,id=user,net=10.9.0.1/24,host=10.9.0.100 \
-device virtio-blk-device,drive=d0 -drive file=virt.qcow2,id=d0,if=none,format=qcow2 \
-kernel vmlinux \
-initrd initramfs.cpio.gz \
-m 128
Linux guest kernel configuration
""""""""""""""""""""""""""""""""
The 'virt_defconfig' for Linux openrisc kernels includes the right drivers for
the ``virt`` machine.
Hardware configuration information
""""""""""""""""""""""""""""""""""
The ``virt`` board automatically generates a device tree blob ("dtb") which it
passes to the guest. This provides information about the addresses, interrupt
lines and other configuration of the various devices in the system.
The location of the DTB will be passed in register ``r3`` to the guest operating
system.

View File

@ -0,0 +1,71 @@
.. _OpenRISC-System-emulator:
OpenRISC System emulator
~~~~~~~~~~~~~~~~~~~~~~~~
QEMU can emulate 32-bit OpenRISC CPUs using the ``qemu-system-or1k`` executable.
OpenRISC CPUs are generally built into "system-on-chip" (SoC) designs that run
on FPGAs. These SoCs are based on the same core architecture as the or1ksim
(the original OpenRISC instruction level simulator) which QEMU supports. For
this reason QEMU does not need to support many different boards to support the
OpenRISC hardware ecosystem.
The OpenRISC CPU supported by QEMU is the ``or1200``, it supports an MMU and can
run linux.
Choosing a board model
======================
For QEMU's OpenRISC system emulation, you must specify which board model you
want to use with the ``-M`` or ``--machine`` option; the default machine is
``or1k-sim``.
If you intend to boot Linux, it is possible to have a single kernel image that
will boot on any of the QEMU machines. To do this one would compile all required
drivers into the kernel. This is possible because QEMU will create a device tree
structure that describes the QEMU machine and pass a pointer to the structure to
the kernel. The kernel can then use this to configure itself for the machine.
However, typically users will have specific firmware images for a specific machine.
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
and large amounts of RAM.
Board-specific documentation
============================
..
This table of contents should be kept sorted alphabetically
by the title text of each file, which isn't the same ordering
as an alphabetical sort by filename.
.. toctree::
:maxdepth: 1
openrisc/or1k-sim
openrisc/virt
Emulated CPU architecture support
=================================
.. toctree::
openrisc/emulation
OpenRISC CPU features
=====================
.. toctree::
openrisc/cpu-features

View File

@ -21,6 +21,7 @@ Contents:
target-m68k
target-mips
target-ppc
target-openrisc
target-riscv
target-rx
target-s390x