Add API documentation for the new KVM_HYPERV_SET_TLB_FLUSH_INHIBIT ioctl.

Signed-off-by: Nikolas Wipper <nikwip@amazon.de>
---
 Documentation/virt/kvm/api.rst | 41 ++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index a4b7dc4a9dda..9c11a8af336b 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -6443,6 +6443,47 @@ the capability to be present.
 `flags` must currently be zero.
 
 
+4.144 KVM_HYPERV_SET_TLB_FLUSH_INHIBIT
+--------------------------------------
+
+:Capability: KVM_CAP_HYPERV_TLB_FLUSH_INHIBIT
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_hyperv_tlb_flush_inhibit
+:returnReturns: 0 on success, this ioctl can't fail
+
+KVM_HYPERV_SET_TLB_FLUSH_INHIBIT allows userspace to prevent Hyper-V hyper-calls
+that remotely flush a vCPU's TLB, i.e. HvFlushVirtualAddressSpace(Ex)/
+HvFlushVirtualAddressList(Ex). When the flag is set, a vCPU attempting to flush
+an inhibited vCPU will be suspended and will only resume once the flag is
+cleared again using this ioctl. During suspension, the vCPU will not finish the
+hyper-call, but may enter the guest to retry it. Because it is caused by a
+hyper-call, the suspension naturally happens on a guest instruction boundary.
+This behaviour and the suspend state itself are specified in Microsoft's
+"Hypervisor Top Level Functional Specification" (TLFS).
+
+::
+
+  /* for KVM_HYPERV_SET_TLB_FLUSH_INHIBIT */
+  struct kvm_hyperv_tlb_flush_inhibit {
+      /* in */
+      __u16 flags;
+  #define KVM_HYPERV_UNINHIBIT_TLB_FLUSH 0
+  #define KVM_HYPERV_INHIBIT_TLB_FLUSH 1
+      __u8  inhibit;
+      __u8 padding[5];
+  };
+
+No flags are specified so far, the corresponding field must be set to zero,
+otherwise the ioctl will fail with exit code -EINVAL.
+
+The suspension is transparent to userspace. It won't cause KVM_RUN to return or
+the MP state to be changed. The suspension cannot be manually induced or exited
+apart from changing the TLB flush inhibit flag of a targeted processor.
+
+There is no way for userspace to query the state of the flush inhibit flag.
+Userspace must keep track of the required state itself.
+
 5. The kvm_run structure
 ========================
 
-- 
2.40.1




Amazon Web Services Development Center Germany GmbH
Krausenstr. 38
10117 Berlin
Geschaeftsfuehrung: Christian Schlaeger, Jonathan Weiss
Eingetragen am Amtsgericht Charlottenburg unter HRB 257764 B
Sitz: Berlin
Ust-ID: DE 365 538 597

Nikolas Wipper <nikwip@amazon.de> writes:

> Add API documentation for the new KVM_HYPERV_SET_TLB_FLUSH_INHIBIT ioctl.
>
> Signed-off-by: Nikolas Wipper <nikwip@amazon.de>
> ---
>  Documentation/virt/kvm/api.rst | 41 ++++++++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
>
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index a4b7dc4a9dda..9c11a8af336b 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -6443,6 +6443,47 @@ the capability to be present.
>  `flags` must currently be zero.
>  
>  
> +4.144 KVM_HYPERV_SET_TLB_FLUSH_INHIBIT
> +--------------------------------------
> +
> +:Capability: KVM_CAP_HYPERV_TLB_FLUSH_INHIBIT
> +:Architectures: x86
> +:Type: vcpu ioctl
> +:Parameters: struct kvm_hyperv_tlb_flush_inhibit
> +:returnReturns: 0 on success, this ioctl can't fail
> +
> +KVM_HYPERV_SET_TLB_FLUSH_INHIBIT allows userspace to prevent Hyper-V
> hyper-calls

Very minor nitpick: I suggest standardize on "hypercall" spelling
without the dash because:

$ grep -c hypercall Documentation/virt/kvm/api.rst
56
$ grep -c hyper-call Documentation/virt/kvm/api.rst
3

(I see all three 'hypercall', 'hyper-call', 'hyper call' usages in the
wild and I honestly don't think it matters but it would be nice to
adhere to one share across the same file / KVM docs).

> +that remotely flush a vCPU's TLB, i.e. HvFlushVirtualAddressSpace(Ex)/
> +HvFlushVirtualAddressList(Ex). When the flag is set, a vCPU attempting to flush
> +an inhibited vCPU will be suspended and will only resume once the flag is
> +cleared again using this ioctl. During suspension, the vCPU will not finish the
> +hyper-call, but may enter the guest to retry it. Because it is caused by a
> +hyper-call, the suspension naturally happens on a guest instruction boundary.
> +This behaviour and the suspend state itself are specified in Microsoft's
> +"Hypervisor Top Level Functional Specification" (TLFS).
> +
> +::
> +
> +  /* for KVM_HYPERV_SET_TLB_FLUSH_INHIBIT */
> +  struct kvm_hyperv_tlb_flush_inhibit {
> +      /* in */
> +      __u16 flags;
> +  #define KVM_HYPERV_UNINHIBIT_TLB_FLUSH 0
> +  #define KVM_HYPERV_INHIBIT_TLB_FLUSH 1
> +      __u8  inhibit;
> +      __u8 padding[5];
> +  };
> +
> +No flags are specified so far, the corresponding field must be set to zero,
> +otherwise the ioctl will fail with exit code -EINVAL.
> +
> +The suspension is transparent to userspace. It won't cause KVM_RUN to return or
> +the MP state to be changed. The suspension cannot be manually induced or exited
> +apart from changing the TLB flush inhibit flag of a targeted processor.
> +
> +There is no way for userspace to query the state of the flush inhibit flag.
> +Userspace must keep track of the required state itself.
> +
>  5. The kvm_run structure
>  ========================

-- 
Vitaly