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

[Noboru Iwamatsu <n_iwamatsu@jp.fujitsu.com>]

[-- Attachment #1: Type: text/plain, Size: 617 bytes --]

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@jp.fujitsu.com>


[-- Attachment #2: README.txt --]
[-- Type: text/plain, Size: 5911 bytes --]

Paravirtualized USB trivial Document

Noboru Iwamatsu <n_iwamatsu@jp.fujitsu.com>
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


[-- Attachment #3: init_xs.sh --]
[-- Type: text/plain, Size: 2242 bytes --]

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

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

[-- Attachment #4: Type: text/plain, Size: 138 bytes --]

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