Xen USB Passthrough

From Xen
Jump to navigationJump to search

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"