[PATCH] doc: do not recommend -blockdev

[PATCH] doc: do not recommend -blockdev

[Michael Tokarev]

Currently, documentation recommends to use -blockdev instead of -drive.
This is quite a bit misleading, because -blockdev is "too" low-level,
requires good knowlege of how to construct block device stack, esp.
in context of various qcow2 layers, and requires too explicit configuration.
More, quite some constructs does not work with -blockdev, - for example
this is -snapshot.

Instead of "recommended" word, use another construct here.

Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
---
 qemu-options.hx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 59bdf67a2c..8fe31b465d 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1143,7 +1143,7 @@ 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 low-level detailed 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.
-- 
2.30.2

Re: [PATCH] doc: do not recommend -blockdev

[Alex Bennée]

Michael Tokarev <mjt@tls.msk.ru> writes:

> Currently, documentation recommends to use -blockdev instead of -drive.
> This is quite a bit misleading, because -blockdev is "too" low-level,
> requires good knowlege of how to construct block device stack, esp.
> in context of various qcow2 layers, and requires too explicit configuration.
> More, quite some constructs does not work with -blockdev, - for example
> this is -snapshot.
>
> Instead of "recommended" word, use another construct here.

Could we expand the images section:

  https://qemu.readthedocs.io/en/latest/system/images.html

to give a better overview of when you should use -device/-blockdev vs -drive?

>
> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
> ---
>  qemu-options.hx | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 59bdf67a2c..8fe31b465d 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1143,7 +1143,7 @@ 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 low-level detailed 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.

How about:

  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. The ``--drive`` option
  combines the device and backend into a single command line options which
  is useful in the majority of cases. Older options like ``-hda`` make a
  bake in a lot of assumptions from the days when QEMU was emulating a
  legacy PC, they are not recommended for modern configurations.

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH] doc: do not recommend -blockdev

[Michael Tokarev]

18.03.2023 15:32, Alex Bennée пишет:
..

> Could we expand the images section:
> 
>    https://qemu.readthedocs.io/en/latest/system/images.html
> 
> to give a better overview of when you should use -device/-blockdev vs -drive?

Probably. It's not really about image formats but this info should be
somewhere anyway.  It's a separate step though.

>> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
>> ---
>>   qemu-options.hx | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index 59bdf67a2c..8fe31b465d 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -1143,7 +1143,7 @@ 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 low-level detailed 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.
> 
> How about:
> 
>    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. The ``--drive`` option
>    combines the device and backend into a single command line options which
>    is useful in the majority of cases. Older options like ``-hda`` make a
>    bake in a lot of assumptions from the days when QEMU was emulating a
>    legacy PC, they are not recommended for modern configurations.

This is much better indeed (with one exception, the double-dash in --drive
isn't usual). Would you like to send it as an actual patch?

Thanks!

/mjt