[PATCH v2 39/39] Documentation: KVM: Add the VGICv5 IRS save/restore sequences
From: Sascha Bischoff <hidden>
Date: 2026-05-21 15:03:54
Also in:
kvm, kvmarm
Subsystem:
documentation, kernel virtual machine (kvm), kernel virtual machine for arm64 (kvm/arm64), the rest · Maintainers:
Jonathan Corbet, Paolo Bonzini, Marc Zyngier, Oliver Upton, Linus Torvalds
When saving/restoring the state of the GICv5 IRS, it is important that it happens in the correct order. Failure to do so will almost certainly result in failing to restore a guest that is capable of handling interrupts correctly. On a save, the ISTs must be saved prior to saving the guest's memory as the guest's LPI IST is written to guest memory. Conversely, on restore the guest's memory must be restored prior to restoring the ISTs. It is important to restore the IRS MMIO registers by first restoring the IRS_IDx registers as they define the capabilities of the IRS, and are used as part of creating and managing ISTs and SPIs. In order to restore the ISTs themselves, the IRS_IST_CFGR must be restored prior to the IRS_IST_BASER. KVM uses these restored registers when KVM_DEV_ARM_VGIC_GRP_IST is restored to determine whether a guest LPI IST exists, how large it must be, and where the guest-provided migration storage lives. The host LPI IST is allocated and populated as part of restoring KVM_DEV_ARM_VGIC_GRP_IST. At this stage the remaining MMIO registers can be restored. The SPI IST gets extracted from a userspace provided buffer, and is transferred to the host-allocated SPI IST. The LPI IST is extracted from guest memory, and is written to the host-allocated LPI IST. As a general rule, the IRS_*_STATUSR registers can be ignored on restore. They are not userspace writable. Signed-off-by: Sascha Bischoff <redacted> --- .../virt/kvm/devices/arm-vgic-v5.rst | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+)
diff --git a/Documentation/virt/kvm/devices/arm-vgic-v5.rst b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
index 0ee0fe9308fc9..188851f22f9eb 100644
--- a/Documentation/virt/kvm/devices/arm-vgic-v5.rst
+++ b/Documentation/virt/kvm/devices/arm-vgic-v5.rst@@ -232,3 +232,48 @@ Groups: or tracking pending interrupts -ETIMEDOUT An IRS save/VM operation timed out =========== ============================================================ + +IRS Save Sequence: +------------------ + +The following operations are required when saving the virtual GICv5 IRS: + +a) Save the ISTs by issuing KVM_GET_DEVICE_ATTR on KVM_DEV_ARM_VGIC_GRP_IST. +b) Save the IRS MMIO register state by issuing KVM_GET_DEVICE_ATTR on + KVM_DEV_ARM_VGIC_GRP_IRS_REGS. + +These two steps may be performed in either order. However, the guest memory +must be serialised after the ISTs have been saved, as saving the LPI IST writes +the IST state back into guest memory. + +IRS Restore Sequence: +--------------------- + +The following ordering must be followed when restoring the virtual GICv5 and +IRS: + +a) Create vCPUs. +b) Provide the IRS base address by issuing KVM_SET_DEVICE_ATTR on + KVM_DEV_ARM_VGIC_GRP_ADDR +c) Restore the number of SPIs by issuing KVM_SET_DEVICE_ATTR on + KVM_DEV_ARM_VGIC_GRP_NR_IRQS. +d) Initialise the GIC - this sets up the default state and creates the SPI + IST - by issuing KVM_SET_DEVICE_ATTR on KVM_DEV_ARM_VGIC_GRP_CTRL with + KVM_DEV_ARM_VGIC_CTRL_INIT +e) Restore guest memory. +f) Restore the IRS MMIO register state by issuing KVM_SET_DEVICE_ATTR on + KVM_DEV_ARM_VGIC_GRP_IRS_REGS. KVM uses the restored IRS_IST_CFGR and + IRS_IST_BASER state to allocate the LPI IST during the following step. +g) Restore the ISTs by issuing KVM_SET_DEVICE_ATTR on + KVM_DEV_ARM_VGIC_GRP_IST. + +The number of SPIs must be restored before VGIC initialization because +initialization allocates the SPI state and fixes the SPI range exposed by the +IRS ID registers. + +The various ``*_STATUSR`` registers are observational state in the current KVM +implementation. Userspace may save them for validation or debugging purposes, +but they are not required as restore input and do not need to be replayed during +restore. + +Then vCPUs can be started.
--
2.34.1