[RFC PATCH] qemu-options: try and clarify preferred block semantics

[RFC PATCH] qemu-options: try and clarify preferred block semantics

[Alex Bennée]

Try to correct any confusion about QEMU's Byzantine disk options by
laying out the preferred "modern" options as-per:

 "<danpb> (best:  -device + -blockdev,  2nd obsolete syntax: -device +
     -drive,  3rd obsolete syntax: -drive, 4th obsolete syntax: -hdNN)"

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: qemu-block@nongnu.org
Cc: Kevin Wolf <kwolf@redhat.com>
Cc: Hanna Reitz <hreitz@redhat.com>
Cc: Daniel P. Berrange <berrange@redhat.com>
Cc: Thomas Huth <thuth@redhat.com>
---
 qemu-options.hx | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index 3f23a42fa8..d57239d364 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1105,6 +1105,19 @@ DEFHEADING()
 
 DEFHEADING(Block device options:)
 
+SRST
+The QEMU block device handling options have a long history and
+have gone through several iterations as the feature set and complexity
+of the block layer have grown. Many online guides to QEMU often
+reference older and deprecated options which can lead to confusion.
+
+The recommended modern way to describe disks is to use combination of
+``-device`` to specify the hardware device and ``-blockdev`` to
+describe the backend. The device defines what the guest sees and the
+backend describes how QEMU handles the data.
+
+ERST
+
 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
     "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
-- 
2.30.2

Re: [RFC PATCH] qemu-options: try and clarify preferred block semantics

[Kevin Wolf]

Am 19.08.2022 um 19:47 hat Alex Bennée geschrieben:
> Try to correct any confusion about QEMU's Byzantine disk options by
> laying out the preferred "modern" options as-per:
> 
>  "<danpb> (best:  -device + -blockdev,  2nd obsolete syntax: -device +
>      -drive,  3rd obsolete syntax: -drive, 4th obsolete syntax: -hdNN)"
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: qemu-block@nongnu.org
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Hanna Reitz <hreitz@redhat.com>
> Cc: Daniel P. Berrange <berrange@redhat.com>
> Cc: Thomas Huth <thuth@redhat.com>

Acked-by: Kevin Wolf <kwolf@redhat.com>

Re: [RFC PATCH] qemu-options: try and clarify preferred block semantics

[Daniel P. Berrangé]

On Fri, Aug 19, 2022 at 06:47:57PM +0100, Alex Bennée wrote:
> Try to correct any confusion about QEMU's Byzantine disk options by
> laying out the preferred "modern" options as-per:
> 
>  "<danpb> (best:  -device + -blockdev,  2nd obsolete syntax: -device +
>      -drive,  3rd obsolete syntax: -drive, 4th obsolete syntax: -hdNN)"

Hmm, i guess my numbering of obsolete syntaxes was off-by-1  as
I missed a "1st obsolete syntax" :-)

> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: qemu-block@nongnu.org
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Hanna Reitz <hreitz@redhat.com>
> Cc: Daniel P. Berrange <berrange@redhat.com>
> Cc: Thomas Huth <thuth@redhat.com>
> ---
>  qemu-options.hx | 13 +++++++++++++
>  1 file changed, 13 insertions(+)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [RFC PATCH] qemu-options: try and clarify preferred block semantics

[Peter Maydell]

On Fri, 19 Aug 2022 at 19:10, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> Try to correct any confusion about QEMU's Byzantine disk options by
> laying out the preferred "modern" options as-per:
>
>  "<danpb> (best:  -device + -blockdev,  2nd obsolete syntax: -device +
>      -drive,  3rd obsolete syntax: -drive, 4th obsolete syntax: -hdNN)"
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: qemu-block@nongnu.org
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Hanna Reitz <hreitz@redhat.com>
> Cc: Daniel P. Berrange <berrange@redhat.com>
> Cc: Thomas Huth <thuth@redhat.com>
> ---
>  qemu-options.hx | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 3f23a42fa8..d57239d364 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1105,6 +1105,19 @@ DEFHEADING()
>
>  DEFHEADING(Block device options:)
>
> +SRST
> +The QEMU block device handling options have a long history and
> +have gone through several iterations as the feature set and complexity
> +of the block layer have grown. Many online guides to QEMU often
> +reference older and deprecated options which can lead to confusion.

"options, "

> +
> +The recommended modern way to describe disks is to use combination of

"a combination"

> +``-device`` to specify the hardware device and ``-blockdev`` to
> +describe the backend. The device defines what the guest sees and the
> +backend describes how QEMU handles the data.

thanks
-- PMM