On 7/14/2026 4:56 AM, Subrahmanya Lingappa wrote:
Document the opt-in virt RPMI transport and the initial HSM, system
reset, and system suspend service groups.
Signed-off-by: Subrahmanya Lingappa <[email protected]>
---
Reviewed-by: Daniel Henrique Barboza <[email protected]>
docs/system/riscv/virt.rst | 65 ++++++++++++++++++++++++++++++++++++++
1 file changed, 65 insertions(+)
diff --git a/docs/system/riscv/virt.rst b/docs/system/riscv/virt.rst
index 60850970ce..31cd945a3b 100644
--- a/docs/system/riscv/virt.rst
+++ b/docs/system/riscv/virt.rst
@@ -146,6 +146,71 @@ The following machine-specific options are supported:
Enables the riscv-iommu-sys platform device. Defaults to 'off'.
+- rpmi=[on|off]
+
+ Enables the RISC-V RPMI shared-memory transport. This option defaults to
+ "off", is TCG-only, and is available only when QEMU is built with librpmi
+ support. This support targets the RISC-V Platform Management Interface
+ (RPMI) Specification v1.0 Ratified (`RPMI v1.0 specification`_). The initial
+ ``virt`` implementation exposes RPMI system reset, system suspend, and HSM
+ service groups. System reset can request shutdown or cold reboot through
+ RPMI. HSM uses the ``virt`` hart IDs and supports hart discovery, status,
+ start, stop, and suspend commands. System suspend uses QEMU's suspend and
+ wakeup path. Migration is currently blocked while RPMI transport and service
+ VMState support is being designed.
+
+ The build dependency is provided by `librpmi`_. QEMU requires librpmi 1.0.0
+ or newer. If the host distribution does not provide a librpmi development
+ package, build and install it from the upstream source tree so that
+ ``pkg-config`` can find ``librpmi.pc``:
+
+ .. code-block:: bash
+
+ $ git clone https://github.com/riscv-software-src/librpmi.git
+ $ cd librpmi
+ $ make
+ $ make install I=/usr/local
+ $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
+ $ pkg-config --modversion librpmi
+
+ The librpmi repository can also generate installable ``librpmi-dev`` Debian
+ packages with ``make deb-pkg`` and ``librpmi-devel`` RPM packages with
+ ``make rpm-pkg``. After installing librpmi, configure QEMU with
+ ``--enable-librpmi`` or ``-Dlibrpmi=enabled``.
+
+.. _RPMI v1.0 specification:
https://github.com/riscv-non-isa/riscv-rpmi/releases/download/v1.0/riscv-rpmi.pdf
+.. _librpmi: https://github.com/riscv-software-src/librpmi
+
+RPMI firmware and guest smoke
+-----------------------------
+
+A firmware-level RPMI smoke test can be run with OpenSBI, a Linux kernel, and a
+RISC-V disk image:
+
+.. code-block:: bash
+
+ $ qemu-system-riscv64 \
+ -machine virt,rpmi=on \
+ -cpu rv64 -smp 4 -m 4G -nographic \
+ -bios /path/to/fw_jump.bin \
+ -kernel /path/to/Image \
+ -append "root=/dev/vda rw console=ttyS0 earlycon=sbi" \
+ -drive file=/path/to/rootfs.img,format=raw,if=virtio,snapshot=on
+
+The OpenSBI banner should report RPMI-backed HSM and system suspend support.
+After the guest reaches a shell, normal guest reboot/poweroff commands exercise
+the RPMI system reset path.
+
+RPMI device tree policy
+-----------------------
+
+RPMI is currently described through FDT only; no ACPI representation is emitted
+for the RPMI transport or service groups. The ``virt`` machine uses the
+``riscv,rpmi-shmem-mbox`` shared-memory mailbox node plus child service nodes
+with ``riscv,rpmi-*`` compatible strings. These binding names are part of the
+RPMI RFC surface and may be revised if the RISC-V RPMI bindings change during
+review.
+
Running Linux kernel
--------------------
