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 <address@hidden> 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?