[Qemu-devel] [PATCH] input: improve docs for input-send-event qmp command

[Qemu-devel] [PATCH] input: improve docs for input-send-event qmp command

[Gerd Hoffmann]

Text partly suggested by Markus Armbruster <armbru@redhat.com>

Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 qapi-schema.json | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/qapi-schema.json b/qapi-schema.json
index d0926d9..fcd49b1 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3250,6 +3250,18 @@
 # Send input event(s) to guest.
 #
 # @console: #optional console to send event(s) to.
+#           This parameter can be used to send the input event to
+#           specific input devices in case (a) multiple input devices
+#           of the same kind are added to the virtual machine and (b)
+#           you have configured input routing (see docs/multiseat.txt)
+#           for those input devices.  If input routing is not
+#           configured this parameter has no effect.
+#           If @console is missing, only devices that aren't associated
+#           with a console are admissible.
+#           If @console is specified, it must exist, and both devices
+#           associated with that console and devices not associated with a
+#           console are admissible, but the former take precedence.
+
 #
 # @events: List of InputEvent union.
 #
-- 
1.8.3.1

Re: [Qemu-devel] [PATCH] input: improve docs for input-send-event qmp command

[Markus Armbruster]

[Copying Eric]

Gerd Hoffmann <kraxel@redhat.com> writes:

> Text partly suggested by Markus Armbruster <armbru@redhat.com>
>
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  qapi-schema.json | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
>
> diff --git a/qapi-schema.json b/qapi-schema.json
> index d0926d9..fcd49b1 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -3250,6 +3250,18 @@
>  # Send input event(s) to guest.
>  #
>  # @console: #optional console to send event(s) to.
> +#           This parameter can be used to send the input event to
> +#           specific input devices in case (a) multiple input devices
> +#           of the same kind are added to the virtual machine and (b)
> +#           you have configured input routing (see docs/multiseat.txt)
> +#           for those input devices.  If input routing is not
> +#           configured this parameter has no effect.
> +#           If @console is missing, only devices that aren't associated
> +#           with a console are admissible.
> +#           If @console is specified, it must exist, and both devices
> +#           associated with that console and devices not associated with a
> +#           console are admissible, but the former take precedence.
> +
>  #
>  # @events: List of InputEvent union.
>  #

What is a "console", and how get input devices assoated with one?  I
checked docs/multiseat.txt for clues, but found none.

Re: [Qemu-devel] [PATCH] input: improve docs for input-send-event qmp command

[Gerd Hoffmann]

On Fr, 2014-11-21 at 12:59 +0100, Markus Armbruster wrote:
> [Copying Eric]
> 
> Gerd Hoffmann <kraxel@redhat.com> writes:
> 
> > Text partly suggested by Markus Armbruster <armbru@redhat.com>
> >
> > Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> > ---
> >  qapi-schema.json | 12 ++++++++++++
> >  1 file changed, 12 insertions(+)
> >
> > diff --git a/qapi-schema.json b/qapi-schema.json
> > index d0926d9..fcd49b1 100644
> > --- a/qapi-schema.json
> > +++ b/qapi-schema.json
> > @@ -3250,6 +3250,18 @@
> >  # Send input event(s) to guest.
> >  #
> >  # @console: #optional console to send event(s) to.
> > +#           This parameter can be used to send the input event to
> > +#           specific input devices in case (a) multiple input devices
> > +#           of the same kind are added to the virtual machine and (b)
> > +#           you have configured input routing (see docs/multiseat.txt)
> > +#           for those input devices.  If input routing is not
> > +#           configured this parameter has no effect.
> > +#           If @console is missing, only devices that aren't associated
> > +#           with a console are admissible.
> > +#           If @console is specified, it must exist, and both devices
> > +#           associated with that console and devices not associated with a
> > +#           console are admissible, but the former take precedence.
> > +
> >  #
> >  # @events: List of InputEvent union.
> >  #
> 
> What is a "console", and how get input devices assoated with one?  I
> checked docs/multiseat.txt for clues, but found none.

Oh, right, in the command line the video device names are used.  video
device emulation actually creates the consoles, typically console 0 is
your vga.  They are numbered in creation order.  You can inspect them in
the qom tree (/backend/console[$nr]).  There is a device link pointing
to the device which created it.

cheers,
  Gerd

Re: [Qemu-devel] [PATCH] input: improve docs for input-send-event qmp command

[Markus Armbruster]

Gerd Hoffmann <kraxel@redhat.com> writes:

> On Fr, 2014-11-21 at 12:59 +0100, Markus Armbruster wrote:
>> [Copying Eric]
>> 
>> Gerd Hoffmann <kraxel@redhat.com> writes:
>> 
>> > Text partly suggested by Markus Armbruster <armbru@redhat.com>
>> >
>> > Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
>> > ---
>> >  qapi-schema.json | 12 ++++++++++++
>> >  1 file changed, 12 insertions(+)
>> >
>> > diff --git a/qapi-schema.json b/qapi-schema.json
>> > index d0926d9..fcd49b1 100644
>> > --- a/qapi-schema.json
>> > +++ b/qapi-schema.json
>> > @@ -3250,6 +3250,18 @@
>> >  # Send input event(s) to guest.
>> >  #
>> >  # @console: #optional console to send event(s) to.
>> > +#           This parameter can be used to send the input event to
>> > +#           specific input devices in case (a) multiple input devices
>> > +#           of the same kind are added to the virtual machine and (b)
>> > +#           you have configured input routing (see docs/multiseat.txt)
>> > +#           for those input devices.  If input routing is not
>> > +#           configured this parameter has no effect.
>> > +#           If @console is missing, only devices that aren't associated
>> > +#           with a console are admissible.
>> > +#           If @console is specified, it must exist, and both devices
>> > +#           associated with that console and devices not associated with a
>> > +#           console are admissible, but the former take precedence.
>> > +
>> >  #
>> >  # @events: List of InputEvent union.
>> >  #
>> 
>> What is a "console", and how get input devices assoated with one?  I
>> checked docs/multiseat.txt for clues, but found none.
>
> Oh, right, in the command line the video device names are used.  video
> device emulation actually creates the consoles, typically console 0 is
> your vga.  They are numbered in creation order.  You can inspect them in
> the qom tree (/backend/console[$nr]).  There is a device link pointing
> to the device which created it.

Begs the question why we're using console numbers in one place (QMP) and
qdev IDs in another (command line).  Why can't we use one of them
everywhere?  Or maybe support both everywhere?

As long as we have both, documentation needs to stitch them together.
Your explanation is a start, but it needs to be in a patch, not just in
a mailing list archive :)

I feel we better figure this out before the release, to avoid getting
stuck with a sub-par interface.

Re: [Qemu-devel] [PATCH] input: improve docs for input-send-event qmp command

[Gerd Hoffmann]

  Hi,

> >> >  # @console: #optional console to send event(s) to.
> >> > +#           This parameter can be used to send the input event to
> >> > +#           specific input devices in case (a) multiple input devices
> >> > +#           of the same kind are added to the virtual machine and (b)
> >> > +#           you have configured input routing (see docs/multiseat.txt)
> >> > +#           for those input devices.  If input routing is not
> >> > +#           configured this parameter has no effect.
> >> > +#           If @console is missing, only devices that aren't associated
> >> > +#           with a console are admissible.
> >> > +#           If @console is specified, it must exist, and both devices
> >> > +#           associated with that console and devices not associated with a
> >> > +#           console are admissible, but the former take precedence.
> >> > +
> >> >  #
> >> >  # @events: List of InputEvent union.
> >> >  #
> >> 
> >> What is a "console", and how get input devices assoated with one?  I
> >> checked docs/multiseat.txt for clues, but found none.
> >
> > Oh, right, in the command line the video device names are used.  video
> > device emulation actually creates the consoles, typically console 0 is
> > your vga.  They are numbered in creation order.  You can inspect them in
> > the qom tree (/backend/console[$nr]).  There is a device link pointing
> > to the device which created it.
> 
> Begs the question why we're using console numbers in one place (QMP) and
> qdev IDs in another (command line).  Why can't we use one of them
> everywhere?  Or maybe support both everywhere?

Console numbers don't appear anywhere on the command line.  User doesn't
create consoles directly, only indirectly (via display device).

Supporting device (additionally to or instead of console) on qmp
certainly is an option.  IIRC that was briefly discussed, then we've
figured console number is simpler and in most cases not relevant anyway
(typical config doesn't has multiple input devices), and if you really
need it there are the qom properties to go figure.

> As long as we have both, documentation needs to stitch them together.
> Your explanation is a start, but it needs to be in a patch, not just in
> a mailing list archive :)

Sure.  Question is where to stick it best.

cheers,
  Gerd

Re: [Qemu-devel] [PATCH] input: improve docs for input-send-event qmp command

[Markus Armbruster]

Uh, you dropped cc: Eric somehow a couple of messages ago.

Gerd Hoffmann <kraxel@redhat.com> writes:

>   Hi,
>
>> >> >  # @console: #optional console to send event(s) to.
>> >> > +#           This parameter can be used to send the input event to
>> >> > +#           specific input devices in case (a) multiple input devices
>> >> > +#           of the same kind are added to the virtual machine and (b)
>> >> > +#           you have configured input routing (see docs/multiseat.txt)
>> >> > +#           for those input devices.  If input routing is not
>> >> > +#           configured this parameter has no effect.
>> >> > +#           If @console is missing, only devices that aren't associated
>> >> > +#           with a console are admissible.
>> >> > +#           If @console is specified, it must exist, and both devices
>> >> > +# associated with that console and devices not associated with
>> >> > a
>> >> > +#           console are admissible, but the former take precedence.
>> >> > +
>> >> >  #
>> >> >  # @events: List of InputEvent union.
>> >> >  #
>> >> 
>> >> What is a "console", and how get input devices assoated with one?  I
>> >> checked docs/multiseat.txt for clues, but found none.
>> >
>> > Oh, right, in the command line the video device names are used.  video
>> > device emulation actually creates the consoles, typically console 0 is
>> > your vga.  They are numbered in creation order.  You can inspect them in
>> > the qom tree (/backend/console[$nr]).  There is a device link pointing
>> > to the device which created it.
>> 
>> Begs the question why we're using console numbers in one place (QMP) and
>> qdev IDs in another (command line).  Why can't we use one of them
>> everywhere?  Or maybe support both everywhere?
>
> Console numbers don't appear anywhere on the command line.  User doesn't
> create consoles directly, only indirectly (via display device).
>
> Supporting device (additionally to or instead of console) on qmp
> certainly is an option.  IIRC that was briefly discussed, then we've
> figured console number is simpler and in most cases not relevant anyway
> (typical config doesn't has multiple input devices), and if you really
> need it there are the qom properties to go figure.
>
>> As long as we have both, documentation needs to stitch them together.
>> Your explanation is a start, but it needs to be in a patch, not just in
>> a mailing list archive :)
>
> Sure.  Question is where to stick it best.

I guess docs/multiseat.txt is the only place where we can explain the
connection in sufficient detail, and have the right context.

My gut feeling is to treat console numbers as an implementation detail,
and go with qdev IDs exclusively.  Could be simpler than documenting
console numbers :-}

However, we're running out of time: rc3 is scheduled for tomorrow.  Two
ways to avoid tying our hands prematurely:

* Radical: disable the command for the release, bring it back
  afterwards.  No compatibility worries whatsoever.

* Surgical: rip out optional parameter console for the release, bring it
  or a replacement back afterwards.  Workable, because we can add
  optional parameters to existing commands.  However, management tools
  might want to figure out whther the optional parameter is accepted,
  and that's not easy since we still can't introspect.

Opinions?

Re: [Qemu-devel] [PATCH] input: improve docs for input-send-event qmp command

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 3060 bytes --]

On 11/24/2014 08:51 AM, Markus Armbruster wrote:
> Uh, you dropped cc: Eric somehow a couple of messages ago.

At least I have my inbox set to flag messages where my name is
mentioned, even when I'm not actually cc'd, so I did see the thread
before this email :)


>> Supporting device (additionally to or instead of console) on qmp
>> certainly is an option.  IIRC that was briefly discussed, then we've
>> figured console number is simpler and in most cases not relevant anyway
>> (typical config doesn't has multiple input devices), and if you really
>> need it there are the qom properties to go figure.
>>
>>> As long as we have both, documentation needs to stitch them together.
>>> Your explanation is a start, but it needs to be in a patch, not just in
>>> a mailing list archive :)
>>
>> Sure.  Question is where to stick it best.
> 
> I guess docs/multiseat.txt is the only place where we can explain the
> connection in sufficient detail, and have the right context.
> 
> My gut feeling is to treat console numbers as an implementation detail,
> and go with qdev IDs exclusively.  Could be simpler than documenting
> console numbers :-}

That seems reasonable, but then we do run into the timing issue.

> 
> However, we're running out of time: rc3 is scheduled for tomorrow.  Two
> ways to avoid tying our hands prematurely:
> 
> * Radical: disable the command for the release, bring it back
>   afterwards.  No compatibility worries whatsoever.

The command is brand new, so ripping it out to avoid baking in a mistake
and then adding it for 2.3 does indeed give us more time to get it right.

> 
> * Surgical: rip out optional parameter console for the release, bring it
>   or a replacement back afterwards.  Workable, because we can add
>   optional parameters to existing commands.  However, management tools
>   might want to figure out whther the optional parameter is accepted,
>   and that's not easy since we still can't introspect.

That does become a bit more difficult.  Hey, what happens if I do:

{"execute":"input-send-event",
 "arguments":{"console":0, "events": [] } }

that is, send a 0-length array of events to console 0?  (Or whatever
name we pick instead of 'console' when adding in an optional argument
for 2.3).  If the resulting error message in 2.2 (when the optional
argument is NOT supported) is obvious, and the code in 2.3 (when the
support is added) either silently does nothing with success, or gives a
distinct error message to 2.2, then that serves as something that
management can probe.  But it is a bit more awkward than the first
proposal of just completely delaying the interface until 2.3.

Of course, if we think we can resolve the interface questions and get a
stable interface into 2.2 where we aren't baking in a mistake, then go
for it.  But I don't think this patch is quite there yet, and we're
running low on time for a v2.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 539 bytes --]