[Qemu-devel] [PATCH 0/2] Document qemu-img create -o

[Qemu-devel] [PATCH 0/2] Document qemu-img create -o

[Kevin Wolf]

The bad habit of implementing things and no letting anybody know what has
hanged... This patch series makes the qemu-img -o option actually usable
without reading the code by documenting things.

Kevin Wolf (2):
  qemu-img: Print available options with -o ?
  Document changes in qemu-img interface

 block/cow.c       |   12 ++++++++++--
 block/qcow.c      |   18 +++++++++++++++---
 block/qcow2.c     |   30 +++++++++++++++++++++++++-----
 block/raw-posix.c |    6 +++++-
 block/raw-win32.c |    6 +++++-
 block/vmdk.c      |   18 +++++++++++++++---
 block/vpc.c       |    6 +++++-
 qemu-img.c        |   27 ++++++++++++++++++++-------
 qemu-img.texi     |   32 ++++++++++++++++++--------------
 qemu-option.c     |   13 +++++++++++++
 qemu-option.h     |    2 ++
 11 files changed, 133 insertions(+), 37 deletions(-)

[Qemu-devel] [PATCH 1/2] qemu-img: Print available options with -o ?

[Kevin Wolf]

This patch adds a small help text to each of the options in the block drivers
which can be displayed by using qemu-img create -f fmt -o ?

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 block/cow.c       |   12 ++++++++++--
 block/qcow.c      |   18 +++++++++++++++---
 block/qcow2.c     |   30 +++++++++++++++++++++++++-----
 block/raw-posix.c |    6 +++++-
 block/raw-win32.c |    6 +++++-
 block/vmdk.c      |   18 +++++++++++++++---
 block/vpc.c       |    6 +++++-
 qemu-img.c        |   18 +++++++++++++++---
 qemu-option.c     |   13 +++++++++++++
 qemu-option.h     |    2 ++
 10 files changed, 110 insertions(+), 19 deletions(-)

diff --git a/block/cow.c b/block/cow.c
index 41d292a..84818f1 100644
--- a/block/cow.c
+++ b/block/cow.c
@@ -262,8 +262,16 @@ static void cow_flush(BlockDriverState *bs)
 }
 
 static QEMUOptionParameter cow_create_options[] = {
-    { BLOCK_OPT_SIZE,           OPT_SIZE },
-    { BLOCK_OPT_BACKING_FILE,   OPT_STRING },
+    {
+        .name = BLOCK_OPT_SIZE,
+        .type = OPT_SIZE,
+        .help = "Virtual disk size"
+    },
+    {
+        .name = BLOCK_OPT_BACKING_FILE,
+        .type = OPT_STRING,
+        .help = "File name of a base image"
+    },
     { NULL }
 };
 
diff --git a/block/qcow.c b/block/qcow.c
index 329b364..55a68a6 100644
--- a/block/qcow.c
+++ b/block/qcow.c
@@ -909,9 +909,21 @@ static int qcow_get_info(BlockDriverState *bs, BlockDriverInfo *bdi)
 
 
 static QEMUOptionParameter qcow_create_options[] = {
-    { BLOCK_OPT_SIZE,           OPT_SIZE },
-    { BLOCK_OPT_BACKING_FILE,   OPT_STRING },
-    { BLOCK_OPT_ENCRYPT,        OPT_FLAG },
+    {
+        .name = BLOCK_OPT_SIZE,
+        .type = OPT_SIZE,
+        .help = "Virtual disk size"
+    },
+    {
+        .name = BLOCK_OPT_BACKING_FILE,
+        .type = OPT_STRING,
+        .help = "File name of a base image"
+    },
+    {
+        .name = BLOCK_OPT_ENCRYPT,
+        .type = OPT_FLAG,
+        .help = "Encrypt the image"
+    },
     { NULL }
 };
 
diff --git a/block/qcow2.c b/block/qcow2.c
index d1611d1..c2be42e 100644
--- a/block/qcow2.c
+++ b/block/qcow2.c
@@ -2981,11 +2981,31 @@ static int qcow_get_buffer(BlockDriverState *bs, uint8_t *buf,
 }
 
 static QEMUOptionParameter qcow_create_options[] = {
-    { BLOCK_OPT_SIZE,           OPT_SIZE },
-    { BLOCK_OPT_BACKING_FILE,   OPT_STRING },
-    { BLOCK_OPT_BACKING_FMT,    OPT_STRING },
-    { BLOCK_OPT_ENCRYPT,        OPT_FLAG },
-    { BLOCK_OPT_CLUSTER_SIZE,   OPT_SIZE },
+    {
+        .name = BLOCK_OPT_SIZE,
+        .type = OPT_SIZE,
+        .help = "Virtual disk size"
+    },
+    {
+        .name = BLOCK_OPT_BACKING_FILE,
+        .type = OPT_STRING,
+        .help = "File name of a base image"
+    },
+    {
+        .name = BLOCK_OPT_BACKING_FMT,
+        .type = OPT_STRING,
+        .help = "Image format of the base image"
+    },
+    {
+        .name = BLOCK_OPT_ENCRYPT,
+        .type = OPT_FLAG,
+        .help = "Encrypt the image"
+    },
+    {
+        .name = BLOCK_OPT_CLUSTER_SIZE,
+        .type = OPT_SIZE,
+        .help = "qcow2 cluster size"
+    },
     { NULL }
 };
 
diff --git a/block/raw-posix.c b/block/raw-posix.c
index 38c4aa7..4798d62 100644
--- a/block/raw-posix.c
+++ b/block/raw-posix.c
@@ -858,7 +858,11 @@ static void raw_flush(BlockDriverState *bs)
 
 
 static QEMUOptionParameter raw_create_options[] = {
-    { BLOCK_OPT_SIZE,           OPT_SIZE },
+    {
+        .name = BLOCK_OPT_SIZE,
+        .type = OPT_SIZE,
+        .help = "Virtual disk size"
+    },
     { NULL }
 };
 
diff --git a/block/raw-win32.c b/block/raw-win32.c
index 6e5c09b..1e95153 100644
--- a/block/raw-win32.c
+++ b/block/raw-win32.c
@@ -234,7 +234,11 @@ static int raw_create(const char *filename, QEMUOptionParameter *options)
 }
 
 static QEMUOptionParameter raw_create_options[] = {
-    { BLOCK_OPT_SIZE,           OPT_SIZE },
+    {
+        .name = BLOCK_OPT_SIZE,
+        .type = OPT_SIZE,
+        .help = "Virtual disk size"
+    },
     { NULL }
 };
 
diff --git a/block/vmdk.c b/block/vmdk.c
index b3ea686..f21f02b 100644
--- a/block/vmdk.c
+++ b/block/vmdk.c
@@ -828,9 +828,21 @@ static void vmdk_flush(BlockDriverState *bs)
 
 
 static QEMUOptionParameter vmdk_create_options[] = {
-    { BLOCK_OPT_SIZE,           OPT_SIZE },
-    { BLOCK_OPT_BACKING_FILE,   OPT_STRING },
-    { BLOCK_OPT_COMPAT6,        OPT_FLAG },
+    {
+        .name = BLOCK_OPT_SIZE,
+        .type = OPT_SIZE,
+        .help = "Virtual disk size"
+    },
+    {
+        .name = BLOCK_OPT_BACKING_FILE,
+        .type = OPT_STRING,
+        .help = "File name of a base image"
+    },
+    {
+        .name = BLOCK_OPT_COMPAT6,
+        .type = OPT_FLAG,
+        .help = "VMDK version 6 image"
+    },
     { NULL }
 };
 
diff --git a/block/vpc.c b/block/vpc.c
index 662a6f6..ba482e9 100644
--- a/block/vpc.c
+++ b/block/vpc.c
@@ -594,7 +594,11 @@ static void vpc_close(BlockDriverState *bs)
 }
 
 static QEMUOptionParameter vpc_create_options[] = {
-    { "size", OPT_SIZE },
+    {
+        .name = BLOCK_OPT_SIZE,
+        .type = OPT_SIZE,
+        .help = "Virtual disk size"
+    },
     { NULL }
 };
 
diff --git a/qemu-img.c b/qemu-img.c
index 3edf25a..947e71b 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -281,15 +281,17 @@ static int img_create(int argc, char **argv)
             break;
         }
     }
-    if (optind >= argc)
-        help();
-    filename = argv[optind++];
 
     /* Find driver and parse its options */
     drv = bdrv_find_format(fmt);
     if (!drv)
         error("Unknown file format '%s'", fmt);
 
+    if (options && !strcmp(options, "?")) {
+        print_option_help(drv->create_options);
+        return 0;
+    }
+
     if (options) {
         param = parse_option_parameters(options, drv->create_options, param);
         if (param == NULL) {
@@ -299,6 +301,11 @@ static int img_create(int argc, char **argv)
         param = parse_option_parameters("", drv->create_options, param);
     }
 
+    /* Get the filename */
+    if (optind >= argc)
+        help();
+    filename = argv[optind++];
+
     /* Add size to parameters */
     if (optind < argc) {
         set_option_parameter(param, BLOCK_OPT_SIZE, argv[optind++]);
@@ -596,6 +603,11 @@ static int img_convert(int argc, char **argv)
     if (!drv)
         error("Unknown file format '%s'", out_fmt);
 
+    if (options && !strcmp(options, "?")) {
+        print_option_help(drv->create_options);
+        return 0;
+    }
+
     if (options) {
         param = parse_option_parameters(options, drv->create_options, param);
         if (param == NULL) {
diff --git a/qemu-option.c b/qemu-option.c
index 3cebdd5..646bbad 100644
--- a/qemu-option.c
+++ b/qemu-option.c
@@ -347,3 +347,16 @@ void print_option_parameters(QEMUOptionParameter *list)
         list++;
     }
 }
+
+/*
+ * Prints an overview of all available options
+ */
+void print_option_help(QEMUOptionParameter *list)
+{
+    printf("Supported options:\n");
+    while (list && list->name) {
+        printf("%-16s %s\n", list->name,
+            list->help ? list->help : "No description available");
+        list++;
+    }
+}
diff --git a/qemu-option.h b/qemu-option.h
index ac24694..059c0a4 100644
--- a/qemu-option.h
+++ b/qemu-option.h
@@ -40,6 +40,7 @@ typedef struct QEMUOptionParameter {
         uint64_t n;
         char* s;
     } value;
+    const char *help;
 } QEMUOptionParameter;
 
 
@@ -63,5 +64,6 @@ QEMUOptionParameter *parse_option_parameters(const char *param,
     QEMUOptionParameter *list, QEMUOptionParameter *dest);
 void free_option_parameters(QEMUOptionParameter *list);
 void print_option_parameters(QEMUOptionParameter *list);
+void print_option_help(QEMUOptionParameter *list);
 
 #endif
-- 
1.6.0.6

[Qemu-devel] [PATCH 2/2] Document changes in qemu-img interface

[Kevin Wolf]

Update the documentation to reflect the introduction of format specific options
with -o. Don't advertise -e or -6 any more, they exist only for compatibility
reasons and can be replaced by the corresponding -o options.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 qemu-img.c    |    9 +++++----
 qemu-img.texi |   32 ++++++++++++++++++--------------
 2 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/qemu-img.c b/qemu-img.c
index 947e71b..aff3980 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -59,9 +59,9 @@ static void help(void)
            "\n"
            "Command syntax:\n"
            "  check [-f fmt] filename\n"
-           "  create [-e] [-6] [-F fmt] [-b base_image] [-f fmt] filename [size]\n"
+           "  create [-F fmt] [-b base_image] [-f fmt] [-o options] filename [size]\n"
            "  commit [-f fmt] filename\n"
-           "  convert [-c] [-e] [-6] [-f fmt] [-O output_fmt] [-B output_base_image] filename [filename2 [...]] output_filename\n"
+           "  convert [-c] [-f fmt] [-O output_fmt] [-o options] [-B output_base_image] filename [filename2 [...]] output_filename\n"
            "  info [-f fmt] filename\n"
            "  snapshot [-l | -a snapshot | -c snapshot | -d snapshot] filename\n"
            "\n"
@@ -79,9 +79,10 @@ static void help(void)
            "    supported any 'k' or 'K' is ignored\n"
            "  'output_filename' is the destination disk image filename\n"
            "  'output_fmt' is the destination format\n"
+           "  'options' is a comma separated list of format specific options in a\n"
+           "    name=value format. Use -o ? for an overview of the options supported by the\n"
+           "    used format\n"
            "  '-c' indicates that target image must be compressed (qcow format only)\n"
-           "  '-e' indicates that the target image must be encrypted (qcow format only)\n"
-           "  '-6' indicates that the target image must use compatibility level 6 (vmdk format only)\n"
            "  '-h' with or without a command shows this help and lists the supported formats\n"
            "\n"
            "Parameters to snapshot subcommand:\n"
diff --git a/qemu-img.texi b/qemu-img.texi
index deef2ab..dae7b82 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -8,9 +8,9 @@ usage: qemu-img command [command options]
 
 The following commands are supported:
 @table @option
-@item create [-e] [-6] [-F @var{base_fmt}] [-b @var{base_image}] [-f @var{fmt}] @var{filename} [@var{size}]
+@item create [-F @var{base_fmt}] [-b @var{base_image}] [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
 @item commit [-f @var{fmt}] @var{filename}
-@item convert [-c] [-e] [-6] [-f @var{fmt}] [-O @var{output_fmt}] [-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}] [-B @var{output_base_image}] @var{filename} [@var{filename2} [...]] @var{output_filename}
 @item info [-f @var{fmt}] @var{filename}
 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename}
 @end table
@@ -61,22 +61,23 @@ CD-ROM images present for example in the Knoppix CD-ROMs.
 @end table
 
 @item size
-is the disk image size in kilobytes. Optional suffixes @code{M}
-(megabyte, 1024 * 1024) and @code{G} (gigabyte, 1024 * 1024 * 1024)
-are supported and any @code{k} or @code{K} is ignored.
+is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
+(kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
+and T (terabyte, 1024G) are supported.  @code{b} is ignored.
 
 @item output_filename
 is the destination disk image filename
 
 @item output_fmt
  is the destination format
+@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
+
 
 @item -c
 indicates that target image must be compressed (qcow format only)
-@item -e
-indicates that the target image must be encrypted (qcow format only)
-@item -6
-indicates that the target image must use compatibility level 6 (vmdk format only)
 @item -h
 with or without a command shows help and lists the supported formats
 @end table
@@ -100,7 +101,7 @@ lists all snapshots in the given image
 Command description:
 
 @table @option
-@item create [-6] [-e] [-b @var{base_image}] [-f @var{fmt}] @var{filename} [@var{size}]
+@item create [-F @var{base_fmt}] [-b @var{base_image}] [-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}.
@@ -110,17 +111,20 @@ 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.
 
+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.
+
 @item commit [-f @var{fmt}] @var{filename}
 
 Commit the changes recorded in @var{filename} in its base image.
 
-@item convert [-c] [-e] [-f @var{fmt}] @var{filename} [-O @var{output_fmt}] @var{output_filename}
+@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}
 
 Convert the disk image @var{filename} to disk image @var{output_filename}
-using format @var{output_fmt}. It can be optionally encrypted
-(@code{-e} option) or compressed (@code{-c} option).
+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 format @code{qcow} supports encryption or compression. The
+Only the formats @code{qcow} and @code{qcow2} support encryption or compression. The
 compression is read-only. It means that if a compressed sector is
 rewritten, then it is rewritten as uncompressed data.
 
-- 
1.6.0.6

Re: [Qemu-devel] [PATCH 0/2] Document qemu-img create -o

[Blue Swirl]

On 6/4/09, Kevin Wolf <kwolf@redhat.com> wrote:
> The bad habit of implementing things and no letting anybody know what has
>  hanged... This patch series makes the qemu-img -o option actually usable
>  without reading the code by documenting things.

Thanks, applied.

With hxtool the documentation and code could be kept in one place...