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

[Thomas Huth <thuth@redhat.com>]

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