Corrected kvm documentation to reflect current handling of
polling interval on successful and un-successful polling events.
Also updated the description about newly added halt_poll_ns_grow_start
parameter.
Co-developed-by: Rajendran Jaishankar <[email protected]>
Signed-off-by: Rajendran Jaishankar <[email protected]>
Signed-off-by: Parshuram Sangle <[email protected]>
---
Documentation/virt/kvm/halt-polling.rst | 24 +++++++++++++-----------
1 file changed, 13 insertions(+), 11 deletions(-)
diff --git a/Documentation/virt/kvm/halt-polling.rst b/Documentation/virt/kvm/halt-polling.rst
index 64f32a81133f..cff388d9dc72 100644
--- a/Documentation/virt/kvm/halt-polling.rst
+++ b/Documentation/virt/kvm/halt-polling.rst
@@ -44,12 +44,14 @@ or in the case of powerpc kvm-hv, in the vcore struct:
Thus this is a per vcpu (or vcore) value.
-During polling if a wakeup source is received within the halt polling interval,
-the interval is left unchanged. In the event that a wakeup source isn't
-received during the polling interval (and thus schedule is invoked) there are
-two options, either the polling interval and total block time[0] were less than
-the global max polling interval (see module params below), or the total block
-time was greater than the global max polling interval.
+During polling if a wakeup source is not received within the halt polling
+interval (and thus schedule is invoked), the interval is always shrunk in
+shrink_halt_poll_ns(). In the event that a wakeup source is received during
+the polling interval, polling interval is left unchanged if total block time
+is below or equal to current interval value otherwise there are two options,
+either the polling interval and total block time[0] were less than the global
+max polling interval (see module params below), or the total block time was
+greater than the global max polling interval.
In the event that both the polling interval and total block time were less than
the global max polling interval then the polling interval can be increased in
@@ -79,11 +81,11 @@ adjustment of the polling interval.
Module Parameters
=================
-The kvm module has 3 tuneable module parameters to adjust the global max
-polling interval as well as the rate at which the polling interval is grown and
-shrunk. These variables are defined in include/linux/kvm_host.h and as module
-parameters in virt/kvm/kvm_main.c, or arch/powerpc/kvm/book3s_hv.c in the
-powerpc kvm-hv case.
+The kvm module has 4 tunable module parameters to adjust the global max
+polling interval, initial value (to grow from 0) as well as the rate at which
+the polling interval is grown and shrunk. These variables are defined in
+include/linux/kvm_host.h and as module parameters in virt/kvm/kvm_main.c, or
+arch/powerpc/kvm/book3s_hv.c in the powerpc kvm-hv case.
+-----------------------+---------------------------+-------------------------+
|Module Parameter | Description | Default Value |
--
2.17.1
On Thu, Nov 02, 2023, Parshuram Sangle wrote:
> Corrected kvm documentation to reflect current handling of
> polling interval on successful and un-successful polling events.
> Also updated the description about newly added halt_poll_ns_grow_start
> parameter.
>
> Co-developed-by: Rajendran Jaishankar <[email protected]>
> Signed-off-by: Rajendran Jaishankar <[email protected]>
> Signed-off-by: Parshuram Sangle <[email protected]>
> ---
> Documentation/virt/kvm/halt-polling.rst | 24 +++++++++++++-----------
> 1 file changed, 13 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/virt/kvm/halt-polling.rst b/Documentation/virt/kvm/halt-polling.rst
> index 64f32a81133f..cff388d9dc72 100644
> --- a/Documentation/virt/kvm/halt-polling.rst
> +++ b/Documentation/virt/kvm/halt-polling.rst
> @@ -44,12 +44,14 @@ or in the case of powerpc kvm-hv, in the vcore struct:
>
> Thus this is a per vcpu (or vcore) value.
>
> -During polling if a wakeup source is received within the halt polling interval,
> -the interval is left unchanged. In the event that a wakeup source isn't
> -received during the polling interval (and thus schedule is invoked) there are
> -two options, either the polling interval and total block time[0] were less than
> -the global max polling interval (see module params below), or the total block
> -time was greater than the global max polling interval.
> +During polling if a wakeup source is not received within the halt polling
> +interval (and thus schedule is invoked), the interval is always shrunk in
> +shrink_halt_poll_ns().
This is wrong. KVM grows the interval if the wakeup event arrives after KVM
stops polling if the total halt time is less than the max allowed interval.
The existing wording is a bit odd, and it fails to document the per-VM capability,
but I didn't find anything in the existing documentation that is incorrect (ignoring
the Module Parameters section below).
If we wanted to clean things up, I would vote for something like the below. For
this patch, I'm going to drop this update and just keep the Module Parameters fixes.
During polling if a wakeup source is received within the halt polling interval,
the interval is left unchanged (the total block time[0] is less than or equal
to the current interval). If the block time is greater than the interval,
there are two possibilities: either the polling interval and total block time
were less than the VM's max polling interval (see module params and
KVM_CAP_HALT_POLL below), or the total block time was greater than the VM's max
polling interval.
In the event that both the polling interval and total block time were less than
the max polling interval then the polling interval can be increased in the hope
that next time during the longer polling interval the wake up source will be
received while the host is polling and the latency benefits will be received.
The polling interval is grown in the function grow_halt_poll_ns() and is
multiplied by the module parameters halt_poll_ns_grow and
halt_poll_ns_grow_start.
In the event that the total block time was greater than the VM's max polling
interval then the host will never poll for long enough to wakeup during the
polling interval (KVM will always poll for less time than the block time), so
the polling internal is shrunk in order to avoid pointless polling. The polling
interval is shrunk in the function shrink_halt_poll_ns() and is divided by the
module parameter halt_poll_ns_shrink, or set to 0 iff halt_poll_ns_shrink == 0.
It is worth noting that this adjustment process attempts to hone in on some
steady state polling interval but will only really do a good job for wakeups
which come at an approximately constant rate, otherwise there will be constant
adjustment of the polling interval.