| Message ID | 20230330101141.30199-5-alex.bennee@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | more misc fixes for 8.0 (tests, gdbstub, meta, docs) | expand |
On 30/03/2023 12.11, Alex Bennée wrote: > We are a bit premature in recommending -blockdev/-device as the best > way to configure block devices, especially in the common case. > 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> > --- > qemu-options.hx | 8 ++++++-- > 1 file changed, 6 insertions(+), 2 deletions(-) > > diff --git a/qemu-options.hx b/qemu-options.hx > index 59bdf67a2c..9a69ed838e 100644 > --- a/qemu-options.hx > +++ b/qemu-options.hx > @@ -1143,10 +1143,14 @@ 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. 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`` > +bake in a lot of assumptions from the days when QEMU was emulating a > +legacy PC, they are not recommended for modern configurations. Reviewed-by: Thomas Huth <thuth@redhat.com>
30.03.2023 13:11, Alex Bennée wrote: > We are a bit premature in recommending -blockdev/-device as the best > way to configure block devices, especially in the common case. > 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> > --- > qemu-options.hx | 8 ++++++-- > 1 file changed, 6 insertions(+), 2 deletions(-) > > diff --git a/qemu-options.hx b/qemu-options.hx > index 59bdf67a2c..9a69ed838e 100644 > --- a/qemu-options.hx > +++ b/qemu-options.hx > @@ -1143,10 +1143,14 @@ 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. 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`` > +bake in a lot of assumptions from the days when QEMU was emulating a > +legacy PC, they are not recommended for modern configurations. Reviewed-by: Michael Tokarev <mjt@tls.msk.ru> This is a very welcome change, in my opinion. Thank you Alex! /mjt
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, especially in the common case. > 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> > --- > qemu-options.hx | 8 ++++++-- > 1 file changed, 6 insertions(+), 2 deletions(-) > > diff --git a/qemu-options.hx b/qemu-options.hx > index 59bdf67a2c..9a69ed838e 100644 > --- a/qemu-options.hx > +++ b/qemu-options.hx > @@ -1143,10 +1143,14 @@ 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. The ``-drive`` option > +combines the device and backend into a single command line options > +which is useful in the majority of cases. -drive may look simpler from afar, but it really is a hot mess. Sadly, we can't get rid of it until we find a replacement for configuring onboard block devices. We might be able to clean it up some if we accept compatibility breaks. A new convenience option would be less confusing, I guess. > Older options like ``-hda`` > +bake in a lot of assumptions from the days when QEMU was emulating a > +legacy PC, they are not recommended for modern configurations. > > ERST These older options and the non-option argument are simple macros for -drive: IMG-FILE -drive index=0,file=IMG-FILE,media=disk -hda IMG-FILE -drive index=0,file=IMG-FILE,media=disk -hdb IMG-FILE -drive index=1,file=IMG-FILE,media=disk -hdc IMG-FILE -drive index=2,file=IMG-FILE,media=disk -hdd IMG-FILE -drive index=3,file=IMG-FILE,media=disk -cdrom IMG-FILE -drive index=2,file=IMG-FILE,media=cdrom -fda IMG-FILE -drive if=floppy,index=0,file=IMG-FILE -fdb IMG-FILE -drive if=floppy,index=1,file=IMG-FILE -mtdblock IMG-FILE -drive if=mtd,file=IMG-FILE -sd IMG-FILE -drive if=sd,file=IMG-FILE -pflash IMG-FILE -drive if=pflash,file=IMG-FILE What assumptions do you have in mind? I think you need at least Kevin's Acked-by for this.
Markus Armbruster <armbru@redhat.com> writes: > 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, especially in the common case. >> 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> >> --- >> qemu-options.hx | 8 ++++++-- >> 1 file changed, 6 insertions(+), 2 deletions(-) >> >> diff --git a/qemu-options.hx b/qemu-options.hx >> index 59bdf67a2c..9a69ed838e 100644 >> --- a/qemu-options.hx >> +++ b/qemu-options.hx >> @@ -1143,10 +1143,14 @@ 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. The ``-drive`` option >> +combines the device and backend into a single command line options >> +which is useful in the majority of cases. > > -drive may look simpler from afar, but it really is a hot mess. Sadly, > we can't get rid of it until we find a replacement for configuring > onboard block devices. We might be able to clean it up some if we > accept compatibility breaks. A new convenience option would be less > confusing, I guess. This is only a partial revert of the original wording which others have pointed out was a little too prescriptive. I believe the case of snapshot was one where a pure device/blockdev command line is hard to use. >> Older options like ``-hda`` >> +bake in a lot of assumptions from the days when QEMU was emulating a >> +legacy PC, they are not recommended for modern configurations. >> >> ERST > > These older options and the non-option argument are simple macros for > -drive: > > IMG-FILE -drive index=0,file=IMG-FILE,media=disk > -hda IMG-FILE -drive index=0,file=IMG-FILE,media=disk > -hdb IMG-FILE -drive index=1,file=IMG-FILE,media=disk > -hdc IMG-FILE -drive index=2,file=IMG-FILE,media=disk > -hdd IMG-FILE -drive index=3,file=IMG-FILE,media=disk > -cdrom IMG-FILE -drive index=2,file=IMG-FILE,media=cdrom > -fda IMG-FILE -drive if=floppy,index=0,file=IMG-FILE > -fdb IMG-FILE -drive if=floppy,index=1,file=IMG-FILE > -mtdblock IMG-FILE -drive if=mtd,file=IMG-FILE > -sd IMG-FILE -drive if=sd,file=IMG-FILE > -pflash IMG-FILE -drive if=pflash,file=IMG-FILE > > What assumptions do you have in mind? I was under the impression things like -hda wouldn't work say on an Arm machine because you don't know what sort of interface you might be using and -hda implies IDE. Where is this macro substitution done? > I think you need at least Kevin's Acked-by for this. In the ideal world I could convince the block maintainers to write a new section to the manual that explains the theory behind the block subsystem and how things interact and are put together. Until then this is merely a sticking plaster to make the manual a little more authoritative than then numerous example command lines our users blindly copy from online blog posts. Of course we could* always ask our new AI overlords: 1. `qemu-system-x86_64 -drive file=disk.img,format=raw,if=virtio` In this command, we are running QEMU on an x86_64 CPU architecture and creating a virtual block device using the file `disk.img` as its storage. The format of the file is set to `raw`, which means that it will be accessed directly as a block device. We are using the `virtio` interface to connect the block device to the virtual machine. 2. `qemu-system-x86_64 -drive file=disk.img,format=qcow2,if=virtio` This command is similar to the first one, but the format of the `disk.img` file is set to `qcow2`. This means that the file is a disk image in the QEMU Copy-On-Write format, which allows for more efficient storage of virtual disks. We are still using the `virtio` interface to connect the device to the VM. 3. `qemu-system-x86_64 -drive file=/dev/sda,if=virtio` In this command, we are using a physical block device as the backend for the virtual block device. The device we are using is `/dev/sda`, which is typically the first hard disk on a Linux system. We are still using the `virtio` interface to connect the device to the VM. 4. `qemu-system-x86_64 -device ide-hd,drive=mydrive -drive file=disk.img,format=qcow2,id=mydrive` This command sets up two block devices for the virtual machine. The first device is connected using the `ide-hd` device type, and is connected to a virtual drive called `mydrive`. The second device is a `qcow2` disk image file, also using the virtual drive `mydrive`. The `id` property on the second command tells QEMU to use the virtual drive with the identifier `mydrive` as the backend for this block device. The differences between these commands lie in the backend layout of the virtual devices. In the first two commands, we are using file-based storage for the devices, with different formats. In the third command, we are using a physical block device as the backend. In the fourth command, we are using a combination of virtual and file-based storage, with virtual drives connected to individual devices. The choice of backend layout will depend on the specific requirements of the virtual machine and its workload. 5. `qemu-system-arm -machine virt,gic-version=3 -cpu cortex-a57 -drive file=disk1.qcow2,if=none,id=drive0 -device virtio-blk-device,drive=drive0 -blockdev node-name=my-snapshot,driver=qcow2,file=snapshot.qcow2,backing=drive0 -device virtio-blk-device,drive=my-snapshot` In this command, we are using an "ARM virtual machine" and creating a block device using `disk1.qcow2` file as its storage with `if=none` parameter to not attach it directly to the device. Then, we create a virtual device of `virtio-blk-device` type and connecting `drive0` to it using the `-device` option. Next, we are creating a new block device named `my-snapshot` with the `qcow2` driver using `-blockdev` and specifying `file=snapshot.qcow2` as its storage. We are also specifying `backing=drive0`, which means the new block device is a snapshot of `drive0`. Finally, we are creating another virtual device of `virtio-blk-device` type and connecting `my-snapshot` to it using the `-device` option. This command creates a snapshot of the original `disk1.qcow2` image, which allows us to create clones of the original disk that are based on different points in time. 6. `qemu-system-ppc64 -M pseries -drive file=disk1.raw,if=none,id=drive0 -blockdev node-name=my-backup,driver=file,cache.direct=on,cache.no-flush=off,filename=backup.raw -blockdev node-name=my-snapshot,driver=qcow2,file=snapshot.qcow2,backing=my-backup -device virtio-blk-device,drive=my-snapshot` In this command, we are using a "PowerPC64 virtual machine" machine type and creating a block device using `disk1.raw` as its storage with `if=none` parameter to not attach it directly to the device. Next, we are creating a backup block device using the `file` driver, and set `cache.direct` to `on` and `cache.no-flush` to `off`, which means that the write operations will go directly to the `backup.raw` image file and reduces the risk of data loss. Then, we create a new block device named `my-snapshot` with the `qcow2` driver using `-blockdev` and specifying `file=snapshot.qcow2` as its storage. We are also specifying `backing=my-backup`, which means the new block device is a snapshot of `my-backup`. Finally, we are creating a virtual device of `virtio-blk-device` type and connecting `my-snapshot` to it using the `-device` option. This command creates a snapshot of the `my-backup` block device, which can be used to recover data if the original disk becomes corrupted or lost. The `cache` options are used to ensure that write operations are written directly to the backup file, rather than being buffered in memory and potentially lost in the event of a system crash. But even these stochastic parrots gloss over the meaning of such vagaries as if=none. * just because we could doesn't mean we should
Alex Bennée <alex.bennee@linaro.org> writes: > Markus Armbruster <armbru@redhat.com> writes: > >> 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, especially in the common case. >>> 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> >>> --- >>> qemu-options.hx | 8 ++++++-- >>> 1 file changed, 6 insertions(+), 2 deletions(-) >>> >>> diff --git a/qemu-options.hx b/qemu-options.hx >>> index 59bdf67a2c..9a69ed838e 100644 >>> --- a/qemu-options.hx >>> +++ b/qemu-options.hx >>> @@ -1143,10 +1143,14 @@ 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. The ``-drive`` option >>> +combines the device and backend into a single command line options >>> +which is useful in the majority of cases. >> >> -drive may look simpler from afar, but it really is a hot mess. Sadly, >> we can't get rid of it until we find a replacement for configuring >> onboard block devices. We might be able to clean it up some if we >> accept compatibility breaks. A new convenience option would be less >> confusing, I guess. > > This is only a partial revert of the original wording which others have > pointed out was a little too prescriptive. I believe the case of > snapshot was one where a pure device/blockdev command line is hard to > use. > >>> Older options like ``-hda`` >>> +bake in a lot of assumptions from the days when QEMU was emulating a >>> +legacy PC, they are not recommended for modern configurations. >>> >>> ERST >> >> These older options and the non-option argument are simple macros for >> -drive: >> >> IMG-FILE -drive index=0,file=IMG-FILE,media=disk >> -hda IMG-FILE -drive index=0,file=IMG-FILE,media=disk >> -hdb IMG-FILE -drive index=1,file=IMG-FILE,media=disk >> -hdc IMG-FILE -drive index=2,file=IMG-FILE,media=disk >> -hdd IMG-FILE -drive index=3,file=IMG-FILE,media=disk >> -cdrom IMG-FILE -drive index=2,file=IMG-FILE,media=cdrom >> -fda IMG-FILE -drive if=floppy,index=0,file=IMG-FILE >> -fdb IMG-FILE -drive if=floppy,index=1,file=IMG-FILE >> -mtdblock IMG-FILE -drive if=mtd,file=IMG-FILE >> -sd IMG-FILE -drive if=sd,file=IMG-FILE >> -pflash IMG-FILE -drive if=pflash,file=IMG-FILE >> >> What assumptions do you have in mind? > > I was under the impression things like -hda wouldn't work say on an Arm > machine because you don't know what sort of interface you might be > using and -hda implies IDE. Where is this macro substitution done? qemu_init() calls drive_add() for all these options. drive_add(TYPE, INDEX, FILE, OPTSTR) creates a QemuOpts in group "drive". It sets "if" to if_name[TYPE] unless TYPE is IF_DEFAULT, "index" to INDEX unless it's negative, and "file" to FILE unless it's null. Then it parses OPTSTR on top. For -hdX, the call looks like drive_add(IF_DEFAULT, popt->index - QEMU_OPTION_hda, optarg, HD_OPTS); We pass IF_DEFAULT, so "if" remains unset. "index" is set to 0 for -hda, 1, for -hdb and so forth. "file" is set to the option argument. Since HD_OPTS is "media=disk", we set "media" to "disk". The QemuOpts in config group "drive" get passed to drive_new() via drive_init_func(). Unset "if" defaults to the current machine's class's block_default_type. If a machine doesn't set this member explicitly, it remains zero, which is IF_NONE. Documented in blockdev.h: typedef enum { IF_DEFAULT = -1, /* for use with drive_add() only */ /* * IF_NONE must be zero, because we want MachineClass member ---> * block_default_type to default-initialize to IF_NONE */ IF_NONE = 0, IF_IDE, IF_SCSI, IF_FLOPPY, IF_PFLASH, IF_MTD, IF_SD, IF_VIRTIO, IF_XEN, IF_COUNT } BlockInterfaceType; Questions? >> I think you need at least Kevin's Acked-by for this. > > In the ideal world I could convince the block maintainers to write a new > section to the manual that explains the theory behind the block > subsystem and how things interact and are put together. Until then this > is merely a sticking plaster to make the manual a little more > authoritative than then numerous example command lines our users blindly > copy from online blog posts. > > Of course we could* always ask our new AI overlords: > [...] > * just because we could doesn't mean we should Heh!
On 03/04/2023 16.55, Markus Armbruster wrote: > Alex Bennée <alex.bennee@linaro.org> writes: > >> Markus Armbruster <armbru@redhat.com> writes: >> >>> Alex Bennée <alex.bennee@linaro.org> writes: ... >> I was under the impression things like -hda wouldn't work say on an Arm >> machine because you don't know what sort of interface you might be >> using and -hda implies IDE. Where is this macro substitution done? > > qemu_init() calls drive_add() for all these options. > > drive_add(TYPE, INDEX, FILE, OPTSTR) creates a QemuOpts in group > "drive". It sets "if" to if_name[TYPE] unless TYPE is IF_DEFAULT, > "index" to INDEX unless it's negative, and "file" to FILE unless it's > null. Then it parses OPTSTR on top. > > For -hdX, the call looks like > > drive_add(IF_DEFAULT, popt->index - QEMU_OPTION_hda, optarg, > HD_OPTS); > > We pass IF_DEFAULT, so "if" remains unset. "index" is set to 0 for > -hda, 1, for -hdb and so forth. "file" is set to the option argument. > Since HD_OPTS is "media=disk", we set "media" to "disk". > > The QemuOpts in config group "drive" get passed to drive_new() via > drive_init_func(). Unset "if" defaults to the current machine's class's > block_default_type. > > If a machine doesn't set this member explicitly, it remains zero, which > is IF_NONE. Documented in blockdev.h: > > typedef enum { > IF_DEFAULT = -1, /* for use with drive_add() only */ > /* > * IF_NONE must be zero, because we want MachineClass member > ---> * block_default_type to default-initialize to IF_NONE > */ > IF_NONE = 0, > IF_IDE, IF_SCSI, IF_FLOPPY, IF_PFLASH, IF_MTD, IF_SD, IF_VIRTIO, IF_XEN, > IF_COUNT > } BlockInterfaceType; > > Questions? How's the average user supposed to know that? Our qemu-options.hx just says: "-hda/-hdb file use 'file' as IDE hard disk 0/1 image"... Thomas
Thomas Huth <thuth@redhat.com> writes: > On 03/04/2023 16.55, Markus Armbruster wrote: >> Alex Bennée <alex.bennee@linaro.org> writes: >> >>> Markus Armbruster <armbru@redhat.com> writes: >>> >>>> Alex Bennée <alex.bennee@linaro.org> writes: > ... >>> I was under the impression things like -hda wouldn't work say on an Arm >>> machine because you don't know what sort of interface you might be >>> using and -hda implies IDE. Where is this macro substitution done? >> >> qemu_init() calls drive_add() for all these options. >> >> drive_add(TYPE, INDEX, FILE, OPTSTR) creates a QemuOpts in group >> "drive". It sets "if" to if_name[TYPE] unless TYPE is IF_DEFAULT, >> "index" to INDEX unless it's negative, and "file" to FILE unless it's >> null. Then it parses OPTSTR on top. >> >> For -hdX, the call looks like >> >> drive_add(IF_DEFAULT, popt->index - QEMU_OPTION_hda, optarg, >> HD_OPTS); >> >> We pass IF_DEFAULT, so "if" remains unset. "index" is set to 0 for >> -hda, 1, for -hdb and so forth. "file" is set to the option argument. >> Since HD_OPTS is "media=disk", we set "media" to "disk". >> >> The QemuOpts in config group "drive" get passed to drive_new() via >> drive_init_func(). Unset "if" defaults to the current machine's class's >> block_default_type. >> >> If a machine doesn't set this member explicitly, it remains zero, which >> is IF_NONE. Documented in blockdev.h: >> >> typedef enum { >> IF_DEFAULT = -1, /* for use with drive_add() only */ >> /* >> * IF_NONE must be zero, because we want MachineClass member >> ---> * block_default_type to default-initialize to IF_NONE >> */ >> IF_NONE = 0, >> IF_IDE, IF_SCSI, IF_FLOPPY, IF_PFLASH, IF_MTD, IF_SD, IF_VIRTIO, IF_XEN, >> IF_COUNT >> } BlockInterfaceType; >> >> Questions? > > How's the average user supposed to know that? Our qemu-options.hx just says: > "-hda/-hdb file use 'file' as IDE hard disk 0/1 image"... Ancient doc bug. Should have been updated in commit 2d0d2837dcf (Support default block interfaces per QEMUMachine) back in 2012.
diff --git a/qemu-options.hx b/qemu-options.hx index 59bdf67a2c..9a69ed838e 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -1143,10 +1143,14 @@ 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. 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`` +bake in a lot of assumptions from the days when QEMU was emulating a +legacy PC, they are not recommended for modern configurations. ERST
We are a bit premature in recommending -blockdev/-device as the best way to configure block devices, especially in the common case. 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> --- qemu-options.hx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-)