[PATCH 42/43] Documentation: KVM: Add docs for KVM_DEV_ARM_VGIC_GRP_IST

Sascha Bischoff
2026-04-27T16:21:47Z

Document the IST save/restore userspace interface for the VGICv5
device, KVM_DEV_ARM_VGIC_GRP_IST.

Signed-off-by: Sascha Bischoff <sascha.bischoff@arm.com>
---
.../virt/kvm/devices/arm-vgic-v5.rst | 40 +++++++++++++++++++
1 file changed, 40 insertions(+)

diff --git a/Documentation/virt/kvm/devices/arm-vgic-v5.rst b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
index 9fc6afe16154a..38eef7cc63e3e 100644
--- a/Documentation/virt/kvm/devices/arm-vgic-v5.rst
+++ b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
@@ -161,3 +161,43 @@ Groups:
aligned for 64-bit registers
-EBUSY one or more VCPUS are running
======= =================================================================
+
+ KVM_DEV_ARM_VGIC_GRP_IST
+ Attributes:
+ This interface is used to either save the state of the IRS's Interrupt
+ State Tables (ISTs) or to restore them, by doing either a get or a set,
+ respectively. As part of saving the IST state, the system is also quiesced
+ in order to ensure that there are no in-flight interrupts at the time of
+ doing so.
+
+ The LPI IST is written to or read from guest-allocated memory, assuming
+ that the guest has provisioned a virtual IST as there is sufficient
+ storage to serialise/unserialise the ISTs into/from guest memory in this
+ case. However, there is no such storage present for the SPI IST in guest
+ memory, and hence userspace must provide the storage for these.
+
+ The addr field of kvm_device_attr is used to provide the base address of
+ an appropriately-sized userspace buffer (32-bits per SPI) which is used to
+ either write the contents of the SPI IST to or to read it from. The number
+ of SPIs can be queried by first inspecting the guest's IRS_IDR5, IRS_IDR6,
+ and IRS_IDR7 to determine the number of SPIs that the guest can use. In
+ the case where the guest doesn't use SPIs at all, this address can be
+ omitted, but it is otherwise mandatory for both set and get operations via
+ this interface.
+
+ Errors:
+
+ =========== ============================================================
+ -EBUSY One or more VCPUs are running, or the save operation failed
+ to quiesce the VM
+ -EINVAL The VM is not valid, or a userspace SPI IST buffer was not
+ supplied when one is required
+ -ENOENT A userspace SPI IST buffer was supplied, but there is no SPI
+ IST to serialise/unserialise
+ -EFAULT Invalid user pointer for attr->addr, or the guest memory
+ backing the LPI IST could not be accessed
+ -ENXIO Required per-VM VGICv5/IST backing state is missing or
+ inconsistent
+ -ENOMEM Restoring IST state failed while tracking pending interrupts
+ -ETIMEDOUT An IRS save/VM operation timed out
+ =========== ============================================================
--
2.34.1