[Qemu-devel] [PATCH] block: document block-stream in qmp-commands.hx

[Qemu-devel] [PATCH] block: document block-stream in qmp-commands.hx

[Stefan Hajnoczi]

The 'block-stream' QMP command is documented in block-core.json but not
qmp-commands.hx.  Add a summary of the command to qmp-commands.hx
(similar to the documentation for 'block-commit').

Reported-by: Kashyap Chamarthy <kchamart@redhat.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 qmp-commands.hx | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/qmp-commands.hx b/qmp-commands.hx
index 3a42ad0..7a745ed 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -1008,6 +1008,43 @@ EQMP
         .mhandler.cmd_new = qmp_marshal_input_block_stream,
     },
 
+SQMP
+block-stream
+------------
+
+Copy data from a backing file into a block device.
+
+Arguments:
+
+- "device": The device's ID, must be unique (json-string)
+- "base": The file name of the backing image above which copying starts
+          (json-string, optional)
+- "backing-file": The backing file string to write into the active layer. This
+                  filename is not validated.
+
+                  If a pathname string is such that it cannot be resolved by
+                  QEMU, that means that subsequent QMP or HMP commands must use
+                  node-names for the image in question, as filename lookup
+                  methods will fail.
+
+                  If not specified, QEMU will automatically determine the
+                  backing file string to use, or error out if there is no
+                  obvious choice.  Care should be taken when specifying the
+                  string, to specify a valid filename or protocol.
+                  (json-string, optional) (Since 2.1)
+- "speed":  the maximum speed, in bytes per second (json-int, optional)
+- "on-error": the action to take on an error (default 'report').  'stop' and
+              'enospc' can only be used if the block device supports io-status.
+              (json-string, optional) (Since 2.1)
+
+Example:
+
+-> { "execute": "block-stream", "arguments": { "device": "virtio0",
+                                               "base": "/tmp/master.qcow2" } }
+<- { "return": {} }
+
+EQMP
+
     {
         .name       = "block-commit",
         .args_type  = "device:B,base:s?,top:s?,backing-file:s?,speed:o?",
-- 
2.1.0

Re: [Qemu-devel] [PATCH] block: document block-stream in qmp-commands.hx

[Eric Blake]

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

On 04/15/2015 04:43 AM, Stefan Hajnoczi wrote:
> The 'block-stream' QMP command is documented in block-core.json but not
> qmp-commands.hx.  Add a summary of the command to qmp-commands.hx
> (similar to the documentation for 'block-commit').
> 
> Reported-by: Kashyap Chamarthy <kchamart@redhat.com>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  qmp-commands.hx | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)

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

-- 
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] block: document block-stream in qmp-commands.hx

[Max Reitz]

On 15.04.2015 12:43, Stefan Hajnoczi wrote:
> The 'block-stream' QMP command is documented in block-core.json but not
> qmp-commands.hx.  Add a summary of the command to qmp-commands.hx
> (similar to the documentation for 'block-commit').
>
> Reported-by: Kashyap Chamarthy <kchamart@redhat.com>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>   qmp-commands.hx | 37 +++++++++++++++++++++++++++++++++++++
>   1 file changed, 37 insertions(+)
>
> diff --git a/qmp-commands.hx b/qmp-commands.hx
> index 3a42ad0..7a745ed 100644
> --- a/qmp-commands.hx
> +++ b/qmp-commands.hx
> @@ -1008,6 +1008,43 @@ EQMP
>           .mhandler.cmd_new = qmp_marshal_input_block_stream,
>       },
>   
> +SQMP
> +block-stream
> +------------
> +
> +Copy data from a backing file into a block device.

It looks like you stopped just copy-pasting the information from 
block-core.json here...

> +
> +Arguments:
> +
> +- "device": The device's ID, must be unique (json-string)

...instead sometimes copying it from block-commit...

> +- "base": The file name of the backing image above which copying starts
> +          (json-string, optional)

...or creating new descriptions...

> +- "backing-file": The backing file string to write into the active layer. This
> +                  filename is not validated.

...and then you are continuing copying the block-core.json entry.

Is there a reason why you didn't just take all of the block-core.json 
comment and put it here? (just curious)

Reviewed-by: Max Reitz <mreitz@redhat.com>

> +
> +                  If a pathname string is such that it cannot be resolved by
> +                  QEMU, that means that subsequent QMP or HMP commands must use
> +                  node-names for the image in question, as filename lookup
> +                  methods will fail.
> +
> +                  If not specified, QEMU will automatically determine the
> +                  backing file string to use, or error out if there is no
> +                  obvious choice.  Care should be taken when specifying the
> +                  string, to specify a valid filename or protocol.
> +                  (json-string, optional) (Since 2.1)
> +- "speed":  the maximum speed, in bytes per second (json-int, optional)
> +- "on-error": the action to take on an error (default 'report').  'stop' and
> +              'enospc' can only be used if the block device supports io-status.
> +              (json-string, optional) (Since 2.1)
> +
> +Example:
> +
> +-> { "execute": "block-stream", "arguments": { "device": "virtio0",
> +                                               "base": "/tmp/master.qcow2" } }
> +<- { "return": {} }
> +
> +EQMP
> +
>       {
>           .name       = "block-commit",
>           .args_type  = "device:B,base:s?,top:s?,backing-file:s?,speed:o?",

Re: [Qemu-devel] [PATCH] block: document block-stream in qmp-commands.hx

[Stefan Hajnoczi]

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

On Wed, Apr 15, 2015 at 03:08:30PM +0200, Max Reitz wrote:
> On 15.04.2015 12:43, Stefan Hajnoczi wrote:
> >The 'block-stream' QMP command is documented in block-core.json but not
> >qmp-commands.hx.  Add a summary of the command to qmp-commands.hx
> >(similar to the documentation for 'block-commit').
> >
> >Reported-by: Kashyap Chamarthy <kchamart@redhat.com>
> >Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> >---
> >  qmp-commands.hx | 37 +++++++++++++++++++++++++++++++++++++
> >  1 file changed, 37 insertions(+)
> >
> >diff --git a/qmp-commands.hx b/qmp-commands.hx
> >index 3a42ad0..7a745ed 100644
> >--- a/qmp-commands.hx
> >+++ b/qmp-commands.hx
> >@@ -1008,6 +1008,43 @@ EQMP
> >          .mhandler.cmd_new = qmp_marshal_input_block_stream,
> >      },
> >+SQMP
> >+block-stream
> >+------------
> >+
> >+Copy data from a backing file into a block device.
> 
> It looks like you stopped just copy-pasting the information from
> block-core.json here...
> 
> >+
> >+Arguments:
> >+
> >+- "device": The device's ID, must be unique (json-string)
> 
> ...instead sometimes copying it from block-commit...
> 
> >+- "base": The file name of the backing image above which copying starts
> >+          (json-string, optional)
> 
> ...or creating new descriptions...
> 
> >+- "backing-file": The backing file string to write into the active layer. This
> >+                  filename is not validated.
> 
> ...and then you are continuing copying the block-core.json entry.
> 
> Is there a reason why you didn't just take all of the block-core.json
> comment and put it here? (just curious)

Yes.  block-commit has a similar approach where the qmp-commands.hx
doesn't contain the full command description, just a summary.

Unfortunately, the QAPI schema and QMP argument descriptions differ.
They use different conventions so I needed to adapt or rewrite them.
The path I chose was a mixture of a little bit from, a little bit from
there, and some of my own magic :P.

The best long-term step would be to pick a canonical documentation unit
- either QAPI schema or qmp-commands - and resolve differences between
them.  Then we'll have just 1 location and all documentation can be
generated from it.

Stefan

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

Re: [Qemu-devel] [PATCH] block: document block-stream in qmp-commands.hx

[Stefan Hajnoczi]

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

On Wed, Apr 15, 2015 at 11:43:42AM +0100, Stefan Hajnoczi wrote:
> The 'block-stream' QMP command is documented in block-core.json but not
> qmp-commands.hx.  Add a summary of the command to qmp-commands.hx
> (similar to the documentation for 'block-commit').
> 
> Reported-by: Kashyap Chamarthy <kchamart@redhat.com>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  qmp-commands.hx | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)

Thanks, applied to my block-next tree:
https://github.com/stefanha/qemu/commits/block-next

Stefan

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

Re: [Qemu-devel] [PATCH] block: document block-stream in qmp-commands.hx

[Markus Armbruster]

Stefan Hajnoczi <stefanha@redhat.com> writes:

> On Wed, Apr 15, 2015 at 03:08:30PM +0200, Max Reitz wrote:
>> On 15.04.2015 12:43, Stefan Hajnoczi wrote:
>> >The 'block-stream' QMP command is documented in block-core.json but not
>> >qmp-commands.hx.  Add a summary of the command to qmp-commands.hx
>> >(similar to the documentation for 'block-commit').
>> >
>> >Reported-by: Kashyap Chamarthy <kchamart@redhat.com>
>> >Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
>> >---
>> >  qmp-commands.hx | 37 +++++++++++++++++++++++++++++++++++++
>> >  1 file changed, 37 insertions(+)
>> >
>> >diff --git a/qmp-commands.hx b/qmp-commands.hx
>> >index 3a42ad0..7a745ed 100644
>> >--- a/qmp-commands.hx
>> >+++ b/qmp-commands.hx
>> >@@ -1008,6 +1008,43 @@ EQMP
>> >          .mhandler.cmd_new = qmp_marshal_input_block_stream,
>> >      },
>> >+SQMP
>> >+block-stream
>> >+------------
>> >+
>> >+Copy data from a backing file into a block device.
>> 
>> It looks like you stopped just copy-pasting the information from
>> block-core.json here...
>> 
>> >+
>> >+Arguments:
>> >+
>> >+- "device": The device's ID, must be unique (json-string)
>> 
>> ...instead sometimes copying it from block-commit...
>> 
>> >+- "base": The file name of the backing image above which copying starts
>> >+          (json-string, optional)
>> 
>> ...or creating new descriptions...
>> 
>> >+- "backing-file": The backing file string to write into the active
>> > layer. This
>> >+                  filename is not validated.
>> 
>> ...and then you are continuing copying the block-core.json entry.
>> 
>> Is there a reason why you didn't just take all of the block-core.json
>> comment and put it here? (just curious)
>
> Yes.  block-commit has a similar approach where the qmp-commands.hx
> doesn't contain the full command description, just a summary.
>
> Unfortunately, the QAPI schema and QMP argument descriptions differ.
> They use different conventions so I needed to adapt or rewrite them.
> The path I chose was a mixture of a little bit from, a little bit from
> there, and some of my own magic :P.
>
> The best long-term step would be to pick a canonical documentation unit
> - either QAPI schema or qmp-commands - and resolve differences between
> them.  Then we'll have just 1 location and all documentation can be
> generated from it.

qmp-commands.hx needs to go.  A few things keep it around, and one of
them is qemu-commands.txt.  Need to generate a satisfactory replacement
from the QAPI schema.