[Qemu-devel] [PATCH 0/1] QAPI schema: turn example commands/returns into proper JSON

[Qemu-devel] [PATCH 0/1] QAPI schema: turn example commands/returns into proper JSON

[Cleber Rosa]

The QAPI schema documentation sections contain examples of QMP input
and output.  These are supposed to follow the "JSON-based" wire
protocol, but in practice, there are a few data structure problems and
also documentation.

This turns all inputs and outputs into parseable JSON-like data.
Besides allowing humans to copy and paste the examples without
surprises, this also paves the way towards automatic execution of
examples as tests.

Cleber Rosa(1):
   QAPI schema: turn example commands/returns into proper JSON

 qapi-schema.json     |  9 ++++-----
 qapi/block-core.json | 32 ++++++++++++++++----------------
 qapi/rocker.json     |  5 +----
 3 files changed, 21 insertions(+), 25 deletions(-)

[Qemu-devel] [PATCH 1/1] QAPI schema: turn example commands/returns into proper JSON

[Cleber Rosa]

Most QMP commands and returns in the QAPI schema documentation
are valid "JSON-based wire format".  A few examples are either
malformed, or contain comments.

This fixes all the examples command and return data, making them
proper JSON, as they would be received and generated by QEMU's
QMP monitor.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
---
 qapi-schema.json     |  9 ++++-----
 qapi/block-core.json | 32 ++++++++++++++++----------------
 qapi/rocker.json     |  5 +----
 3 files changed, 21 insertions(+), 25 deletions(-)

diff --git a/qapi-schema.json b/qapi-schema.json
index 802ea53d00..78c1e8cbde 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -2000,8 +2000,7 @@
 #                "host": "127.0.0.1",
 #                "channel-id": 0,
 #                "tls": false
-#             },
-#             [ ... more channels follow ... ]
+#             }
 #          ]
 #       }
 #    }
@@ -2039,7 +2038,7 @@
 #
 # -> { "execute": "query-balloon" }
 # <- { "return": {
-#          "actual": 1073741824,
+#          "actual": 1073741824
 #       }
 #    }
 #
@@ -3536,7 +3535,7 @@
 #
 # -> { "execute": "query-dump-guest-memory-capability" }
 # <- { "return": { "formats":
-#                  ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
+#                  ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } }
 #
 ##
 { 'command': 'query-dump-guest-memory-capability',
@@ -6500,7 +6499,7 @@
 #        "vcpus-count": 1 },
 #      { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
 #        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
-#    ]}'
+#    ]}
 #
 # For pc machine type started with -smp 1,maxcpus=2:
 #
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 833c602150..ab273a4729 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -801,10 +801,10 @@
 #                   "wr_bytes":9786368,
 #                   "wr_operations":751,
 #                   "rd_bytes":122567168,
-#                   "rd_operations":36772
-#                   "wr_total_times_ns":313253456
-#                   "rd_total_times_ns":3465673657
-#                   "flush_total_times_ns":49653
+#                   "rd_operations":36772,
+#                   "wr_total_times_ns":313253456,
+#                   "rd_total_times_ns":3465673657,
+#                   "flush_total_times_ns":49653,
 #                   "flush_operations":61,
 #                   "rd_merged":0,
 #                   "wr_merged":0,
@@ -818,10 +818,10 @@
 #                "wr_bytes":9786368,
 #                "wr_operations":692,
 #                "rd_bytes":122739200,
-#                "rd_operations":36604
+#                "rd_operations":36604,
 #                "flush_operations":51,
-#                "wr_total_times_ns":313253456
-#                "rd_total_times_ns":3465673657
+#                "wr_total_times_ns":313253456,
+#                "rd_total_times_ns":3465673657,
 #                "flush_total_times_ns":49653,
 #                "rd_merged":0,
 #                "wr_merged":0,
@@ -837,10 +837,10 @@
 #                "wr_bytes":0,
 #                "wr_operations":0,
 #                "rd_bytes":0,
-#                "rd_operations":0
+#                "rd_operations":0,
 #                "flush_operations":0,
-#                "wr_total_times_ns":0
-#                "rd_total_times_ns":0
+#                "wr_total_times_ns":0,
+#                "rd_total_times_ns":0,
 #                "flush_total_times_ns":0,
 #                "rd_merged":0,
 #                "wr_merged":0,
@@ -855,10 +855,10 @@
 #                "wr_bytes":0,
 #                "wr_operations":0,
 #                "rd_bytes":0,
-#                "rd_operations":0
+#                "rd_operations":0,
 #                "flush_operations":0,
-#                "wr_total_times_ns":0
-#                "rd_total_times_ns":0
+#                "wr_total_times_ns":0,
+#                "rd_total_times_ns":0,
 #                "flush_total_times_ns":0,
 #                "rd_merged":0,
 #                "wr_merged":0,
@@ -873,10 +873,10 @@
 #                "wr_bytes":0,
 #                "wr_operations":0,
 #                "rd_bytes":0,
-#                "rd_operations":0
+#                "rd_operations":0,
 #                "flush_operations":0,
-#                "wr_total_times_ns":0
-#                "rd_total_times_ns":0
+#                "wr_total_times_ns":0,
+#                "rd_total_times_ns":0,
 #                "flush_total_times_ns":0,
 #                "rd_merged":0,
 #                "wr_merged":0,
diff --git a/qapi/rocker.json b/qapi/rocker.json
index 3587661161..345863b600 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -249,10 +249,7 @@
 #                   "hits": 138,
 #                   "cookie": 0,
 #                   "action": {"goto-tbl": 10},
-#                   "mask": {"in-pport": 4294901760}
-#                  },
-#                  {...more...},
-#    ]}
+#                   "mask": {"in-pport": 4294901760} } ] }
 #
 ##
 { 'command': 'query-rocker-of-dpa-flows',
-- 
2.13.4

Re: [Qemu-devel] [PATCH 1/1] QAPI schema: turn example commands/returns into proper JSON

[Eric Blake]

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

On 08/08/2017 03:53 PM, Cleber Rosa wrote:
> Most QMP commands and returns in the QAPI schema documentation
> are valid "JSON-based wire format".  A few examples are either
> malformed, or contain comments.
> 
> This fixes all the examples command and return data, making them
> proper JSON, as they would be received and generated by QEMU's
> QMP monitor.
> 
> Signed-off-by: Cleber Rosa <crosa@redhat.com>
> ---
>  qapi-schema.json     |  9 ++++-----
>  qapi/block-core.json | 32 ++++++++++++++++----------------
>  qapi/rocker.json     |  5 +----
>  3 files changed, 21 insertions(+), 25 deletions(-)


> +++ b/qapi-schema.json
> @@ -2000,8 +2000,7 @@
>  #                "host": "127.0.0.1",
>  #                "channel-id": 0,
>  #                "tls": false
> -#             },
> -#             [ ... more channels follow ... ]
> +#             }

I still wonder if we want SOME sort of markup to make it obvious where
we are compressing the example for the sake of brevity, where whatever
we use to automate tests based on the docs would know how to recognize
that the actual values given in reply to the test can be longer than the
documented example.  But I guess we can cross that when we have an
automated test where it matters.

> @@ -2039,7 +2038,7 @@
>  #
>  # -> { "execute": "query-balloon" }
>  # <- { "return": {
> -#          "actual": 1073741824,
> +#          "actual": 1073741824
>  #       }

I also suspect that test automation will have to do a lot of filtering,
even for commands that don't need to be abbreviated, since some of the
examples have pretty arbitrary numbers that will be difficult to
reliably reproduce any particular number.

This is a documentation fix, so it could still go in 2.10 - but since we
are past -rc2, it's probably just as easy to save it for 2.11.  Either way,

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


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

Re: [Qemu-devel] [PATCH 1/1] QAPI schema: turn example commands/returns into proper JSON

[Cleber Rosa]

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



On 08/08/2017 05:13 PM, Eric Blake wrote:
> On 08/08/2017 03:53 PM, Cleber Rosa wrote:
>> Most QMP commands and returns in the QAPI schema documentation
>> are valid "JSON-based wire format".  A few examples are either
>> malformed, or contain comments.
>>
>> This fixes all the examples command and return data, making them
>> proper JSON, as they would be received and generated by QEMU's
>> QMP monitor.
>>
>> Signed-off-by: Cleber Rosa <crosa@redhat.com>
>> ---
>>  qapi-schema.json     |  9 ++++-----
>>  qapi/block-core.json | 32 ++++++++++++++++----------------
>>  qapi/rocker.json     |  5 +----
>>  3 files changed, 21 insertions(+), 25 deletions(-)
> 
> 
>> +++ b/qapi-schema.json
>> @@ -2000,8 +2000,7 @@
>>  #                "host": "127.0.0.1",
>>  #                "channel-id": 0,
>>  #                "tls": false
>> -#             },
>> -#             [ ... more channels follow ... ]
>> +#             }
> 
> I still wonder if we want SOME sort of markup to make it obvious where
> we are compressing the example for the sake of brevity, where whatever
> we use to automate tests based on the docs would know how to recognize
> that the actual values given in reply to the test can be longer than the
> documented example.  But I guess we can cross that when we have an
> automated test where it matters.
> 

I wonder the same.  Also, we seem to agree that it's a separate and more
complex problem, to be tackled later.

>> @@ -2039,7 +2038,7 @@
>>  #
>>  # -> { "execute": "query-balloon" }
>>  # <- { "return": {
>> -#          "actual": 1073741824,
>> +#          "actual": 1073741824
>>  #       }
> 
> I also suspect that test automation will have to do a lot of filtering,
> even for commands that don't need to be abbreviated, since some of the
> examples have pretty arbitrary numbers that will be difficult to
> reliably reproduce any particular number.
> 

Yes.  I'm already aware of a couple of use cases that will require
different types of comparison, including pretty relaxed ones.  Expect
more about that in a later thread.

> This is a documentation fix, so it could still go in 2.10 - but since we
> are past -rc2, it's probably just as easy to save it for 2.11.  Either way,
> 
> Reviewed-by: Eric Blake <eblake@redhat.com>
> 

Thanks for the prompt review!

-- 
Cleber Rosa
[ Sr Software Engineer - Virtualization Team - Red Hat ]
[ Avocado Test Framework - avocado-framework.github.io ]
[  7ABB 96EB 8B46 B94D 5E0F  E9BB 657E 8D33 A5F2 09F3  ]


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

Re: [Qemu-devel] [PATCH 1/1] QAPI schema: turn example commands/returns into proper JSON

[Markus Armbruster]

Cleber Rosa <crosa@redhat.com> writes:

> On 08/08/2017 05:13 PM, Eric Blake wrote:
>> On 08/08/2017 03:53 PM, Cleber Rosa wrote:
>>> Most QMP commands and returns in the QAPI schema documentation
>>> are valid "JSON-based wire format".  A few examples are either
>>> malformed, or contain comments.
>>>
>>> This fixes all the examples command and return data, making them
>>> proper JSON, as they would be received and generated by QEMU's
>>> QMP monitor.
>>>
>>> Signed-off-by: Cleber Rosa <crosa@redhat.com>
>>> ---
>>>  qapi-schema.json     |  9 ++++-----
>>>  qapi/block-core.json | 32 ++++++++++++++++----------------
>>>  qapi/rocker.json     |  5 +----
>>>  3 files changed, 21 insertions(+), 25 deletions(-)
>> 
>> 
>>> +++ b/qapi-schema.json
>>> @@ -2000,8 +2000,7 @@
>>>  #                "host": "127.0.0.1",
>>>  #                "channel-id": 0,
>>>  #                "tls": false
>>> -#             },
>>> -#             [ ... more channels follow ... ]
>>> +#             }
>> 
>> I still wonder if we want SOME sort of markup to make it obvious where
>> we are compressing the example for the sake of brevity, where whatever
>> we use to automate tests based on the docs would know how to recognize
>> that the actual values given in reply to the test can be longer than the
>> documented example.  But I guess we can cross that when we have an
>> automated test where it matters.
>> 
>
> I wonder the same.  Also, we seem to agree that it's a separate and more
> complex problem, to be tackled later.

We can cross that bridge when we get to it.

Any particular reason not to keep the [ ... more channels follow ... ]
until then?

>>> @@ -2039,7 +2038,7 @@
>>>  #
>>>  # -> { "execute": "query-balloon" }
>>>  # <- { "return": {
>>> -#          "actual": 1073741824,
>>> +#          "actual": 1073741824
>>>  #       }

This is a straighforward doc fix.

>> I also suspect that test automation will have to do a lot of filtering,
>> even for commands that don't need to be abbreviated, since some of the
>> examples have pretty arbitrary numbers that will be difficult to
>> reliably reproduce any particular number.
>> 
>
> Yes.  I'm already aware of a couple of use cases that will require
> different types of comparison, including pretty relaxed ones.  Expect
> more about that in a later thread.
>
>> This is a documentation fix, so it could still go in 2.10 - but since we
>> are past -rc2, it's probably just as easy to save it for 2.11.  Either way,
>> 
>> Reviewed-by: Eric Blake <eblake@redhat.com>
>> 
>
> Thanks for the prompt review!