Describe QEMU USB pass-through

1 files changed, 72 insertions, 2 deletions

diff --git a/source/qemu.rst b/source/qemu.rst
index d2f885a..58f508a 100644
--- a/source/qemu.rst
+++ b/source/qemu.rst
@@ -32,8 +32,7 @@ Basic VM command
 
 .. admonition:: TODO
 
-   Describe the command and split into parts and move them apart in sepatate
-   sections.
+   Describe the command and split it apart into sepatate sections.
 
 
 Exchange files with the host using samba [#shared-folder]_
@@ -68,4 +67,75 @@ Overall it looks like this:
 
 .. image:: windows-guest-explorer-exe-qemu-samba.png
 
+Pass specific USB port to the guest [#qemu-usb-emulation]_
+==========================================================
+
+Here is how it's done::
+
+  -device qemu-xhci \
+  -device usb-host,hostbus=<bus>,hostport=<port> \
+
+First find the <bus> and <port> values of the USB port (physical socket) you
+need to pass to the guest machine. Take a USB device you can clearly identify in
+the ``lsusb`` output and insert it into the port. Then run ``lsusb -t`` and
+observe the output::
+
+  /:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/10p, 480M
+      |__ Port 001: Dev 123, If 0, Class=Hub, Driver=hub/4p, 480M
+          |__ Port 002: Dev 031, If 0, Class=Vendor Specific Class, Driver=cp210x, 12M
+          |__ Port 004: Dev 127, If 0, Class=Hub, Driver=hub/4p, 480M
+              |__ Port 002: Dev 006, If 0, Class=Hub, Driver=hub/4p, 480M
+      |__ Port 004: Dev 003, If 0, Class=Wireless, Driver=btusb, 12M
+      |__ Port 004: Dev 003, If 1, Class=Wireless, Driver=btusb, 12M
+      |__ Port 007: Dev 005, If 0, Class=Human Interface Device, Driver=usbhid, 12M
+      |__ Port 008: Dev 007, If 0, Class=Wireless, Driver=btusb, 12M
+      |__ Port 008: Dev 007, If 1, Class=Wireless, Driver=btusb, 12M
+  /:  Bus 002.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/4p, 10000M
+      |__ Port 001: Dev 015, If 0, Class=Hub, Driver=hub/4p, 5000M
+  /:  Bus 003.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/4p, 480M
+      |__ Port 002: Dev 002, If 0, Class=Audio, Driver=snd-usb-audio, 12M
+      |__ Port 002: Dev 002, If 1, Class=Audio, Driver=snd-usb-audio, 12M
+      |__ Port 002: Dev 002, If 2, Class=Audio, Driver=snd-usb-audio, 12M
+      |__ Port 002: Dev 002, If 3, Class=Human Interface Device, Driver=usbhid, 12M
+      |__ Port 003: Dev 003, If 0, Class=Human Interface Device, Driver=usbhid, 12M
+      |__ Port 003: Dev 003, If 1, Class=Human Interface Device, Driver=usbhid, 12M
+      |__ Port 003: Dev 003, If 2, Class=Human Interface Device, Driver=usbhid, 12M
+      |__ Port 004: Dev 004, If 0, Class=Human Interface Device, Driver=usbhid, 12M
+      |__ Port 004: Dev 004, If 1, Class=Human Interface Device, Driver=usbhid, 12M
+      |__ Port 004: Dev 004, If 2, Class=Human Interface Device, Driver=usbhid, 12M
+  /:  Bus 004.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/4p, 10000M
+
+You can also run just ``lsusb`` command, since it has human friendly device
+description, but without tree structure, and note the ``Device`` number listed
+to use it to identify the device in the ``lsusb -t`` command output::
+
+  Bus 001 Device 031: ID 10c4:ea60 Silicon Labs CP210x UART Bridge
+
+My device here is ``cp210x`` with number ``031`` and it sits on the bus ``1``
+and port ``1.2``. Look closely at how these numbers are inferred::
+
+            +- The bus number (1)
+            |    +- The first number of the <port> value (1)
+            |    |   +- The second number of the <port> value (2)
+            v    |   |
+  /:  Bus 001    v   |  Dev 001, Class=root_hub, Driver=xhci_hcd/10p, 480M
+      |__ Port 001:  v  123, If 0, Class=Hub, Driver=hub/4p, 480M
+          |__ Port 002: Dev 031, If 0, Class=Vendor Specific Class, Driver=cp210x, 12M
+
+I am going to use these ``<hostbus>`` (``1``) and ``<port>`` (``1.2``) values
+like this::
+
+  -device qemu-xhci \
+  -device usb-host,hostbus=1,hostport=1.2 \
+
+Note that the ``<port>`` value complexity depends on how many USB hubs you have
+inserted into each other. If there are no USB hubs, then there will be most
+likely just a single number. If you are trying to pass a port of a USB hub, then
+you will end up with two numbers separated by dot. If it is a port of a USB hub
+inserted in another USB hub, then you will need three numbers separated by dots
+to describe the ``hostport`` like ``1.5.2``. It is possible that your
+motherboard has a USB hub on it (laptops are made like this sometimes) and
+expose it's ports, then such a port may have two numbers, separated by a dot.
+
 .. [#shared-folder] `Shared folder between QEMU Windows guest and Linux host / stackexchange.com <https://unix.stackexchange.com/a/183609>`_
+.. [#qemu-usb-emulation] `USB emulation - QEMU documentation / www.qemu.org <https://www.qemu.org/docs/master/system/devices/usb.html>`_