Document qemu-img create -o
cover Document qemu-img create -o
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(-)
PATCH 1/2 qemu-img: Print available options with -o ?
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 ?
--- 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(-)
block/cow.c +10 -2
@@ -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 } };
block/qcow.c +15 -3
@@ -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 } };
block/qcow2.c +25 -5
@@ -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 } };
block/raw-posix.c +5 -1
@@ -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 } };
block/raw-win32.c +5 -1
@@ -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 } };
block/vmdk.c +15 -3
@@ -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 } };
block/vpc.c +5 -1
@@ -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 } };
qemu-img.c +15 -3
@@ -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 ) {
qemu-option.c +13 -0
@@ -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++; + } +}
qemu-option.h +2 -0
@@ -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
Signature · 1 line
1.6.0.6
PATCH 2/2 Document changes in qemu-img interface
In reply to Kevin WolfUpdate 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.
--- qemu-img.c | 9 +++++---- qemu-img.texi | 32 ++++++++++++++++++-------------- 2 files changed, 23 insertions(+), 18 deletions(-)
qemu-img.c +5 -4
@@ -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"
qemu-img.texi +18 -14
@@ -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.
Signature · 1 line
1.6.0.6
Blue Swirl
AppliedQuoted 3 lines · 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.
Thanks, applied.
With hxtool the documentation and code could be kept in one place...