docs: Fold usb2.txt passthrough information into usb.rst

Fold the usb2.txt information on device passthrough into usb.rst;
since this is the last part of the .txt file we can delete it now.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20210728141457.14825-5-peter.maydell@linaro.org>
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
This commit is contained in:
Peter Maydell 2021-07-28 15:14:57 +01:00 committed by Gerd Hoffmann
parent 557ae9763a
commit 30a20f2c5a
3 changed files with 49 additions and 59 deletions

View File

@ -1837,7 +1837,6 @@ F: hw/usb/*
F: stubs/usb-dev-stub.c
F: tests/qtest/usb-*-test.c
F: docs/system/devices/usb.rst
F: docs/usb-storage.txt
F: include/hw/usb.h
F: include/hw/usb/

View File

@ -300,3 +300,52 @@ are not supported yet.
When relaunching QEMU, you may have to unplug and plug again the USB
device to make it work again (this is a bug).
``usb-host`` properties for specifying the host device
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The example above uses the ``vendorid`` and ``productid`` to
specify which host device to pass through, but this is not
the only way to specify the host device. ``usb-host`` supports
the following properties:
``hostbus=<nr>``
Specifies the bus number the device must be attached to
``hostaddr=<nr>``
Specifies the device address the device got assigned by the guest os
``hostport=<str>``
Specifies the physical port the device is attached to
``vendorid=<hexnr>``
Specifies the vendor ID of the device
``productid=<hexnr>``
Specifies the product ID of the device.
In theory you can combine all these properties as you like. In
practice only a few combinations are useful:
- ``vendorid`` and ``productid`` -- match for a specific device, pass it to
the guest when it shows up somewhere in the host.
- ``hostbus`` and ``hostport`` -- match for a specific physical port in the
host, any device which is plugged in there gets passed to the
guest.
- ``hostbus`` and ``hostaddr`` -- most useful for ad-hoc pass through as the
hostaddr isn't stable. The next time you plug the device into the host it
will get a new hostaddr.
Note that on the host USB 1.1 devices are handled by UHCI/OHCI and USB
2.0 by EHCI. That means different USB devices plugged into the very
same physical port on the host may show up on different host buses
depending on the speed. Supposing that devices plugged into a given
physical port appear as bus 1 + port 1 for 2.0 devices and bus 3 + port 1
for 1.1 devices, you can pass through any device plugged into that port
and also assign it to the correct USB bus in QEMU like this:
.. parsed-literal::
|qemu_system| -M pc [...] \\
-usb \\
-device usb-ehci,id=ehci \\
-device usb-host,bus=usb-bus.0,hostbus=3,hostport=1 \\
-device usb-host,bus=ehci.0,hostbus=1,hostport=1

View File

@ -1,58 +0,0 @@
More USB tips & tricks
======================
Recently the USB pass through driver (also known as usb-host) and the
QEMU USB subsystem gained a few capabilities which are available only
via qdev properties, i,e. when using '-device'.
USB pass through hints
----------------------
The usb-host driver has a bunch of properties to specify the device
which should be passed to the guest:
hostbus=<nr> -- Specifies the bus number the device must be attached
to.
hostaddr=<nr> -- Specifies the device address the device got
assigned by the guest os.
hostport=<str> -- Specifies the physical port the device is attached
to.
vendorid=<hexnr> -- Specifies the vendor ID of the device.
productid=<hexnr> -- Specifies the product ID of the device.
In theory you can combine all these properties as you like. In
practice only a few combinations are useful:
(1) vendorid+productid -- match for a specific device, pass it to
the guest when it shows up somewhere in the host.
(2) hostbus+hostport -- match for a specific physical port in the
host, any device which is plugged in there gets passed to the
guest.
(3) hostbus+hostaddr -- most useful for ad-hoc pass through as the
hostaddr isn't stable, the next time you plug in the device it
gets a new one ...
Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by
EHCI. That means a device plugged into the very same physical port
may show up on different buses depending on the speed. The port I'm
using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1
for 1.1 devices. Passing through any device plugged into that port
and also assign them to the correct bus can be done this way:
qemu -M pc ${otheroptions} \
-usb \
-device usb-ehci,id=ehci \
-device usb-host,bus=usb-bus.0,hostbus=3,hostport=1 \
-device usb-host,bus=ehci.0,hostbus=1,hostport=1
enjoy,
Gerd
--
Gerd Hoffmann <kraxel@redhat.com>