@@ -1140,10 +1140,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
@@ -1636,6 +1648,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,