Re: [Qemu-devel] [PATCH v2 3/3] doc: Document driver-specific -blockdev options

[Max Reitz <mreitz@redhat.com>]

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

On 23.09.2016 18:06, Kevin Wolf wrote:
> This documents the driver-specific options for the raw, qcow2 and file
> block drivers for the man page. For everything else, we refer to the
> QAPI documentation.
> 
> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> ---
>  qemu-options.hx | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 103 insertions(+), 1 deletion(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 8766589..9811370 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -522,7 +522,18 @@ STEXI
>  @item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
>  @findex -blockdev
>  
> -Define a new block driver node.
> +Define a new block driver node. Some of the options apply to all block drivers,
> +other options are only accepted for a specific block driver. See below for a
> +list of generic options and options for the most common block drivers.
> +
> +Options that expect a reference to another node (e.g. @code{file}) can given
> +given in two ways. Either you specify the node name of an already existing node

s/given given/be given/

> +(file=@var{node-name}), or you define a new node inline, adding options
> +for the referenced node after a dot (file.filename=@var{path},file.aio=native).
> +
> +A block driver node created with @option{-blockdev} can be used for a guest
> +device by specifying its node name for the @code{drive} property in a
> +@option{-device} argument that defines a block device.
>  
>  @table @option
>  @item Valid options for any block driver node:
> @@ -558,6 +569,97 @@ zero write commands. You may even choose "unmap" if @var{discard} is set
>  to "unmap" to allow a zero write to be converted to an UNMAP operation.
>  @end table
>  
> +@item Driver-specific options for @code{file}

I'd really like a short explanation of what this driver does here,
really just a "This is a protocol-level block driver for reading normal
files." because I don't think that is obvious to most users.

> +@table @code
> +@item filename
> +The path to the image file in the local filesystem
> +@item aio
> +Specifies the AIO backend (threads/native, default: threads)
> +@end table
> +Example:
> +@example
> +-blockdev driver=file,node-name=disk,filename=disk.img
> +@end example
> +
> +@item Driver-specific options for @code{raw}

I think a "This is a format(-level) block driver for raw image files."
could be useful here, too, although I can imagine that most people can
guess that already. But it wouldn't hurt, I think.

> +@table @code
> +@item file
> +Reference to or definition of the data source block driver ndoe

s/ndoe/node/

> +(e.g. a @code{file} driver node)
> +@end table
> +Example 1:
> +@example
> +-blockdev driver=file,node-name=disk_file,filename=disk.img
> +-blockdev driver=raw,node-name=disk,file=disk_file
> +@end example
> +Example 2:
> +@example
> +-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
> +@end example
> +
> +@item Driver-specific options for @code{qcow2}
> +@table @code
> +@item file
> +Reference to or definition of the data source block driver node
> +(e.g. a @code{file} driver node)
> +
> +@item backing
> +Reference to or definition of the backing file block device (if missing, taken

I'd use "not specified" or a plain "defaults to..." instead of
"missing", because "missing" sounds like it's supposed to be specified.

> +from the image file content). It is allowed to pass an empty string here in
> +order to disable the default backing file.
> +
> +@item lazy-refcounts
> +Whether to enable the lazy refcounts feature (on/off; default is taken from the
> +image file)
> +
> +@item cache-size
> +The maximum total size of the L2 table and refcount block caches in bytes
> +(default: 1048576 bytes or 8 clusters, whichever is larger)
> +
> +@item l2-cache-size
> +The maximum size of the L2 table cache in bytes
> +(default: 4/5 of the total cache size)
> +
> +@item refcount-cache-size
> +The maximum size of the refcount block cache in bytes
> +(default: 1/5 of the total cache size)
> +
> +@item cache-clean-interval
> +Clean unused entries in the L2 and refcount caches. The interval is in seconds.
> +The default value is 0 and it disables this feature.
> +
> +@item pass-discard-request
> +Whether discard requests to the qcow2 device should be forwarded to the data
> +source (on/off; default: on if discard=unmap is specified, off otherwise)
> +
> +@item pass-discard-snapshot
> +Whether discard requests for the data source should be issued when a snapshot
> +operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
> +default: on)
> +
> +@item pass-discard-other
> +Whether discard requests for the data source should be issued on other
> +occasions where a cluster gets freed (on/off; default: off)
> +
> +@item overlap-check
> +Which overlap checks to perform for writes to the image
> +(none/constant/cache/all; default: cached). For details or finer

s/cache/cached/

Max

> +granularity control refer to the QAPI documentation of @code{blockdev-add}.
> +@end table
> +
> +Example 1:
> +@example
> +-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
> +-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
> +@end example
> +Example 2:
> +@example
> +-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
> +@end example
> +
> +@item Driver-specific options for other drivers
> +Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
> +
>  @end table
>  
>  ETEXI
> 



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