Re: [Qemu-devel] x-input-send-event marked as experimental

[Markus Armbruster]

Marcelo Tosatti <address@hidden> writes:

> On Fri, Dec 18, 2015 at 09:01:33PM +0100, Markus Armbruster wrote:
>> Marcelo Tosatti <address@hidden> writes:
>> 
>> > Gerd,
>> >
>> > commit df5b2adb7398d71016ee469f71e52075ed95e04e
>> > Author: Gerd Hoffmann <address@hidden>
>> > Date:   Tue Nov 25 14:54:17 2014 +0100
>> >
>> >     input: move input-send-event into experimental namespace
>> >     
>> >     Ongoing discussions on how we are going to specify the console,
>> >     so tag the command as experiental so we can refine things in
>> >     the 2.3 development cycle.
>> >
>> > So what is the problem here again? 
>> > input-send-event can send an input event to a 
>> > particular console, so that (the console number)
>> > has to be specified somehow.
>> >
>> > But, its already there, you can specify the console:
>> >
>> > -{ 'command': 'input-send-event',
>> > +{ 'command': 'x-input-send-event',
>> >    'data': { '*console':'int', 'events': [ 'InputEvent' ] } }
>> >
>> > So what its waiting for to be moved out of experimental status?
>> 
>> See
>> 
>> * http://lists.gnu.org/archive/html/qemu-devel/2014-11/msg03425.html
>>   Message-ID: <address@hidden>
>>   and the thread around it
>
> There are multiple points, the reason is not clear to me (i am looking
> for the reason why this has been marked as experimental, as there is not
> much ambiguity in the meaning of "sending an event to an input device".
>
> Is it because console numbers should not be exposed?

I wouldn't go as far as "should not".

The problem is we use two different addressing schemes:

> "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?"

Obvious ways to resolve this issue:

(a) Standardize external interface on qdev IDs

    Make QMP work with qdev IDs instead of console numbers.
    Incompatible change, but the interface is experimental.

(b) Standardize external interface on console numbers

    Make command line work with console numbers instead of qdev IDs.
    Incompatible change, no go.

(c) Inconsistent external interface

    (c1) Consistently use qdev IDs, but also use console numbers
         sometimes

         Make QMP work with qdev IDs in addition to console numbers.
    

    (c2) Consistently use console numbers, but also use qdev IDs
         sometimes

         Make command line work with console numbers in addition to qdev
         IDs.

    (c3) Use either console numbers or qdev IDs, depending on the
         interface.

         Do nothing.

(d) Consistently accept both addressing schemes

    Both (c1) and (c2).

I prefer my external interfaces consistent.  But I could live with any
of the above.

However, for (c) and (d), the next sentence after the ones you quoted
applies: "As long as we have both, documentation needs to stitch them
together".  This is a hard requirement for me.

Implementing (a) or (b) could be simpler than writing the documentation
necessary for (c) or (d).

Now why didn't we do any of this back then, and instead marked the
interface as experimental?  "rc3 is scheduled for tomorrow", simple as
that.

>> * http://lists.gnu.org/archive/html/qemu-devel/2015-11/msg02935.html
>>   Message-ID: <address@hidden>
>
> "The latter would be consistent with how we are doing input routing,
> i.e.
> grouping display and input devices to a seat for multiseat setups (see
> docs/multiseat.txt for more details).

Where "the latter" refers to "IIRC the question was [whether] we'll
leave it as-is (console=<index>), or [whether] we'll do something like
display=<id>,head=<nr> instead."  Oh joy, third addressing scheme.

> The consoles are already present in the qom tree
> as /backend/console[<index>] nodes, and they have device + head
> children.  So qom users can map console=<index> to
> display=<id>,head=<nr> and visa versa already.  So from a functionality
> point of view it doesn't really matter, it is largely a matter of
> taste ..."

Yes.  My personal taste prefers simple, consistent external interfaces,
but as I said, I could live with inconsistent ones.  My only hard
requirement is that if we have multiple non-deprecated, non-experimental
addressing schemes, I want documentation stitching them together.

>> * commit 513e7cd input: Document why x-input-send-event is still
>>   experimental
>
> This explains nothing.
>
> -# Note: this command is experimental, and not a stable API.
> +# Note: this command is experimental, and not a stable API.  Things that
> +# might change before it becomes stable include the spelling of enum
> +# values for InputButton and InputAxis, and the notion of how to designate
> +# which console will receive the event.
>  #

This doesn't explain *why* the command is experimental, only *what*
aspects of it may change before it becomes non-experimental.  Doesn't
answer your question, but it's useful for other legitimate questions.

> ---
>
> Ok, so can't find an actual argument for this 
> experimental flag at this point.

To make this command a stable interface, we need to decide which
addressing schemes to use where, and implement them.  If we have more
than one, then for any interface that doesn't support all of them, we
need to document how to work around the missing addressing scheme,
i.e. how to find an address in a supported scheme given an address in an
unsupported scheme.

Are things clearer now?