Markus Armbruster <arm...@redhat.com> writes:
> 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, especially in the common case. >> 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> >> --- >> 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 Virtualisation Tech Lead @ Linaro