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 <kw...@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 >
signature.asc
Description: OpenPGP digital signature