Xen USB Passthrough: Difference between revisions

From Xen
Jump to navigationJump to search
m (Removed superfluous <nowiki></nowiki> tag pairs.)
 
(24 intermediate revisions by 8 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 usb backend in qemu (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 1.1 and USB 2.0. PVUSB supports both PV and HVM guests.

As of Xen 4.4 PVUSB is only supported with xm/xend toolstack.

Since Xen 4.7, PVUSB support to XL/libxl toolstack is introduced. For PVUSB in xl, usb backend can be usbback in dom0 or usb backend in qemu, so called 'qusb'. Later one is still in process.

= 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 also after a reboot.

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

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

As of Xen 4.7, xl PVUSB support and hot-plug support is introduced.

From the config file, specify USB controllers and USB host devices with <code>usbctrl</code> and <code>usbdev</code>. For example:

<pre>
usbctrl=['type=pv,version=2,ports=4', 'type=pv,version=1, ports=4', ]
usbdev=['hostbus=2, hostaddr=1, controller=0,port=1', ]
</pre>

To hot-plug PVUSB device, use commands <code>usbctrl-attach</code>, <code>usbctrl-detach</code>, <code>usb-list</code>, <code>usbdev-attach</code> and <code>usb-detach</code>. For example:

<pre>
#xl usbctrl-attach test_vm version=1 ports=8
This will create a USB controller which is version USB 1.1 and has 8 ports.
#xl usb-list test_vm
This will show all USB controllers and USB devices in the domain.
#xl usbdev-attach test_vm hostbus=1 hostaddr=2
This will find the first available controller:port in the domain, and attach USB device whose busnum:devnum is 1:2 to it.
One can also specify <code>controller</code> and <code>port</code>.
#xl usbdev-detach test_vm 0 1
This will detach USB device under controller 0 port 1.
#xl usbctrl-detach test_vm dev_id
This will remove USB controller with the indicated dev_id, and all USB devices under it.
</pre>

== 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 introduced since Xen 4.7, including both PVUSB device from config file and PVUSB device hot-plug and un-plug. Currently it supports USB 1.1 and USB 2.0.

From the config file, specify USB controllers and USB host devices with <code>usbctrl</code> and <code>usbdev</code>. For example:

<pre>
usbctrl=['type=qusb,version=2,ports=4', 'type=qusb,version=1, ports=4', ]
usbdev=['hostbus=2, hostaddr=1, controller=0,port=1', ]
</pre>

For <code>type</code> you can specify <code>auto</code> (the default: xl tries to select the most appropriate type), <code>qusb</code> (paravirtualized qemu based backend, should be specified for pvUSB used by HVM domains), <code>pv</code> (paravirtualized kernel based backend, not supported by current standard linux), or <code>devicemodel</code> (qemu emulated USB controller, not yet supported).

You can also specify <code>usbdev</code> only, for example:

<pre>
usbdev=['hostbus=2, hostaddr=1, ]
</pre>

Then it will automatically create a USB controller of version 2.0 and 8 ports, and attach the USB device to the first port of this new controller.

To hot-plug and un-plug PVUSB device, use commands <code>usbctrl-attach</code>, <code>usbctrl-detach</code>, <code>usb-list</code>, <code>usbdev-attach</code> and <code>usbdev-detach</code>. For example:

<pre>
#xl usbctrl-attach test_vm version=1 ports=8
</pre>

This will create a USB controller which is version USB 1.1 and has 8 ports.

<pre>
#xl usb-list test_vm
</pre>

This will show all USB controllers and USB devices in the domain.

<pre>
#xl usbdev-attach test_vm hostbus=1 hostaddr=2
</pre>

This will find the first available controller:port in the domain, and attach USB device whose busnum:devnum is 1:2 to it.
One can also specify <code>controller</code> and <code>port</code>.

<pre>
#xl usbdev-detach test_vm 0 1
</pre>


This will detach USB device under controller 0 port 1.


<pre>
<pre>
#xl usbctrl-detach test_vm dev_id
usb_add host:xxxx:yyyy
</pre>
</pre>


This will remove USB controller with the indicated dev_id, and all USB devices under it.
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:


= More info =
* xm usb-add
* xm usb-del


== PVUSB support in Xen 4.0 and newer versions ==
== PVUSB support in Xen 4.0 and newer versions ==
Line 65: Line 205:
* 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 .
* Since Linux 5.17 the PVUSB driver is generally available.
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 73: Line 217:
* 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]]

Latest revision as of 11:48, 18 August 2022

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 usb backend in qemu (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 1.1 and USB 2.0. PVUSB supports both PV and HVM guests.

As of Xen 4.4 PVUSB is only supported with xm/xend toolstack.

Since Xen 4.7, PVUSB support to XL/libxl toolstack is introduced. For PVUSB in xl, usb backend can be usbback in dom0 or usb backend in qemu, so called 'qusb'. Later one is still in process.

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.

As of Xen 4.7, xl PVUSB support and hot-plug support is introduced.

From the config file, specify USB controllers and USB host devices with usbctrl and usbdev. For example: 

usbctrl=['type=pv,version=2,ports=4', 'type=pv,version=1, ports=4', ]
usbdev=['hostbus=2, hostaddr=1, controller=0,port=1', ]

To hot-plug PVUSB device, use commands usbctrl-attach, usbctrl-detach, usb-list, usbdev-attach and usb-detach. For example: 

#xl usbctrl-attach test_vm version=1 ports=8
This will create a USB controller which is version USB 1.1 and has 8 ports.
    
#xl usb-list test_vm
This will show all USB controllers and USB devices in the domain.
    
#xl usbdev-attach test_vm hostbus=1 hostaddr=2
This will find the first available controller:port in the domain, and attach USB device whose busnum:devnum is 1:2 to it.
One can also specify <code>controller</code> and <code>port</code>.
    
#xl usbdev-detach test_vm 0 1
This will detach USB device under controller 0 port 1.
    
#xl usbctrl-detach test_vm dev_id
This will remove USB controller with the indicated dev_id, and all USB devices under it.

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 introduced since Xen 4.7, including both PVUSB device from config file and PVUSB device hot-plug and un-plug. Currently it supports USB 1.1 and USB 2.0.

From the config file, specify USB controllers and USB host devices with usbctrl and usbdev. For example: 

usbctrl=['type=qusb,version=2,ports=4', 'type=qusb,version=1, ports=4', ]
usbdev=['hostbus=2, hostaddr=1, controller=0,port=1', ]

For type you can specify auto (the default: xl tries to select the most appropriate type), qusb (paravirtualized qemu based backend, should be specified for pvUSB used by HVM domains), pv (paravirtualized kernel based backend, not supported by current standard linux), or devicemodel (qemu emulated USB controller, not yet supported).

You can also specify usbdev only, for example: 

usbdev=['hostbus=2, hostaddr=1, ]

Then it will automatically create a USB controller of version 2.0 and 8 ports, and attach the USB device to the first port of this new controller.

To hot-plug and un-plug PVUSB device, use commands usbctrl-attach, usbctrl-detach, usb-list, usbdev-attach and usbdev-detach. For example: 

#xl usbctrl-attach test_vm version=1 ports=8

This will create a USB controller which is version USB 1.1 and has 8 ports. 

#xl usb-list test_vm

This will show all USB controllers and USB devices in the domain. 

#xl usbdev-attach test_vm hostbus=1 hostaddr=2

This will find the first available controller:port in the domain, and attach USB device whose busnum:devnum is 1:2 to it. One can also specify controller and port. 

#xl usbdev-detach test_vm 0 1

This will detach USB device under controller 0 port 1. 

#xl usbctrl-detach test_vm dev_id

This will remove USB controller with the indicated dev_id, and all USB devices under it.

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=19982"