Re: [PATCH v3] qemu-options: finesse the recommendations around -blockdev

[Markus Armbruster]

Alex Bennée <alex.bennee@linaro.org> writes:

> We are a bit premature in recommending -blockdev/-device as the best
> way to configure block devices. It seems there are times the more
> human friendly -drive still makes sense especially when -snapshot is
> involved.
>
> Improve the language to hopefully make things clearer.
>
> Suggested-by: Michael Tokarev <mjt@tls.msk.ru>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Reviewed-by: Thomas Huth <thuth@redhat.com>
> Cc: Markus Armbruster <armbru@redhat.com>
> Cc: Kevin Wolf <kwolf@redhat.com>
> Message-Id: <20230330101141.30199-5-alex.bennee@linaro.org>
>
> ---
> v3
>   - more re-wording to try and approach consensus
>   - add explicit warning to -snapshot option
> ---
>  qemu-options.hx | 24 ++++++++++++++++++++++--
>  1 file changed, 22 insertions(+), 2 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 59bdf67a2c..4b8855a4f7 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1143,10 +1143,22 @@ 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 a combination of
> +The most explicit way to describe disks is to use a 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.
> +backend describes how QEMU handles the data. It is the only guaranteed
> +stable interface for describing block devices and as such is
> +recommended for management tools and scripting.
> +
> +The ``-drive`` option combines the device and backend into a single
> +command line option which is a more human friendly. There is however no
> +interface stability guarantee although some older board models still
> +need updating to work with the modern blockdev forms.
> +
> +Older options like ``-hda`` are essentially macros which expand into
> +``-drive`` options for various drive interfaces. The original forms
> +bake in a lot of assumptions from the days when QEMU was emulating a
> +legacy PC, they are not recommended for modern configurations.
>  
>  ERST
>  
> @@ -1639,6 +1651,14 @@ SRST
>      the raw disk image you use is not written back. You can however
>      force the write back by pressing C-a s (see the :ref:`disk images`
>      chapter in the System Emulation Users Guide).
> +
> +    .. warning::
> +       snapshot is incompatible with ``-blockdev`` (instead use qemu-img
> +       to manually create snapshot images to attach to your blockdev).
> +       If you have mixed ``-blockdev`` and ``-drive`` declarations you
> +       can use the 'snapshot' property on your drive declarations
> +       instead of this global option.
> +
>  ERST
>  
>  DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,

Works for me.  Kevin, what do you think?

Should QEMU warn when -snapshot and -blockdev are used together?