On Thu, Jun 04, 2026 at 06:52:44AM -0300, Daniel Henrique Barboza wrote: > Add documentation for the new riscv-server-ref board. > > Signed-off-by: Daniel Henrique Barboza <[email protected]> > --- > docs/system/riscv/riscv-server-ref.rst | 52 ++++++++++++++++++++++++++ > docs/system/target-riscv.rst | 1 + > 2 files changed, 53 insertions(+) > create mode 100644 docs/system/riscv/riscv-server-ref.rst > > diff --git a/docs/system/riscv/riscv-server-ref.rst > b/docs/system/riscv/riscv-server-ref.rst > new file mode 100644 > index 0000000000..379b7ef76e > --- /dev/null > +++ b/docs/system/riscv/riscv-server-ref.rst > @@ -0,0 +1,52 @@ > +.. SPDX-License-Identifier: GPL-2.0-or-later > + > +RISC-V Server Platform Reference board (``riscv-server-ref``) > +============================================================= > + > +The RISC-V Server Platform specification `spec`_ defines a standardized > +set of hardware and software capabilities that portable system software, > +such as OS and hypervisors, can rely on being present in a RISC-V server > +platform. This machine aims to emulate this specification, providing > +an environment for firmware/OS development and testing. > + > +`spec`_ is version 1.0 at the introduction of this board. New spec versions > +might trigger a revision of the emulation itself, which will strive to always > +match the latest version available. In case the emulation changes aren't > +backwards compatible we'll introduce a versioning scheme, probably via
Even in the case the changes are backwards compatible we'll introduce a versioning scheme. Because... > +a machine property, to allow older SW to run with older spec versions. ...we aren't as worried about older SW running on something than we are about new SW being tested on older machine models in order to allow OS developers to ensure changes to the OS to support newer spec versions don't regress support for older spec versions. (And I think we're currently leaning towards a global property instead of a machine property in order to cover the cpu model too.) > + > +The main features included in the riscv-server-ref board are: > + > +* IOMMU platform device (riscv-iommu-sys) > +* AIA > +* PCIe AHCI > +* PCIe NIC > +* No virtio mmio bus > +* No fw_cfg device > +* No ACPI table > +* Minimal device tree nodes > + > +There are multiple ways of using this reference board, some of them being: > + > +* BIOS: u-boot-spl.bin; SD-CARD: <disk_containing_FIT>; NVME: <distro_disk> > +* BIOS: fw_dynamic.bin; KERNEL: u-boot.bin; NVME: <distro_disk> > +* BIOS: fw_dynamic.bin; KERNEL: EDK2.fd; NVME: <distro_disk> > +* BIOS: fw_dynamic.bin; KERNEL: <linux_image>; INITRD: <busybox_initrd> Maybe we need to point out that a firmware that generates ACPI tables and supports EFI runtime services is required for a completely spec conforming platform. I think that's only the 3rd bullet above. > + > +Here's an usage example with a recent (June 2026) ``Image`` and > ``rootfs.ext2`` > +files from buildroot: > + > +.. code-block:: bash > + > + qemu-system-riscv64 -M riscv-server-ref \ > + -kernel ./buildroot/Image -append "rw rootwait root=/dev/vda" \ > + -drive file=./buildroot/rootfs.ext2,format=raw,id=hd0,if=virtio \ > + -nographic This example does not generate a server platform that conforms to the spec since there are no ACPI tables and no EFI support for the OS/hypervisor. Also, how is the disk configured? It should be a PCIe device. Thanks, drew > + > +The images QEMU is using for selftests of the riscv-server-ref machine can > +be found below: > + > +https://github.com/danielhb/qemu-machine-boot/tree/master/riscv/images/virt64/buildroot > + > + > +.. _spec: https://github.com/riscv-non-isa/riscv-server-platform > diff --git a/docs/system/target-riscv.rst b/docs/system/target-riscv.rst > index afd86ca2ba..b2aeb39a8e 100644 > --- a/docs/system/target-riscv.rst > +++ b/docs/system/target-riscv.rst > @@ -73,6 +73,7 @@ undocumented; you can get a complete list by running > riscv/sifive_u > riscv/virt > riscv/xiangshan-kunminghu > + riscv/riscv-server-ref > > RISC-V CPU firmware > ------------------- > -- > 2.43.0 >
