Difference between revisions of "Xen USB Passthrough"

From Xen
(Created page with "<!-- MoinMoin name: XenUSBPassthrough --> <!-- Comment: Added info about Linux kernel USBIP support. --> <!-- WikiMedia name: XenUSBPassthrough --> <!-- Page revision: …")
 
(added link to device models stub domains page)
(16 intermediate revisions by 7 users not shown)
Line 1: Line 1:
  +
= Overview =
<!-- MoinMoin name: XenUSBPassthrough -->
 
<!-- Comment: Added info about Linux kernel USBIP support. -->
 
<!-- WikiMedia name: XenUSBPassthrough -->
 
<!-- Page revision: 00000032 -->
 
<!-- Original date: Wed Oct 26 19:19:08 2011 (1319656748000000) -->
 
   
  +
There are two general methods for passing through individual host devices to a guest. The first is via an emulated USB device controller; the second is PVUSB.
__NOTOC__
 
= Xen USB Passthrough =
 
Xen supports passthru of USB devices from dom0 to guests using two different methods.
 
   
  +
Additionally, there are two ways to add USB devices to a guest: via the config file at domain creation time, and via hot-plug while the VM is running.
For Xen HVM (fully virtualized) guests:
 
   
  +
Another popular method for passing through USB devices, particular for gaming rigs, is to use [[XenPCIpassthrough|PCI pass-through]] to pass through the entire host USB controller. This will result in the lowest overhead and best feature support. It does mean however that you cannot choose individual USB devices on a controller to the guest: it's all or nothing. This is suitable for both PV and HVM guests.
* Xen qemu-dm USB passthru using USB 1.1 emulation, by specifying "usb = 1" and "usbdevice = host:xxxx:yyyy" in /etc/xen/<guest> cfgfile. This method is low performance and doesn't support all USB devices, but it's available in all Xen 3.x and newer versions and doesn't require any special drivers in dom0 kernel or in the HVM guest.
 
* Xen PVUSB support in Xen 4.0 and newer versions, when PVUSB drivers are available for both dom0 and the VM kernel.
 
* Linux kernel USBIP support. For details refer to [http://usbip.sourceforge.net/ USB IP sourceforge webpage]
 
   
  +
There are also non-Xen solutions like [http://usbip.sourceforge.net/ USB IP], in which USB devices are shared over the network.
For Xen PV (paravirtualized) guests:
 
   
  +
== Emulated USB ==
* Xen PVUSB support in Xen 4.0 and newer versions. Note that PVUSB requires special pvusb drivers in the kernel, in both the dom0 kernel and domU kernel.
 
* Linux kernel USBIP support. For details refer to [http://usbip.sourceforge.net/ USB IP sourceforge webpage]
 
   
  +
In emulated USB, the device model (qemu) presents an emulated USB controller to the guest. The device model process then grabs control of the device from domain 0 and and passes the USB commands between the guest OS and the host USB device.
== Xen HVM guest qemu-dm USB 1.1 emulation/passthru ==
 
Qemu-dm used for Xen HVM (fully virtualized) guests supports USB passthru of devices from dom0 to the guest. Qemu-dm emulates USB 1.1 UHCI 2-port controller, which is pretty slow and limited in features and device support. Qemu-dm USB 1.1 passthru support is in all Xen 3.x (and newer) versions.
 
   
  +
This method is only available to HVM domains, and is not available for domains running with [[Device Model Stub Domains|device model stub domains]].
Qemu-dm USB 1.1 passthru doesn't require any additional backend drivers in dom0 or any additional frontend drivers in the guest!
 
   
  +
== PVUSB ==
Usage example in /etc/xen/<guest> cfgfile:
 
   
  +
PVUSB uses a paravirtialized front-end/back-end interface, similar to the traditional Xen PV network and disk protocols. In order to use PVUSB, you need usbfront in your guest OS, and usbback in dom0 (or your USB driver domain).
   
  +
Unfortunately, kernel support for the PVUSB protocol isn't very good currently. See the section below for links to more information about PVUSB driver support.
<pre><nowiki>
 
usb = 1
 
usbdevice = "host:xxxx:yyyy"
 
</nowiki></pre>
 
   
  +
Additionally, for easy use of PVUSB, you need support in the toolstack to get the two sides to talk to each other. (Alternately, you can write a script to talk over xenstore to the front and backends manually; see the section below for more information.)
You can find out the "xxxx:yyyy" part by using "lsusb" command in dom0.
 
   
  +
Currently PVUSB supports USB 2.0 devices. PVUSB supports both PV and HVM guests.
You can also do the USB 1.1 passthru to a running HVM guest from the qemu-dm console (hit ctrl-alt-2 to access the qemu console) by using a command like this:
 
   
  +
As of Xen 4.4 PVUSB is only supported with xm/xend toolstack. There is ongoing work to add PVUSB support to XL/libxl toolstack.
   
  +
= Details =
<pre><nowiki>
 
usb_add host:xxxx:yyyy</nowiki></pre>
 
   
  +
== Specifying a host USB device ==
Xen 3.4.3 and Xen 4.0.0 (and newer versions) add support for the HVM guest USB 1.1 add/del also by using "xm" commands:
 
   
  +
USB devices are primarily specified either by their bus address (in the form <code>bus.device</code>) or their device tag (in the form <code>vendorid:deviceid</code>).
* xm usb-add
 
  +
* xm usb-del
 
  +
Each way of specifying has its advantages:
  +
  +
* Specifying by device tag will always get the same device, regardless of where the device ends up in the USB bus topology. However, if there are two identical devices, it will not allow you to specify which one.
  +
  +
* Specifying by bus address will always allow you to choose a specific device, even if you have duplicates. However, the bus address may change depending on which port you plugged the device into, and possibly also after a reboot.
  +
  +
You can use <code>lsusb</code> to list the USB devices on the system:
  +
  +
<pre>
  +
Bus 001 Device 003: ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub
  +
Bus 003 Device 002: ID f617:0905
  +
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
  +
Bus 001 Device 004: ID 0424:2640 Standard Microsystems Corp. USB 2.0 Hub
  +
Bus 001 Device 005: ID 0424:4060 Standard Microsystems Corp. Ultra Fast Media Reader
  +
Bus 001 Device 006: ID 046d:c016 Logitech, Inc. Optical Wheel Mouse
  +
</pre>
  +
  +
To pass through the Logitec mouse, for instance, you could specify either <code>046d:c016</code> or <code>1.6</code>.
  +
  +
'''Note''': lsusb lists the bus and device number with leading zeroes, but you should remove these when specifying the device to xl. (Leading zeroes will result in xl interpreting the number as an octal.)
  +
  +
== Host USB in xl ==
  +
  +
As of Xen 4.6, xl only has support for emulated USB, from the config file.
  +
  +
Enable the emulated USB hub with <code>usb=1</code>. Then specify devices among the list of devices in the config file along with other emulated devices by using <code>host:USBID</code>. For example:
  +
  +
<pre>
  +
usb=1
  +
usbdevice=['tablet','host:1.6','host:0424:460']
  +
</pre>
  +
  +
The default USB controller created by qemu is USB 1.1. For some devices, this isn't sufficient. For this reason, as of 4.6, you can specify that the USB controller version as well, with <code>usbversion</code>. However, at the moment this is incompatible with <code>usbdevice</code>, and so is only useful in conjunction with spice USB redirection. This option is not available for qemu-traditional.
  +
  +
xl PVUSB support and hot-plug support is in progress and expected to make the 4.7 release.
  +
== Host USB in xm/xend ==
  +
  +
'''Note''': <code>xend</code>/<code>xm</code> has been deprecated since 4.2, and is removed from Xen 4.5.
  +
  +
<code>xend</code> has support for both emulated USB and PVUSB.
  +
  +
Please note however, that emulated USB and PVUSB use different sets of commands, both for hotplug, and in the config file, and the naming scheme isn't very obvious.
  +
  +
=== Emulated USB in xm/xend ===
  +
  +
In order to use emulated USB, you must enable it in the config file with <code>usb=1</code>.
  +
  +
You can specify a device in the config file; but unfortunately the <code>xend</code> syntax for <code>usbdevice</code> only allows you to specify a single USB device of any kind:
  +
  +
<pre>
  +
usb=1
  +
usbdevice=host:1.6
  +
</pre>
  +
  +
Fortunately, you can also hot-plug and un-plug devices after boot:
  +
  +
* <code>xm usb-add domain host:xx.yy</code>
  +
* <code>xm usb-del domain host:xx.yy</code>
  +
  +
<code>xend</code> only supports USB 1.1, because xm/xend only supports qemu-dm-traditional. USB 2.0 and USB 3.0 are only supported with qemu-upstream and XL.
  +
  +
=== PVUSB in xm/xend ===
  +
  +
PVUSB uses the following hotplug commands: <code>usb-hc-create</code>, <code>usb-hc-destroy</code>, <code>usb-attach</code>, <code>usb-destroy</code>
  +
  +
PVUSB can also be specified in the config file via the <code>vusb</code> directive.
  +
  +
Please see the <code>xm</code> and <code>xm.cfg</code> man pages for more information.
  +
  +
=== PVUSB in xl/libxl ===
  +
The support for PVUSB in xl/libxl is in the development. The main task is to design appropriate interface to add/delete usb devices.
  +
  +
= More info =
   
 
== PVUSB support in Xen 4.0 and newer versions ==
 
== PVUSB support in Xen 4.0 and newer versions ==
Line 64: Line 125:
 
* linux-2.6.18-xen has both the PVUSB backend and frontend drivers included. http://xenbits.xen.org/linux-2.6.18-xen.hg
 
* linux-2.6.18-xen has both the PVUSB backend and frontend drivers included. http://xenbits.xen.org/linux-2.6.18-xen.hg
 
* PVUSB drivers are currently being ported to the pvops kernel (2.6.32). RFC patch available from: http://lists.xensource.com/archives/html/xen-devel/2011-01/msg00354.html (http://members.iinet.net.au/~nathanael/pvusb.diff).
 
* PVUSB drivers are currently being ported to the pvops kernel (2.6.32). RFC patch available from: http://lists.xensource.com/archives/html/xen-devel/2011-01/msg00354.html (http://members.iinet.net.au/~nathanael/pvusb.diff).
* Novell SLES11 SP1 kernel-xen (2.6.32) has PVUSB backend and frontend drivers.
+
* Novell/SuSe SLES11 SP1 kernel-xen (2.6.32) has PVUSB backend and frontend drivers.
  +
* SuSe SLES12 kernel-xen (3.x) has PVUSB backend and frontend drivers.
  +
* OpenSuSe also has PVUSB drivers.
  +
* Linux 3.x pvops PVUSB patches: http://lists.xen.org/archives/html/xen-devel/2012-02/msg00576.html and http://lists.xen.org/archives/html/xen-devel/2012-02/msg00571.html .
 
More information about different kernel versions and drivers in them:
 
More information about different kernel versions and drivers in them:
 
* List of various Xen dom0 capable kernel trees for Linux: [[XenDom0Kernels:]]
 
* List of various Xen dom0 capable kernel trees for Linux: [[XenDom0Kernels:]]
Line 72: Line 136:
 
* Xen Windows GPLPV drivers by James Harper have an early version of PVUSB frontend driver included.
 
* Xen Windows GPLPV drivers by James Harper have an early version of PVUSB frontend driver included.
 
* Discussion about initial GPLPV usbfront implementation: http://lists.xensource.com/archives/html/xen-devel/2009-09/msg00491.html
 
* Discussion about initial GPLPV usbfront implementation: http://lists.xensource.com/archives/html/xen-devel/2009-09/msg00491.html
== USB passthrough of the whole controller ==
 
You can also use Xen PCI passthrough ( [[XenPCIpassthrough]] ) to passthru the whole USB controller PCI device, with all USB devices connected to that USB controller.
 
   
 
[[Category:Xen]]
 
[[Category:Xen]]
[{Category:Users]]
+
[[Category:Users]]
 
[[Category:HowTo]]
 
[[Category:HowTo]]

Revision as of 22:27, 24 February 2016

Overview

There are two general methods for passing through individual host devices to a guest. The first is via an emulated USB device controller; the second is PVUSB.

Additionally, there are two ways to add USB devices to a guest: via the config file at domain creation time, and via hot-plug while the VM is running.

Another popular method for passing through USB devices, particular for gaming rigs, is to use PCI pass-through to pass through the entire host USB controller. This will result in the lowest overhead and best feature support. It does mean however that you cannot choose individual USB devices on a controller to the guest: it's all or nothing. This is suitable for both PV and HVM guests.

There are also non-Xen solutions like USB IP, in which USB devices are shared over the network.

Emulated USB

In emulated USB, the device model (qemu) presents an emulated USB controller to the guest. The device model process then grabs control of the device from domain 0 and and passes the USB commands between the guest OS and the host USB device.

This method is only available to HVM domains, and is not available for domains running with device model stub domains.

PVUSB

PVUSB uses a paravirtialized front-end/back-end interface, similar to the traditional Xen PV network and disk protocols. In order to use PVUSB, you need usbfront in your guest OS, and usbback in dom0 (or your USB driver domain).

Unfortunately, kernel support for the PVUSB protocol isn't very good currently. See the section below for links to more information about PVUSB driver support.

Additionally, for easy use of PVUSB, you need support in the toolstack to get the two sides to talk to each other. (Alternately, you can write a script to talk over xenstore to the front and backends manually; see the section below for more information.)

Currently PVUSB supports USB 2.0 devices. PVUSB supports both PV and HVM guests.

As of Xen 4.4 PVUSB is only supported with xm/xend toolstack. There is ongoing work to add PVUSB support to XL/libxl toolstack.

Details

Specifying a host USB device

USB devices are primarily specified either by their bus address (in the form bus.device) or their device tag (in the form vendorid:deviceid).

Each way of specifying has its advantages:

  • Specifying by device tag will always get the same device, regardless of where the device ends up in the USB bus topology. However, if there are two identical devices, it will not allow you to specify which one.
  • Specifying by bus address will always allow you to choose a specific device, even if you have duplicates. However, the bus address may change depending on which port you plugged the device into, and possibly also after a reboot.

You can use lsusb to list the USB devices on the system:

Bus 001 Device 003: ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub
Bus 003 Device 002: ID f617:0905  
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 004: ID 0424:2640 Standard Microsystems Corp. USB 2.0 Hub
Bus 001 Device 005: ID 0424:4060 Standard Microsystems Corp. Ultra Fast Media Reader
Bus 001 Device 006: ID 046d:c016 Logitech, Inc. Optical Wheel Mouse

To pass through the Logitec mouse, for instance, you could specify either 046d:c016 or 1.6.

Note: lsusb lists the bus and device number with leading zeroes, but you should remove these when specifying the device to xl. (Leading zeroes will result in xl interpreting the number as an octal.)

Host USB in xl

As of Xen 4.6, xl only has support for emulated USB, from the config file.

Enable the emulated USB hub with usb=1. Then specify devices among the list of devices in the config file along with other emulated devices by using host:USBID. For example:

usb=1
usbdevice=['tablet','host:1.6','host:0424:460']

The default USB controller created by qemu is USB 1.1. For some devices, this isn't sufficient. For this reason, as of 4.6, you can specify that the USB controller version as well, with usbversion. However, at the moment this is incompatible with usbdevice, and so is only useful in conjunction with spice USB redirection. This option is not available for qemu-traditional.

xl PVUSB support and hot-plug support is in progress and expected to make the 4.7 release.

Host USB in xm/xend

Note: xend/xm has been deprecated since 4.2, and is removed from Xen 4.5.

xend has support for both emulated USB and PVUSB.

Please note however, that emulated USB and PVUSB use different sets of commands, both for hotplug, and in the config file, and the naming scheme isn't very obvious.

Emulated USB in xm/xend

In order to use emulated USB, you must enable it in the config file with usb=1.

You can specify a device in the config file; but unfortunately the xend syntax for usbdevice only allows you to specify a single USB device of any kind:

usb=1
usbdevice=host:1.6

Fortunately, you can also hot-plug and un-plug devices after boot:

  • xm usb-add domain host:xx.yy
  • xm usb-del domain host:xx.yy

xend only supports USB 1.1, because xm/xend only supports qemu-dm-traditional. USB 2.0 and USB 3.0 are only supported with qemu-upstream and XL.

PVUSB in xm/xend

PVUSB uses the following hotplug commands: usb-hc-create, usb-hc-destroy, usb-attach, usb-destroy

PVUSB can also be specified in the config file via the vusb directive.

Please see the xm and xm.cfg man pages for more information.

PVUSB in xl/libxl

The support for PVUSB in xl/libxl is in the development. The main task is to design appropriate interface to add/delete usb devices.

More info

PVUSB support in Xen 4.0 and newer versions

PVUSB is a new high performance method of doing USB passthru from dom0 to the guests, supporting both USB 2.0 and USB 1.1 devices. PVUSB does not use Qemu-dm. PVUSB can be used with both HVM and PV domUs, but it requires special pvusb drivers in dom0 kernel (xen-usbback) and the frontend driver (xen-usbfront) in the VM.

Presentation slides about PVUSB from XenSummits (contains usage examples and syntax):

Links related to PVUSB:

Xen Linux kernels that have PVUSB support included:

More information about different kernel versions and drivers in them:

Windows Xen PVUSB drivers (frontends):