* [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc
@ 2020-05-01 19:34 Joshua Abraham
2020-05-01 20:18 ` Sean Christopherson
0 siblings, 1 reply; 6+ messages in thread
From: Joshua Abraham @ 2020-05-01 19:34 UTC (permalink / raw)
To: pbonzini; +Cc: corbet, kvm, linux-doc, linux-kernel, j.abraham1776
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.
Signed-off-by: Joshua Abraham <j.abraham1776@gmail.com>
---
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 host will set a flag in the pvclock structure that is checked
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc
2020-05-01 19:34 [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc Joshua Abraham
@ 2020-05-01 20:18 ` Sean Christopherson
2020-05-01 20:32 ` Joshua Abraham
0 siblings, 1 reply; 6+ messages in thread
From: Sean Christopherson @ 2020-05-01 20:18 UTC (permalink / raw)
To: Joshua Abraham; +Cc: pbonzini, corbet, kvm, linux-doc, linux-kernel
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@gmail.com>
> ---
> 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
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc
2020-05-01 20:18 ` Sean Christopherson
@ 2020-05-01 20:32 ` Joshua Abraham
2020-05-01 20:51 ` Sean Christopherson
0 siblings, 1 reply; 6+ messages in thread
From: Joshua Abraham @ 2020-05-01 20:32 UTC (permalink / raw)
To: Sean Christopherson; +Cc: pbonzini, corbet, kvm, linux-doc, linux-kernel
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc
2020-05-01 20:32 ` Joshua Abraham
@ 2020-05-01 20:51 ` Sean Christopherson
2020-05-01 21:10 ` Joshua Abraham
0 siblings, 1 reply; 6+ messages in thread
From: Sean Christopherson @ 2020-05-01 20:51 UTC (permalink / raw)
To: Joshua Abraham; +Cc: pbonzini, corbet, kvm, linux-doc, linux-kernel
On Fri, May 01, 2020 at 04:32:34PM -0400, Joshua Abraham wrote:
> 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.
I don't disagree, but simply doing s/host/guest yields a misleading
sentence and inconsistencies with the rest of the paragraph.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc
2020-05-01 20:51 ` Sean Christopherson
@ 2020-05-01 21:10 ` Joshua Abraham
2020-05-01 21:38 ` Sean Christopherson
0 siblings, 1 reply; 6+ messages in thread
From: Joshua Abraham @ 2020-05-01 21:10 UTC (permalink / raw)
To: Sean Christopherson
Cc: pbonzini, corbet, kvm, linux-doc, linux-kernel, j.abraham1776
On Fri, May 01, 2020 at 01:51:06PM -0700, Sean Christopherson wrote:
> I don't disagree, but simply doing s/host/guest yields a misleading
> sentence and inconsistencies with the rest of the paragraph.
I see your point. Would this wording be clearer:
"This ioctl sets a flag accessible to the guest indicating that it has been
paused from the host userspace.
The host will set a flag in the pvclock structure that is checked
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
field of the pvclock_vcpu_time_info structure. It will be set exclusively by
the host and read/cleared exclusively by the guest. The guest operation of
checking and clearing the flag must be an atomic operation so
load-link/store-conditional, or equivalent must be used. There are two cases
where the guest will clear the flag: when the soft lockup watchdog timer resets
itself or when a soft lockup is detected. This ioctl can be called any time
after pausing the vcpu, but before it is resumed."
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc
2020-05-01 21:10 ` Joshua Abraham
@ 2020-05-01 21:38 ` Sean Christopherson
0 siblings, 0 replies; 6+ messages in thread
From: Sean Christopherson @ 2020-05-01 21:38 UTC (permalink / raw)
To: Joshua Abraham; +Cc: pbonzini, corbet, kvm, linux-doc, linux-kernel
On Fri, May 01, 2020 at 05:10:40PM -0400, Joshua Abraham wrote:
> On Fri, May 01, 2020 at 01:51:06PM -0700, Sean Christopherson wrote:
> > I don't disagree, but simply doing s/host/guest yields a misleading
> > sentence and inconsistencies with the rest of the paragraph.
>
> I see your point. Would this wording be clearer:
>
> "This ioctl sets a flag accessible to the guest indicating that it has been
> paused from the host userspace.
Ya. Minor nit, probably worth clarifying that 'it' refers to the vCPU, e.g.
This ioctl sets a flag accessible to the guest indicating that the specified
vCPU has been paused by the host userspace.
>
> The host will set a flag in the pvclock structure that is checked
> 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
> field of the pvclock_vcpu_time_info structure. It will be set exclusively by
> the host and read/cleared exclusively by the guest. The guest operation of
> checking and clearing the flag must be an atomic operation so
> load-link/store-conditional, or equivalent must be used. There are two cases
> where the guest will clear the flag: when the soft lockup watchdog timer resets
> itself or when a soft lockup is detected. This ioctl can be called any time
> after pausing the vcpu, but before it is resumed."
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-05-01 21:38 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-05-01 19:34 [PATCH] docs: kvm: Fix KVM_KVMCLOCK_CTRL API doc Joshua Abraham
2020-05-01 20:18 ` Sean Christopherson
2020-05-01 20:32 ` Joshua Abraham
2020-05-01 20:51 ` Sean Christopherson
2020-05-01 21:10 ` Joshua Abraham
2020-05-01 21:38 ` Sean Christopherson
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).