[Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Gerd Hoffmann]

Ongoing discussions on how we are going to specify the console,
so tag the command as experiemntal so we can refine things in
the 2.3 development cycle.

Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 qmp-commands.hx | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/qmp-commands.hx b/qmp-commands.hx
index 8812401..d6b7362 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -3791,13 +3791,13 @@ Example:
 EQMP
 
     {
-        .name       = "input-send-event",
+        .name       = "x-input-send-event",
         .args_type  = "console:i?,events:q",
         .mhandler.cmd_new = qmp_marshal_input_input_send_event,
     },
 
 SQMP
-@input-send-event
+@x-input-send-event
 -----------------
 
 Send input event to guest.
@@ -3815,13 +3815,13 @@ Example (1):
 
 Press left mouse button.
 
--> { "execute": "input-send-event",
+-> { "execute": "x-input-send-event",
     "arguments": { "console": 0,
                    "events": [ { "type": "btn",
                     "data" : { "down": true, "button": "Left" } } } }
 <- { "return": {} }
 
--> { "execute": "input-send-event",
+-> { "execute": "x-input-send-event",
     "arguments": { "console": 0,
                    "events": [ { "type": "btn",
                     "data" : { "down": false, "button": "Left" } } } }
@@ -3831,7 +3831,7 @@ Example (2):
 
 Press ctrl-alt-del.
 
--> { "execute": "input-send-event",
+-> { "execute": "x-input-send-event",
      "arguments": { "console": 0, "events": [
         { "type": "key", "data" : { "down": true,
           "key": {"type": "qcode", "data": "ctrl" } } },
@@ -3845,7 +3845,7 @@ Example (3):
 
 Move mouse pointer to absolute coordinates (20000, 400).
 
--> { "execute": "input-send-event" ,
+-> { "execute": "x-input-send-event" ,
   "arguments": { "console": 0, "events": [
                { "type": "abs", "data" : { "axis": "X", "value" : 20000 } },
                { "type": "abs", "data" : { "axis": "Y", "value" : 400 } } ] } }
-- 
1.8.3.1

Re: [Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Amos Kong]

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

On Tue, Nov 25, 2014 at 08:18:54AM +0100, Gerd Hoffmann wrote:
> Ongoing discussions on how we are going to specify the console,
> so tag the command as experiemntal so we can refine things in
> the 2.3 development cycle.

%s/experiemntal/experimental/


Reviewed-by: Amos Kong <akong@redhat.com>

> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  qmp-commands.hx | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/qmp-commands.hx b/qmp-commands.hx
> index 8812401..d6b7362 100644
> --- a/qmp-commands.hx
> +++ b/qmp-commands.hx
> @@ -3791,13 +3791,13 @@ Example:
>  EQMP
>  
>      {
> -        .name       = "input-send-event",
> +        .name       = "x-input-send-event",
>          .args_type  = "console:i?,events:q",
>          .mhandler.cmd_new = qmp_marshal_input_input_send_event,
>      },
>  
>  SQMP
> -@input-send-event
> +@x-input-send-event
>  -----------------
>  
>  Send input event to guest.
> @@ -3815,13 +3815,13 @@ Example (1):
>  
>  Press left mouse button.
>  
> --> { "execute": "input-send-event",
> +-> { "execute": "x-input-send-event",
>      "arguments": { "console": 0,
>                     "events": [ { "type": "btn",
>                      "data" : { "down": true, "button": "Left" } } } }

(not problem of this patch)
typo, lack of ']'

>  <- { "return": {} }
>  
> --> { "execute": "input-send-event",
> +-> { "execute": "x-input-send-event",
>      "arguments": { "console": 0,
>                     "events": [ { "type": "btn",
>                      "data" : { "down": false, "button": "Left" } } } }

some typo.

> @@ -3831,7 +3831,7 @@ Example (2):
>  
>  Press ctrl-alt-del.
>  
> --> { "execute": "input-send-event",
> +-> { "execute": "x-input-send-event",
>       "arguments": { "console": 0, "events": [
>          { "type": "key", "data" : { "down": true,
>            "key": {"type": "qcode", "data": "ctrl" } } },
> @@ -3845,7 +3845,7 @@ Example (3):
>  
>  Move mouse pointer to absolute coordinates (20000, 400).
>  
> --> { "execute": "input-send-event" ,
> +-> { "execute": "x-input-send-event" ,
>    "arguments": { "console": 0, "events": [
>                 { "type": "abs", "data" : { "axis": "X", "value" : 20000 } },
>                 { "type": "abs", "data" : { "axis": "Y", "value" : 400 } } ] } }
> -- 
> 1.8.3.1
> 

-- 
			Amos.

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Markus Armbruster]

Gerd Hoffmann <kraxel@redhat.com> writes:

> Ongoing discussions on how we are going to specify the console,
> so tag the command as experiemntal so we can refine things in
> the 2.3 development cycle.
>
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  qmp-commands.hx | 12 ++++++------

Don't you need to patch qapi-schema.json, too?

Do we actually explain "x- means experimental" anywhere?

Re: [Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Amos Kong]

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

On Tue, Nov 25, 2014 at 09:06:34AM +0100, Markus Armbruster wrote:
> Gerd Hoffmann <kraxel@redhat.com> writes:
> 
> > Ongoing discussions on how we are going to specify the console,
> > so tag the command as experiemntal so we can refine things in
> > the 2.3 development cycle.
> >
> > Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> > ---
> >  qmp-commands.hx | 12 ++++++------
> 
> Don't you need to patch qapi-schema.json, too?

Not necessary in function level.
 
> Do we actually explain "x- means experimental" anywhere?

What's the official way to make command experimental?

Quote from qapi-schema.json:
| # Notes: This command is experimental and may change
| syntax in future releases.

-- 
			Amos.

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Markus Armbruster]

Amos Kong <akong@redhat.com> writes:

> On Tue, Nov 25, 2014 at 09:06:34AM +0100, Markus Armbruster wrote:
>> Gerd Hoffmann <kraxel@redhat.com> writes:
>> 
>> > Ongoing discussions on how we are going to specify the console,
>> > so tag the command as experiemntal so we can refine things in
>> > the 2.3 development cycle.
>> >
>> > Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
>> > ---
>> >  qmp-commands.hx | 12 ++++++------
>> 
>> Don't you need to patch qapi-schema.json, too?
>
> Not necessary in function level.

s/need to/want to/?

For consistency, especially because the QAPI schema also serves as QMP
command documentation.

>> Do we actually explain "x- means experimental" anywhere?
>
> What's the official way to make command experimental?

I think we have an understanding / convention that an "x-" prefix marks
names as unstable API.  But I can't find it spelled out anywhere.
Anyway, separate issue.

> Quote from qapi-schema.json:
> | # Notes: This command is experimental and may change
> | syntax in future releases.

Next to the return type ObjectTypeInfo rathe than the command
qom-list-types, blech.

Re: [Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

> Amos Kong <akong@redhat.com> writes:
>
>> On Tue, Nov 25, 2014 at 09:06:34AM +0100, Markus Armbruster wrote:
>>> Gerd Hoffmann <kraxel@redhat.com> writes:
>>> 
>>> > Ongoing discussions on how we are going to specify the console,
>>> > so tag the command as experiemntal so we can refine things in
>>> > the 2.3 development cycle.
>>> >
>>> > Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
>>> > ---
>>> >  qmp-commands.hx | 12 ++++++------
>>> 
>>> Don't you need to patch qapi-schema.json, too?
>>
>> Not necessary in function level.
>
> s/need to/want to/?
>
> For consistency, especially because the QAPI schema also serves as QMP
> command documentation.
>
>>> Do we actually explain "x- means experimental" anywhere?
>>
>> What's the official way to make command experimental?
>
> I think we have an understanding / convention that an "x-" prefix marks
> names as unstable API.  But I can't find it spelled out anywhere.
> Anyway, separate issue.
>
>> Quote from qapi-schema.json:
>> | # Notes: This command is experimental and may change
>> | syntax in future releases.
>
> Next to the return type ObjectTypeInfo rathe than the command
> qom-list-types, blech.

I went with "Note: this command is experimental, and not a stable API",
following precedence in qemu-options.hx.

Re: [Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Eric Blake]

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

On 11/25/2014 04:58 AM, Markus Armbruster wrote:
> Amos Kong <akong@redhat.com> writes:
> 
>> On Tue, Nov 25, 2014 at 09:06:34AM +0100, Markus Armbruster wrote:
>>> Gerd Hoffmann <kraxel@redhat.com> writes:
>>>
>>>> Ongoing discussions on how we are going to specify the console,
>>>> so tag the command as experiemntal so we can refine things in
>>>> the 2.3 development cycle.
>>>>
>>>> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
>>>> ---
>>>>  qmp-commands.hx | 12 ++++++------
>>>
>>> Don't you need to patch qapi-schema.json, too?
>>
>> Not necessary in function level.
> 
> s/need to/want to/?

Yes, if you are going to mark the HMP command experimental, please also
mark the QMP command as experimental.

> 
>>> Do we actually explain "x- means experimental" anywhere?

Hmm, In my (not yet finished) series for improving qapi generation type
safety, I have added:

$ git grep -A1 'x-' docs/
...
docs/qapi-code-gen.txt:Any command, type, or field name beginning with
"x-" is marked
docs/qapi-code-gen.txt-experimental, and may be withdrawn in a future
release.  Downstream
...

but I obviously need to find time to revisit my series since that text
is not in upstream yet.

>>
>> What's the official way to make command experimental?
> 
> I think we have an understanding / convention that an "x-" prefix marks
> names as unstable API.  But I can't find it spelled out anywhere.
> Anyway, separate issue.

Yep, and on my plate to finish it.

-- 
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 --]

Re: [Qemu-devel] [PATCH] input: move input-send-event into experimental namespace

[Amos Kong]

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

On Tue, Nov 25, 2014 at 09:35:26AM -0700, Eric Blake wrote:
> On 11/25/2014 04:58 AM, Markus Armbruster wrote:
> > Amos Kong <akong@redhat.com> writes:
> > 
> >> On Tue, Nov 25, 2014 at 09:06:34AM +0100, Markus Armbruster wrote:
> >>> Gerd Hoffmann <kraxel@redhat.com> writes:
> >>>
> >>>> Ongoing discussions on how we are going to specify the console,
> >>>> so tag the command as experiemntal so we can refine things in
> >>>> the 2.3 development cycle.
> >>>>
> >>>> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> >>>> ---
> >>>>  qmp-commands.hx | 12 ++++++------
> >>>
> >>> Don't you need to patch qapi-schema.json, too?
> >>
> >> Not necessary in function level.
> > 
> > s/need to/want to/?
> 
> Yes, if you are going to mark the HMP command experimental, please also
> mark the QMP command as experimental.

Gerd's patch wasn't make hmp command experimental, but QMP. Inputted
command will be compared with .name field in qmp-commands.hx, not
qapi-schema.json. The command name in qapi-schema.json only effects
the function name.

But it's good to also update qapi-schema.json.

-- 
			Amos.

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]