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

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

[Thomas Huth]

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. Thus let's improve this situation by providing
a proper list of available drivers when running QEMU with
"-blockdev help".

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 v2: Don't re-use the code from "-drive format=help" and print the
     help in a better readable way instead

 include/block/block-common.h |  1 +
 block.c                      | 15 +++++++++++++++
 system/vl.c                  |  7 +++++--
 3 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/include/block/block-common.h b/include/block/block-common.h
index 895ea175413..c76a72c1220 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 bdrv_show_help(void);
 
 #endif /* BLOCK_COMMON_H */
diff --git a/block.c b/block.c
index f0a6042e616..895d6db5acf 100644
--- a/block.c
+++ b/block.c
@@ -524,6 +524,21 @@ bool bdrv_uses_whitelist(void)
     return use_bdrv_whitelist;
 }
 
+static void bdrv_help_format_print(void *opaque, const char *name)
+{
+    if (bdrv_format_is_whitelisted(name, false)) {
+        printf("%s\n", name);
+    } else {
+        printf("%s (read-only)\n", name);
+    }
+}
+
+void bdrv_show_help(void)
+{
+      printf("Available blockdev drivers:\n");
+      bdrv_iterate_format(bdrv_help_format_print, NULL, true);
+}
+
 typedef struct CreateCo {
     BlockDriver *drv;
     char *filename;
diff --git a/system/vl.c b/system/vl.c
index 9bd7664b85c..dc93e8737cb 100644
--- a/system/vl.c
+++ b/system/vl.c
@@ -2960,7 +2960,10 @@ void qemu_init(int argc, char **argv)
                           HD_OPTS);
                 break;
             case QEMU_OPTION_blockdev:
-                {
+                if (is_help_option(optarg)) {
+                    bdrv_show_help();
+                    exit(EXIT_SUCCESS);
+                } else {
                     Visitor *v;
                     BlockdevOptionsQueueEntry *bdo;
 
@@ -2973,8 +2976,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 v2] block: Print simple help text when calling "-blockdev help"

[Thomas Huth]

On 14/09/2026 11.00, Thomas Huth wrote:
> 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. Thus let's improve this situation by providing
> a proper list of available drivers when running QEMU with
> "-blockdev help".
> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>   v2: Don't re-use the code from "-drive format=help" and print the
>       help in a better readable way instead

Ping?

>   include/block/block-common.h |  1 +
>   block.c                      | 15 +++++++++++++++
>   system/vl.c                  |  7 +++++--
>   3 files changed, 21 insertions(+), 2 deletions(-)
> 
> diff --git a/include/block/block-common.h b/include/block/block-common.h
> index 895ea175413..c76a72c1220 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 bdrv_show_help(void);
>   
>   #endif /* BLOCK_COMMON_H */
> diff --git a/block.c b/block.c
> index f0a6042e616..895d6db5acf 100644
> --- a/block.c
> +++ b/block.c
> @@ -524,6 +524,21 @@ bool bdrv_uses_whitelist(void)
>       return use_bdrv_whitelist;
>   }
>   
> +static void bdrv_help_format_print(void *opaque, const char *name)
> +{
> +    if (bdrv_format_is_whitelisted(name, false)) {
> +        printf("%s\n", name);
> +    } else {
> +        printf("%s (read-only)\n", name);
> +    }
> +}
> +
> +void bdrv_show_help(void)
> +{
> +      printf("Available blockdev drivers:\n");
> +      bdrv_iterate_format(bdrv_help_format_print, NULL, true);
> +}
> +
>   typedef struct CreateCo {
>       BlockDriver *drv;
>       char *filename;
> diff --git a/system/vl.c b/system/vl.c
> index 9bd7664b85c..dc93e8737cb 100644
> --- a/system/vl.c
> +++ b/system/vl.c
> @@ -2960,7 +2960,10 @@ void qemu_init(int argc, char **argv)
>                             HD_OPTS);
>                   break;
>               case QEMU_OPTION_blockdev:
> -                {
> +                if (is_help_option(optarg)) {
> +                    bdrv_show_help();
> +                    exit(EXIT_SUCCESS);
> +                } else {
>                       Visitor *v;
>                       BlockdevOptionsQueueEntry *bdo;
>   
> @@ -2973,8 +2976,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)) {

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

[Eric Blake]

On Mon, Sep 14, 2026 at 11:00:36AM +0200, Thomas Huth wrote:
> 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. Thus let's improve this situation by providing
> a proper list of available drivers when running QEMU with
> "-blockdev help".
> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  v2: Don't re-use the code from "-drive format=help" and print the
>      help in a better readable way instead

One format per line rather than space-separated does seem a bit more
machine-parseable, although the output no longer fits in my preferred
terminal size without scrolling. I guess "more readable" is subjective
;)

> 
>  include/block/block-common.h |  1 +
>  block.c                      | 15 +++++++++++++++
>  system/vl.c                  |  7 +++++--
>  3 files changed, 21 insertions(+), 2 deletions(-)

Reviewed-by: Eric Blake <eblake@redhat.com>
Tested-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

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

[Eric Blake]

On Wed, Oct 21, 2026 at 08:34:20AM -0500, Eric Blake wrote:
> On Mon, Sep 14, 2026 at 11:00:36AM +0200, Thomas Huth wrote:
> > 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. Thus let's improve this situation by providing
> > a proper list of available drivers when running QEMU with
> > "-blockdev help".
> > 
> > Signed-off-by: Thomas Huth <thuth@redhat.com>
> > ---
> >  v2: Don't re-use the code from "-drive format=help" and print the
> >      help in a better readable way instead
> 
> One format per line rather than space-separated does seem a bit more
> machine-parseable, although the output no longer fits in my preferred
> terminal size without scrolling. I guess "more readable" is subjective
> ;)

That said, we aren't very consistent; "-chardev help" indents each
line by two, while "-netdev help" and this patch for "-blockdev help"
does not indent.  May be worth a followup patch.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

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

[Kevin Wolf]

Am 14.09.2026 um 11:00 hat Thomas Huth geschrieben:
> 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. Thus let's improve this situation by providing
> a proper list of available drivers when running QEMU with
> "-blockdev help".
> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>

Thanks, applied to the block branch.

Kevin