qemu-block
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Qemu-block] [PATCH v2 2/3] doc: Document generic -blockdev options


From: Max Reitz
Subject: Re: [Qemu-block] [PATCH v2 2/3] doc: Document generic -blockdev options
Date: Fri, 23 Sep 2016 19:15:59 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.3.0

On 23.09.2016 18:06, Kevin Wolf wrote:
> This adds documentation for the -blockdev options that apply to all
> nodes independent of the block driver used.
> 
> All options that are shared by -blockdev and -drive are now explained in
> the section for -blockdev. The documentation of -drive mentions that all
> -blockdev options are accepted as well.
> 
> Signed-off-by: Kevin Wolf <address@hidden>
> Reviewed-by: Eric Blake <address@hidden>
> ---
>  qemu-options.hx | 98 
> ++++++++++++++++++++++++++++++++++++++++-----------------
>  1 file changed, 69 insertions(+), 29 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 542c483..8766589 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -523,6 +523,43 @@ STEXI
>  @findex -blockdev
>  
>  Define a new block driver node.
> +
> address@hidden @option
> address@hidden Valid options for any block driver node:
> +
> address@hidden @code
> address@hidden driver
> +Specifies the block driver to use for the given node.
> address@hidden node-name
> +This defines the name of the block driver node by which it will be referenced
> +later. The name must be unique, i.e. it must not match the name of a 
> different
> +block driver node, or (if you use @option{-drive} as well) the ID of a drive.

Could use a mention of the default behavior, but since you didn't do
that anywhere else, not doing so is fine, too.

> address@hidden read-only
> +Open the node read-only. Guest write attempts will fail.
> address@hidden cache.direct
> +The host page cache can be avoided with @option{cache.direct=on}. This will
> +attempt to do disk IO directly to the guest's memory. QEMU may still perform 
> an
> +internal copy of the data.
> address@hidden cache.no-flush
> +In case you don't care about data integrity over host failures, use
> address@hidden This option tells QEMU that it never needs to write

Just text movement, but that doesn't mean we can improve it: While it's
a matter of test whether to use contractions in official documentations
(some do not (e.g. me), others do; and the state of the qemu man page
reflects this well), I'd definitely rather not use an imperative here.
If people do not care about this, they *may contemplate* using this
option. But we should not tell them to.

> +any data to the disk but can instead keep things in cache. If anything goes
> +wrong, like your host losing power, the disk storage getting disconnected
> +accidentally, etc. your image will most probably be rendered unusable.

Especially since losing integrity of your data is something different
than losing access to your data entirely.

> address@hidden address@hidden
> address@hidden is one of "ignore" (or "off") or "unmap" (or "on") and controls
> +whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) requests are
> +ignored or passed to the filesystem.  Some machine types may not support

Again, just text movement, but the double whitespace after the period
here is inconsistent with the rest.

> +discard requests.
> address@hidden address@hidden
> address@hidden is "off", "on" or "unmap" and enables the automatic
> +conversion of plain zero writes by the OS to driver specific optimized
> +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.

Once more, just text movement, but to be consistent, I'd prefer
@dfn{unmap} here like above.

Max

> address@hidden table
> +
> address@hidden table
> +
>  ETEXI
>  
>  DEF("drive", HAS_ARG, QEMU_OPTION_drive,

Attachment: signature.asc
Description: OpenPGP digital signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]