[Qemu-devel] [PATCH] qmp-shell: add documentation

[Qemu-devel] [PATCH] qmp-shell: add documentation

[John Snow]

I should probably document the changes that were made.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 scripts/qmp/qmp-shell | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/scripts/qmp/qmp-shell b/scripts/qmp/qmp-shell
index 65280d2..fa39bf0 100755
--- a/scripts/qmp/qmp-shell
+++ b/scripts/qmp/qmp-shell
@@ -29,6 +29,41 @@
 # (QEMU) device_add driver=e1000 id=net1
 # {u'return': {}}
 # (QEMU)
+#
+# key=value pairs also support Python or JSON object literal subset notations,
+# without spaces. Dictionaries/objects {} are supported as are arrays [].
+#
+#    example-command arg-name1={'key':'value','obj'={'prop':"value"}}
+#
+# Both JSON and Python formatting should work, including both styles of
+# string literal quotes. Both paradigms of literal values should work,
+# including null/true/false for JSON and None/True/False for Python.
+#
+#
+# Transactions have the following multi-line format:
+#
+#    transaction(
+#    action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
+#    ...
+#    action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
+#    )
+#
+# One line transactions are also supported:
+#
+#    transaction( action-name1 ... )
+#
+# For example:
+#
+#     (QEMU) transaction(
+#     TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
+#     TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
+#     TRANS> )
+#     {"return": {}}
+#     (QEMU)
+#
+# Use the -v and -p options to activate the verbose and pretty-print options,
+# which will echo back the properly formatted JSON-compliant QMP that is being
+# sent to QEMU, which is useful for debugging and documentation generation.
 
 import qmp
 import json
-- 
2.1.0

Re: [Qemu-devel] [PATCH] qmp-shell: add documentation

[Luiz Capitulino]

On Wed,  1 Jul 2015 14:25:49 -0400
John Snow <jsnow@redhat.com> wrote:

> I should probably document the changes that were made.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>

Looks good to me, CC'ing maintainer.

> ---
>  scripts/qmp/qmp-shell | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
> 
> diff --git a/scripts/qmp/qmp-shell b/scripts/qmp/qmp-shell
> index 65280d2..fa39bf0 100755
> --- a/scripts/qmp/qmp-shell
> +++ b/scripts/qmp/qmp-shell
> @@ -29,6 +29,41 @@
>  # (QEMU) device_add driver=e1000 id=net1
>  # {u'return': {}}
>  # (QEMU)
> +#
> +# key=value pairs also support Python or JSON object literal subset notations,
> +# without spaces. Dictionaries/objects {} are supported as are arrays [].
> +#
> +#    example-command arg-name1={'key':'value','obj'={'prop':"value"}}
> +#
> +# Both JSON and Python formatting should work, including both styles of
> +# string literal quotes. Both paradigms of literal values should work,
> +# including null/true/false for JSON and None/True/False for Python.
> +#
> +#
> +# Transactions have the following multi-line format:
> +#
> +#    transaction(
> +#    action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
> +#    ...
> +#    action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
> +#    )
> +#
> +# One line transactions are also supported:
> +#
> +#    transaction( action-name1 ... )
> +#
> +# For example:
> +#
> +#     (QEMU) transaction(
> +#     TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
> +#     TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
> +#     TRANS> )
> +#     {"return": {}}
> +#     (QEMU)
> +#
> +# Use the -v and -p options to activate the verbose and pretty-print options,
> +# which will echo back the properly formatted JSON-compliant QMP that is being
> +# sent to QEMU, which is useful for debugging and documentation generation.
>  
>  import qmp
>  import json

Re: [Qemu-devel] [PATCH] qmp-shell: add documentation

[John Snow]

On 07/02/2015 11:31 AM, Luiz Capitulino wrote:
> On Wed,  1 Jul 2015 14:25:49 -0400
> John Snow <jsnow@redhat.com> wrote:
> 
>> I should probably document the changes that were made.
>>
>> Signed-off-by: John Snow <jsnow@redhat.com>
> 
> Looks good to me, CC'ing maintainer.
> 

Whoops, didn't realize Markus took this file over, too. Sorry Luiz.

Markus, would you consider staging this? It's purely a documentation
update for only a dev tool, so it doesn't really matter /when/ it lands
either way, just shoring up some changes I made a while back to the
interpreter here.

tldr: "ping"

>> ---
>>  scripts/qmp/qmp-shell | 35 +++++++++++++++++++++++++++++++++++
>>  1 file changed, 35 insertions(+)
>>
>> diff --git a/scripts/qmp/qmp-shell b/scripts/qmp/qmp-shell
>> index 65280d2..fa39bf0 100755
>> --- a/scripts/qmp/qmp-shell
>> +++ b/scripts/qmp/qmp-shell
>> @@ -29,6 +29,41 @@
>>  # (QEMU) device_add driver=e1000 id=net1
>>  # {u'return': {}}
>>  # (QEMU)
>> +#
>> +# key=value pairs also support Python or JSON object literal subset notations,
>> +# without spaces. Dictionaries/objects {} are supported as are arrays [].
>> +#
>> +#    example-command arg-name1={'key':'value','obj'={'prop':"value"}}
>> +#
>> +# Both JSON and Python formatting should work, including both styles of
>> +# string literal quotes. Both paradigms of literal values should work,
>> +# including null/true/false for JSON and None/True/False for Python.
>> +#
>> +#
>> +# Transactions have the following multi-line format:
>> +#
>> +#    transaction(
>> +#    action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
>> +#    ...
>> +#    action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
>> +#    )
>> +#
>> +# One line transactions are also supported:
>> +#
>> +#    transaction( action-name1 ... )
>> +#
>> +# For example:
>> +#
>> +#     (QEMU) transaction(
>> +#     TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
>> +#     TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
>> +#     TRANS> )
>> +#     {"return": {}}
>> +#     (QEMU)
>> +#
>> +# Use the -v and -p options to activate the verbose and pretty-print options,
>> +# which will echo back the properly formatted JSON-compliant QMP that is being
>> +# sent to QEMU, which is useful for debugging and documentation generation.
>>  
>>  import qmp
>>  import json
> 
> 

Re: [Qemu-devel] [PATCH] qmp-shell: add documentation

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On 07/02/2015 11:31 AM, Luiz Capitulino wrote:
>> On Wed,  1 Jul 2015 14:25:49 -0400
>> John Snow <jsnow@redhat.com> wrote:
>> 
>>> I should probably document the changes that were made.

John, what do you mean here?

>>> Signed-off-by: John Snow <jsnow@redhat.com>
>> 
>> Looks good to me, CC'ing maintainer.

Luiz, is this a R-by?

> Whoops, didn't realize Markus took this file over, too. Sorry Luiz.

Don't worry about our maintainer reshuffling.

> Markus, would you consider staging this? It's purely a documentation
> update for only a dev tool, so it doesn't really matter /when/ it lands
> either way, just shoring up some changes I made a while back to the
> interpreter here.
>
> tldr: "ping"

I'm happy to include this in the next pull after it got reviewed.  I'm
ignorant about qmp-shell, because I don't use it myself, so I'd have to
dig through it to verify your documentation is accurate and reasonably
complete.

Fishing for more qualified reviewers:

    $ scripts/get_maintainer.pl --git-blame -f scripts/qmp/qmp-shell 
    Markus Armbruster <armbru@redhat.com> (supporter:QMP)
    Luiz Capitulino <lcapitulino@redhat.com> (authored lines:230/390=59%,commits:10/10=100%)
    John Snow <jsnow@redhat.com> (authored lines:117/390=30%,commits:4/10=40%)
    "Daniel P. Berrange" <berrange@redhat.com> (authored lines:27/390=7%)
    Eric Blake <eblake@redhat.com> (commits:6/10=60%)
    Stefan Hajnoczi <stefanha@redhat.com> (commits:2/10=20%)
    Benoit Canet <benoit@irqsave.net> (commits:1/10=10%)

Luiz, can you review for accuracy and reasonable completeness?

Of course, I'm the reviewer of last resort for anything I maintain,
whether I understand it or not :)

Re: [Qemu-devel] [PATCH] qmp-shell: add documentation

[John Snow]

On 07/23/2015 03:36 AM, Markus Armbruster wrote:
> John Snow <jsnow@redhat.com> writes:
> 
>> On 07/02/2015 11:31 AM, Luiz Capitulino wrote:
>>> On Wed,  1 Jul 2015 14:25:49 -0400
>>> John Snow <jsnow@redhat.com> wrote:
>>>
>>>> I should probably document the changes that were made.
> 
> John, what do you mean here?
> 

I'm sorry, Markus.

It's a giant circle of people just barely out of the loop. During the
2.4 window I augmented the QMP shell tool to be able to issue
transactional commands, and improved the json/python parsing for the
key=value pairs.

It was primarily motivated by wanting an easy way to issue and test
bitmap commands.

Eric Blake knows the most about the improvements, as he was the original
reviewer, but you know how this list likes to strip him out of the CC
fields.

>>>> Signed-off-by: John Snow <jsnow@redhat.com>
>>>
>>> Looks good to me, CC'ing maintainer.
> 
> Luiz, is this a R-by?
> 
>> Whoops, didn't realize Markus took this file over, too. Sorry Luiz.
> 
> Don't worry about our maintainer reshuffling.
> 
>> Markus, would you consider staging this? It's purely a documentation
>> update for only a dev tool, so it doesn't really matter /when/ it lands
>> either way, just shoring up some changes I made a while back to the
>> interpreter here.
>>
>> tldr: "ping"
> 
> I'm happy to include this in the next pull after it got reviewed.  I'm
> ignorant about qmp-shell, because I don't use it myself, so I'd have to
> dig through it to verify your documentation is accurate and reasonably
> complete.
> 
> Fishing for more qualified reviewers:
> 
>     $ scripts/get_maintainer.pl --git-blame -f scripts/qmp/qmp-shell 
>     Markus Armbruster <armbru@redhat.com> (supporter:QMP)
>     Luiz Capitulino <lcapitulino@redhat.com> (authored lines:230/390=59%,commits:10/10=100%)
>     John Snow <jsnow@redhat.com> (authored lines:117/390=30%,commits:4/10=40%)
>     "Daniel P. Berrange" <berrange@redhat.com> (authored lines:27/390=7%)
>     Eric Blake <eblake@redhat.com> (commits:6/10=60%)
>     Stefan Hajnoczi <stefanha@redhat.com> (commits:2/10=20%)
>     Benoit Canet <benoit@irqsave.net> (commits:1/10=10%)
> 
> Luiz, can you review for accuracy and reasonable completeness?
> 
> Of course, I'm the reviewer of last resort for anything I maintain,
> whether I understand it or not :)
> 

Re: [Qemu-devel] [PATCH] qmp-shell: add documentation

[Eric Blake]

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

On 07/26/2015 09:30 PM, John Snow wrote:

> 
> It's a giant circle of people just barely out of the loop. During the
> 2.4 window I augmented the QMP shell tool to be able to issue
> transactional commands, and improved the json/python parsing for the
> key=value pairs.
> 
> It was primarily motivated by wanting an easy way to issue and test
> bitmap commands.
> 
> Eric Blake knows the most about the improvements, as he was the original
> reviewer, but you know how this list likes to strip him out of the CC
> fields.

More my fault (and mailman's lousy defaults) than anything else,
although I have my own filters set up to try and flag anything with my
name, so I usually catch conversations even if I'm omitted from cc.

Did you still need my review on this series at this point, or is it
covered now?

-- 
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: 604 bytes --]

Re: [Qemu-devel] [PATCH] qmp-shell: add documentation

[Luiz Capitulino]

On Thu, 23 Jul 2015 09:36:38 +0200
Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
> 
> > On 07/02/2015 11:31 AM, Luiz Capitulino wrote:
> >> On Wed,  1 Jul 2015 14:25:49 -0400
> >> John Snow <jsnow@redhat.com> wrote:
> >> 
> >>> I should probably document the changes that were made.
> 
> John, what do you mean here?
> 
> >>> Signed-off-by: John Snow <jsnow@redhat.com>
> >> 
> >> Looks good to me, CC'ing maintainer.
> 
> Luiz, is this a R-by?

Reviewed-by: Luiz Capitulino <lcapitulino@redhat.com>

This one is :)

> 
> > Whoops, didn't realize Markus took this file over, too. Sorry Luiz.
> 
> Don't worry about our maintainer reshuffling.
> 
> > Markus, would you consider staging this? It's purely a documentation
> > update for only a dev tool, so it doesn't really matter /when/ it lands
> > either way, just shoring up some changes I made a while back to the
> > interpreter here.
> >
> > tldr: "ping"
> 
> I'm happy to include this in the next pull after it got reviewed.  I'm
> ignorant about qmp-shell, because I don't use it myself, so I'd have to
> dig through it to verify your documentation is accurate and reasonably
> complete.
> 
> Fishing for more qualified reviewers:
> 
>     $ scripts/get_maintainer.pl --git-blame -f scripts/qmp/qmp-shell 
>     Markus Armbruster <armbru@redhat.com> (supporter:QMP)
>     Luiz Capitulino <lcapitulino@redhat.com> (authored lines:230/390=59%,commits:10/10=100%)
>     John Snow <jsnow@redhat.com> (authored lines:117/390=30%,commits:4/10=40%)
>     "Daniel P. Berrange" <berrange@redhat.com> (authored lines:27/390=7%)
>     Eric Blake <eblake@redhat.com> (commits:6/10=60%)
>     Stefan Hajnoczi <stefanha@redhat.com> (commits:2/10=20%)
>     Benoit Canet <benoit@irqsave.net> (commits:1/10=10%)
> 
> Luiz, can you review for accuracy and reasonable completeness?
> 
> Of course, I'm the reviewer of last resort for anything I maintain,
> whether I understand it or not :)
> 

Re: [Qemu-devel] [PATCH] qmp-shell: add documentation

[Markus Armbruster]

Luiz Capitulino <lcapitulino@redhat.com> writes:

> On Thu, 23 Jul 2015 09:36:38 +0200
> Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>> 
>> > On 07/02/2015 11:31 AM, Luiz Capitulino wrote:
>> >> On Wed,  1 Jul 2015 14:25:49 -0400
>> >> John Snow <jsnow@redhat.com> wrote:
>> >> 
>> >>> I should probably document the changes that were made.
>> 
>> John, what do you mean here?
>> 
>> >>> Signed-off-by: John Snow <jsnow@redhat.com>
>> >> 
>> >> Looks good to me, CC'ing maintainer.
>> 
>> Luiz, is this a R-by?
>
> Reviewed-by: Luiz Capitulino <lcapitulino@redhat.com>
>
> This one is :)

Applied to my qapi-next branch, with "Cc: qemu-trivial@nongnu.org" added
to commit message, thanks!

Re: [Qemu-devel] [PATCH] qmp-shell: add documentation

[Kashyap Chamarthy]

On Wed, Jul 01, 2015 at 02:25:49PM -0400, John Snow wrote:
> I should probably document the changes that were made.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  scripts/qmp/qmp-shell | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)

Since I did some tests[1] when you wrote these improvements to
qmp-shell, the change looks good, FWIW:

    Reviewed-By: Kashyap Chamarthy <kchamart@redhat.com>

[1]
https://lists.nongnu.org/archive/html/qemu-devel/2015-04/msg04201.html

> diff --git a/scripts/qmp/qmp-shell b/scripts/qmp/qmp-shell
> index 65280d2..fa39bf0 100755
> --- a/scripts/qmp/qmp-shell
> +++ b/scripts/qmp/qmp-shell
> @@ -29,6 +29,41 @@
>  # (QEMU) device_add driver=e1000 id=net1
>  # {u'return': {}}
>  # (QEMU)
> +#
> +# key=value pairs also support Python or JSON object literal subset notations,
> +# without spaces. Dictionaries/objects {} are supported as are arrays [].
> +#
> +#    example-command arg-name1={'key':'value','obj'={'prop':"value"}}
> +#
> +# Both JSON and Python formatting should work, including both styles of
> +# string literal quotes. Both paradigms of literal values should work,
> +# including null/true/false for JSON and None/True/False for Python.
> +#
> +#
> +# Transactions have the following multi-line format:
> +#
> +#    transaction(
> +#    action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
> +#    ...
> +#    action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
> +#    )
> +#
> +# One line transactions are also supported:
> +#
> +#    transaction( action-name1 ... )
> +#
> +# For example:
> +#
> +#     (QEMU) transaction(
> +#     TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
> +#     TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
> +#     TRANS> )
> +#     {"return": {}}
> +#     (QEMU)
> +#
> +# Use the -v and -p options to activate the verbose and pretty-print options,
> +# which will echo back the properly formatted JSON-compliant QMP that is being
> +# sent to QEMU, which is useful for debugging and documentation generation.
>  
>  import qmp
>  import json
> -- 
> 2.1.0
> 
> 

-- 
/kashyap