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

[Max Reitz]

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 <address@hidden>
> ---
>  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/

> +(address@hidden), or you define a new node inline, adding options
> +for the referenced node after a dot (address@hidden,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
> address@hidden 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
>  
> address@hidden 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.

> address@hidden @code
> address@hidden filename
> +The path to the image file in the local filesystem
> address@hidden aio
> +Specifies the AIO backend (threads/native, default: threads)
> address@hidden table
> +Example:
> address@hidden
> +-blockdev driver=file,node-name=disk,filename=disk.img
> address@hidden example
> +
> address@hidden 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.

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

s/ndoe/node/

> +(e.g. a @code{file} driver node)
> address@hidden table
> +Example 1:
> address@hidden
> +-blockdev driver=file,node-name=disk_file,filename=disk.img
> +-blockdev driver=raw,node-name=disk,file=disk_file
> address@hidden example
> +Example 2:
> address@hidden
> +-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
> address@hidden example
> +
> address@hidden Driver-specific options for @code{qcow2}
> address@hidden @code
> address@hidden file
> +Reference to or definition of the data source block driver node
> +(e.g. a @code{file} driver node)
> +
> address@hidden 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.
> +
> address@hidden lazy-refcounts
> +Whether to enable the lazy refcounts feature (on/off; default is taken from 
> the
> +image file)
> +
> address@hidden 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)
> +
> address@hidden l2-cache-size
> +The maximum size of the L2 table cache in bytes
> +(default: 4/5 of the total cache size)
> +
> address@hidden refcount-cache-size
> +The maximum size of the refcount block cache in bytes
> +(default: 1/5 of the total cache size)
> +
> address@hidden 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.
> +
> address@hidden 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)
> +
> address@hidden 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)
> +
> address@hidden 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)
> +
> address@hidden 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}.
> address@hidden table
> +
> +Example 1:
> address@hidden
> +-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
> address@hidden example
> +Example 2:
> address@hidden
> +-blockdev 
> driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
> address@hidden example
> +
> address@hidden Driver-specific options for other drivers
> +Please refer to the QAPI documentation of the @code{blockdev-add} QMP 
> command.
> +
>  @end table
>  
>  ETEXI
>

signature.asc
Description: OpenPGP digital signature