[Xen-devel] [RFC][PATCH 0/4] PVUSB: add paravirtualized USB support for Xen

[Noboru Iwamatsu <n_iwamatsu@xxxxxxxxxxxxxx>]

Hi,

This patch series adds the paravirtualized USB (PVUSB) support that I
gave a presentation on the last Xen Summit at Oracle.
http://www.xen.org/files/xensummit_oracle09/PVUSB.pdf

After the last summit, I finished the device disconnection functions
and removed the critical issues.

The following patches can be applied to the linux-2.6.18-xen.hg tree.

The PVUSB has no xend support yet, but I prepared the simple
shell-script for setting up and initializing the XenStore entries.

Please read attached README.txt and use init_xs.sh.

Thanks,

Noboru

Signed-off-by: Noboru Iwamatsu <n_iwamatsu@xxxxxxxxxxxxxx>

Paravirtualized USB trivial Document

Noboru Iwamatsu <n_iwamatsu@xxxxxxxxxxxxxx>
16th Mar. 2009


Kernel config options
========================
1) First, you need to make USB work correctly.

   Enable USB support and choose the proper HCD.
   You can select ether [*] built-in or <M> module.

        MAIN MENU -> Device Drivers -> USB support ->
                <M> Support for Host-side USB
                ---     USB Host Controller Drivers
                <M> EHCI HCD (USB 2.0) support
                <M> OHCI HCD support
                <M> UHCI HCD (most Intel and VIA) support
        
        After selecting the above options, then select drivers
        for the USB peripherals you'll be using.
        
        You need not select the USB peripherals drivers for
        the backend, moreover, you should not select the USB
        peripherals drivers as [*] built-in in the backend.
        Built-in USB peripherals drivers always have a priority
        to      claim the attached device, so that device       cannot be
        assigned to the guest domain.
        
2) Options for the backend (domain 0)  
        MAIN MENU -> XEN ->
                [*] Privileged Guest (domain 0)
                <M> Backend driver support
                <M>     USB backend driver

3) Options for the frontend (guest domain)  
        MAIN MENU -> XEN ->
                <M> USB frontend driver
                [*]     Taking the HCD statistics (for debug)


Modules
========
usbback:
/lib/modules/<`uname -r`>/kernel/drivers/xen/usbback/usbbk.ko

usbfront:
/lib/modules/<`uname -r`>/kernel/drivers/xen/usbfront/xen-hcd.ko


How to use
============
Current PVUSB has no xend support :-)
So, you have to manually setup the xenstore entries and the hotplug rule.

Setup:
- loading the modules.
        # modprobe usbbk                (in the backend)
        # modprobe xen-hcd      (in the frontend)

- Setup and initialize the XenStore
        Example.
        # ./init_xs.sh 1 0      (for the domid 1)


Hotplug:
1) First, you have to start from the state that no device is connected.
   And, if any usb device driver other than "usbbk.ko" are loaded in 
   the backend, you should remove the modules.
    (e.g.
        If usb-storage or usbhid is loaded, you should do the following.
        # rmmod usb-storage
        # rmmod usbhid
        )

2) Write the hotplug-rule through the sysfs interface of the backenend driver.

 - The hotplug-rule format
 
   <usbbusname>:<domid>:<vusb number>:<port number>
 
   "usbbusname" is the combination of the USB Bus number and the port number.
   It's a quite complex thing, but when the new device connected, you can see
   this number in the kernel messages.
   
   Example of usbbusname:
   # dmesg
   ...
        usb 4-1: new low speed USB device using uhci_hcd and address 2
        usb 4-1: configuration #1 chosen from 1 choice
            ^^^^^
            (this means USB Bus number #4 and root port number #1)
   ...

 - Setting the hotplug-rule
        /sys/bus/usb/drivers/usbback/new_vport is the sysfs path for
        setting the hotplug-rules.
 
        Example:
        # echo 1-2.3:1:0:3 > /sys/bus/usb/drivers/usbback/new_vport
        # echo 1-4:2:0:1 > /sys/bus/usb/drivers/usbback/new_vport
        # echo 4-1:2:0:2 > /sys/bus/usb/drivers/usbback/new_vport

 - Show the current hotplug-rules
        /sys/bus/usb/drivers/usbback/vports shows you current hotplug-rules.

        Example:
        # cat /sys/bus/usb/drivers/usbback/vports
        1-2.3:1:0:3
        1-4:2:0:1
        4-1:2:0:2

 - Remove hotplug-rule
        /sys/bus/usb/drivers/usbback/remove_vport is the sysfs path for
        removing the hotplug-rules.
        
        Example:
        # echo 1-4:2:0:1 > /sys/bus/usb/drivers/usbback/remove_vport

3) Plug the device.
        Plug the USB device to the appropriate port that wrote in the
        hotplug-rule.
        If the device is successfuly claimed by the backend driver, you
        can see the claimed USB interfaces through the sysfs.
        
        Example:
        # cat /sys/bus/usb/drivers/usbback/grabbed_devices
        1-4:1.0

        If the backend driver failed to claim the device, and other driver
        got the device, there is a pssibility that udev got in the way of
        the backend driver's probing.
        In order to avoid the execution of events from udevd, you should
        temporarily stop the udevd while plugging the device. 

        Example:
        # udevcontrol stop_exec_queue   (stop)
        ...
         plug the device
        ...
        # udevcontrol start_exec_queue  (restart)



Known issues
==============
- Webcams not works, other Isoc devices not tested.


Tested environment
======================
Fujitsu CELSIUS Workstation N450:
        CPU:            Intel(R) Core 2 Duo E6700 (2.66GHz)
        Chipset:        Intel 975X Express
        RAM:            4GB

Xen:
        Xen:            3.3.0, x86_64
        kernel:         linux-2.6.18-xen (c/s 806), x86_64
        OS:             CentOS 5.2, x86_64

Number of the guest domain:     1
VCPU assignment:        dom0 (CPU0, CPU1), domU (CPU1)


XenStore Reference
=====================

/local/domain/<domid>
                backend/
                        vusb/                           - a directory 
containing vusb backends
                                <domid>/                - a directory vusb's 
for domid
                                        <id>/                   - a directory 
for each virtual host controller
                                                frontend-id     - the domain id 
of the frontend
                                                frontend                - the 
path to the frontend domain
                                                num-ports               - 
number of the root ports (max. 16)
                                                port-1                  - the 
port connection status
                                                ...                             
        0=disconnected, 1=low_speed, 2=full_speed, 3= high_speed
                                                port-16
                                                state                   - 
communication state across XenBus to the frontend.
                device/
                        vusb/                           - a directory 
containing the virtual hcd
                                <id>/                           - a directory 
containing the virtual hcd id for the domain
                                        backend-id              - the domain id 
of the backend
                                        backend                 - the path to 
the backend domain
                                        ring-ref                        - the 
grant table reference for the usb request ring queue
                                        event-channel           - the event 
channel used for the usb request ring queue
                                        state                           - 
communication state across XenBus to the backend.



Sysfs Reference
==================

usbback:
/sys/bus/usb/drivers/usbback/
                                grabbed_devices         - devices that be 
claimed usbback driver. 
                                new_vport                               - the 
path to set the new hotplug-rule
                                remove_vport                    - the path to 
remove the hotplug-rule
                                vports                                  - show 
the current hotplug-rules

usbfront:
/syb/class/usb/usb_host/usb_host<bus number>/
                                statistics                      - show the 
statistics and the debbuging informations

#!/bin/sh
#
# Setup XenStore entry for paravirtualized USB driver.
# 
# Written by Noboru Iwamatsu <n_iwamatsu@xxxxxxxxxxxxxx>
#

XSWRITE=/usr/bin/xenstore-write
XSCHMOD=/usr/bin/xenstore-chmod

DEV_NAME=vusb
# Max 16 ports.
NUM_PORTS=8

usage () {
    echo "Usage: `basename $0` <frontend-id> <device-id>"
    echo "    <frontend-id>: the domain id of frontend"
    echo "    <device-id>: the device id of frontend"
    echo ""
    echo "Example:"
    echo "    If you use paravirtual USB driver on Domain ID 1,"
    echo "    simply do"
    echo "    `basename $0` 1 0"
    exit 1
}

[ $# -eq 2 ] || usage

DEV_ID=$2

# Write backend information into the location that frontend look for.
$XSWRITE /local/domain/$1/device/$DEV_NAME/$DEV_ID/backend-id 0
$XSWRITE /local/domain/$1/device/$DEV_NAME/$DEV_ID/backend \
/local/domain/0/backend/$DEV_NAME/$1/$DEV_ID

# Write frontend information into the location that backend look for.
$XSWRITE /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/frontend-id $1
$XSWRITE /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/frontend \
/local/domain/$1/device/$DEV_NAME/$DEV_ID

# Write virtual root hub field.
$XSWRITE /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/num-ports $NUM_PORTS
for i in $(seq 1 $NUM_PORTS)
do
        # Set all port to disconnected state
        $XSWRITE /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/port-$i "0"
done

# Set permission
$XSCHMOD /local/domain/$1/device/$DEV_NAME/$DEV_ID n$1 r0
$XSCHMOD /local/domain/$1/device/$DEV_NAME/$DEV_ID/backend-id n$1 r0
$XSCHMOD /local/domain/$1/device/$DEV_NAME/$DEV_ID/backend n$1 r0
$XSCHMOD /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID n0 r$1
$XSCHMOD /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/frontend-id n0 r$1
$XSCHMOD /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/frontend n0 r$1
$XSCHMOD /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/num-ports n0 r$1
for i in $(seq 1 $NUM_PORTS)
do
        $XSCHMOD /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/port-$i n0 r$1
done

# Set state to XenbusStateInitialising
$XSWRITE /local/domain/$1/device/$DEV_NAME/$DEV_ID/state 1
$XSCHMOD /local/domain/$1/device/$DEV_NAME/$DEV_ID/state n$1 r0
$XSWRITE /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/state 1
$XSCHMOD /local/domain/0/backend/$DEV_NAME/$1/$DEV_ID/state n0 r$1

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel