From: Sascha Bischoff <Sascha.Bischoff@arm•com>
To: "linux-arm-kernel@lists•infradead.org"
<linux-arm-kernel@lists•infradead.org>,
"kvmarm@lists•linux.dev" <kvmarm@lists•linux.dev>,
"kvm@vger•kernel.org" <kvm@vger•kernel.org>
Cc: nd <nd@arm•com>, "maz@kernel•org" <maz@kernel•org>,
"oliver.upton@linux•dev" <oliver.upton@linux•dev>,
Joey Gouly <Joey.Gouly@arm•com>,
Suzuki Poulose <Suzuki.Poulose@arm•com>,
"yuzenghui@huawei•com" <yuzenghui@huawei•com>,
"peter.maydell@linaro•org" <peter.maydell@linaro•org>,
"lpieralisi@kernel•org" <lpieralisi@kernel•org>,
Timothy Hayes <Timothy.Hayes@arm•com>
Subject: [PATCH v2 38/39] Documentation: KVM: Add docs for KVM_DEV_ARM_VGIC_GRP_IST
Date: Thu, 21 May 2026 15:02:13 +0000 [thread overview]
Message-ID: <20260521144846.1899475-39-sascha.bischoff@arm.com> (raw)
In-Reply-To: <20260521144846.1899475-1-sascha.bischoff@arm.com>
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 | 55 +++++++++++++++++++
1 file changed, 55 insertions(+)
diff --git a/Documentation/virt/kvm/devices/arm-vgic-v5.rst b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
index 217a1ecfbdc5f..0ee0fe9308fc9 100644
--- a/Documentation/virt/kvm/devices/arm-vgic-v5.rst
+++ b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
@@ -177,3 +177,58 @@ Groups:
64-bit aligned for 64-bit registers
-EBUSY VGIC is not initialized, or 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. A get operation saves IST state,
+ and a set operation restores IST state. kvm_device_attr.attr is reserved
+ and must be zero.
+
+ The VGIC must be initialized before using this interface. Restore must be
+ performed before the VM has run. For restore, userspace must have already
+ restored the IRS state and guest memory needed to describe and back any
+ guest LPI IST.
+
+ Saving first asks the IRS to save and quiesce the VM so that interrupt
+ state has been written back to the ISTs. KVM checks that the VM remains
+ quiesced while copying out the SPI and LPI IST state.
+
+ The LPI IST is written to or read from guest-allocated memory. KVM assumes
+ that the guest has provisioned a linear virtual IST through IRS_IST_CFGR
+ and IRS_IST_BASER, and uses that guest memory as the LPI IST migration
+ storage. If the guest has not enabled an LPI IST, there is no LPI IST
+ state to save or restore.
+
+ The SPI IST has no guest-owned backing memory, so userspace must provide a
+ buffer through kvm_device_attr.addr for both get and set operations. The
+ buffer contains one little-endian 32-bit IST entry per exposed SPI, in SPI
+ number order. Its size is:
+
+ nr_spis * sizeof(__u32)
+
+ where nr_spis is the value returned by KVM_DEV_ARM_VGIC_GRP_NR_IRQS for
+ the VGICv5 device. For VGICv5 this value is the number of SPIs, not the
+ total number of interrupts. Since VGICv5 currently exposes at least 32
+ SPIs, kvm_device_attr.addr must be non-zero.
+
+ Errors:
+
+ =========== ============================================================
+ -EBUSY One or more VCPUs are running, the VGIC is not initialized,
+ restore was requested after the VM has run, an LPI IST
+ already exists, or the save operation completed but the VM
+ did not remain quiesced
+ -EINVAL A userspace SPI IST buffer was not supplied when one is
+ required, or an internal VM table operation rejected the VM
+ state
+ -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 allocating the host LPI IST
+ or tracking pending interrupts
+ -ETIMEDOUT An IRS save/VM operation timed out
+ =========== ============================================================
--
2.34.1
next prev parent reply other threads:[~2026-05-21 15:03 UTC|newest]
Thread overview: 47+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-05-21 14:49 [PATCH v2 00/39] KVM: arm64: Add GICv5 IRS support Sascha Bischoff
2026-05-21 14:49 ` [PATCH v2 01/39] irqchip/gic-v5: Allow KVM setup without a maintenance IRQ Sascha Bischoff
2026-05-21 14:49 ` [PATCH v2 02/39] irqchip/gic-v5: Provide OF IRS config frame attrs to KVM Sascha Bischoff
2026-05-21 14:50 ` [PATCH v2 03/39] irqchip/gic-v5: Setup gic_kvm_info on ACPI hosts Sascha Bischoff
2026-05-27 10:51 ` Marc Zyngier
2026-05-29 14:33 ` Sascha Bischoff
2026-05-28 7:14 ` Lorenzo Pieralisi
2026-05-29 14:41 ` Sascha Bischoff
2026-05-21 14:50 ` [PATCH v2 04/39] KVM: arm64: gic-v5: Define remaining IRS MMIO registers Sascha Bischoff
2026-05-21 14:50 ` [PATCH v2 05/39] arm64/sysreg: Add GICv5 GIC VDPEND and VDRCFG encodings Sascha Bischoff
2026-05-21 14:51 ` [PATCH v2 06/39] arm64/sysreg: Update ICC_CR0_EL1 with LINK and LINK_IDLE fields Sascha Bischoff
2026-05-21 14:51 ` [PATCH v2 07/39] KVM: arm64: gic-v5: Extract host IRS caps from IRS config frame Sascha Bischoff
2026-05-21 14:51 ` [PATCH v2 08/39] KVM: arm64: gic-v5: Add VPE doorbell domain Sascha Bischoff
2026-05-21 14:52 ` [PATCH v2 09/39] KVM: arm64: gic-v5: Create & manage VM and VPE tables Sascha Bischoff
2026-05-21 14:52 ` [PATCH v2 10/39] KVM: arm64: gic-v5: Introduce guest IST alloc and management Sascha Bischoff
2026-05-21 14:52 ` [PATCH v2 11/39] KVM: arm64: gic-v5: Implement VMT/vIST IRS MMIO Ops Sascha Bischoff
2026-05-21 14:53 ` [PATCH v2 12/39] KVM: arm64: gic-v5: Keep GICv5 vCPU limit model-specific Sascha Bischoff
2026-05-21 14:53 ` [PATCH v2 13/39] KVM: arm64: gic-v5: Implement VPE IRS MMIO Ops Sascha Bischoff
2026-05-21 14:53 ` [PATCH v2 14/39] KVM: arm64: gic-v5: Set up VMTEs and VPE doorbells Sascha Bischoff
2026-05-21 14:54 ` [PATCH v2 15/39] KVM: arm64: gic-v5: Add resident/non-resident hyp calls Sascha Bischoff
2026-05-21 14:54 ` [PATCH v2 16/39] KVM: arm64: gic-v5: Request doorbells when VPEs enter WFI Sascha Bischoff
2026-05-21 14:54 ` [PATCH v2 17/39] KVM: arm64: gic-v5: Introduce struct vgic_v5_irs and IRS base address Sascha Bischoff
2026-05-21 14:55 ` [PATCH v2 18/39] KVM: arm64: gic-v5: Add IRS IODEV support to MMIO handlers Sascha Bischoff
2026-05-21 14:55 ` [PATCH v2 19/39] KVM: arm64: gic-v5: Add KVM_VGIC_V5_ADDR_TYPE_IRS to UAPI Sascha Bischoff
2026-05-21 14:55 ` [PATCH v2 20/39] KVM: arm64: gic-v5: Add GICv5 IRS IODEV and MMIO emulation Sascha Bischoff
2026-05-21 14:56 ` [PATCH v2 21/39] KVM: arm64: gic-v5: Initialise per-VM IRS state Sascha Bischoff
2026-05-21 14:56 ` [PATCH v2 22/39] KVM: arm64: gic-v5: Register the IRS IODEV Sascha Bischoff
2026-05-21 14:57 ` [PATCH v2 23/39] KVM: arm64: gic-v5: Set IRICHPPIDIS based on IRS enable state Sascha Bischoff
2026-05-21 14:57 ` [PATCH v2 24/39] KVM: arm64: selftests: Update vGICv5 selftest to set IRS address Sascha Bischoff
2026-05-21 14:57 ` [PATCH v2 25/39] KVM: arm64: gic-v5: Introduce SPI AP list Sascha Bischoff
2026-05-21 14:58 ` [PATCH v2 26/39] KVM: arm64: gic-v5: Add GIC VDPEND and GIC VDRCFG hyp calls Sascha Bischoff
2026-05-21 14:58 ` [PATCH v2 27/39] KVM: arm64: gic-v5: Track SPI state for in-flight SPIs Sascha Bischoff
2026-05-21 14:58 ` [PATCH v2 28/39] KVM: arm64: gic: Introduce set_pending_state() to irq_op Sascha Bischoff
2026-05-21 14:59 ` [PATCH v2 29/39] KVM: arm64: gic-v5: Support SPI injection Sascha Bischoff
2026-05-26 13:41 ` Vladimir Murzin
2026-05-28 14:59 ` Sascha Bischoff
2026-05-21 14:59 ` [PATCH v2 30/39] Documentation: KVM: Extend VGICv5 docs for KVM_VGIC_V5_ADDR_TYPE_IRS Sascha Bischoff
2026-05-21 14:59 ` [PATCH v2 31/39] KVM: arm64: gic-v5: Add GICv5 SPI injection to irqfd Sascha Bischoff
2026-06-04 10:51 ` Vladimir Murzin
2026-05-21 15:00 ` [PATCH v2 32/39] KVM: arm64: gic-v5: Mask per-vcpu PPI state in vgic_v5_finalize_ppi_state() Sascha Bischoff
2026-05-21 15:00 ` [PATCH v2 33/39] KVM: arm64: gic-v5: Add GICv5 EL1 sysreg userspace accessors Sascha Bischoff
2026-05-21 15:00 ` [PATCH v2 34/39] KVM: arm64: gic-v5: Handle userspace accesses to IRS MMIO region Sascha Bischoff
2026-05-21 15:01 ` [PATCH v2 35/39] KVM: arm64: gic-v5: Implement save/restore mechanisms for ISTs Sascha Bischoff
2026-05-21 15:01 ` [PATCH v2 36/39] Documentation: KVM: Document KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS for VGICv5 Sascha Bischoff
2026-05-21 15:01 ` [PATCH v2 37/39] Documentation: KVM: Add KVM_DEV_ARM_VGIC_GRP_IRS_REGS to VGICv5 docs Sascha Bischoff
2026-05-21 15:02 ` Sascha Bischoff [this message]
2026-05-21 15:02 ` [PATCH v2 39/39] Documentation: KVM: Add the VGICv5 IRS save/restore sequences Sascha Bischoff
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20260521144846.1899475-39-sascha.bischoff@arm.com \
--to=sascha.bischoff@arm$(echo .)com \
--cc=Joey.Gouly@arm$(echo .)com \
--cc=Suzuki.Poulose@arm$(echo .)com \
--cc=Timothy.Hayes@arm$(echo .)com \
--cc=kvm@vger$(echo .)kernel.org \
--cc=kvmarm@lists$(echo .)linux.dev \
--cc=linux-arm-kernel@lists$(echo .)infradead.org \
--cc=lpieralisi@kernel$(echo .)org \
--cc=maz@kernel$(echo .)org \
--cc=nd@arm$(echo .)com \
--cc=oliver.upton@linux$(echo .)dev \
--cc=peter.maydell@linaro$(echo .)org \
--cc=yuzenghui@huawei$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox