From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:55224) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bnU58-0004wF-Py for qemu-devel@nongnu.org; Fri, 23 Sep 2016 13:16:15 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bnU56-0001UT-Jh for qemu-devel@nongnu.org; Fri, 23 Sep 2016 13:16:13 -0400 References: <1474646781-18951-1-git-send-email-kwolf@redhat.com> <1474646781-18951-3-git-send-email-kwolf@redhat.com> From: Max Reitz Message-ID: <1c843f20-a649-91da-67b6-9aa594a23e94@redhat.com> Date: Fri, 23 Sep 2016 19:15:59 +0200 MIME-Version: 1.0 In-Reply-To: <1474646781-18951-3-git-send-email-kwolf@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="jfnsj8Hf8exF9njme1pd1pcxAFHaXp2xX" Subject: Re: [Qemu-devel] [PATCH v2 2/3] doc: Document generic -blockdev options List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Kevin Wolf , qemu-block@nongnu.org Cc: eblake@redhat.com, qemu-devel@nongnu.org This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --jfnsj8Hf8exF9njme1pd1pcxAFHaXp2xX From: Max Reitz To: Kevin Wolf , qemu-block@nongnu.org Cc: eblake@redhat.com, qemu-devel@nongnu.org Message-ID: <1c843f20-a649-91da-67b6-9aa594a23e94@redhat.com> Subject: Re: [PATCH v2 2/3] doc: Document generic -blockdev options References: <1474646781-18951-1-git-send-email-kwolf@redhat.com> <1474646781-18951-3-git-send-email-kwolf@redhat.com> In-Reply-To: <1474646781-18951-3-git-send-email-kwolf@redhat.com> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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. >=20 > All options that are shared by -blockdev and -drive are now explained i= n > the section for -blockdev. The documentation of -drive mentions that al= l > -blockdev options are accepted as well. >=20 > Signed-off-by: Kevin Wolf > Reviewed-by: Eric Blake > --- > qemu-options.hx | 98 ++++++++++++++++++++++++++++++++++++++++---------= -------- > 1 file changed, 69 insertions(+), 29 deletions(-) >=20 > 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 > =20 > Define a new block driver node. > + > +@table @option > +@item Valid options for any block driver node: > + > +@table @code > +@item driver > +Specifies the block driver to use for the given node. > +@item node-name > +This defines the name of the block driver node by which it will be ref= erenced > +later. The name must be unique, i.e. it must not match the name of a d= ifferent > +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. > +@item read-only > +Open the node read-only. Guest write attempts will fail. > +@item cache.direct > +The host page cache can be avoided with @option{cache.direct=3Don}. Th= is will > +attempt to do disk IO directly to the guest's memory. QEMU may still p= erform an > +internal copy of the data. > +@item cache.no-flush > +In case you don't care about data integrity over host failures, use > +@option{cache.no-flush=3Don}. This option tells QEMU that it never nee= ds 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 disconnec= ted > +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. > +@item discard=3D@var{discard} > +@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and c= ontrols > +whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) reques= ts are > +ignored or passed to the filesystem. Some machine types may not suppo= rt Again, just text movement, but the double whitespace after the period here is inconsistent with the rest. > +discard requests. > +@item detect-zeroes=3D@var{detect-zeroes} > +@var{detect-zeroes} is "off", "on" or "unmap" and enables the automati= c > +conversion of plain zero writes by the OS to driver specific optimized= > +zero write commands. You may even choose "unmap" if @var{discard} is s= et > +to "unmap" to allow a zero write to be converted to an UNMAP operation= =2E Once more, just text movement, but to be consistent, I'd prefer @dfn{unmap} here like above. Max > +@end table > + > +@end table > + > ETEXI > =20 > DEF("drive", HAS_ARG, QEMU_OPTION_drive, --jfnsj8Hf8exF9njme1pd1pcxAFHaXp2xX Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- iQEvBAEBCAAZBQJX5WNQEhxtcmVpdHpAcmVkaGF0LmNvbQAKCRD0B9sAYdXPQOT4 B/0U+7ABgtd5A0fFLxaimFY1Ecz+UcJDltGqdUB/2IQhx+FcMCWYq/p6VHcKFBqI F+4Kr67aLf4+6B8S/lU76eCIaniVqJ03n3mZWYprfyk4eJyW0Nid7BL7Q4XpgIuW SsgDuy789H3++WrhCN5j+3BPgJyXwI0Bs9Hv6UWRPZsF6VyNAWJLSbidIv2zPe0F J5bhZy11aI6fzm2PN6GgJFcxbDqjpwzt5Ov2ywdvcd8n3JKOosm+cS7qdRt7Wo2C DJ1Ivc4lgPE3WUC1sudzd6wUlTlQ5n6XW92WnMDogW/xPG4uItN4scczCal9iTdt 555sx/VvMB1hTiealEQJSfLO =lJ+y -----END PGP SIGNATURE----- --jfnsj8Hf8exF9njme1pd1pcxAFHaXp2xX--