[PATCH 10/10] Documentation: KVM: Document KVM_{GET, SET}_SYSTEM_COUNTER_STATE ioctls

[Oliver Upton <oupton@google.com>]

Reviewed-by: David Matlack <dmatlack@google.com>
Reviewed-by: Peter Shier <pshier@google.com>
Reviewed-by: Ricardo Koller <ricarkol@google.com>
Signed-off-by: Oliver Upton <oupton@google.com>
---
 Documentation/virt/kvm/api.rst | 98 ++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 7fcb2fd38f42..85654748156a 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -5034,6 +5034,104 @@ see KVM_XEN_VCPU_SET_ATTR above.
 The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used
 with the KVM_XEN_VCPU_GET_ATTR ioctl.
 
+4.130 KVM_GET_SYSTEM_COUNTER_STATE
+---------------------------
+
+:Capability: KVM_CAP_SYSTEM_COUNTER_STATE
+:Architectures: arm64, x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_system_counter_state
+:Returns: 0 on success, < 0 on error
+
+Allows the vCPU counter state to be read. Each architecture defines
+its own kvm_system_counter_state structure depending on the backing hardware
+controls used for the guest's counter.
+
+ARM64
+
+::
+
+  struct kvm_system_counter_state {
+	/* indicates what fields are valid in the structure */
+	__u32 flags;
+
+Enumerates what fields are valid in the kvm_system_counter_state structure.
+Userspace should set this field to indicate what fields it wants the kernel
+to populate.
+
+::
+
+	__u32 pad;
+	/*
+	 * Guest physical counter-timer offset, relative to host cntpct_el0.
+	 * Valid when KVM_SYSTEM_COUNTER_STATE_PHYS_OFFSET is set.
+	 */
+	__u64 cntvoff;
+
+Offset for the guest virtual counter-timer, as it relates to the host's
+physical counter-timer (CNTPCT_EL0). This field is populated when the
+KVM_SYSTEM_COUNTER_STATE_PHYS_OFFSET bit is set in the flags field.
+
+::
+
+	/* guest physical counter-timer offset, relative to host cntpct_el0 */
+	__u64 cntpoff;
+
+Offset for the guest physical counter-timer, as it relates to the host's
+physical counter-timer (CNTPCT_EL0).
+
+::
+
+	__u64 rsvd[5];
+  };
+
+x86
+
+::
+
+  struct kvm_system_counter_state {
+	__u32 flags;
+
+Enumerates what fields are valid in the kvm_system_counter_state structure.
+Currently, the structure has not been extended, so there are no valid flag
+bits. This field should then be set to zero.
+
+::
+
+	__u32 pad;
+	__u64 tsc_offset;
+
+Offset for the guest TSC, as it relates to the host's TSC.
+
+::
+
+	__u64 rsvd[6];
+  };
+
+4.131 KVM_SET_SYSTEM_COUNTER_STATE
+---------------------------
+
+:Capability: KVM_CAP_SYSTEM_COUNTER_STATE
+:Architectures: arm64, x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_system_counter_state
+:Returns: 0 on success, < 0 on error.
+
+Allows the vCPU counter state to be written. For more details on the
+structure, see KVM_GET_SYSTEM_COUNTER_STATE above.
+
+ARM64
+
+VMMs should either use this ioctl *OR* directly write to the vCPU's
+CNTVCT_EL0 register. Mixing both methods of restoring counter state
+can cause drift between virtual CPUs.
+
+x86
+
+VMMs should either use this ioctl *OR* directly write to the vCPU's
+IA32_TSC register. Mixing both methods of restoring TSC state can
+cause drift between virtual CPUs.
+
 5. The kvm_run structure
 ========================
 
-- 
2.32.0.rc1.229.g3e70b5a671-goog

_______________________________________________
kvmarm mailing list
kvmarm@lists.cs.columbia.edu
https://lists.cs.columbia.edu/mailman/listinfo/kvmarm