docs: Fold usb2.txt USB controller information into usb.rst
Fold the information in docs/usb2.txt about the different kinds of supported USB controller into the main rST manual. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20210728141457.14825-3-peter.maydell@linaro.org> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
This commit is contained in:
Peter Maydell
Gerd Hoffmann
parent
2a49e4e927
commit
78da86dce1
|
|
@ -8,6 +8,92 @@ 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.
|
||||
|
||||
USB controllers
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
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:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -M pc ${otheroptions} \\
|
||||
-drive if=none,id=usbstick,format=raw,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, which you can use like this:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -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.
|
||||
|
||||
|
||||
.. _Connecting USB devices:
|
||||
|
||||
Connecting USB devices
|
||||
|
|
|
|||
|
|
@ -1,86 +1,4 @@
|
|||
|
||||
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
|
||||
======================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue