I am sponsoring this fast-track on behalf of Strony Zhang,
with a timeout set to 08/12/2009. The project desires
minor release binding.
-jg
----------------------------------
Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
VirtualBox USB Device Capture
1.2. Name of Document Author/Supplier:
Author: Strony.Zhang
1.3 Date of This Document:
04 Aug, 2009
4. Technical Description
Background:
The VirtualBox is a virtualization software product. When VirtualBox
runs on Solaris host OS), it should be able to proxy the USB devices
plugged in the host OS to the guest OS depending on user's
configuration. To achieve this, the VirtualBox needs to control the
entire USB device completely and ensure the USB device in the pristine
state for guest OS. No driver in host OS should be attached to the
device. Therefore, the VirtualBox team developed a Monitor driver for
capturing devices using the callback and a VirtualBox-specific USB
client driver for transferring data between guest OS and device.
Problem:
When the USB device is plugged in the Solaris system, usba (7D) will
create the compatible names and then attach the corresponding USB client
driver to it by default. During the process, the VirtualBox doesn't have
a chance to request to attach its own driver to the USB device in which
it is interested.
Solution:
The usba(7D) provides the registration entry to VirtualBox for the
callback and makes the Virtual-specific USB client driver higher
priority than the default USB client driver. When a USB device is
plugged in the system, the usba(7D) will first call the registered
callback function to query if VirtualBox wants to capture the device.
If yes, the VirtualBox-specific USB client driver will be attached to
the device. Once the VirtualBox exits or user doesn't want to access the
USB device on guest OS, the VirtualBox will unregister the callback and
then Solaris will take over the USB device taken by VirtualBox.
Interfaces:
The interfaces are Contracted Project Private since they are intended to
be only used by the VirtualBox.
The following new Interfaces provided by this project:
|-----------------------------------------------------------------------
| Interfaces | Class. | Comments |
|-----------------------------------------------------------------------
| struct usb_dev_str(9s) | C.P.P. | usb capture device info |
| usb_register_dev_driver(9f) | C.P.P | usb capture register |
| usb_unregister_dev_driver(9f) | C.P.P | usb capture unregister |
| usb_dev_driver_callback() | C.P.P | usb capture callback |
|-----------------------------------------------------------------------
They will be available in the <sys/usb/usbai.h>.
/*
* getting the device strings of manufacturer, product and serial number
*/
typedef struct usb_dev_str {
char *usb_mfg; /* manufacturer string */
char *usb_product; /* product string */
char *usb_serialno; /* serial number string */
} usb_dev_str_t;
The callback interface is:
/*
* Return Values:
* USB_SUCCESS - VirtualBox will capture the device
* USB_FAILURE - VirtualBox will not capture the device
*/
typedef int (*usb_dev_driver_callback)(
usb_dev_descr_t *dev_descr, /* ptr to device descriptor */
usb_dev_str_t *dev_str, /* ptr to device strings */
char *path, /* ptr to physical path */
int bus, /* USB bus address */
int port, /* USB port number */
char **drv, /* capture driver name */
void *reserved)
usb_dev_driver_t;
If VirtualBox wants to capture the device, the client driver name
to be attached to the device will be returned by the parameter
(char **drv).
The callback registration and unregistration interfaces are:
int usb_register_dev_driver(dev_info_t *dip, usb_dev_driver_t cb);
void usb_unregister_dev_driver(dev_info_t *dip);
The return value of usb_register_dev_driver() will be USB_SUCCESS
or USB_FAILURE which indicates that the callback registration was
successful or failed.
5. Reference Documents:
PSARC/2000/542 USB Architecture Update project
PSARC/2003/207 USBA2.0: adding USBA interfaces to the DDI
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
