Skip to contentSkip to conversation

KVM: Halt-polling documentation cleanups

PATCH Applied David Matlack 2 participants 4 messages Dec 1, 2022 – Dec 2, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover KVM: Halt-polling documentation cleanups

This series makes some small cleanups to the existing halt-polling documentation. Patch 1 moves halt-polling.rst out of the x86-specific directory, and patch 2 clarifies the interaction between KVM_CAP_HALT_POLL and kvm.halt_poll_ns, which was recently broken and a source of confusion [1].

[1] https://lore.kernel.org/kvm/[email protected]/

Cc Yanan Wang <[email protected]>
Cc Christian Borntraeger <[email protected]>

David Matlack (2):
KVM: Move halt-polling documentation into common directory
KVM: Document the interaction between KVM_CAP_HALT_POLL and
halt_poll_ns

 Documentation/virt/kvm/api.rst                    | 15 +++++++--------
 Documentation/virt/kvm/{x86 => }/halt-polling.rst | 13 +++++++++++++
 Documentation/virt/kvm/index.rst                  |  1 +
 Documentation/virt/kvm/x86/index.rst              |  1 -
 4 files changed, 21 insertions(+), 9 deletions(-)
 rename Documentation/virt/kvm/{x86 => }/halt-polling.rst (92%)

base-commit: 7e3bba93f42e9d9abe81344bdba5ddc635b7c449

Signature · 1 line
2.39.0.rc0.267.gcb52ba06e7-goog
#1 lore raw

PATCH 1/2 KVM: Move halt-polling documentation into common directory

Move halt-polling.rst into the common KVM documentation directory and out of the x86-specific directory. Halt-polling is a common feature and the existing documentation is already written as such.

---
 Documentation/virt/kvm/{x86 => }/halt-polling.rst | 0
 Documentation/virt/kvm/index.rst                  | 1 +
 Documentation/virt/kvm/x86/index.rst              | 1 -
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename Documentation/virt/kvm/{x86 => }/halt-polling.rst (100%)
Documentation/virt/kvm/halt-polling.rst renamed from Documentation/virt/kvm/x86/halt-polling.rst +0 -0
similarity index 100%
rename from Documentation/virt/kvm/x86/halt-polling.rst
rename to Documentation/virt/kvm/halt-polling.rst
Documentation/virt/kvm/index.rst +1 -0
index e0a2c74e1043..ad13ec55ddfe 100644
@@ -17,4 +17,5 @@ KVM
 
    locking
    vcpu-requests
+   halt-polling
    review-checklist
Documentation/virt/kvm/x86/index.rst +0 -1
index 7ff588826b9f..9ece6b8dc817 100644
@@ -10,7 +10,6 @@ KVM for x86 systems
    amd-memory-encryption
    cpuid
    errata
-   halt-polling
    hypercalls
    mmu
    msr
Signature · 1 line
2.39.0.rc0.267.gcb52ba06e7-goog
#2 lore raw

PATCH 2/2 KVM: Document the interaction between KVM_CAP_HALT_POLL and halt_poll_ns

In reply to David Matlack

Clarify the existing documentation about how KVM_CAP_HALT_POLL and halt_poll_ns interact to make it clear that VMs using KVM_CAP_HALT_POLL ignore halt_poll_ns.

---
 Documentation/virt/kvm/api.rst          | 15 +++++++--------
 Documentation/virt/kvm/halt-polling.rst | 13 +++++++++++++
 2 files changed, 20 insertions(+), 8 deletions(-)
Documentation/virt/kvm/api.rst +7 -8
index eee9f857a986..896914e3a847 100644
@@ -7213,14 +7213,13 @@ veto the transition.
 :Parameters: args[0] is the maximum poll time in nanoseconds
 :Returns: 0 on success; -1 on error
 
-This capability overrides the kvm module parameter halt_poll_ns for the
-target VM.
-
-VCPU polling allows a VCPU to poll for wakeup events instead of immediately
-scheduling during guest halts. The maximum time a VCPU can spend polling is
-controlled by the kvm module parameter halt_poll_ns. This capability allows
-the maximum halt time to specified on a per-VM basis, effectively overriding
-the module parameter for the target VM.
+KVM_CAP_HALT_POLL overrides the kvm.halt_poll_ns module parameter to set the
+maximum halt-polling time for all vCPUs in the target VM. This capability can
+be invoked at any time and any number of times to dynamically change the
+maximum halt-polling time.
+
+See Documentation/virt/kvm/halt-polling.rst for more information on halt
+polling.
 
 7.21 KVM_CAP_X86_USER_SPACE_MSR
 -------------------------------
Documentation/virt/kvm/halt-polling.rst +13 -0
index 4922e4a15f18..3fae39b1a5ba 100644
@@ -119,6 +119,19 @@ These module parameters can be set from the debugfs files in:
 Note: that these module parameters are system wide values and are not able to
       be tuned on a per vm basis.
 
+Any changes to these parameters will be picked up by new and existing vCPUs the
+next time they halt, with the notable exception of VMs using KVM_CAP_HALT_POLL
+(see next section).
+
+KVM_CAP_HALT_POLL
+=================
+
+KVM_CAP_HALT_POLL is a VM capability that allows userspace to override halt_poll_ns
+on a per-VM basis. VMs using KVM_CAP_HALT_POLL ignore halt_poll_ns completely (but
+still obey halt_poll_ns_grow, halt_poll_ns_grow_start, and halt_poll_ns_shrink).
+
+See Documentation/virt/kvm/api.rst for more information on this capability.
+
 Further Notes
 =============
 
Signature · 1 line
2.39.0.rc0.267.gcb52ba06e7-goog
maintainer Applied
#3 lore raw
In reply to David Matlack
Quoted 21 lines · David Matlack

This series makes some small cleanups to the existing halt-polling documentation. Patch 1 moves halt-polling.rst out of the x86-specific directory, and patch 2 clarifies the interaction between KVM_CAP_HALT_POLL and kvm.halt_poll_ns, which was recently broken and a source of confusion [1].

[1] https://lore.kernel.org/kvm/[email protected]/

Cc Yanan Wang <[email protected]>
Cc Christian Borntraeger <[email protected]>

David Matlack (2):
KVM: Move halt-polling documentation into common directory
KVM: Document the interaction between KVM_CAP_HALT_POLL and
halt_poll_ns

  Documentation/virt/kvm/api.rst                    | 15 +++++++--------
  Documentation/virt/kvm/{x86 => }/halt-polling.rst | 13 +++++++++++++
  Documentation/virt/kvm/index.rst                  |  1 +
  Documentation/virt/kvm/x86/index.rst              |  1 -
  4 files changed, 21 insertions(+), 9 deletions(-)
Quoted 4 lines

rename Documentation/virt/kvm/{x86 => }/halt-polling.rst (92%)

base-commit: 7e3bba93f42e9d9abe81344bdba5ddc635b7c449

Queued, thanks.

Paolo