From: Daniel Henrique Barboza <dbarb...@ventanamicro.com>
Also add a new page, docs/specs/riscv-aia.rst, where we're documenting
the state of AIA support in QEMU w.r.t the controllers being emulated or
not depending on the AIA and accelerator settings.
Signed-off-by: Daniel Henrique Barboza <dbarb...@ventanamicro.com>
Reviewed-by: Alistair Francis <alistair.fran...@wdc.com>
Message-ID: <20241119191706.718860-9-dbarb...@ventanamicro.com>
Signed-off-by: Alistair Francis <alistair.fran...@wdc.com>
---
docs/specs/index.rst | 1 +
docs/specs/riscv-aia.rst | 83 ++++++++++++++++++++++++++++++++++++++
docs/system/riscv/virt.rst | 7 ++++
3 files changed, 91 insertions(+)
create mode 100644 docs/specs/riscv-aia.rst
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index ff5a1f03da..d7675cebc2 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -37,3 +37,4 @@ guest hardware that is specific to QEMU.
rapl-msr
rocker
riscv-iommu
+ riscv-aia
diff --git a/docs/specs/riscv-aia.rst b/docs/specs/riscv-aia.rst
new file mode 100644
index 0000000000..8097e2f897
--- /dev/null
+++ b/docs/specs/riscv-aia.rst
@@ -0,0 +1,83 @@
+.. _riscv-aia:
+
+RISC-V AIA support for RISC-V machines
+======================================
+
+AIA (Advanced Interrupt Architecture) support is implemented in the ``virt``
+RISC-V machine for TCG and KVM accelerators.
+
+The support consists of two main modes:
+
+- "aia=aplic": adds one or more APLIC (Advanced Platform Level Interrupt
Controller)
+ devices
+- "aia=aplic-imsic": adds one or more APLIC device and an IMSIC (Incoming MSI
+ Controller) device for each CPU
+
+From an user standpoint, these modes will behave the same regardless of the
accelerator
+used. From a developer standpoint the accelerator settings will change what
it being
+emulated in userspace versus what is being emulated by an in-kernel irqchip.
+
+When running TCG, all controllers are emulated in userspace, including machine
mode
+(m-mode) APLIC and IMSIC (when applicable).
+
+When running KVM:
+
+- no m-mode is provided, so there is no m-mode APLIC or IMSIC emulation
regardless of
+ the AIA mode chosen
+- with "aia=aplic", s-mode APLIC will be emulated by userspace
+- with "aia=aplic-imsic" there are two possibilities. If no additional KVM
option
+ is provided there will be no APLIC or IMSIC emulation in userspace, and the
virtual
+ machine will use the provided in-kernel APLIC and IMSIC controllers. If the
user
+ chooses to use the irqchip in split mode via "-accel
kvm,kernel-irqchip=split",
+ s-mode APLIC will be emulated while using the s-mode IMSIC from the irqchip
+
+The following table summarizes how the AIA and accelerator options defines what
+we will emulate in userspace:
+
+
+.. list-table:: How AIA and accel options changes controller emulation
+ :widths: 25 25 25 25 25 25 25
+ :header-rows: 1
+
+ * - Accel
+ - Accel props
+ - AIA type
+ - APLIC m-mode
+ - IMSIC m-mode
+ - APLIC s-mode
+ - IMSIC s-mode
+ * - tcg
+ - ---
+ - aplic
+ - emul
+ - n/a
+ - emul
+ - n/a
+ * - tcg
+ - ---
+ - aplic-imsic
+ - emul
+ - emul
+ - emul
+ - emul
+ * - kvm
+ - ---
+ - aplic
+ - n/a
+ - n/a
+ - emul
+ - n/a
+ * - kvm
+ - none
+ - aplic-imsic
+ - n/a
+ - n/a
+ - in-kernel
+ - in-kernel
+ * - kvm
+ - irqchip=split
+ - aplic-imsic
+ - n/a
+ - n/a
+ - emul
+ - in-kernel
diff --git a/docs/system/riscv/virt.rst b/docs/system/riscv/virt.rst
index 537aac0340..60850970ce 100644
--- a/docs/system/riscv/virt.rst
+++ b/docs/system/riscv/virt.rst
@@ -129,6 +129,13 @@ The following machine-specific options are supported:
MSIs. When not specified, this option is assumed to be "none" which selects
SiFive PLIC to handle wired interrupts.
+ This option also interacts with '-accel kvm'. When using "aia=aplic-imsic"
+ with KVM, it is possible to set the use of the kernel irqchip in split mode
+ by using "-accel kvm,kernel-irqchip=split". In this case the ``virt``
machine
+ will emulate the APLIC controller instead of using the APLIC controller from
+ the irqchip. See :ref:`riscv-aia` for more details on all available AIA
+ modes.
+
- aia-guests=nnn
The number of per-HART VS-level AIA IMSIC pages to be emulated for a guest
--
2.47.1
