Skip to contentSkip to conversation

docs/qdev-device-use: Clean up the sentences related to -usbdevice

PATCH In review Thomas Huth 3 participants 4 messages Jul 10, 2020 – Aug 6, 2020

lore
Share & tools
lore
#0 lore raw

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
index 4bbbcf561f..f8d0d2fe29 100644
@@ -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
#1 lore raw
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

#2 lore raw
In reply to Thomas Huth
Quoted 13 lines · Thomas Huth

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 +0 -0
index 4bbbcf561f..f8d0d2fe29 100644
@@ -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.

#3 lore raw

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]>