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

[Sascha Bischoff]

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

Signed-off-by: Sascha Bischoff <sascha.bischoff at 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