mirror of https://github.com/xemu-project/xemu.git
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
|
certain host operating systems). QEMU will automatically create and
|
||||||
connect virtual USB hubs as necessary to connect multiple USB devices.
|
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:
|
||||||
|
|
||||||
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
|
More USB tips & tricks
|
||||||
======================
|
======================
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue