[Qemu-devel] [PATCH 2/2] Documentation: Update image format information

[Kevin Wolf]

Document new options, mark QED as deprecated.

Signed-off-by: Kevin Wolf <address@hidden>
---
 qemu-img.texi |   37 ++++++++++++++++++++++++++++++-------
 1 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/qemu-img.texi b/qemu-img.texi
index 60b83fc..2fdb3ef 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -247,6 +247,13 @@ support of multiple VM snapshots.
 
 Supported options:
 @table @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 (this is the default).
address@hidden enables image format extensions that only QEMU 1.1 and
+newer understand. Amongst others, this includes zero clusters, which allow
+efficient copy-on-read for sparse images.
+
 @item backing_file
 File name of a base image (see @option{create} subcommand)
 @item backing_fmt
@@ -267,14 +274,23 @@ Preallocation mode (allowed values: off, metadata). An 
image with preallocated
 metadata is initially larger but can improve performance when the image needs
 to grow.
 
address@hidden lazy_refcounts
+If this option is set to @code{on}, reference count updates are postponed with
+the goal of avoiding metadata I/O and improving performance. This is
+particularly interesting with @option{cache=writethrough} which doesn't batch
+metadata updates. The tradeoff is that after a host crash, the reference count
+tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
+check -r all} is required, which may take some time.
+
+This option can only be enabled if @code{compat=1.1} is specified.
+
 @end table
 
 @item qed
-Image format with support for backing files and compact image files (when your
-filesystem or transport medium does not support holes).  Good performance due
-to less metadata than the more featureful qcow2 format, especially with
-cache=writethrough or cache=directsync.  Consider using qcow2 which will soon
-have a similar optimization and is most actively developed.
+Old QEMU image format. Left for compatibility.
+
+For new images, use qcow2 instead. You might want to consider using the
address@hidden option to get a more QED-like behaviour.
 
 Supported options:
 @table @code
@@ -315,10 +331,17 @@ VMware 3 and 4 compatible image format.
 
 Supported options:
 @table @code
address@hidden backing_fmt
-Image format of the base image
address@hidden backing_file
+File name of a base image (see @option{create} subcommand).
 @item compat6
 Create a VMDK version 6 image (instead of version 4)
address@hidden subformat
+Specifies which VMDK subformat to use. Valid options are
address@hidden (default),
address@hidden,
address@hidden,
address@hidden and
address@hidden
 @end table
 
 @item vpc
-- 
1.7.6.5