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

[Max Reitz <mreitz@redhat.com>]

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