[PATCH] kvm: Document KVM_IOEVENTFD

[PATCH] kvm: Document KVM_IOEVENTFD

[Sasha Levin]

Document KVM_IOEVENTFD that can be used to receive
notifications of PIO/MMIO events without triggering
an exit.

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

diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index 42542eb..80c5fcd 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -1291,6 +1291,36 @@ Returns the tsc frequency of the guest. The unit of the return value is
 KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
 error.
 
+4.56 KVM_IOEVENTFD
+
+Capability: KVM_CAP_IOEVENTFD
+Architectures: all
+Type: vm ioctl
+Parameters: struct kvm_ioeventfd (in)
+Returns: 0 on success, !0 on error
+
+This ioctl attaches or deattaches an ioeventfd to a legal pio/mmio address
+within the guest.  A guest write in the registered address will signal the
+provided event instead of triggering an exit.
+
+struct kvm_ioeventfd {
+	__u64 datamatch;
+	__u64 addr;        /* legal pio/mmio address */
+	__u32 len;         /* 1, 2, 4, or 8 bytes    */
+	__s32 fd;
+	__u32 flags;
+	__u8  pad[36];
+};
+
+The following flags are defined:
+
+#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
+#define KVM_IOEVENTFD_FLAG_PIO       (1 << kvm_ioeventfd_flag_nr_pio)
+#define KVM_IOEVENTFD_FLAG_DEASSIGN  (1 << kvm_ioeventfd_flag_nr_deassign)
+
+If datamatch flag is set, the event will be signaled only if the written value
+to the registered address is equal to datamatch in struct kvm_ioeventfd. 
+
 5. The kvm_run structure
 
 Application code obtains a pointer to the kvm_run structure by
-- 
1.7.5.rc3

Re: [PATCH] kvm: Document KVM_IOEVENTFD

[Takuya Yoshikawa]

On Sat, 28 May 2011 14:12:30 +0300
Sasha Levin <levinsasha928@gmail.com> wrote:

> Document KVM_IOEVENTFD that can be used to receive
> notifications of PIO/MMIO events without triggering
> an exit.
> 
> Cc: Avi Kivity <avi@redhat.com>
> Cc: Marcelo Tosatti <mtosatti@redhat.com>
> Signed-off-by: Sasha Levin <levinsasha928@gmail.com>
> ---
>  Documentation/virtual/kvm/api.txt |   30 ++++++++++++++++++++++++++++++
>  1 files changed, 30 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
> index 42542eb..80c5fcd 100644
> --- a/Documentation/virtual/kvm/api.txt
> +++ b/Documentation/virtual/kvm/api.txt
> @@ -1291,6 +1291,36 @@ Returns the tsc frequency of the guest. The unit of the return value is
>  KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
>  error.
>  
> +4.56 KVM_IOEVENTFD
> +
> +Capability: KVM_CAP_IOEVENTFD
> +Architectures: all
> +Type: vm ioctl
> +Parameters: struct kvm_ioeventfd (in)
> +Returns: 0 on success, !0 on error
> +
> +This ioctl attaches or deattaches an ioeventfd to a legal pio/mmio address

Typo: attach -- detach (probably, I'm not a native)

Thanks,
  Takuya

> +within the guest.  A guest write in the registered address will signal the
> +provided event instead of triggering an exit.
> +
> +struct kvm_ioeventfd {
> +	__u64 datamatch;
> +	__u64 addr;        /* legal pio/mmio address */
> +	__u32 len;         /* 1, 2, 4, or 8 bytes    */
> +	__s32 fd;
> +	__u32 flags;
> +	__u8  pad[36];
> +};
> +
> +The following flags are defined:
> +
> +#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
> +#define KVM_IOEVENTFD_FLAG_PIO       (1 << kvm_ioeventfd_flag_nr_pio)
> +#define KVM_IOEVENTFD_FLAG_DEASSIGN  (1 << kvm_ioeventfd_flag_nr_deassign)
> +
> +If datamatch flag is set, the event will be signaled only if the written value
> +to the registered address is equal to datamatch in struct kvm_ioeventfd. 
> +
>  5. The kvm_run structure
>  
>  Application code obtains a pointer to the kvm_run structure by
> -- 
> 1.7.5.rc3
> 
> --
> To unsubscribe from this list: send the line "unsubscribe kvm" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html


-- 
Takuya Yoshikawa <yoshikawa.takuya@oss.ntt.co.jp>

Re: [PATCH] kvm: Document KVM_IOEVENTFD

[Marcelo Tosatti]

On Sat, May 28, 2011 at 02:12:30PM +0300, Sasha Levin wrote:
> Document KVM_IOEVENTFD that can be used to receive
> notifications of PIO/MMIO events without triggering
> an exit.
> 
> Cc: Avi Kivity <avi@redhat.com>
> Cc: Marcelo Tosatti <mtosatti@redhat.com>
> Signed-off-by: Sasha Levin <levinsasha928@gmail.com>
> ---
>  Documentation/virtual/kvm/api.txt |   30 ++++++++++++++++++++++++++++++
>  1 files changed, 30 insertions(+), 0 deletions(-)

Applied (with wording fix), thanks.

Re: [PATCH] kvm: Document KVM_IOEVENTFD

[Jan Kiszka]

On 2011-05-31 15:44, Marcelo Tosatti wrote:
> On Sat, May 28, 2011 at 02:12:30PM +0300, Sasha Levin wrote:
>> Document KVM_IOEVENTFD that can be used to receive
>> notifications of PIO/MMIO events without triggering
>> an exit.
>>
>> Cc: Avi Kivity <avi@redhat.com>
>> Cc: Marcelo Tosatti <mtosatti@redhat.com>
>> Signed-off-by: Sasha Levin <levinsasha928@gmail.com>
>> ---
>>  Documentation/virtual/kvm/api.txt |   30 ++++++++++++++++++++++++++++++
>>  1 files changed, 30 insertions(+), 0 deletions(-)
> 
> Applied (with wording fix), thanks.

Requires section number fix-up (4.56 -> 4.58).

Jan

-- 
Siemens AG, Corporate Technology, CT T DE IT 1
Corporate Competence Center Embedded Linux

Re: [PATCH] kvm: Document KVM_IOEVENTFD

[Avi Kivity]

On 06/01/2011 01:51 PM, Jan Kiszka wrote:
> On 2011-05-31 15:44, Marcelo Tosatti wrote:
> >  On Sat, May 28, 2011 at 02:12:30PM +0300, Sasha Levin wrote:
> >>  Document KVM_IOEVENTFD that can be used to receive
> >>  notifications of PIO/MMIO events without triggering
> >>  an exit.
> >>
> >>  Cc: Avi Kivity<avi@redhat.com>
> >>  Cc: Marcelo Tosatti<mtosatti@redhat.com>
> >>  Signed-off-by: Sasha Levin<levinsasha928@gmail.com>
> >>  ---
> >>   Documentation/virtual/kvm/api.txt |   30 ++++++++++++++++++++++++++++++
> >>   1 files changed, 30 insertions(+), 0 deletions(-)
> >
> >  Applied (with wording fix), thanks.
>
> Requires section number fix-up (4.56 ->  4.58).

The usual fix is to cut a 5.0 release.

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

Re: [PATCH] kvm: Document KVM_IOEVENTFD

[Jan Kiszka]

On 2011-06-02 15:43, Avi Kivity wrote:
> On 06/01/2011 01:51 PM, Jan Kiszka wrote:
>> On 2011-05-31 15:44, Marcelo Tosatti wrote:
>> >  On Sat, May 28, 2011 at 02:12:30PM +0300, Sasha Levin wrote:
>> >>  Document KVM_IOEVENTFD that can be used to receive
>> >>  notifications of PIO/MMIO events without triggering
>> >>  an exit.
>> >>
>> >>  Cc: Avi Kivity<avi@redhat.com>
>> >>  Cc: Marcelo Tosatti<mtosatti@redhat.com>
>> >>  Signed-off-by: Sasha Levin<levinsasha928@gmail.com>
>> >>  ---
>> >>   Documentation/virtual/kvm/api.txt |   30
>> ++++++++++++++++++++++++++++++
>> >>   1 files changed, 30 insertions(+), 0 deletions(-)
>> >
>> >  Applied (with wording fix), thanks.
>>
>> Requires section number fix-up (4.56 ->  4.58).
> 
> The usual fix is to cut a 5.0 release.

Too bad that we already have one ("5. The kvm_run structure"). :)

Jan

------8<------

From: Jan Kiszka <jan.kiszka@siemens.com>

KVM: Fixup documentation section numbering

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
---
 Documentation/virtual/kvm/api.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index 3755a39..2bd06b0 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -1323,7 +1323,7 @@ struct kvm_lapic_state {
 Copies the input argument into the the Local APIC registers.  The data format
 and layout are the same as documented in the architecture manual.
 
-4.56 KVM_IOEVENTFD
+4.58 KVM_IOEVENTFD
 
 Capability: KVM_CAP_IOEVENTFD
 Architectures: all
-- 
1.7.1

Re: [PATCH] kvm: Document KVM_IOEVENTFD

[Marcelo Tosatti]

On Thu, Jun 02, 2011 at 04:16:20PM +0200, Jan Kiszka wrote:
> On 2011-06-02 15:43, Avi Kivity wrote:
> > On 06/01/2011 01:51 PM, Jan Kiszka wrote:
> >> On 2011-05-31 15:44, Marcelo Tosatti wrote:
> >> >  On Sat, May 28, 2011 at 02:12:30PM +0300, Sasha Levin wrote:
> >> >>  Document KVM_IOEVENTFD that can be used to receive
> >> >>  notifications of PIO/MMIO events without triggering
> >> >>  an exit.
> >> >>
> >> >>  Cc: Avi Kivity<avi@redhat.com>
> >> >>  Cc: Marcelo Tosatti<mtosatti@redhat.com>
> >> >>  Signed-off-by: Sasha Levin<levinsasha928@gmail.com>
> >> >>  ---
> >> >>   Documentation/virtual/kvm/api.txt |   30
> >> ++++++++++++++++++++++++++++++
> >> >>   1 files changed, 30 insertions(+), 0 deletions(-)
> >> >
> >> >  Applied (with wording fix), thanks.
> >>
> >> Requires section number fix-up (4.56 ->  4.58).
> > 
> > The usual fix is to cut a 5.0 release.
> 
> Too bad that we already have one ("5. The kvm_run structure"). :)
> 
> Jan
> 
> ------8<------
> 
> From: Jan Kiszka <jan.kiszka@siemens.com>
> 
> KVM: Fixup documentation section numbering
> 
> Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>

Applied, thanks.