diff mbox

[v2] qemu-doc: Update to use the new way of attaching USB devices

Message ID 1493977087-26668-1-git-send-email-thuth@redhat.com
State New
Headers show

Commit Message

Thomas Huth May 5, 2017, 9:38 a.m. UTC
The preferred way of adding USB devices is via "-device" and
"device_add" nowadays, so let's start to get rid of "-usbdevice"
and "usb_add" in the documentation. While we're at it, also
add the new USB devices there which have been added to QEMU
during the last years.

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 v2:
 - Addressed review feedback from Markus
 - Added the new USB devices that are only available via "-device"
 - Update qdev-device-use.txt about "vendorid" and "productid"

 docs/qdev-device-use.txt |  5 +--
 qemu-doc.texi            | 92 +++++++++++++++++++++++++++---------------------
 2 files changed, 55 insertions(+), 42 deletions(-)

Comments

Markus Armbruster May 5, 2017, 11:54 a.m. UTC | #1
Thomas Huth <thuth@redhat.com> writes:

> The preferred way of adding USB devices is via "-device" and
> "device_add" nowadays, so let's start to get rid of "-usbdevice"
> and "usb_add" in the documentation. While we're at it, also
> add the new USB devices there which have been added to QEMU
> during the last years.
>
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  v2:
>  - Addressed review feedback from Markus
>  - Added the new USB devices that are only available via "-device"
>  - Update qdev-device-use.txt about "vendorid" and "productid"
>
>  docs/qdev-device-use.txt |  5 +--
>  qemu-doc.texi            | 92 +++++++++++++++++++++++++++---------------------
>  2 files changed, 55 insertions(+), 42 deletions(-)
>
> diff --git a/docs/qdev-device-use.txt b/docs/qdev-device-use.txt
> index b059405..2c1331b 100644
> --- a/docs/qdev-device-use.txt
> +++ b/docs/qdev-device-use.txt
> @@ -182,8 +182,9 @@ The appropriate DEVNAME depends on the machine type.  For type "pc":
>  
>    This lets you control I/O ports and IRQs.
>  
> -* -usbdevice serial:vendorid=VID,productid=PRID becomes
> -  -device usb-serial,vendorid=VID,productid=PRID
> +* -usbdevice serial:[vendorid=VID,productid=PRID]:chardev becomes
> +  -device usb-serial,chardev=dev.  The possibility to set a vendor
> +  and product ID has been removed since QEMU version 0.14.0.

If we intend to fix -usbdevice serial:VID,PRID, the hunk should be
dropped.

If we don't intend to fix it, I'd simple delete the old crap that
doesn't work anymore:

   * -usbdevice serial::chardev becomes -device usb-serial,chardev=dev.

As far as I can tell, we don't intend to fix it.

>  * -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
>    uses "braille".  With -device, this useful default is gone, so you
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 794ab4a..b446ac4 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -182,7 +182,7 @@ Gravis Ultrasound GF1 sound card
>  @item
>  CS4231A compatible sound card
>  @item
> -PCI UHCI USB controller and a virtual USB hub.
> +PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
>  @end itemize
>  
>  SMP is supported with up to 255 CPUs.
> @@ -1357,10 +1357,10 @@ monitor (@pxref{pcsys_keys}).
>  @node pcsys_usb
>  @section USB emulation
>  
> -QEMU emulates a PCI UHCI USB controller. You can virtually plug
> -virtual USB devices or real host USB devices (experimental, works only
> -on Linux hosts).  QEMU will automatically create and connect virtual USB hubs
> -as necessary to connect multiple USB devices.
> +QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
> +plug virtual USB devices or real host USB devices (only works with certain
> +host operating systems). QEMU will automatically create and connect virtual
> +USB hubs as necessary to connect multiple USB devices.
>  
>  @menu
>  * usb_devices::
> @@ -1369,53 +1369,65 @@ as necessary to connect multiple USB devices.
>  @node usb_devices
>  @subsection Connecting USB devices
>  
> -USB devices can be connected with the @option{-usbdevice} commandline option
> -or the @code{usb_add} monitor command.  Available devices are:
> +USB devices can be connected with the @option{-device usb-...} command line
> +option or the @code{device_add} monitor command. Available devices are:
>  
>  @table @code
> -@item mouse
> +@item usb-mouse
>  Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
> -@item tablet
> +@item usb-tablet
>  Pointer device that uses absolute coordinates (like a touchscreen).
>  This means QEMU is able to report the mouse position without having
>  to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
> -@item disk:@var{file}
> -Mass storage device based on @var{file} (@pxref{disk_images})
> -@item host:@var{bus.addr}
> -Pass through the host device identified by @var{bus.addr}
> -(Linux only)
> -@item host:@var{vendor_id:product_id}
> -Pass through the host device identified by @var{vendor_id:product_id}
> -(Linux only)
> -@item wacom-tablet
> +@item usb-storage,drive=@var{drive_id}
> +Mass storage device (@pxref{disk_images})

Most items explain the properties they mention.  This one doesn't.
Perhaps:

   Mass storage device backed by @var{drive_id} (@pxref{disk_images}).

> +@item usb-uas
> +USB attached SCSI device, see
> +@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}

404

{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt}
works for me.

> +for details
> +@item usb-bot
> +Bulk-only transport storage device, see
> +@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}

Likewise.

> +for details here, too
> +@item usb-mtp,x-root=@var{dir}
> +Media transfer protocol device

Suggest to either explain x-root, or omit it.

> +@item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
> +Pass through the host device identified by @var{bus} and @var{addr}
> +(this only works on Linux or other OS with support for libusb)

Hmm, host-legacy.c still exists.  Didn't expect that.  Gerd, what's the
reason for dragging it along?

Without it, I'd suggest

   (requires libusb)

Alternatively, just drop the parenthesis.  The manual documents numerous
features without explaining their build and run time requirements.

> +@item usb-host,vendorid=@var{vendor},productid=@var{product}
> +Pass through the host device identified by @var{vendor} and @var{product} ID
> +(this only works on Linux or other OS with support for libusb)

Likewise.

> +@item usb-wacom-tablet
>  Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
>  above but it can be used with the tslib library because in addition to touch
>  coordinates it reports touch pressure.
> -@item keyboard
> +@item usb-kbd
>  Standard USB keyboard.  Will override the PS/2 keyboard (if present).
> -@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
> +@item usb-serial,chardev=@var{dev}
>  Serial converter. This emulates an FTDI FT232BM chip connected to host character
> -device @var{dev}. The available character devices are the same as for the
> -@code{-serial} option. The @code{vendorid} and @code{productid} options can be
> -used to override the default 0403:6001. For instance,
> -@example
> -usb_add serial:productid=FA00:tcp:192.168.0.2:4444
> -@end example
> -will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
> -serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
> -@item braille
> +device @var{dev}.
> +@item usb-braille
>  Braille device.  This will use BrlAPI to display the braille output on a real
>  or fake device.
> -@item net:@var{options}
> -Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
> -specifies NIC options as with @code{-net nic,}@var{options} (see description).
> +@item usb-net[,netdev=@var{id}]
> +Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
> +specifies a netdev defined with @code{-netdev xxx,id=}@var{id}.

Semantically, the @var{id} is within the @code{}.  Does writing it that
way work?

The xxx isn't so hot.  @code{-netdev id=@var{id},@dots{}} might work.
Use your judgement.

>  For instance, user-mode networking can be used with
>  @example
> -qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
> -@end example
> -Currently this cannot be used in machines that support PCI NICs.
> -@item bt[:@var{hci-type}]
> -Bluetooth dongle whose type is specified in the same format as with
> +qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
> +@end example
> +@item usb-ccid
> +Smartcard reader device
> +@item usb-audio
> +USB audio device
> +@item usb-bt-dongle
> +Bluetooth dongle for the transport layer of HCI. It is connected to HCI
> +scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
> +Note that the syntax for the @code{-device usb-bt-dongle} option is not as
> +useful yet as it was with the legacy @code{-usbdevice} option. So to
> +configure an USB bluetooth device, you might need to use
> +"@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
> +bluetooth dongle whose type is specified in the same format as with
>  the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
>  no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
>  This USB device implements the USB Transport Layer of HCI.  Example

Works for me.

> @@ -1460,11 +1472,11 @@ hubs, it won't work).
>  
>  @item Add the device in QEMU by using:
>  @example
> -usb_add host:1234:5678
> +device_add usb-host,vendorid=0x1234,productid=0x5678
>  @end example
>  
> -Normally the guest OS should report that a new USB device is
> -plugged. You can use the option @option{-usbdevice} to do the same.
> +Normally the guest OS should report that a new USB device is plugged.
> +You can use the option @option{-device usb-host,...} to do the same.
>  
>  @item Now you can try to use the host USB device in QEMU.

With at least and qdev-device-use.txt streamlined and the links fixed
(assuming they need fixing):

Reviewed-by: Markus Armbruster <armbru@redhat.com>
Thomas Huth May 8, 2017, 11:17 a.m. UTC | #2
On 05.05.2017 13:54, Markus Armbruster wrote:
> Thomas Huth <thuth@redhat.com> writes:
> 
>> The preferred way of adding USB devices is via "-device" and
>> "device_add" nowadays, so let's start to get rid of "-usbdevice"
>> and "usb_add" in the documentation. While we're at it, also
>> add the new USB devices there which have been added to QEMU
>> during the last years.
>>
>> Signed-off-by: Thomas Huth <thuth@redhat.com>
>> ---
>>  v2:
>>  - Addressed review feedback from Markus
>>  - Added the new USB devices that are only available via "-device"
>>  - Update qdev-device-use.txt about "vendorid" and "productid"
>>
>>  docs/qdev-device-use.txt |  5 +--
>>  qemu-doc.texi            | 92 +++++++++++++++++++++++++++---------------------
>>  2 files changed, 55 insertions(+), 42 deletions(-)
>>
>> diff --git a/docs/qdev-device-use.txt b/docs/qdev-device-use.txt
>> index b059405..2c1331b 100644
>> --- a/docs/qdev-device-use.txt
>> +++ b/docs/qdev-device-use.txt
>> @@ -182,8 +182,9 @@ The appropriate DEVNAME depends on the machine type.  For type "pc":
>>  
>>    This lets you control I/O ports and IRQs.
>>  
>> -* -usbdevice serial:vendorid=VID,productid=PRID becomes
>> -  -device usb-serial,vendorid=VID,productid=PRID
>> +* -usbdevice serial:[vendorid=VID,productid=PRID]:chardev becomes
>> +  -device usb-serial,chardev=dev.  The possibility to set a vendor
>> +  and product ID has been removed since QEMU version 0.14.0.
> 
> If we intend to fix -usbdevice serial:VID,PRID, the hunk should be
> dropped.
> 
> If we don't intend to fix it, I'd simple delete the old crap that
> doesn't work anymore:
> 
>    * -usbdevice serial::chardev becomes -device usb-serial,chardev=dev.
> 
> As far as I can tell, we don't intend to fix it.

OK, we certainly not going to fix that legacy stuff, so I'll simply
remove vendorid/productid here.

>>  * -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
>>    uses "braille".  With -device, this useful default is gone, so you
>> diff --git a/qemu-doc.texi b/qemu-doc.texi
>> index 794ab4a..b446ac4 100644
>> --- a/qemu-doc.texi
>> +++ b/qemu-doc.texi
>> @@ -182,7 +182,7 @@ Gravis Ultrasound GF1 sound card
>>  @item
>>  CS4231A compatible sound card
>>  @item
>> -PCI UHCI USB controller and a virtual USB hub.
>> +PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
>>  @end itemize
>>  
>>  SMP is supported with up to 255 CPUs.
>> @@ -1357,10 +1357,10 @@ monitor (@pxref{pcsys_keys}).
>>  @node pcsys_usb
>>  @section USB emulation
>>  
>> -QEMU emulates a PCI UHCI USB controller. You can virtually plug
>> -virtual USB devices or real host USB devices (experimental, works only
>> -on Linux hosts).  QEMU will automatically create and connect virtual USB hubs
>> -as necessary to connect multiple USB devices.
>> +QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
>> +plug virtual USB devices or real host USB devices (only works with certain
>> +host operating systems). QEMU will automatically create and connect virtual
>> +USB hubs as necessary to connect multiple USB devices.
>>  
>>  @menu
>>  * usb_devices::
>> @@ -1369,53 +1369,65 @@ as necessary to connect multiple USB devices.
>>  @node usb_devices
>>  @subsection Connecting USB devices
>>  
>> -USB devices can be connected with the @option{-usbdevice} commandline option
>> -or the @code{usb_add} monitor command.  Available devices are:
>> +USB devices can be connected with the @option{-device usb-...} command line
>> +option or the @code{device_add} monitor command. Available devices are:
>>  
>>  @table @code
>> -@item mouse
>> +@item usb-mouse
>>  Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
>> -@item tablet
>> +@item usb-tablet
>>  Pointer device that uses absolute coordinates (like a touchscreen).
>>  This means QEMU is able to report the mouse position without having
>>  to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
>> -@item disk:@var{file}
>> -Mass storage device based on @var{file} (@pxref{disk_images})
>> -@item host:@var{bus.addr}
>> -Pass through the host device identified by @var{bus.addr}
>> -(Linux only)
>> -@item host:@var{vendor_id:product_id}
>> -Pass through the host device identified by @var{vendor_id:product_id}
>> -(Linux only)
>> -@item wacom-tablet
>> +@item usb-storage,drive=@var{drive_id}
>> +Mass storage device (@pxref{disk_images})
> 
> Most items explain the properties they mention.  This one doesn't.
> Perhaps:
> 
>    Mass storage device backed by @var{drive_id} (@pxref{disk_images}).
> 
>> +@item usb-uas
>> +USB attached SCSI device, see
>> +@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
> 
> 404
> 
> {http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt}
> works for me.

You have to look at the generated HTML instead of the markup language:
The ",usb-storage.txt" simply means that "usb-storage.txt" should be
used in the text, but the hyperlink should of course be used as link
target instead.

>> +for details
>> +@item usb-bot
>> +Bulk-only transport storage device, see
>> +@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
> 
> Likewise.
> 
>> +for details here, too
>> +@item usb-mtp,x-root=@var{dir}
>> +Media transfer protocol device
> 
> Suggest to either explain x-root, or omit it.

The parameter is required, not optional, so I guess I should rather
explain it (though it is a "x-" parameter)...

>> +@item usb-wacom-tablet
>>  Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
>>  above but it can be used with the tslib library because in addition to touch
>>  coordinates it reports touch pressure.
>> -@item keyboard
>> +@item usb-kbd
>>  Standard USB keyboard.  Will override the PS/2 keyboard (if present).
>> -@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
>> +@item usb-serial,chardev=@var{dev}
>>  Serial converter. This emulates an FTDI FT232BM chip connected to host character
>> -device @var{dev}. The available character devices are the same as for the
>> -@code{-serial} option. The @code{vendorid} and @code{productid} options can be
>> -used to override the default 0403:6001. For instance,
>> -@example
>> -usb_add serial:productid=FA00:tcp:192.168.0.2:4444
>> -@end example
>> -will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
>> -serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
>> -@item braille
>> +device @var{dev}.
>> +@item usb-braille
>>  Braille device.  This will use BrlAPI to display the braille output on a real
>>  or fake device.
>> -@item net:@var{options}
>> -Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
>> -specifies NIC options as with @code{-net nic,}@var{options} (see description).
>> +@item usb-net[,netdev=@var{id}]
>> +Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
>> +specifies a netdev defined with @code{-netdev xxx,id=}@var{id}.
> 
> Semantically, the @var{id} is within the @code{}.  Does writing it that
> way work?

Yes, that works, too, so I'll change that.

> The xxx isn't so hot.  @code{-netdev id=@var{id},@dots{}} might work.
> Use your judgement.

@dots looks nice, I'll use that instead.

[...]
>> @@ -1460,11 +1472,11 @@ hubs, it won't work).
>>  
>>  @item Add the device in QEMU by using:
>>  @example
>> -usb_add host:1234:5678
>> +device_add usb-host,vendorid=0x1234,productid=0x5678
>>  @end example
>>  
>> -Normally the guest OS should report that a new USB device is
>> -plugged. You can use the option @option{-usbdevice} to do the same.
>> +Normally the guest OS should report that a new USB device is plugged.
>> +You can use the option @option{-device usb-host,...} to do the same.
>>  
>>  @item Now you can try to use the host USB device in QEMU.
> 
> With at least and qdev-device-use.txt streamlined and the links fixed
> (assuming they need fixing):
> 
> Reviewed-by: Markus Armbruster <armbru@redhat.com>

Thanks!

 Thomas
diff mbox

Patch

diff --git a/docs/qdev-device-use.txt b/docs/qdev-device-use.txt
index b059405..2c1331b 100644
--- a/docs/qdev-device-use.txt
+++ b/docs/qdev-device-use.txt
@@ -182,8 +182,9 @@  The appropriate DEVNAME depends on the machine type.  For type "pc":
 
   This lets you control I/O ports and IRQs.
 
-* -usbdevice serial:vendorid=VID,productid=PRID becomes
-  -device usb-serial,vendorid=VID,productid=PRID
+* -usbdevice serial:[vendorid=VID,productid=PRID]:chardev becomes
+  -device usb-serial,chardev=dev.  The possibility to set a vendor
+  and product ID has been removed since QEMU version 0.14.0.
 
 * -usbdevice braille doesn't support LEGACY-CHARDEV syntax.  It always
   uses "braille".  With -device, this useful default is gone, so you
diff --git a/qemu-doc.texi b/qemu-doc.texi
index 794ab4a..b446ac4 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -182,7 +182,7 @@  Gravis Ultrasound GF1 sound card
 @item
 CS4231A compatible sound card
 @item
-PCI UHCI USB controller and a virtual USB hub.
+PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
 @end itemize
 
 SMP is supported with up to 255 CPUs.
@@ -1357,10 +1357,10 @@  monitor (@pxref{pcsys_keys}).
 @node pcsys_usb
 @section USB emulation
 
-QEMU emulates a PCI UHCI USB controller. You can virtually plug
-virtual USB devices or real host USB devices (experimental, works only
-on Linux hosts).  QEMU will automatically create and connect virtual USB hubs
-as necessary to connect multiple USB devices.
+QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
+plug virtual USB devices or real host USB devices (only works with certain
+host operating systems). QEMU will automatically create and connect virtual
+USB hubs as necessary to connect multiple USB devices.
 
 @menu
 * usb_devices::
@@ -1369,53 +1369,65 @@  as necessary to connect multiple USB devices.
 @node usb_devices
 @subsection Connecting USB devices
 
-USB devices can be connected with the @option{-usbdevice} commandline option
-or the @code{usb_add} monitor command.  Available devices are:
+USB devices can be connected with the @option{-device usb-...} command line
+option or the @code{device_add} monitor command. Available devices are:
 
 @table @code
-@item mouse
+@item usb-mouse
 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
-@item tablet
+@item usb-tablet
 Pointer device that uses absolute coordinates (like a touchscreen).
 This means QEMU is able to report the mouse position without having
 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
-@item disk:@var{file}
-Mass storage device based on @var{file} (@pxref{disk_images})
-@item host:@var{bus.addr}
-Pass through the host device identified by @var{bus.addr}
-(Linux only)
-@item host:@var{vendor_id:product_id}
-Pass through the host device identified by @var{vendor_id:product_id}
-(Linux only)
-@item wacom-tablet
+@item usb-storage,drive=@var{drive_id}
+Mass storage device (@pxref{disk_images})
+@item usb-uas
+USB attached SCSI device, see
+@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
+for details
+@item usb-bot
+Bulk-only transport storage device, see
+@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
+for details here, too
+@item usb-mtp,x-root=@var{dir}
+Media transfer protocol device
+@item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
+Pass through the host device identified by @var{bus} and @var{addr}
+(this only works on Linux or other OS with support for libusb)
+@item usb-host,vendorid=@var{vendor},productid=@var{product}
+Pass through the host device identified by @var{vendor} and @var{product} ID
+(this only works on Linux or other OS with support for libusb)
+@item usb-wacom-tablet
 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
 above but it can be used with the tslib library because in addition to touch
 coordinates it reports touch pressure.
-@item keyboard
+@item usb-kbd
 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
-@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
+@item usb-serial,chardev=@var{dev}
 Serial converter. This emulates an FTDI FT232BM chip connected to host character
-device @var{dev}. The available character devices are the same as for the
-@code{-serial} option. The @code{vendorid} and @code{productid} options can be
-used to override the default 0403:6001. For instance,
-@example
-usb_add serial:productid=FA00:tcp:192.168.0.2:4444
-@end example
-will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
-serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
-@item braille
+device @var{dev}.
+@item usb-braille
 Braille device.  This will use BrlAPI to display the braille output on a real
 or fake device.
-@item net:@var{options}
-Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
-specifies NIC options as with @code{-net nic,}@var{options} (see description).
+@item usb-net[,netdev=@var{id}]
+Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
+specifies a netdev defined with @code{-netdev xxx,id=}@var{id}.
 For instance, user-mode networking can be used with
 @example
-qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
-@end example
-Currently this cannot be used in machines that support PCI NICs.
-@item bt[:@var{hci-type}]
-Bluetooth dongle whose type is specified in the same format as with
+qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
+@end example
+@item usb-ccid
+Smartcard reader device
+@item usb-audio
+USB audio device
+@item usb-bt-dongle
+Bluetooth dongle for the transport layer of HCI. It is connected to HCI
+scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
+Note that the syntax for the @code{-device usb-bt-dongle} option is not as
+useful yet as it was with the legacy @code{-usbdevice} option. So to
+configure an USB bluetooth device, you might need to use
+"@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
+bluetooth dongle whose type is specified in the same format as with
 the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
 no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
 This USB device implements the USB Transport Layer of HCI.  Example
@@ -1460,11 +1472,11 @@  hubs, it won't work).
 
 @item Add the device in QEMU by using:
 @example
-usb_add host:1234:5678
+device_add usb-host,vendorid=0x1234,productid=0x5678
 @end example
 
-Normally the guest OS should report that a new USB device is
-plugged. You can use the option @option{-usbdevice} to do the same.
+Normally the guest OS should report that a new USB device is plugged.
+You can use the option @option{-device usb-host,...} to do the same.
 
 @item Now you can try to use the host USB device in QEMU.