Alex Bennée <alex.ben...@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 <m...@tls.msk.ru>
> Signed-off-by: Alex Bennée <alex.ben...@linaro.org>
> Reviewed-by: Thomas Huth <th...@redhat.com>
> Cc: Markus Armbruster <arm...@redhat.com>
> Cc: Kevin Wolf <kw...@redhat.com>
> Message-Id: <20230330101141.30199-5-alex.ben...@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?
