Xen USB Passthrough: Difference between revisions

From Xen
Jump to navigationJump to search
(Complete re-write, updated as of 4.4.)
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: HVM USB and PV USB. They use separate command sets which unfortunately look very similar:
* '''HVM USB''' uses the following commands: <code>usb-add</code>, <code>usb-del</code>
* '''PV USB'''' uses the following commands: <code>usb-hc-create</code>, <code>usb-hc-destroy</code>, <code>usb-attach</code>, <code>usb-destroy</code>


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:


== Emultated 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 stubdomains.
Qemu-dm USB 1.1 passthru doesn't require any additional backend drivers in dom0 or any additional frontend drivers in the guest!


== PVUSB ==
As of Xen 4.2, HVM passthru is not available via xl, only xm. Support is slated for the 4.3 release.


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).
Usage example in /etc/xen/<guest> cfgfile:

Unfortunately, kernel support for the PVUSB protocol isn't very good. 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.)

= Details =

== Specifying a host USB device ==

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>).

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

You can use <code>lsusb</code> to list the USB devices on the system:


<pre>
<pre>
Bus 001 Device 003: ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub
usb = 1
Bus 003 Device 002: ID f617:0905
usbdevice = "host:xxxx:yyyy"
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>
</pre>


To pass through the Logitec mouse, for instance, you could specify either <code>046d:c016</code> or <code>1.6</code>.
You can find out the "xxxx:yyyy" part by using "lsusb" command in dom0.

'''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 4.4, 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.4, 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.

With the removal of <code>xend</code> slated for 4.4, we expect xl PVUSB support and hot-plug support to be a requirement to release 4.5.
== Host USB in xm/xend ==

'''Note''': <code>xend</code>/<code>xm</code> has been deprecated since 4.2, and as of this writing is slated to be removed as of 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.

=== 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.


= More info =
You can also plug a device into a running VM using usb-add and usb-del:
* <code>xm usb-add domain host:xxxx:yyyy</code>
* <code>xm usb-del domain host:xxxx:yyyy</code>


== PVUSB support in Xen 4.0 and newer versions ==
== PVUSB support in Xen 4.0 and newer versions ==
Line 69: Line 127:
* 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]]

Revision as of 16:01, 30 April 2014

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.

Emultated 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 stubdomains.

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. 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.)

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

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 4.4, 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.4, 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.

With the removal of xend slated for 4.4, we expect xl PVUSB support and hot-plug support to be a requirement to release 4.5.

Host USB in xm/xend

Note: xend/xm has been deprecated since 4.2, and as of this writing is slated to be removed as of 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.

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.

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):

Retrieved from "https://wiki.xenproject.org/index.php?title=Xen_USB_Passthrough&oldid=11493"