Re: [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc

[Sean Christopherson]

On Fri, May 01, 2020 at 03:34:06PM -0400, Joshua Abraham wrote:
> The KVM_KVMCLOCK_CTRL ioctl signals to supported KVM guests
> that the hypervisor has paused it.  This updates the documentation
> to reflect that the guest, not the host is notified by this API.

No, the current documentation is correct.  It's probably not as clear as
it could be, but it's accurate as written.  More below.

> Signed-off-by: Joshua Abraham <j.abraham1776@xxxxxxxxx>
> ---
>  Documentation/virt/kvm/api.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index efbbe570aa9b..06a4d9bfc6e5 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -2572,7 +2572,7 @@ list in 4.68.
>  :Parameters: None
>  :Returns: 0 on success, -1 on error
>  
> -This signals to the host kernel that the specified guest is being paused by
> +This signals to the guest kernel that the specified guest is being paused by
>  userspace.

The ioctl() signals to the host kernel that host userspace has paused the
vCPU.

>  The host will set a flag in the pvclock structure that is checked

The host kernel, i.e. KVM, then takes that information and forwards it to
the guest kernel via the aforementioned pvclock flag.

The proposed change would imply the ioctl() is somehow getting routed
directly to the guest, which is wrong.

>  from the soft lockup watchdog.  The flag is part of the pvclock structure that
>  is shared between guest and host, specifically the second bit of the flags
> -- 
> 2.17.1
>