Re: [Qemu-devel] [PATCH] docs: add qemu-block-drivers(7) man page

[Eric Blake]

On 06/22/2017 07:17 AM, Stefan Hajnoczi wrote:
> Block driver documentation is available in qemu-doc.html.  It would be
> convenient to have documentation for formats, protocols, and filter
> drivers in a man page.
> 
> Extract the relevant part of qemu-doc.html into a new file called
> docs/qemu-block-drivers.texi.  This file can also be built as a
> stand-alone document (man, html, etc).
> 
> Signed-off-by: Stefan Hajnoczi <address@hidden>
> ---

> +
> address@hidden @option
> address@hidden raw
> +
> +Raw disk image format. This format has the advantage of
> +being simple and easily exportable to all other emulators. If your
> +file system supports @emph{holes} (for example in ext2 or ext3 on
> +Linux or NTFS on Windows), then only the written sectors will reserve
> +space. Use @code{qemu-img info} to know the real size used by the
> +image or @code{ls -ls} on Unix/Linux.

Worth mentioning the security risk of using raw images under probing
without explicitly calling them out as raw, because then a guest can
impersonate other type of images?

> +
> +Supported options:
> address@hidden @code
> address@hidden preallocation
> +Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
> address@hidden mode preallocates space for image by calling posix_fallocate().
> address@hidden mode preallocates space for image by writing zeros to 
> underlying
> +storage.
> address@hidden table
> +
> address@hidden qcow2
> +QEMU image format, the most versatile format. Use it to have smaller
> +images (useful if your filesystem does not supports holes, for example

s/supports/support/

> +on Windows),

Odd, since you just stated above for raw that Windows DOES support holes
(on NTFS).  Better might be "on FAT filesystems".

> zlib based compression and support of multiple VM
> +snapshots.
> +
> +Supported options:
> address@hidden @code
> address@hidden compat
> +Determines the qcow2 version to use. @code{compat=0.10} uses the
> +traditional image format that can be read by any QEMU since 0.10.
> address@hidden enables image format extensions that only QEMU 1.1 and
> +newer understand (this is the default). Amongst others, this includes

I don't have any strong opinion on US vs. UK spelling, but do like to
point out that this is user-facing, if we are trying to consistently
prefer one flavo[u]r of among[st] in our docs.

Then again, much of your patch is just code motion, rather than new
documentation.  So my comments are probably worth separate patches.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature