95c94f8968
In commit 5cc194caeb019cf1dae7f74ccbdf0401a56c2ac6, the number of ehci ports is corrected to six. Fix docs related to it. Signed-off-by: npes87184 <npes87184@gmail.com> Message-id: 20180801122410.10343-1-npes87184@gmail.com Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
173 lines
6.2 KiB
Plaintext
173 lines
6.2 KiB
Plaintext
|
|
USB Quick Start
|
|
===============
|
|
|
|
XHCI controller support
|
|
-----------------------
|
|
|
|
QEMU has XHCI host adapter support. The XHCI hardware design is much
|
|
more virtualization-friendly when compared to EHCI and UHCI, thus XHCI
|
|
emulation uses less resources (especially cpu). So if your guest
|
|
supports XHCI (which should be the case for any operating system
|
|
released around 2010 or later) we recommend using it:
|
|
|
|
qemu -device qemu-xhci
|
|
|
|
XHCI supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the
|
|
only controller you need. With only a single USB controller (and
|
|
therefore only a single USB bus) present in the system there is no
|
|
need to use the bus= parameter when adding USB devices.
|
|
|
|
|
|
EHCI controller support
|
|
-----------------------
|
|
|
|
The QEMU EHCI Adapter supports USB 2.0 devices. It can be used either
|
|
standalone or with companion controllers (UHCI, OHCI) for USB 1.1
|
|
devices. The companion controller setup is more convenient to use
|
|
because it provides a single USB bus supporting both USB 2.0 and USB
|
|
1.1 devices. See next section for details.
|
|
|
|
When running EHCI in standalone mode you can add UHCI or OHCI
|
|
controllers for USB 1.1 devices too. Each controller creates its own
|
|
bus though, so there are two completely separate USB buses: One USB
|
|
1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by
|
|
the EHCI controller. Devices must be attached to the correct
|
|
controller manually.
|
|
|
|
The easiest way to add a UHCI controller to a 'pc' machine is the
|
|
'-usb' switch. QEMU will create the UHCI controller as function of
|
|
the PIIX3 chipset. The USB 1.1 bus will carry the name "usb-bus.0".
|
|
|
|
You can use the standard -device switch to add a EHCI controller to
|
|
your virtual machine. It is strongly recommended to specify an ID for
|
|
the controller so the USB 2.0 bus gets an individual name, for example
|
|
'-device usb-ehci,id=ehci". This will give you a USB 2.0 bus named
|
|
"ehci.0".
|
|
|
|
When adding USB devices using the -device switch you can specify the
|
|
bus they should be attached to. Here is a complete example:
|
|
|
|
qemu -M pc ${otheroptions} \
|
|
-drive if=none,id=usbstick,file=/path/to/image \
|
|
-usb \
|
|
-device usb-ehci,id=ehci \
|
|
-device usb-tablet,bus=usb-bus.0 \
|
|
-device usb-storage,bus=ehci.0,drive=usbstick
|
|
|
|
This attaches a USB tablet to the UHCI adapter and a USB mass storage
|
|
device to the EHCI adapter.
|
|
|
|
|
|
Companion controller support
|
|
----------------------------
|
|
|
|
The UHCI and OHCI controllers can attach to a USB bus created by EHCI
|
|
as companion controllers. This is done by specifying the masterbus
|
|
and firstport properties. masterbus specifies the bus name the
|
|
controller should attach to. firstport specifies the first port the
|
|
controller should attach to, which is needed as usually one EHCI
|
|
controller with six ports has three UHCI companion controllers with
|
|
two ports each.
|
|
|
|
There is a config file in docs which will do all this for
|
|
you, just try ...
|
|
|
|
qemu -readconfig docs/config/ich9-ehci-uhci.cfg
|
|
|
|
... then use "bus=ehci.0" to assign your USB devices to that bus.
|
|
|
|
Using the '-usb' switch for 'q35' machines will create a similar
|
|
USB controller configuration.
|
|
|
|
|
|
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'.
|
|
|
|
|
|
physical port addressing
|
|
------------------------
|
|
|
|
First you can (for all USB devices) specify the physical port where
|
|
the device will show up in the guest. This can be done using the
|
|
"port" property. UHCI has two root ports (1,2). EHCI has six root
|
|
ports (1-6), the emulated (1.1) USB hub has eight ports.
|
|
|
|
Plugging a tablet into UHCI port 1 works like this:
|
|
|
|
-device usb-tablet,bus=usb-bus.0,port=1
|
|
|
|
Plugging a hub into UHCI port 2 works like this:
|
|
|
|
-device usb-hub,bus=usb-bus.0,port=2
|
|
|
|
Plugging a virtual USB stick into port 4 of the hub just plugged works
|
|
this way:
|
|
|
|
-device usb-storage,bus=usb-bus.0,port=2.4,drive=...
|
|
|
|
You can do basically the same in the monitor using the device_add
|
|
command. If you want to unplug devices too you should specify some
|
|
unique id which you can use to refer to the device ...
|
|
|
|
(qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet
|
|
(qemu) device_del my-tablet
|
|
|
|
... when unplugging it with device_del.
|
|
|
|
|
|
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>
|