docs/qdev-device-use: Clean up the sentences related to -usbdevice
PATCH 1/1 docs/qdev-device-use: Clean up the sentences related to -usbdevice
Most of the -usbdevice paramaters have been removed already. Update the doc accordingly.
--- docs/qdev-device-use.txt | 28 +++------------------------- 1 file changed, 3 insertions(+), 25 deletions(-)
docs/qdev-device-use.txt +3 -25
@@ -125,12 +125,7 @@ The -device argument differs in detail for each type of drive: * if=pflash, if=mtd, if=sd, if=xen are not yet available with -device -For USB devices, the old way is actually different: - - -usbdevice disk:format=FMT:FILENAME - -Provides much less control than -drive's OPTS... The new way fixes -that: +For USB storage devices, you can use something like: -device usb-storage,drive=DRIVE-ID,removable=RMB
@@ -177,8 +172,6 @@ The appropriate DEVNAME depends on the machine type. For type "pc": This lets you control I/O ports and IRQs. -* -usbdevice serial::chardev becomes -device usb-serial,chardev=dev. - * -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always uses "braille". With -device, this useful default is gone, so you have to use something like
@@ -238,10 +231,6 @@ The old way to define the guest part looks like this: -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V -Except for USB it looks like this: - - -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID - The new way is -device: -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
@@ -336,12 +325,7 @@ The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: * mouse -device usb-mouse * tablet -device usb-tablet * wacom-tablet -device usb-wacom-tablet -* host:... See "Host Device Assignment" -* disk:... See "Block Devices" -* serial:... See "Character Devices" * braille See "Character Devices" -* net:... See "Network Devices" -* bt:... not yet available with -device === Watchdog Devices ===
@@ -358,17 +342,11 @@ and host USB devices. PCI devices can only be assigned with -device: -device vfio-pci,host=ADDR,id=ID -The old way to assign a host USB device is - - -usbdevice host:auto:BUS.ADDR:VID:PRID - -where any of BUS, ADDR, VID, PRID can be the wildcard *. - -The new way is +To assign a host USB device use: -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID -Omitted options match anything, just like the old way's wildcard. +Omitted options match anything. === Default Devices ===
Signature · 1 line
2.18.1
Quoted 2 lines · Thomas Huth
Most of the -usbdevice paramaters have been removed already. Update the doc accordingly.
Queued up for 5.1
thanks,
Gerd
Quoted 13 lines · Thomas Huth
Most of the -usbdevice paramaters have been removed already. Update the doc accordingly.
Signed-off-by Thomas Huth <[email protected]>--- docs/qdev-device-use.txt | 28 +++------------------------- 1 file changed, 3 insertions(+), 25 deletions(-)docs/qdev-device-use.txt +0
-0@@ -125,12 +125,7 @@ The -device argument differs in detail for each
Quoted 1 line
type of drive:
Additional context:
The various old ways to define drives all boil down to the common form
-drive if=TYPE,bus=BUS,unit=UNIT,OPTS...
TYPE, BUS and UNIT identify the controller device, which of its buses to use, and the drive's address on that bus. Details depend on TYPE.
[...]
docs/qdev-device-use.txt The -device argument differs in detail for each type of drive: · line 130
Quoted 13 lines
* if=pflash, if=mtd, if=sd, if=xen are not yet available with -device
docs/qdev-device-use.txt +1
-6-For USB devices, the old way is actually different: - - -usbdevice disk:format=FMT:FILENAME - -Provides much less control than -drive's OPTS... The new way fixes -that: +For USB storage devices, you can use something like: -device usb-storage,drive=DRIVE-ID,removable=RMB
Losing "the old way is actually different" makes "The various old ways to define drives all boil down to the common form" apply to USB. Misleading.
We could choose to keep information on the old way, like this:
For USB devices, the old way was actually different:
-usbdevice disk:format=FMT:FILENAME
"Was" because "disk:" is gone since v2.12.0.
The old way provided much less control than -drive's OPTS... The new way fixes that:
-device usb-storage,drive=DRIVE-ID,removable=RMB
If we prefer not to, then perhaps:
For USB devices, the old way was actually different, and is long gone. The new way looks like
-device usb-storage,drive=DRIVE-ID,removable=RMB
docs/qdev-device-use.txt The appropriate DEVNAME depends on the machine type. For type "pc": · line 181
Quoted 6 lines
docs/qdev-device-use.txt +0
-2@@ -177,8 +172,6 @@ The appropriate DEVNAME depends on the machine type. For type "pc": This lets you control I/O ports and IRQs. -* -usbdevice serial::chardev becomes -device usb-serial,chardev=dev. -
If we choose to keep information on old ways, we could
* -usbdevice serial::chardev is gone since v2.12.0. It became -device usb-serial,chardev=dev.
Else:
* Use -device usb-serial,chardev=dev for USB serial devices. The old way is long gone.
docs/qdev-device-use.txt The old way to define the guest part looks like this:
Quoted 4 lines
docs/qdev-device-use.txt +0
-0* -usbdevice braille doesn't support LEGACY-CHARDEV syntax. It always uses "braille". With -device, this useful default is gone, so you have to use something like@@ -238,10 +231,6 @@ The old way to define the guest part looks like this:
Additional context:
=== Network Devices ===
Host and guest part of network devices have always been separate.
The old way to define the guest part looks like this:
docs/qdev-device-use.txt The old way to define the guest part looks like this: · line 236
Quoted 10 lines
docs/qdev-device-use.txt +0
-4-net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V -Except for USB it looks like this: - - -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID - The new way is -device: -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
As for block devices, this now reads as if USB was the same as all the others, which is misleading.
If keep, then perhaps:
Except for USB it looked like this:
-usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID
"Looked" because "net:" is gone since v2.12.0.
If not:
For USB devices, the old way was actually different, and is long gone.
docs/qdev-device-use.txt and host USB devices. PCI devices can only be assigned with -device:
Quoted 14 lines
docs/qdev-device-use.txt +0
-5@@ -336,12 +325,7 @@ The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: * mouse -device usb-mouse * tablet -device usb-tablet * wacom-tablet -device usb-wacom-tablet -* host:... See "Host Device Assignment" -* disk:... See "Block Devices" -* serial:... See "Character Devices" * braille See "Character Devices" -* net:... See "Network Devices" -* bt:... not yet available with -device === Watchdog Devices ===@@ -358,17 +342,11 @@ and host USB devices. PCI devices can only be assigned with -device:
More context:
=== Host Device Assignment ===
QEMU supports assigning host PCI devices (qemu-kvm only at this time) and host USB devices. PCI devices can only be assigned with -device:
Quoted 6 lines
docs/qdev-device-use.txt +0
-3-device vfio-pci,host=ADDR,id=ID -The old way to assign a host USB device is - - -usbdevice host:auto:BUS.ADDR:VID:PRID
docs/qdev-device-use.txt and host USB devices. PCI devices can only be assigned with -device: · line 349
Quoted 10 lines
docs/qdev-device-use.txt +2
-5- -where any of BUS, ADDR, VID, PRID can be the wildcard *. - -The new way is +To assign a host USB device use: -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID -Omitted options match anything, just like the old way's wildcard. +Omitted options match anything.
QEMU supports assigning host PCI devices (qemu-kvm only at this time) and host USB devices. They can only be assigned with -device.
PCI:
-device vfio-pci,host=ADDR,id=ID
USB:
-device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
Omitted options match anything.
If keep, add something like
The old way to assign a USB host device
-usbdevice host:auto:BUS.ADDR:VID:PRID
was removed in v2.12.0. Any of BUS, ADDR, VID, PRID could be the wildcard *.
docs/qdev-device-use.txt and host USB devices. PCI devices can only be assigned with -device: · line 351
Quoted 2 lines
docs/qdev-device-use.txt +0
-0=== Default Devices ===
Since v2.12.0 was more than two years ago, keeping information on the old way may be no longer useful.
My review came too late, so I turned it into a followup patch:
Subject: [PATCH 3/3] docs/qdev-device-use: Don't suggest -drive and -net can do USB
Message-Id: <[email protected]>