[Qemu-devel] [PATCH 0/3] Update qemu-img documentation

[Qemu-devel] [PATCH 0/3] Update qemu-img documentation

[Kevin Wolf]

Early this week, I received a request that qemu-img convert should support the
-F option for the backing file format just like qemu-img create does. In fact,
we already support this as -o backing_fmt=... So I came to the conclusion that
we need to have another patch round for the documentation that removes
references to the deprecated options and moves the focus to -o options.

Kevin Wolf (3):
  Documentation: Move image format descriptions to own section
  Documentation: Don't mention old qemu-img options
  Documentation: Add options to image format descriptions

 qemu-img-cmds.hx |    8 +-
 qemu-img.c       |    6 --
 qemu-img.texi    |  162 ++++++++++++++++++++++++++++++++++--------------------
 3 files changed, 107 insertions(+), 69 deletions(-)

[Qemu-devel] [PATCH 1/3] Documentation: Move image format descriptions to own section

[Kevin Wolf]

The description of the image formats is too long to be a subitem of a parameter
description. It will become even longer when we include the options provided by
the respective format.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 qemu-img.texi |   78 ++++++++++++++++++++++++++++++---------------------------
 1 files changed, 41 insertions(+), 37 deletions(-)

diff --git a/qemu-img.texi b/qemu-img.texi
index ae8ca92..dd248ea 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -25,43 +25,8 @@ differ
 @item base_fmt
 is the disk image format of @var{base_image}. for more information look at @var{fmt}
 @item fmt
-is the disk image format. It is guessed automatically in most cases. The following formats are supported:
-
-@table @code
-@item raw
-
-Raw disk image format (default). 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.
-
-@item host_device
-
-Host device format. This format should be used instead of raw when
-converting to block devices or other devices where "holes" are not
-supported.
-
-@item qcow2
-QEMU image format, the most versatile format. Use it to have smaller
-images (useful if your filesystem does not supports holes, for example
-on Windows), optional AES encryption, zlib based compression and
-support of multiple VM snapshots.
-@item qcow
-Old QEMU image format. Left for compatibility.
-@item cow
-User Mode Linux Copy On Write image format. Used to be the only growable
-image format in QEMU. It is supported only for compatibility with
-previous versions. It does not work on win32.
-@item vdi
-VirtualBox 1.1 compatible image format.
-@item vmdk
-VMware 3 and 4 compatible image format.
-@item cloop
-Linux Compressed Loop image, useful only to reuse directly compressed
-CD-ROM images present for example in the Knoppix CD-ROMs.
-@end table
+is the disk image format. It is guessed automatically in most cases. See below
+for a description of the supported disk formats.
 
 @item size
 is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
@@ -150,6 +115,45 @@ they are displayed too.
 List, apply, create or delete snapshots in image @var{filename}.
 @end table
 
+Supported image file formats:
+
+@table @option
+@item raw
+
+Raw disk image format (default). 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.
+
+@item host_device
+
+Host device format. This format should be used instead of raw when
+converting to block devices or other devices where "holes" are not
+supported.
+
+@item qcow2
+QEMU image format, the most versatile format. Use it to have smaller
+images (useful if your filesystem does not supports holes, for example
+on Windows), optional AES encryption, zlib based compression and
+support of multiple VM snapshots.
+@item qcow
+Old QEMU image format. Left for compatibility.
+@item cow
+User Mode Linux Copy On Write image format. Used to be the only growable
+image format in QEMU. It is supported only for compatibility with
+previous versions. It does not work on win32.
+@item vdi
+VirtualBox 1.1 compatible image format.
+@item vmdk
+VMware 3 and 4 compatible image format.
+@item cloop
+Linux Compressed Loop image, useful only to reuse directly compressed
+CD-ROM images present for example in the Knoppix CD-ROMs.
+@end table
+
+
 @c man end
 
 @ignore
-- 
1.6.2.5

[Qemu-devel] [PATCH 2/3] Documentation: Don't mention old qemu-img options

[Kevin Wolf]

The old options are still supported for compatibility, but they are
inconsistent (for example create -b vs. convert -B for backing files) and
incomplete (-F only exists for create) which tends to confuse people. Remove
all references to the old options from the documentation to guide users to the
more consistent -o options.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 qemu-img-cmds.hx |    8 ++++----
 qemu-img.c       |    6 ------
 qemu-img.texi    |   38 +++++++++++++++++---------------------
 3 files changed, 21 insertions(+), 31 deletions(-)

diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
index ddb86f0..641bd87 100644
--- a/qemu-img-cmds.hx
+++ b/qemu-img-cmds.hx
@@ -16,9 +16,9 @@ STEXI
 ETEXI
 
 DEF("create", img_create,
-    "create [-F fmt] [-b base_image] [-f fmt] [-o options] filename [size]")
+    "create [-f fmt] [-o options] filename [size]")
 STEXI
-@item create [-F @var{base_fmt}] [-b @var{base_image}] [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
+@item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
 ETEXI
 
 DEF("commit", img_commit,
@@ -28,9 +28,9 @@ STEXI
 ETEXI
 
 DEF("convert", img_convert,
-    "convert [-c] [-f fmt] [-O output_fmt] [-o options] [-B output_base_image] filename [filename2 [...]] output_filename")
+    "convert [-c] [-f fmt] [-O output_fmt] [-o options] filename [filename2 [...]] output_filename")
 STEXI
-@item convert [-c] [-f @var{fmt}] [-O @var{output_fmt}] [-o @var{options}] [-B @var{output_base_image}] @var{filename} [@var{filename2} [...]] @var{output_filename}
+@item convert [-c] [-f @var{fmt}] [-O @var{output_fmt}] [-o @var{options}] @var{filename} [@var{filename2} [...]] @var{output_filename}
 ETEXI
 
 DEF("info", img_info,
diff --git a/qemu-img.c b/qemu-img.c
index 204f618..d5db34c 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -71,12 +71,6 @@ static void help(void)
            "\n"
            "Command parameters:\n"
            "  'filename' is a disk image filename\n"
-           "  'base_image' is the read-only disk image which is used as base for a copy on\n"
-           "    write image; the copy on write image only stores the modified data\n"
-           "  'output_base_image' forces the output image to be created as a copy on write\n"
-           "    image of the specified base image; 'output_base_image' should have the same\n"
-           "    content as the input's base image, however the path, image format, etc may\n"
-           "    differ\n"
            "  'fmt' is the disk image format. It is guessed automatically in most cases\n"
            "  'size' is the disk image size in kilobytes. Optional suffixes\n"
            "    'M' (megabyte, 1024 * 1024) and 'G' (gigabyte, 1024 * 1024 * 1024) are\n"
diff --git a/qemu-img.texi b/qemu-img.texi
index dd248ea..2d0106b 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -14,16 +14,6 @@ Command parameters:
 @table @var
 @item filename
  is a disk image filename
-@item base_image
-is the read-only disk image which is used as base for a copy on
-    write image; the copy on write image only stores the modified data
-@item output_base_image
-forces the output image to be created as a copy on write
-image of the specified base image; @code{output_base_image} should have the same
-content as the input's base image, however the path, image format, etc may
-differ
-@item base_fmt
-is the disk image format of @var{base_image}. for more information look at @var{fmt}
 @item fmt
 is the disk image format. It is guessed automatically in most cases. See below
 for a description of the supported disk formats.
@@ -69,15 +59,16 @@ lists all snapshots in the given image
 Command description:
 
 @table @option
-@item create [-F @var{base_fmt}] [-b @var{base_image}] [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
+@item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
 
 Create the new disk image @var{filename} of size @var{size} and format
-@var{fmt}.
+@var{fmt}. Depending on the file format, you can add one or more @var{options}
+that enable additional features of this format.
 
-If @var{base_image} is specified, then the image will record only the
-differences from @var{base_image}. No size needs to be specified in
-this case. @var{base_image} will never be modified unless you use the
-@code{commit} monitor command.
+If the option @var{backing_file} is specified, then the image will record
+only the differences from @var{backing_file}. No size needs to be specified in
+this case. @var{backing_file} will never be modified unless you use the
+@code{commit} monitor command (or qemu-img commit).
 
 The size can also be specified using the @var{size} option with @code{-o},
 it doesn't need to be specified separately in this case.
@@ -86,23 +77,25 @@ it doesn't need to be specified separately in this case.
 
 Commit the changes recorded in @var{filename} in its base image.
 
-@item convert [-c] [-f @var{fmt}] [-O @var{output_fmt}] [-o @var{options}] [-B @var{output_base_image}] @var{filename} [@var{filename2} [...]] @var{output_filename}
+@item convert [-c] [-f @var{fmt}] [-O @var{output_fmt}] [-o @var{options}] @var{filename} [@var{filename2} [...]] @var{output_filename}
 
 Convert the disk image @var{filename} to disk image @var{output_filename}
 using format @var{output_fmt}. It can be optionally compressed (@code{-c}
 option) or use any format specific options like encryption (@code{-o} option).
 
-Only the formats @code{qcow} and @code{qcow2} support encryption or compression. The
+Only the formats @code{qcow} and @code{qcow2} support compression. The
 compression is read-only. It means that if a compressed sector is
 rewritten, then it is rewritten as uncompressed data.
 
-Encryption uses the AES format which is very secure (128 bit keys). Use
-a long password (16 characters) to get maximum protection.
-
 Image conversion is also useful to get smaller image when using a
 growable format such as @code{qcow} or @code{cow}: the empty sectors
 are detected and suppressed from the destination image.
 
+You can use the @var{backing_file} option to force the output image to be
+created as a copy on write image of the specified base image; the
+@var{backing_file} should have the same content as the input's base image,
+however the path, image format, etc may differ.
+
 @item info [-f @var{fmt}] @var{filename}
 
 Give information about the disk image @var{filename}. Use it in
@@ -138,6 +131,9 @@ QEMU image format, the most versatile format. Use it to have smaller
 images (useful if your filesystem does not supports holes, for example
 on Windows), optional AES encryption, zlib based compression and
 support of multiple VM snapshots.
+
+Encryption uses the AES format which is very secure (128 bit keys). Use
+a long password (16 characters) to get maximum protection.
 @item qcow
 Old QEMU image format. Left for compatibility.
 @item cow
-- 
1.6.2.5

[Qemu-devel] [PATCH 3/3] Documentation: Add options to image format descriptions

[Kevin Wolf]

Explain the existing format specific options that can be used with qemu-img
create/convert -o ...

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 qemu-img.texi |   46 +++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 45 insertions(+), 1 deletions(-)

diff --git a/qemu-img.texi b/qemu-img.texi
index 2d0106b..ac97854 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -31,7 +31,7 @@ is the destination disk image filename
 @item options
 is a comma separated list of format specific options in a
 name=value format. Use @code{-o ?} for an overview of the options supported
-by the used format
+by the used format or see the format descriptions below for details.
 
 
 @item -c
@@ -132,10 +132,42 @@ images (useful if your filesystem does not supports holes, for example
 on Windows), optional AES encryption, zlib based compression and
 support of multiple VM snapshots.
 
+Supported options:
+@table @code
+@item backing_file
+File name of a base image (see @option{create} subcommand)
+@item backing_fmt
+Image format of the base image
+@item encryption
+If this option is set to @code{on}, the image is encrypted.
+
 Encryption uses the AES format which is very secure (128 bit keys). Use
 a long password (16 characters) to get maximum protection.
+
+@item cluster_size
+Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
+sizes can improve the image file size whereas larger cluster sizes generally
+provide better performance.
+
+@item preallocation
+Preallocation mode (allowed values: off, metadata). An image with preallocated
+metadata is initially larger but can improve performance when the image needs
+to grow.
+
+@end table
+
+
 @item qcow
 Old QEMU image format. Left for compatibility.
+
+Supported options:
+@table @code
+@item backing_file
+File name of a base image (see @option{create} subcommand)
+@item encryption
+If this option is set to @code{on}, the image is encrypted.
+@end table
+
 @item cow
 User Mode Linux Copy On Write image format. Used to be the only growable
 image format in QEMU. It is supported only for compatibility with
@@ -144,6 +176,18 @@ previous versions. It does not work on win32.
 VirtualBox 1.1 compatible image format.
 @item vmdk
 VMware 3 and 4 compatible image format.
+
+Supported options:
+@table @code
+@item backing_fmt
+Image format of the base image
+@item compat6
+Create a VMDK version 6 image (instead of version 4)
+@end table
+
+@item vpc
+VirtualPC compatible image format (VHD).
+
 @item cloop
 Linux Compressed Loop image, useful only to reuse directly compressed
 CD-ROM images present for example in the Knoppix CD-ROMs.
-- 
1.6.2.5