[PATCH] block: Print simple help text when calling "-blockdev help"

[PATCH] block: Print simple help text when calling "-blockdev help"

[Thomas Huth]

From: Thomas Huth <thuth@redhat.com>

Other command line options like "-chardev", "-netdev" or "-device"
already present the user with a list of available parameters, but
when running "-blockdev help", there is currently only an error
message. There is already the possibility to run "-drive format=help",
but it does not seem to be documented, so this is not very useful
for the average user. Let's improve this situation by providing
the same list of available drivers when running QEMU with
"-blockdev help".

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 include/block/block-common.h |  1 +
 blockdev.c                   | 15 ++++++++++-----
 system/vl.c                  |  7 +++++--
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/include/block/block-common.h b/include/block/block-common.h
index 895ea175413..010c4425dcf 100644
--- a/include/block/block-common.h
+++ b/include/block/block-common.h
@@ -583,5 +583,6 @@ char *path_combine(const char *base_path, const char *filename);
 char *bdrv_get_full_backing_filename_from_filename(const char *backed,
                                                    const char *backing,
                                                    Error **errp);
+void blockdev_show_help(void);
 
 #endif /* BLOCK_COMMON_H */
diff --git a/blockdev.c b/blockdev.c
index 6e86c6262f9..3d179939205 100644
--- a/blockdev.c
+++ b/blockdev.c
@@ -475,6 +475,15 @@ static OnOffAuto account_get_opt(QemuOpts *opts, const char *name)
     return ON_OFF_AUTO_OFF;
 }
 
+void blockdev_show_help(void)
+{
+      qemu_printf("Supported formats:");
+      bdrv_iterate_format(bdrv_format_print, NULL, false);
+      qemu_printf("\nSupported formats (read-only):");
+      bdrv_iterate_format(bdrv_format_print, NULL, true);
+      qemu_printf("\n");
+}
+
 /* Takes the ownership of bs_opts */
 static BlockBackend *blockdev_init(const char *file, QDict *bs_opts,
                                    Error **errp)
@@ -541,11 +550,7 @@ static BlockBackend *blockdev_init(const char *file, QDict *bs_opts,
 
     if ((buf = qemu_opt_get(opts, "format")) != NULL) {
         if (is_help_option(buf)) {
-            qemu_printf("Supported formats:");
-            bdrv_iterate_format(bdrv_format_print, NULL, false);
-            qemu_printf("\nSupported formats (read-only):");
-            bdrv_iterate_format(bdrv_format_print, NULL, true);
-            qemu_printf("\n");
+            blockdev_show_help();
             goto early_err;
         }
 
diff --git a/system/vl.c b/system/vl.c
index 061cbdf860b..40c0593154a 100644
--- a/system/vl.c
+++ b/system/vl.c
@@ -2961,7 +2961,10 @@ void qemu_init(int argc, char **argv)
                           HD_OPTS);
                 break;
             case QEMU_OPTION_blockdev:
-                {
+                if (is_help_option(optarg)) {
+                    blockdev_show_help();
+                    exit(EXIT_SUCCESS);
+                } else {
                     Visitor *v;
                     BlockdevOptionsQueueEntry *bdo;
 
@@ -2974,8 +2977,8 @@ void qemu_init(int argc, char **argv)
                     visit_free(v);
                     loc_save(&bdo->loc);
                     QSIMPLEQ_INSERT_TAIL(&bdo_queue, bdo, entry);
-                    break;
                 }
+                break;
             case QEMU_OPTION_drive:
                 if (!qemu_opts_parse_noisily(qemu_find_opts("drive"),
                                              optarg, false)) {
-- 
2.55.0

Re: [PATCH] block: Print simple help text when calling "-blockdev help"

[Philippe Mathieu-Daudé]

On 10/7/26 11:36, Thomas Huth wrote:
> From: Thomas Huth <thuth@redhat.com>
> 
> Other command line options like "-chardev", "-netdev" or "-device"
> already present the user with a list of available parameters, but
> when running "-blockdev help", there is currently only an error
> message. There is already the possibility to run "-drive format=help",
> but it does not seem to be documented, so this is not very useful
> for the average user. Let's improve this situation by providing
> the same list of available drivers when running QEMU with
> "-blockdev help".
> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>   include/block/block-common.h |  1 +
>   blockdev.c                   | 15 ++++++++++-----
>   system/vl.c                  |  7 +++++--
>   3 files changed, 16 insertions(+), 7 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com>

Re: [PATCH] block: Print simple help text when calling "-blockdev help"

[Kevin Wolf]

Am 10.07.2026 um 11:36 hat Thomas Huth geschrieben:
> From: Thomas Huth <thuth@redhat.com>
> 
> Other command line options like "-chardev", "-netdev" or "-device"
> already present the user with a list of available parameters, but
> when running "-blockdev help", there is currently only an error
> message. There is already the possibility to run "-drive format=help",
> but it does not seem to be documented, so this is not very useful
> for the average user. Let's improve this situation by providing
> the same list of available drivers when running QEMU with
> "-blockdev help".
> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>

Seems like a good idea to print at least some minimal help there.
However, I find the list from -drive format=help quite hard to read, and
repeating the same list twice for read-write and read-only doesn't help
either.

I don't expect we can change -drive because I seem to remember that
management tools look at it, but can we make -blockdev help more
consistent with the other examples you mention? Something like this:

    Available blockdev drivers:
      blkdebug
      blklogwrites (read-only)
      blkreplay
      ...

Ideally, I'd also love to have a way to show all the options a specific
driver offers, but that probably won't happen before Markus QAPIfies the
CLI. :-)

>  include/block/block-common.h |  1 +
>  blockdev.c                   | 15 ++++++++++-----
>  system/vl.c                  |  7 +++++--
>  3 files changed, 16 insertions(+), 7 deletions(-)
> 
> diff --git a/include/block/block-common.h b/include/block/block-common.h
> index 895ea175413..010c4425dcf 100644
> --- a/include/block/block-common.h
> +++ b/include/block/block-common.h
> @@ -583,5 +583,6 @@ char *path_combine(const char *base_path, const char *filename);
>  char *bdrv_get_full_backing_filename_from_filename(const char *backed,
>                                                     const char *backing,
>                                                     Error **errp);
> +void blockdev_show_help(void);
>  
>  #endif /* BLOCK_COMMON_H */
> diff --git a/blockdev.c b/blockdev.c
> index 6e86c6262f9..3d179939205 100644
> --- a/blockdev.c
> +++ b/blockdev.c
> @@ -475,6 +475,15 @@ static OnOffAuto account_get_opt(QemuOpts *opts, const char *name)
>      return ON_OFF_AUTO_OFF;
>  }
>  
> +void blockdev_show_help(void)
> +{
> +      qemu_printf("Supported formats:");

We should definitely talk about "drivers" rather than "formats" with
-blockdev. The help in -drive was added in QEMU 0.10 when "formats" was
actually still accurate, but it hasn't been for a long time.

> +      bdrv_iterate_format(bdrv_format_print, NULL, false);
> +      qemu_printf("\nSupported formats (read-only):");
> +      bdrv_iterate_format(bdrv_format_print, NULL, true);
> +      qemu_printf("\n");
> +}
> +
>  /* Takes the ownership of bs_opts */
>  static BlockBackend *blockdev_init(const char *file, QDict *bs_opts,
>                                     Error **errp)
> @@ -541,11 +550,7 @@ static BlockBackend *blockdev_init(const char *file, QDict *bs_opts,
>  
>      if ((buf = qemu_opt_get(opts, "format")) != NULL) {
>          if (is_help_option(buf)) {
> -            qemu_printf("Supported formats:");
> -            bdrv_iterate_format(bdrv_format_print, NULL, false);
> -            qemu_printf("\nSupported formats (read-only):");
> -            bdrv_iterate_format(bdrv_format_print, NULL, true);
> -            qemu_printf("\n");
> +            blockdev_show_help();
>              goto early_err;
>          }
>  
> diff --git a/system/vl.c b/system/vl.c
> index 061cbdf860b..40c0593154a 100644
> --- a/system/vl.c
> +++ b/system/vl.c
> @@ -2961,7 +2961,10 @@ void qemu_init(int argc, char **argv)
>                            HD_OPTS);
>                  break;
>              case QEMU_OPTION_blockdev:
> -                {
> +                if (is_help_option(optarg)) {
> +                    blockdev_show_help();
> +                    exit(EXIT_SUCCESS);
> +                } else {
>                      Visitor *v;
>                      BlockdevOptionsQueueEntry *bdo;
>  
> @@ -2974,8 +2977,8 @@ void qemu_init(int argc, char **argv)
>                      visit_free(v);
>                      loc_save(&bdo->loc);
>                      QSIMPLEQ_INSERT_TAIL(&bdo_queue, bdo, entry);
> -                    break;
>                  }
> +                break;
>              case QEMU_OPTION_drive:
>                  if (!qemu_opts_parse_noisily(qemu_find_opts("drive"),
>                                               optarg, false)) {
> -- 
> 2.55.0

Kevin