Re: [PATCH] docs/qdev-device-use: Clean up the sentences related to -usbdevice

[Markus Armbruster]

Thomas Huth <thuth@redhat.com> writes:

> Most of the -usbdevice paramaters have been removed already. Update
> the doc accordingly.
>
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  docs/qdev-device-use.txt | 28 +++-------------------------
>  1 file changed, 3 insertions(+), 25 deletions(-)
>
> diff --git a/docs/qdev-device-use.txt b/docs/qdev-device-use.txt
> index 4bbbcf561f..f8d0d2fe29 100644
> --- a/docs/qdev-device-use.txt
> +++ b/docs/qdev-device-use.txt
> @@ -125,12 +125,7 @@ The -device argument differs in detail for each
> 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.
[...]
>  
>  * 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
>  

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

> @@ -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.

>  * -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:
>  
>      -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.

> @@ -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:
>  
>      -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.

   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 *.

>  
>  === Default Devices ===

Since v2.12.0 was more than two years ago, keeping information on the
old way may be no longer useful.