[PATCH] KVM: Document KVM_NMI

[PATCH] KVM: Document KVM_NMI

[Sasha Levin]

Cc: Avi Kivity <avi@redhat.com>
Cc: Marcelo Tosatti <mtosatti@redhat.com>
Cc: kvm@vger.kernel.org
Signed-off-by: Sasha Levin <levinsasha928@gmail.com>
---
 Documentation/virtual/kvm/api.txt |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)

diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index 7945b0b..0b7b8f2 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -1450,6 +1450,19 @@ is supported; 2 if the processor requires all virtual machines to have
 an RMA, or 1 if the processor can use an RMA but doesn't require it,
 because it supports the Virtual RMA (VRMA) facility.
 
+4.64 KVM_NMI
+
+Capability: basic
+Architectures: none
+Type: vcpu ioctl
+Parameters: none
+Returns: 0 on success, -1 on error
+
+Trigger an NMI on the specified VCPU.
+
+This can be used to cause a panic in the guest, which in turn would result
+in a backtrace/dump.
+
 5. The kvm_run structure
 
 Application code obtains a pointer to the kvm_run structure by
-- 
1.7.8

Re: [PATCH] KVM: Document KVM_NMI

[Avi Kivity]

On 12/06/2011 10:50 PM, Sasha Levin wrote:
> Cc: Avi Kivity <avi@redhat.com>
> Cc: Marcelo Tosatti <mtosatti@redhat.com>
> Cc: kvm@vger.kernel.org

Somehow, the changelog became the place where people manage their cc lists.

>  
> +4.64 KVM_NMI
> +
> +Capability: basic
> +Architectures: none
> +Type: vcpu ioctl
> +Parameters: none
> +Returns: 0 on success, -1 on error
> +
> +Trigger an NMI on the specified VCPU.
> +
> +This can be used to cause a panic in the guest, which in turn would result
> +in a backtrace/dump.
> +

I'm nitpicking, but this is too strongly worded.  It's completely up to
the guest how to interpret the NMI.

It's also subtly broken with kernel irqchip - it injects an NMI
unconditionally even though LINT1 can be configured to mask NMIs, or to
do something other than queue an NMI (for example, queue a regular
interrupt).  Please note this.

On second thoughts, I'll just document this instead of telling you what
to write.

-- 
error compiling committee.c: too many arguments to function
 

[PATCH] KVM: Document KVM_NMI

[Avi Kivity]

Signed-off-by: Avi Kivity <avi@redhat.com>
---
 Documentation/virtual/kvm/api.txt |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)

diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index 7945b0b..38f68ca 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -1450,6 +1450,31 @@ is supported; 2 if the processor requires all virtual machines to have
 an RMA, or 1 if the processor can use an RMA but doesn't require it,
 because it supports the Virtual RMA (VRMA) facility.
 
+4.64 KVM_NMI
+
+Capability: KVM_CAP_USER_NMI
+Architectures: x86
+Type: vcpu ioctl
+Parameters: none
+Returns: 0 on success, -1 on error
+
+Queues an NMI on the thread's vcpu.  Note this is well defined only
+when KVM_CREATE_IRQCHIP has not been called, since this is an interface
+between the virtual cpu core and virtual local APIC.  After KVM_CREATE_IRQCHIP
+has been called, this interface is completely emulated within the kernel.
+
+To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the
+following algorithm:
+
+  - pause the vpcu
+  - read the local APIC's state (KVM_GET_LAPIC)
+  - check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1)
+  - if so, issue KVM_NMI
+  - resume the vcpu
+
+Some guests configure the LINT1 NMI input to cause a panic, aiding in
+debugging.
+
 5. The kvm_run structure
 
 Application code obtains a pointer to the kvm_run structure by
-- 
1.7.7.1

Re: [PATCH] KVM: Document KVM_NMI

[Sasha Levin]

On Wed, 2011-12-07 at 12:43 +0200, Avi Kivity wrote:
> Signed-off-by: Avi Kivity <avi@redhat.com>
> ---
>  Documentation/virtual/kvm/api.txt |   25 +++++++++++++++++++++++++
>  1 files changed, 25 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
> index 7945b0b..38f68ca 100644
> --- a/Documentation/virtual/kvm/api.txt
> +++ b/Documentation/virtual/kvm/api.txt
> @@ -1450,6 +1450,31 @@ is supported; 2 if the processor requires all virtual machines to have
>  an RMA, or 1 if the processor can use an RMA but doesn't require it,
>  because it supports the Virtual RMA (VRMA) facility.
>  
> +4.64 KVM_NMI
> +
> +Capability: KVM_CAP_USER_NMI
> +Architectures: x86
> +Type: vcpu ioctl
> +Parameters: none
> +Returns: 0 on success, -1 on error
> +
> +Queues an NMI on the thread's vcpu.  Note this is well defined only
> +when KVM_CREATE_IRQCHIP has not been called, since this is an interface
> +between the virtual cpu core and virtual local APIC.  After KVM_CREATE_IRQCHIP
> +has been called, this interface is completely emulated within the kernel.
> +
> +To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the
> +following algorithm:
> +
> +  - pause the vpcu

I don't see the QEMU patch doing a stop before grabbing LAPIC state. Or
does it happen somewhere before?

-- 

Sasha.

Re: [PATCH] KVM: Document KVM_NMI

[Avi Kivity]

On 12/07/2011 01:02 PM, Sasha Levin wrote:
> I don't see the QEMU patch doing a stop before grabbing LAPIC state. Or
> does it happen somewhere before?

It got dropped on the floor; it's now in next.

-- 
error compiling committee.c: too many arguments to function

Re: [PATCH] KVM: Document KVM_NMI

[Sasha Levin]

On Wed, 2011-12-07 at 14:12 +0200, Avi Kivity wrote:
> On 12/07/2011 01:02 PM, Sasha Levin wrote:
> > I don't see the QEMU patch doing a stop before grabbing LAPIC state. Or
> > does it happen somewhere before?
> 
> It got dropped on the floor; it's now in next.

I was talking about that patch you merged. I don't see where the vcpu is
being paused before getting the LAPIC state.

-- 

Sasha.

Re: [PATCH] KVM: Document KVM_NMI

[Avi Kivity]

On 12/07/2011 02:20 PM, Sasha Levin wrote:
> On Wed, 2011-12-07 at 14:12 +0200, Avi Kivity wrote:
> > On 12/07/2011 01:02 PM, Sasha Levin wrote:
> > > I don't see the QEMU patch doing a stop before grabbing LAPIC state. Or
> > > does it happen somewhere before?
> > 
> > It got dropped on the floor; it's now in next.
>
> I was talking about that patch you merged. I don't see where the vcpu is
> being paused before getting the LAPIC state.
>

Oh, sorry.  Well, once you exit from KVM_RUN, the vcpu is paused.

It's really implied by the fact that vcpu ioctls must be issued from the
same thread.

-- 
error compiling committee.c: too many arguments to function

Re: [PATCH] KVM: Document KVM_NMI

[Sasha Levin]

On Wed, 2011-12-07 at 14:31 +0200, Avi Kivity wrote:
> On 12/07/2011 02:20 PM, Sasha Levin wrote:
> > On Wed, 2011-12-07 at 14:12 +0200, Avi Kivity wrote:
> > > On 12/07/2011 01:02 PM, Sasha Levin wrote:
> > > > I don't see the QEMU patch doing a stop before grabbing LAPIC state. Or
> > > > does it happen somewhere before?
> > > 
> > > It got dropped on the floor; it's now in next.
> >
> > I was talking about that patch you merged. I don't see where the vcpu is
> > being paused before getting the LAPIC state.
> >
> 
> Oh, sorry.  Well, once you exit from KVM_RUN, the vcpu is paused.
> 
> It's really implied by the fact that vcpu ioctls must be issued from the
> same thread.

Oh, I totally forgot about that (here, and in my 'kvm nmi' patch).

Thanks!

-- 

Sasha.

Re: [PATCH] KVM: Document KVM_NMI

[Avi Kivity]

On 12/07/2011 02:37 PM, Sasha Levin wrote:
> > 
> > It's really implied by the fact that vcpu ioctls must be issued from the
> > same thread.
>
> Oh, I totally forgot about that (here, and in my 'kvm nmi' patch).

It keeps biting people.  We should make the kernel warn about it.

The reason it's important is because we might some day want to move to a
syscall based API, rather than ioctl based.  In this model a vcpu is
bound to the thread that calls kvm_create_vcpu(2), and all vcpu syscalls
derive the vcpu from the thread.

This model is more natural than the ioctl model, however it is a lot of
work and doesn't solve any real life problems; it only creates a larger
compatibility burden.  But it's still the right thing.

-- 
error compiling committee.c: too many arguments to function

Re: [PATCH] KVM: Document KVM_NMI

[Marcelo Tosatti]

On Wed, Dec 07, 2011 at 12:43:33PM +0200, Avi Kivity wrote:
> Signed-off-by: Avi Kivity <avi@redhat.com>
> ---
>  Documentation/virtual/kvm/api.txt |   25 +++++++++++++++++++++++++
>  1 files changed, 25 insertions(+), 0 deletions(-)

Applied, thanks.