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

[Joshua Abraham]

On Fri, May 01, 2020 at 01:18:36PM -0700, Sean Christopherson wrote:
> No, the current documentation is correct.  It's probably not as clear as
> it could be, but it's accurate as written.  More below.
> 
> 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.

The rationale is that the guest is what consumes the pvclock flag, the
host kernel does nothing interesting (from the API caller perspective) 
besides setting up the kvmclock update. The ioctl calls kvm_set_guest_paused() 
which even has a comment saying "[it] indicates to the guest kernel that it has 
been stopped by the hypervisor." I think that the docs first sentence should 
clearly reflect that the API tells the guest that it has been paused. 

-Josh