[Xen-devel] [PATCH V3 0/6] libxl pvusb toolstack work

[Chunyan Liu <cyliu@xxxxxxxx>]

This patch series is to add pvusb toolstack work, supporting hot add|remove
USB device to|from guest and specify USB device in domain configuration file.

1/6~5/6 implement clean pvusb work. 6/6 is an independent patch to refactor
codes for merging QEMU emulated USB code later.

1/6 is to export some functions for later usage
2/6 fixes read_file_content limit when reading sysfs file, for later usage.
3/6 libxl pvusb API implementation
4/6 xl pvusb hotplug commands implementation
5/6 usb from config file implementation
6/6 changing codes to unify qemu and pvusb.

Changes to v2:
* change xl interfaces from specifing usb device by busid to specifing
  usb device by bus.addr, so that pvusb and qemu can use same interface
* remove usb-assignable-list interface
* call existing helper functions to read sysfs file content to get usb
  device info.
* reorganize patches, first implement clean pvusb work, then in last
  patch changing codes for pvusb and qemu merging.
* Many fixes to address coding style, build on different platform, etc.
  Codes adjustment to better view.

V2 is here:
http://lists.xen.org/archives/html/xen-devel/2015-01/threads.html#03636

Related Discussion Threads:
http://www.redhat.com/archives/libvir-list/2014-June/msg00038.html
http://lists.xen.org/archives/html/xen-devel/2014-06/msg00086.html

For a better understanding, a summary is posted in following.

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

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

Additionally, for easy use of PVUSB, you need support in the toolstack
to get the two sides to talk to each other.

2. Specifying a host USB device

QEMU hmp commands allows USB devices to be 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. 

To avoid duplication of vendorid:deviceid, we'll use bus address to
specify host USB device in xl toolstack.

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
1.6 (remove leading zeroes).

Note: USB Hub could not be assigned to guest.

3. PVUSB toolstack

* Specify USB device in xl config file

You can just specify usb devices, like:
usb=['1.6']

Then it will create a USB controller automatically and attach the USB
device to the first available USB controller:port.

or, you can explicitly specify usb controllers and usb devices, like:
usbctrl=['verison=1, ports=4', 'version=2, ports=8', ]
usb=['1.6, controller=0, port=1']

Then it will create two USB controllers as you specified.
And if controller and port are specified in usb config, then it will
attach the USB device to that controller:port. About the controller
and port value:
Each USB controller has a index (or called devid) based on 0. The 1st
controller has index 0, the 2nd controller has index 1, ...
Under controller, each port has a port number based on 1. In above
configuration, the 1st controller will have port 1,2,3,4.

To be compatible with QEMU emulated USB, this interface could be
extended to:
usb=['1.6, type=pv|qemu',]
type=pv means attaching the USB device in pvusb way; type=qemu means
attaching USB device in QEMU emulated way.

* Hot-Plug USB device

To attach a USB device, you should first create a USB controller.
e.g.
xl usb-ctrl-attach domain [version=1|2] [ports=value]
By default, it will create a USB2.0 controller with 8 ports.

Then you could attach a USB device.
e.g.
xl usb-attach domain 1.6 [controller=index port=number]
By default, it will find the 1st available controller:port to attach
the USB device.

You could view USB device status of the domain by usb-list.
e.g.
xl usb-list domain
It will list USB controllers and USB devices under each controller.

You could detach a USB device with usb-detach command.
e.g.
xl usb-detach domain 1.6

You can also remove the whole USB controller by usb-ctrl-detach
command.
e.g.
xl usb-ctrl-detach domain 0
It will remove the USB controller with index 0 and all USB devices
under it.

To be compatible with QEMU emulated USB, these interfaces could be
extended to:
xl usb-attach domain 1.6 type=pv|qemu
xl usb-detach domain 1.6 type=pv|qemu
QEMU emulated USB won't handle USB controller create/delete through
xl, so usb-ctrl-attach|detach operations are currently pvusb only.

4. PVUSB Libxl implementation

* usb-ctrl-attach
To create a usb controller, we need:
1) generate usb controler related information
2) write usb controller frontend/backend info to xenstore
PVUSB frontend and backend driver will probe xenstore paths and build
connection between frontend and backend.

* usb-ctrl-detach
To remove a usb controller, we need:
1) check if the usb controller exists or not
2) remove all usb devices under controller
3) remove usb controller info from xenstore

* usb-attach
To attach a usb device, we need:
1) check if the usb device type is assignable
2) check if the usb device is already assigned to a domain
3) add 'busid' of the usb device to xenstore contoller/port/.
   PVUSB driver watches the xenstore changes and detects that,
   and needs to use 'busid' to do following work.
4) unbind usb device from original driver and bind to usbback.
   If usb device has many interfaces, then:
   - unbind each interface from its original driver and bind to usbback.
   - store the original driver to xenstore for later rebinding when
     detaching the device.

* usb-detach
To detach a usb device, we need:
1) check if the usb device is assigned to the domain
2) remove the usb device from xenstore controller/port.
3) unbind usb device from usbback and rebind to its original driver.
   If usb device has many interfaces, do it to each interface.

* usb-list
List all USB controllers and USB devices under each controller.


Chunyan Liu (6):
  libxl: export some functions for pvusb use
  libxl_read_file_contents: fix reading sysfs file
  libxl: add pvusb API
  xl: add pvusb commands
  domcreate: support pvusb in configuration file
  refactor codes to unify pvusb and qemu emulated usb

 docs/man/xl.cfg.pod.5                |   70 +++
 docs/man/xl.pod.1                    |   38 ++
 tools/libxl/Makefile                 |    2 +-
 tools/libxl/libxl.c                  |    8 +-
 tools/libxl/libxl.h                  |   45 ++
 tools/libxl/libxl_create.c           |   73 ++-
 tools/libxl/libxl_internal.h         |   20 +-
 tools/libxl/libxl_osdeps.h           |   13 +
 tools/libxl/libxl_pvusb.c            | 1042 ++++++++++++++++++++++++++++++++++
 tools/libxl/libxl_types.idl          |   52 ++
 tools/libxl/libxl_types_internal.idl |    1 +
 tools/libxl/libxl_usb.c              |  224 ++++++++
 tools/libxl/libxl_utils.c            |    5 +-
 tools/libxl/xl.h                     |    5 +
 tools/libxl/xl_cmdimpl.c             |  364 +++++++++++-
 tools/libxl/xl_cmdtable.c            |   25 +
 16 files changed, 1974 insertions(+), 13 deletions(-)
 create mode 100644 tools/libxl/libxl_pvusb.c
 create mode 100644 tools/libxl/libxl_usb.c

-- 
1.8.5.2


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel