Re: [PATCH 2/2] KVM: documentation update to halt polling

[Sean Christopherson <seanjc@google.com>]

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 <jaishankar.rajendran@intel.com>
> Signed-off-by: Rajendran Jaishankar <jaishankar.rajendran@intel.com>
> Signed-off-by: Parshuram Sangle <parshuram.sangle@intel.com>
> ---
>  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.