/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License (the "License").
* You may not use this file except in compliance with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/*
* Copyright 2009 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
/*
* Sample skeleton USB driver.
* This driver provides a framework for developing USB client drivers.
*
* As a simplistic example, usbskel implements a data transfer by reading
* raw configuration data, which every USB device has. It is expected that
* the caller will issue an initial 4-byte read to get the total length of the
* first configuration, and follow up with a second read, passing the total
* length to read the entire configuration cloud.
*
* The device has four states (refer to usbai.h):
* USB_DEV_ONLINE: In action or ready for action.
* resume (CPR).
* USB_DEV_SUSPENDED: Device has been suspended along with the system.
* USB_DEV_PWRED_DOWN: Device has been powered down. (Note that this
* driver supports only two power states, powered down and
* full power.)
*
* In order to avoid race conditions between driver entry points,
* access to the device is serialized. Race conditions are an issue in
* particular between disconnect event callbacks, detach, power, open
* and data transfer callbacks. The functions usbskel_serialize/release_access
* are implemented for this purpose.
*
* Mutexes should never be held when making calls into USBA or when
* sleeping.
*
* pm_busy_component and pm_idle_component mark the device as busy or idle to
* the system. These functions are paired, and are called only from code
* bracketed by usbskel_serialize_access and usbskel_release_access.
*
* NOTE: PM and CPR will be enabled at a later release of S10.
*/
#define DEBUG
#endif
#define USBDRV_MINOR_VER 0
/* Uncomment to enable Power Management, when the OS PM framework is ready. */
/*
* #ifndef USBSKEL_PM
* #define USBSKEL_PM
* #endif
*/
/*
* Uncomment to enable Check Point Resume (system suspend and resume) when the
* OS CPR framework is ready.
*/
/*
* #ifndef USBSKEL_CPR
* #define USBSKEL_CPR
* #endif
*/
/*
* Boolean set to whether or not to dump the device's descriptor tree.
* Can be changed with the usblog_dumptree property in a usbskel.conf file.
*/
/*
* Function Prototypes
*/
static int usbskel_strategy(struct buf *);
static void usbskel_minphys(struct buf *);
static int usbskel_disconnect_callback(dev_info_t *);
static int usbskel_reconnect_callback(dev_info_t *);
static int usbskel_cpr_suspend(dev_info_t *);
static void usbskel_cpr_resume(dev_info_t *);
static int usbskel_test_and_adjust_device_state(usbskel_state_t *);
static int usbskel_open_pipes(usbskel_state_t *);
static void usbskel_close_pipes(usbskel_state_t *);
static int usbskel_pm_busy_component(usbskel_state_t *);
static void usbskel_pm_idle_component(usbskel_state_t *);
static int usbskel_power(dev_info_t *, int, int);
#ifdef USBSKEL_PM
static int usbskel_init_power_mgmt(usbskel_state_t *);
static void usbskel_destroy_power_mgmt(usbskel_state_t *);
#endif
static void usbskel_release_access(usbskel_state_t *);
static int usbskel_check_same_device(usbskel_state_t *);
/*PRINTFLIKE3*/
static void usbskel_log(usbskel_state_t *, int, char *, ...);
/* _NOTE is an advice for locklint. Locklint checks lock use for deadlocks. */
/* module loading stuff */
usbskel_open, /* open */
usbskel_close, /* close */
usbskel_strategy, /* strategy */
nulldev, /* print */
nulldev, /* dump */
usbskel_read, /* read */
nodev, /* write */
usbskel_ioctl, /* ioctl */
nulldev, /* devmap */
nodev, /* mmap */
nodev, /* segmap */
nochpoll, /* poll */
ddi_prop_op, /* cb_prop_op */
NULL, /* streamtab */
};
DEVO_REV, /* devo_rev, */
0, /* refcnt */
usbskel_info, /* info */
nulldev, /* identify */
nulldev, /* probe */
usbskel_attach, /* attach */
usbskel_detach, /* detach */
nodev, /* reset */
&usbskel_cb_ops, /* driver operations */
NULL, /* bus operations */
usbskel_power, /* power */
ddi_quiesce_not_needed, /* devo_quiesce */
};
"USB skeleton driver",
};
};
/* local variables */
/* Soft state structures */
static void *usbskel_statep;
/*
* Module-wide initialization routine.
*/
int
_init(void)
{
int rval;
sizeof (usbskel_state_t), USBSKEL_INITIAL_SOFT_SPACE)) != 0) {
return (rval);
}
}
return (rval);
}
/*
* Module-wide tear-down routine.
*/
int
_fini(void)
{
int rval;
return (rval);
}
return (rval);
}
int
{
}
/*
* usbskel_info:
* Get minor number, soft state structure, etc.
*/
/*ARGSUSED*/
static int
{
switch (infocmd) {
case DDI_INFO_DEVT2DEVINFO:
error = DDI_SUCCESS;
}
} else {
}
break;
case DDI_INFO_DEVT2INSTANCE:
error = DDI_SUCCESS;
break;
default:
break;
}
return (error);
}
/*
* usbskel_attach:
* Attach or resume.
*
* For attach, initialize state and device, including:
* state variables, locks, device node
* device registration with system
* power management, hotplugging
* For resume, restore device and state
*/
static int
{
char *devinst;
int devinstlen;
int status;
switch (cmd) {
case DDI_ATTACH:
break;
case DDI_RESUME:
/*
* Always return success to work around enumeration failures.
* This works around an issue where devices which are present
* before a suspend and absent upon resume could cause a system
* panic on resume.
*/
return (DDI_SUCCESS);
default:
return (DDI_FAILURE);
}
}
return (DDI_FAILURE);
}
"usbskel_parse_level", USB_PARSE_LVL_ALL);
switch (parse_level) {
case USB_PARSE_LVL_NONE:
/* This driver needs a tree. */
"parse_level requested to NOT DUMP");
/*FALLTHROUGH*/
case USB_PARSE_LVL_IF:
"parse_level set to dump specific interface");
break;
case USB_PARSE_LVL_CFG:
"parse_level set to dump specific config");
break;
case USB_PARSE_LVL_ALL:
"parse_level set to dump everything");
break;
default:
"attach: parse_level will default to dump everything");
}
USB_SUCCESS) {
"attach: usb_client_attach failed, error code:%d", status);
goto fail;
}
0)) != USB_SUCCESS) {
"attach: usb_get_dev_data failed, error code:%d", status);
goto fail;
}
if (usbskel_dumptree) {
(void) usb_print_descr_tree(
}
/*
* Get the descriptor for an intr pipe at alt 0 of current interface.
* This will be used later to open the pipe.
*/
"attach: Error getting intr endpoint descriptor");
goto fail;
}
/* create minor node */
"usb_skeleton", 0) != DDI_SUCCESS) {
"attach: Error creating minor node");
goto fail;
}
/* Put online before PM init as can get power managed afterward. */
#ifdef USBSKEL_PM
/* initialize power management */
"attach: Could not initialize power mgmt");
}
#endif
goto fail;
}
/* Report device */
return (DDI_SUCCESS);
fail:
if (usbskelp) {
}
return (DDI_FAILURE);
}
/*
* usbskel_detach:
* detach or suspend driver instance
*
* Note: in detach, only contention threads is from pm and disconnnect.
*/
static int
{
switch (cmd) {
case DDI_DETACH:
"Detach: enter for detach");
break;
case DDI_SUSPEND:
"Detach: enter for suspend");
default:
break;
}
}
/*
* usbskel_cleanup:
* clean up the driver state for detach
*/
static int
{
if (usbskelp->usbskel_locks_initialized) {
/* This must be done 1st to prevent more events from coming. */
/*
* At this point, no new activity can be initiated. The driver
* has disabled hotplug callbacks. The Solaris framework has
* disabled new opens on a device being detached, and does not
* allow detaching an open device.
*
* The following ensures that all driver activity has drained.
*/
#ifdef USBSKEL_PM
/* All device activity has died down. */
#endif
/* start dismantling */
}
}
return (USB_SUCCESS);
}
/*ARGSUSED*/
static int
{
int rval = 0;
return (ENXIO);
}
/*
* Keep it simple: one client at a time.
* Exclusive open only
*/
return (EBUSY);
}
/*
* This is in place so that a disconnect or CPR doesn't interfere with
* pipe opens.
*/
return (EINTR);
}
"open: Error raising power");
goto done;
}
/* Fail if device is no longer ready. */
goto done;
}
goto done;
}
/* Device specific initialization goes here. */
done:
if (rval != 0) {
} else {
/* Device is idle until it is used. */
}
return (rval);
}
/*ARGSUSED*/
static int
{
/* Perform device session cleanup here. */
/*
* when they are closed. We can't reset default pipe, but we
* can wait for all requests on it from this dip to drain.
*/
USB_FLAGS_SLEEP, NULL, 0);
return (0);
}
/*ARGSUSED*/
static int
{
usbskel_minphys, uio_p));
}
/*
* strategy:
* Called through physio to setup and start the transfer.
*/
static int
{
int status;
/*
* Initialize residual count here in case transfer doesn't even get
* started.
*/
/* Needed as this is a character driver. */
}
/* Make sure device has not been disconnected. */
"usbskel_strategy: device can't be accessed");
goto fail;
}
/*
* Since every device has raw configuration data, set up a control
* transfer to read the raw configuration data. In a production driver
* a read would probably be done on a pipe other than the default pipe,
* and would be reading data streamed by the device.
*/
/* Allocate and initialize the request. */
NULL) {
"usbskel_read: Error allocating request");
goto fail;
}
/* For now, return only the first configuration. */
request->ctrl_wIndex = 0;
/* Autoclearing automatically set on default pipe. */
/* Hook the req to the bp, so callback knows where to put the data. */
/* Now both bp and request know about each other. */
/*
* Issue the request asynchronously. Physio will block waiting for an
* "interrupt" which comes as a callback. The callback calls biodone
* to release physio from its wait.
*/
USB_SUCCESS) {
"usbskel_strategy: can't start transfer: status: %d",
status);
goto fail;
}
/*
* Normally, usbskel_release_access() and usbskel_pm_idle_component
* is called in callback handler.
*/
return (0);
fail:
return (0);
}
static void
{
/* the config cloud is limited to 64k */
}
}
/*
* usbskel_normal_callback:
* Completion handler for successful transfer.
* Copy data from mblk returned by USBA, into
* buffer passed by physio, to get it back to user.
* Idle device
* update counts, etc.
* release request.
* signal completion via biodone
*/
/*ARGSUSED*/
static void
{
/* Copy data out of mblk, into buffer. */
if (amt_transferred) {
}
"normal callback: transferring %d bytes from 0x%p to 0x%p",
/* Unhook. */
/* Free request. */
/* Finish up. */
}
/*
* usbskel_exception_callback:
* Completion handler for an erred transfer.
* Copy data from mblk returned by USBA, if any, into
* buffer passed by physio, to get it back to user.
* Idle device
* update counts, etc.
* release request.
* signal completion via biodone
*/
/*ARGSUSED*/
static void
{
"at except cb entry, b_bcount = %lu, b_resid = %lu, trans = %d",
/* Copy data, if any, out of mblk, into buffer. */
if (amt_transferred) {
}
"exception cb: req = 0x%p, cr = %d\n\t cb_flags = 0x%x "
"data = 0x%p, amt xfered = %d", (void *)request,
/* Unhook */
/* Free request. */
"at except cb exit, b_bcount = %lu, b_resid = %lu, trans = %d",
}
/*
* XXX Empty ioctl for now.
*/
/*ARGSUSED*/
static int
{
return (ENOTTY);
}
/*
* usbskel_disconnect_callback:
* Called when device hotplug-removed.
* Close pipes. (This does not attempt to contact device.)
* Set state to DISCONNECTED
*/
static int
{
/*
* Save any state of device or IO in progress required by
* usbskel_restore_device_state for proper device "thawing" later.
*/
return (USB_SUCCESS);
}
/*
* usbskel_reconnect_callback:
* Called with device hotplug-inserted
* Restore state
*/
static int
{
return (USB_SUCCESS);
}
/*
* usbskel_restore_device_state:
* Called during hotplug-reconnect and resume.
* reenable power management
* Verify the device is the same as before the disconnect/suspend.
* Restore device state
* Thaw any IO which was frozen.
* Quiesce device. (Other routines will activate if thawed IO.)
* Set device online.
* Leave device disconnected if there are problems.
*/
static void
{
int rval;
"usbskel_restore_device_state: enter");
"usbskel_restore_device_state: Error raising power");
goto fail;
}
/* Check if we are talking to the same device */
goto fail;
}
USB_SUCCESS) {
"usbskel_restore_device_state: "
"Error adjusting device: rval = %d", rval);
goto fail;
}
if (usbskelp->usbskel_pm) {
/* Failure here means device disappeared again. */
USB_SUCCESS) {
"device may or may not be accessible. "
"Please verify reconnection");
}
}
"usbskel_restore_device_state: end");
return;
fail:
/* change the device state from suspended to disconnected */
}
/*
* usbskel_cpr_suspend:
* Clean up device.
* Wait for any IO to finish, then close pipes.
* Quiesce device.
*/
static int
{
instance);
/* Serialize to prevent races with detach, open, device access. */
"suspend: Error raising power");
return (USB_FAILURE);
}
/*
* Set dev_state to suspended so other driver threads don't start any
* new I/O. In a real driver, there may be draining of requests done
* afterwards, and we don't want the draining to compete with new
* requests being queued.
*/
/* Don't suspend if the device is open. */
"suspend: Device is open. Can't suspend");
return (USB_FAILURE);
}
/* Access device here to clean it up. */
/*
* Save any state of device required by usbskel_restore_device_state
* for proper device "thawing" later.
*/
return (USB_SUCCESS);
}
/*
* usbskel_cpr_resume:
*
* usbskel_restore_device_state marks success by putting device back online
*/
static void
{
instance);
/*
* NOTE: A pm_raise_power in usbskel_restore_device_state will bring
* the power-up state of device into synch with the system.
*/
}
/*
* usbskel_test_and_adjust_device_state:
* Place any device-specific initialization or sanity verification here.
*/
static int
{
return (USB_SUCCESS);
}
/*
* usbskel_open_pipes:
* Open any pipes other than default pipe.
* Mutex is assumed to be held.
*/
static int
{
/*
* Allow that pipes can support at least two asynchronous operations
* going on simultaneously. Operations include asynchronous callbacks,
* resets, closures.
*/
"usbskel_open_pipes: Error opening intr pipe: status = %d",
rval);
rval = USB_FAILURE;
}
/*
* At this point, polling could be started on the pipe by making an
* asynchronous input request on the pipe. Allocate a request by
* calling usb_alloc_intr_req(9F) with a zero length, initialize
* attributes with USB_ATTRS_SHORT_XFER_OK | USB_ATTRS_AUTOCLEARING,
* initialize length to be packetsize of the endpoint, specify the
* callbacks. Pass this request to usb_pipe_intr_xfer to start polling.
* Call usb_pipe_stop_intr_poling(9F) to stop polling.
*/
return (rval);
}
/*
* usbskel_close_pipes:
* Close pipes. Mutex is assumed to be held.
*/
/*ARGSUSED*/
static void
{
if (usbskelp->usbskel_intr_ph) {
USB_FLAGS_SLEEP, NULL, 0);
}
}
static int
{
DDI_SUCCESS) {
(void) pm_raise_power(
} else {
rval = DDI_FAILURE;
}
}
return (rval);
}
static void
{
DDI_SUCCESS) {
}
"usbskel_pm_idle_component: %d",
}
}
/*
* usbskel_power :
* Power entry point, the workhorse behind pm_raise_power, pm_lower_power,
* usb_req_raise_power and usb_req_lower_power.
*/
/* ARGSUSED */
static int
{
"usbskel_power: enter: level = %d", level);
/*
* If we are disconnected/suspended, return success. Note that if we
* return failure, bringing down the system will hang when
* PM tries to power up all devices
*/
"usbskel_power: disconnected/suspended "
rval = USB_SUCCESS;
goto done;
}
goto done;
}
/* Check if we are transitioning to a legal power level */
"usbskel_power: illegal power level = %d "
goto done;
}
switch (level) {
case USB_DEV_OS_PWR_OFF :
/* fail attempt to go to low power if busy */
if (pm->usbskel_pm_busy) {
goto done;
}
} else {
rval = USB_SUCCESS;
}
break;
case USB_DEV_OS_FULL_PWR :
/*
* PM framework tries to put us in full power during system
* shutdown.
*/
break;
/* Levels 1 and 2 are not supported by this driver to keep it simple. */
default:
"usbskel_power: power level %d not supported", level);
break;
}
done:
}
#ifdef USBSKEL_PM
/*
* usbskel_init_power_mgmt:
* Initialize power management and remote wakeup functionality.
* No mutex is necessary in this function as it's called only by attach.
*/
static int
{
/*
* If remote wakeup is not available you may not want to do
* power management.
*/
/* Allocate the state structure */
if ((rval = usb_create_pm_components(
"usbskel_init_power_mgmt: created PM components");
(void) pm_raise_power(
} else {
"usbskel_init_power_mgmt: create_pm_compts failed");
}
} else {
"usbskel_init_power_mgmt: failure enabling remote wakeup");
}
return (rval);
}
/*
* usbskel_destroy_power_mgmt:
* Shut down and destroy power management and remote wakeup functionality.
*/
static void
{
if (usbskelp->usbskel_pm) {
(void) usbskel_pm_busy_component(usbskelp);
int rval;
if ((rval = usb_handle_remote_wakeup(
USB_SUCCESS) {
"usbskel_destroy_power_mgmt: "
"Error disabling rmt wakeup: rval = %d",
rval);
}
} else {
}
/*
* Since remote wakeup is disabled now,
* no one can raise power
* and get to device once power is lowered here.
*/
}
}
#endif
/*
* usbskel_serialize_access:
* Get the serial synchronization object before returning.
*
* Arguments:
* usbskelp - Pointer to usbskel state structure
* waitsig - Set to:
* USBSKEL_SER_SIG - to wait such that a signal can interrupt
* USBSKEL_SER_NOSIG - to wait such that a signal cannot interrupt
*/
static int
{
while (usbskelp->usbskel_serial_inuse) {
if (waitsig == USBSKEL_SER_SIG) {
} else {
}
}
return (rval);
}
/*
* usbskel_release_access:
* Release the serial synchronization object.
*/
static void
{
}
/*
* usbskel_check_same_device:
* Check if the device connected to the port is the same as
* the previous device that was in the port. The previous device is
* represented by the dip on record for the port. Print a message
* if the device is different. Can block.
*
* return values:
* USB_SUCCESS: same device
* USB_INVALID_VERSION not same device
* USB_FAILURE: Failure processing request
*/
static int
{
int rval;
char *buf;
USB_REQ_GET_DESCR, /* bRequest */
USB_DESCR_TYPE_SETUP_DEV, /* wValue */
0, /* wIndex */
USB_DEV_DESCR_SIZE, /* wLength */
0 /* request attributes */
};
/* get the "new" device descriptor */
if (rval != USB_SUCCESS) {
"usbskel_check_same_device: "
"getting device descriptor failed "
"rval=%d, cr=%d, cb=0x%x\n",
return (USB_FAILURE);
}
sizeof (usb_dev_descr_t));
/* Always check the device descriptor length. */
/* Always check the device descriptor. */
} else if (bcmp(orig_usb_dev_descr,
(char *)&usb_dev_descr, USB_DEV_DESCR_SIZE) != 0) {
}
/* if requested & this device has a serial number check and compare */
USB_MAXSTRINGLEN) == USB_SUCCESS) {
match =
}
}
"Device is not identical to the "
"previous one this port.\n"
"Please disconnect and reconnect");
return (USB_INVALID_VERSION);
}
return (USB_SUCCESS);
}
/*
* usbskel_log:
* Switchable logging to logfile and screen.
*
* Arguments:
* usbskelp: usbskel state pointer.
* if NULL, driver name and instance won't print with the message
* msglevel:
* if USBSKEL_LOG_LOG, goes only to logfile.
* (usbskel_errlevel must be set to USBSKEL_LOG_LOG too.)
* if USBSKEL_LOG_CONSOLE, goes to both logfile and screen
* (usbskel_errlevel can be either value for this to work.)
* cmn_err_level: error level passed to cmn_err(9F)
* format and args: as you would call cmn_err, except without special
* first routing character.
*
* Do not call this in an interrupt context, since kmem_alloc can sleep.
*/
static void
{
if (msglevel <= usbskel_errlevel) {
char *format;
int devinst_start = 0;
/* Allocate extra room if driver name and instance is present */
}
if (msglevel == USBSKEL_LOG_LOG) {
format[0] = '!';
devinst_start = 1;
}
}
}
}