usbai.h revision a7df97bafe5a886e6ddb3fe8170b2d547cd3b029
/*
* 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.
*/
#ifndef _SYS_USB_USBAI_H
#define _SYS_USB_USBAI_H
#ifdef __cplusplus
extern "C" {
#endif
/* This header file is for USBA2.0 */
#define USBA_MAJOR_VER 2
#define USBA_MINOR_VER 0
/*
* USBAI: Interfaces Between USBA and Client Driver
*
*
* Universal USB device state management :
*
* PWRED_DWN---<3----4>--ONLINE---<2-----1>-DISCONNECTED
* | ^ |
* | 6 |
* | | |
* | 5 |
* | v |
* +----5>----------SUSPENDED----<5----7>---+
*
* 1 = Device Unplug
* 2 = Original Device reconnected
* 3 = Device idles for time T & transitions to low power state
* 4 = Remote wakeup by device OR Application kicking off IO to device
* 5 = Notification to save state prior to DDI_SUSPEND
* 6 = Notification to restore state after DDI_RESUME with correct device
* 7 = Notification to restore state after DDI_RESUME with device
* disconnected or a wrong device
*
* NOTE: device states 0x80 to 0xff are device specific and can be
* used by client drivers
*/
/*
* ***************************************************************************
* USBA error and status definitions
* ***************************************************************************
*/
/*
* USBA function return values
*/
#define USB_SUCCESS 0 /* call success */
/*
* USB request completion flags, more than one may be set.
* The following flags are returned after a recovery action by
* HCD or USBA (autoclearing) or callbacks from pipe_close,
* abort, reset, or stop polling. More than one may be set.
*
* For sync requests, the client should check the request structure
* for this flag to determine what has happened.
*
* All callbacks are queued to preserve order. Note that if a normal callback
* uses a kernel thread, order is not guaranteed since each callback may use
* its own thread. The next request will be submitted to the
* HCD after the threads exits.
*
* Exception callbacks using a kernel thread may do auto clearing and no
* new request will be started until this thread has completed its work.
*/
typedef enum {
/* to HCD which rejected it */
/*
* completion reason
*
* Set by HCD; only one can be set.
*/
typedef enum {
USB_CR_OK = 0, /* no errors detected */
} usb_cr_t;
/*
* ***************************************************************************
* General definitions, used all over
* ***************************************************************************
*
* A pipe handle is returned by usb_pipe_open() on success for
* all pipes except the default pipe which is accessed from
* the registration structure. Placed here as forward referenced by
* usb_client_dev_data_t below.
*
* The pipe_handle is opaque to the client driver.
*/
typedef struct usb_pipe_handle *usb_pipe_handle_t;
/*
* General opaque pointer.
*/
typedef struct usb_opaque *usb_opaque_t;
/*
* USB flags argument to USBA interfaces
*/
typedef enum {
/* do not block until resources are available */
USB_FLAGS_NOSLEEP = 0x0000,
/* block until resources are available */
USB_FLAGS_SLEEP = 0x0100,
/* reserved */
USB_FLAGS_RESERVED = 0xFE00
} usb_flags_t;
/*
* ***************************************************************************
* Descriptor definitions (from USB 2.0 specification, chapter 9)
* ***************************************************************************
*/
/*
* USB Descriptor Management
*
* Standard USB descriptors:
*
* USB devices present their configuration information in response to
* a GET_DESCRIPTOR request in a form which is little-endian and,
* for multibyte integers, unaligned. It is also position-dependent,
* which makes non-sequential access to particular interface or
* endpoint data inconvenient.
* A GET_DESCRIPTOR request may yield a chunk of data that contains
* multiple descriptor types. For example, a GET_DESCRIPTOR request
* for a CONFIGURATION descriptor could return the configuration
* descriptor followed by an interface descriptor and the relevant
* endpoint descriptors.
*
* usb_get_dev_data() interface provides an easy way to get all
* the descriptors and avoids parsing standard descriptors by each
* client driver
*
* usb_dev_descr:
* usb device descriptor, refer to USB 2.0/9.6.1,
*/
typedef struct usb_dev_descr {
/*
* USB Device Qualifier Descriptor
*
* The device_qualifier descriptor describes information about a High
* speed capable device that would change if the device were operating
* at other (Full) speed. Example: if the device is currently operating
* at Full-speed, the device_qualifier returns information about how if
* would operate at high-speed and vice-versa.
*
* usb_dev_qlf_descr:
*
* usb device qualifier descriptor, refer to USB 2.0/9.6.2
*/
typedef struct usb_dev_qlf_descr {
/*
* usb_cfg_descr:
* usb configuration descriptor, refer to USB 2.0/9.6.3
*/
typedef struct usb_cfg_descr {
/*
* Default configuration index setting for devices with multiple
* configurations. Note the distinction between config index and config
* number
*/
#define USB_DEV_DEFAULT_CONFIG_INDEX 0
/*
* bmAttribute values for Configuration Descriptor
*/
#define USB_CFG_ATTR_SELFPWR 0x40
#define USB_CFG_ATTR_REMOTE_WAKEUP 0x20
#define USB_CFG_ATTR_BAT_PWR 0x10
/*
* USB Other Speed Configuration Descriptor
*
* The other_speed_configuration descriptor describes a configuration of
* a High speed capable device if it were operating at its other possible
* (Full) speed and vice-versa.
*
* usb_other_speed_cfg_descr:
* usb other speed configuration descriptor, refer to USB 2.0/9.6.4
*/
typedef struct usb_other_speed_cfg_descr {
/*
* usb_ia_descr:
* usb interface association descriptor, refer to USB 2.0 ECN(IAD)
*/
typedef struct usb_ia_descr {
/*
* usb_if_descr:
* usb interface descriptor, refer to USB 2.0/9.6.5
*/
typedef struct usb_if_descr {
/*
* usb_ep_descr:
* usb endpoint descriptor, refer to USB 2.0/9.6.6
*/
typedef struct usb_ep_descr {
/*
* bEndpointAddress masks
*/
/*
* bmAttribute transfer types for endpoints
*/
/*
* bmAttribute synchronization types for endpoints (isochronous only)
*/
/*
* bmAttribute synchronization feedback types for endpoints (isochronous only)
*/
/*
* wMaxPacketSize values for endpoints (isoch and interrupt, high speed only)
*/
/*
* Ranges for endpoint parameter values.
*/
/* Min and Max NAK rates for high sped control endpoints. */
#define USB_EP_MIN_HIGH_CONTROL_INTRVL 0
#define USB_EP_MAX_HIGH_CONTROL_INTRVL 255
/* Min and Max NAK rates for high speed bulk endpoints. */
#define USB_EP_MIN_HIGH_BULK_INTRVL 0
#define USB_EP_MAX_HIGH_BULK_INTRVL 255
/* Min and Max polling intervals for low, full speed interrupt endpoints. */
#define USB_EP_MIN_LOW_INTR_INTRVL 1
#define USB_EP_MAX_LOW_INTR_INTRVL 255
#define USB_EP_MIN_FULL_INTR_INTRVL 1
#define USB_EP_MAX_FULL_INTR_INTRVL 255
/*
* Min and Max polling intervals for high speed interrupt endpoints, and for
* isochronous endpoints.
* Note that the interval is 2**(value-1). See Section 9.6.6 of USB 2.0 spec.
*/
#define USB_EP_MIN_HIGH_INTR_INTRVL 1
#define USB_EP_MAX_HIGH_INTR_INTRVL 16
#define USB_EP_MIN_FULL_ISOCH_INTRVL 1
#define USB_EP_MAX_FULL_ISOCH_INTRVL 16
#define USB_EP_MIN_HIGH_ISOCH_INTRVL 1
#define USB_EP_MAX_HIGH_ISOCH_INTRVL 16
/*
* usb_string_descr:
* usb string descriptor, refer to USB 2.0/9.6.7
*/
typedef struct usb_string_descr {
/* encoded string */
/*
* usb_bos_descr:
* usb BOS descriptor, refer to WUSB 1.0/7.4.1
*/
typedef struct usb_bos_descr {
/*
* usb_dev_cap_header:
* usb device capability descriptor header, refer to WUSB 1.0/7.4.1
*/
typedef struct usb_cap_descr_header {
typedef struct usb_cap_descr {
#define USB_CAP_TYPE_WUSB 1
/* Wireless USB device capability descriptor - UWB descriptor */
typedef struct usb_uwb_cap_descr {
/*
* usb_ep_comp_descr:
* usb endpoint companion descriptor, refer to WUSB 1.0/7.4.4
*/
typedef struct usb_ep_comp_descr {
/*
* usb_security_descr:
* usb security descriptor, refer to WUSB 1.0/7.4.5
*/
typedef struct usb_security_descr {
/*
* usb_encryption_descr:
* usb encryption descriptor, refer to WUSB 1.0/7.4.5
*/
typedef struct usb_encryption_descr {
#define USB_ENC_TYPE_UNSECURE 0x00
#define USB_ENC_TYPE_WIRED 0x01
#define USB_ENC_TYPE_CCM_1 0x02
#define USB_ENC_TYPE_RSA_1 0x03
/*
* usb_key_descr:
* usb key descriptor, refer to WUSB 1.0/7.4.5
*/
typedef struct usb_key_descr {
#define USB_EP_COMP_DESCR_SIZE 10
#define USB_BOS_DESCR_SIZE 5
#define USB_CAP_DESCR_HEADER_SIZE 3
#define USB_UWB_CAP_DESCR_SIZE 11
#define USB_SECURITY_DESCR_SIZE 5
#define USB_ENCRYPTION_DESCR_SIZE 5
/*
* ***************************************************************************
* Client driver registration with USBA
* ***************************************************************************
*
* The client registers with USBA during attach in two steps
* using usb_client_attach() and usb_get_dev_data(). On completion, the
* registration data has been initialized. Most data items are
* straightforward. Among the items returned in the data is the tree of
* parsed descriptors, in dev_cfg; the number of configurations parsed,
* in dev_n_cfg; a pointer to the current configuration in the tree,
* in dev_curr_cfg; the index of the first valid interface in the
* tree, in dev_curr_if, and a parse level that accurately reflects what
* is in the tree, in dev_parse_level.
*/
/*
* ***************************************************************************
* Data structures used in the configuration tree
* ***************************************************************************
*/
/*
* Tree data structure for each configuration in the tree
*/
typedef struct usb_cfg_data {
/* indexed by interface num */
char *cfg_str; /* string descriptor */
/*
* Tree data structure for each alternate interface set
* in each represented configuration
*/
typedef struct usb_if_data {
/* indexed by alt setting */
/*
* Tree data structure for each alternate of each alternate interface set
*/
typedef struct usb_alt_if_data {
/* (not a sparse array */
char *altif_str; /* string descriptor */
/*
* Tree data structure for each endpoint of each alternate
*/
typedef struct usb_ep_data {
/*
*/
typedef struct usb_cvs_data {
/*
* Data structure for wireless USB specific descriptor
*/
typedef struct usb_bos_data {
/*
* Parse_level determines the extent to which the tree is built, the amount
* of parsing usb_client_attach() is to do. It has the following values:
*
* USB_PARSE_LVL_NONE - Build no tree. dev_n_cfg will return 0, dev_cfg
* will return NULL, the dev_curr_xxx fields will be
* invalid.
* USB_PARSE_LVL_IF - Parse configured interface only, if configuration#
* and interface properties are set (as when different
* interfaces are viewed by the OS as different device
* instances). If an OS device instance is set up to
* represent an entire physical device, this works
* like USB_PARSE_LVL_ALL.
* USB_PARSE_LVL_CFG - Parse entire configuration of configured interface
* only. This is like USB_PARSE_LVL_IF except entire
* configuration is returned.
* USB_PARSE_LVL_ALL - Parse entire device (all configurations), even
* when driver is bound to a single interface of a
* single configuration.
*/
typedef enum {
USB_PARSE_LVL_NONE = 0,
USB_PARSE_LVL_IF = 1,
USB_PARSE_LVL_CFG = 2,
/*
* Registration data returned by usb_get_dev_data(). Configuration tree roots
* are returned in dev_cfg array.
*/
typedef struct usb_client_dev_data {
char *dev_mfg; /* manufacturing ID */
char *dev_product; /* product ID */
char *dev_serial; /* serial number */
/* indexed by config index */
int dev_curr_if; /* current interface number */
/*
* ***************************************************************************
* Device configuration descriptor tree functions
* ***************************************************************************
*/
/*
* usb_get_dev_data:
* returns initialized registration data. Most data items are clear.
* Among the items returned is the tree ofparsed descriptors in dev_cfg;
* and the number of configurations parsed in dev_n_cfg.
*
* Arguments:
* dip - pointer to devinfo node of the client
* dev_data - return registration data at this address
* parse_level - See above
* flags - None used
*
* Return Values:
* USB_SUCCESS - usb_register_client succeeded
* USB_INVALID_ARGS - received null dip or reg argument
* USB_INVALID_CONTEXT - called with sleep from callback context
* USB_FAILURE - bad descriptor info or other internal failure
*
* Notes:
* 1) The non-standard USB descriptors are returned in RAW format.
*
* 2) The registration data is unshared. Each client receives its own copy.
* (The default control pipe may be shared, even though its tree
* description will be unique per device.)
*
*/
int usb_get_dev_data(
/*
* usb_free_dev_data:
* undoes what usb_get_dev_data() set up. It releases
* memory for all strings, descriptors, and trees set up by usb_get_dev_data().
*
* Arguments:
* dip - pointer to devinfo node of the client
* dev_data - pointer to registration data containing the tree.
*/
void usb_free_dev_data(
/*
* usb_free_descr_tree:
* Take down the configuration tree while leaving the rest of the
* registration intact. This can be used, for example, after attach has
* copied any descriptors it needs from the tree, but the rest of the
* registration data needs to remain intact.
*
* The following usb_client_dev_data_t fields will be modified:
* dev_cfg will be NULL
* dev_n_cfg will be 0
* dev_curr_cfg_ndx and dev_curr_if will be invalid
* dev_parse_level will be USB_REG_DESCR_NONE
*
* Arguments:
* dip - pointer to devinfo node of the client
* dev_data - pointer to registration data containing the tree.
*/
void usb_free_descr_tree(
/*
* usb_print_descr_tree:
* Dump to the screen a descriptor tree as returned by
* usbai_register_client.
*
* Arguments:
* dip - pointer to devinfo of the client
* dev_data - pointer to registration area containing the tree
*
* Returns:
* USB_SUCCESS - tree successfully dumped
* USB_INVALID_CONTEXT - called from callback context
* USB_INVALID_ARGS - bad arguments given
*/
int usb_print_descr_tree(
/*
* ***************************************************************************
* Registration and versioning
* ***************************************************************************
*/
/*
* USBA client drivers are required to define USBDRV_MAJOR_VER
* USBDRV_MINOR_VER and pass USBDRV_VERSION as the version
* number to usb_client_attach
*/
#if !defined(USBA_MAJOR_VER) || !defined(USBA_MINOR_VER)
#endif
/*
* Driver major version must be the same as USBA major version, and
* driver minor version must be <= USBA minor version
*/
#if !defined(USBA_FRAMEWORK)
#if defined(USBDRV_MAJOR_VER) && defined(USBDRV_MINOR_VER)
#if (USBDRV_MAJOR_VER != USBA_MAJOR_VER)
#endif
#if (USBDRV_MINOR_VER > USBA_MINOR_VER)
#endif
#endif
#endif
/*
* usb_client_attach:
*
* Arguments:
* dip - pointer to devinfo node of the client
* version - USBA registration version number
* flags - None used
*
* Return Values:
* USB_SUCCESS - attach succeeded
* USB_INVALID_ARGS - received null dip or reg argument
* USB_INVALID_CONTEXT - called with sleep from callback context
* or not at attach time
* USB_INVALID_VERSION - version argument is incorrect.
* USB_FAILURE - other internal failure
*/
int usb_client_attach(
/*
* usb_client_detach:
*
* Arguments:
* dip - pointer to devinfo node of the client
* dev_data - pointer to data to free. may be NULL
*/
void usb_client_detach(
struct usb_client_dev_data *dev_data);
/*
* ***************************************************************************
* Functions for parsing / retrieving data from the descriptor tree
* ***************************************************************************
*/
/*
* Function for unpacking any kind of little endian data, usually desriptors
*
* Arguments:
* format - string indicating the format in c, s, w, eg. "2c4ws"
* which describes 2 bytes, 4 int, one short.
* The number prefix parses the number of items of
* the following type.
* data - pointer to the LE data buffer
* datalen - length of the data
* structure - pointer to return structure where the unpacked data
* will be written
* structlen - length of the return structure
*
* return value:
* total number of bytes of the original data that was unpacked
* or USB_PARSE_ERROR
*/
#define USB_PARSE_ERROR 0
char *format,
void *structure,
/*
* usb_lookup_ep_data:
* Function to get specific endpoint data
* This function will not access the device.
*
* Arguments:
* dip - pointer to dev info
* dev_datap - pointer to registration data
* interface - requested interface
* alternate - requested alternate
* skip - number of endpoints which match the requested type and
* direction to skip before finding one to retrieve
* type - endpoint type
* direction - endpoint direction: USB_EP_DIR_IN/OUT or none
*
* Return Values:
* NULL or an endpoint data pointer
*/
/* Language ID for string descriptors. */
/*
* usb_get_string_descr:
* Reads the string descriptor. This function access the device and
* blocks.
*
* Arguments:
* dip - pointer to devinfo of the client.
* langid - LANGID to read different LOCALEs.
* index - index to the string.
* buf - user provided buffer for string descriptor.
* buflen - user provided length of the buffer.
*
* Return Values:
* USB_SUCCESS - descriptor is valid.
* USB_FAILURE - full descriptor could not be retrieved.
*/
int usb_get_string_descr(
char *buf,
/*
* ***************************************************************************
* Addressing utility functions
* ***************************************************************************
*/
/*
* usb_get_addr returns the current usb address, mostly for debugging
* This address will not change on a disconnect/reconnect of open device.
*/
/*
* usb_get_if_number returns USB_COMBINED_NODE or USB_DEVICE_NODE
* if the driver is responsible for the entire device.
* Otherwise it returns the interface number.
*/
#define USB_COMBINED_NODE -1
#define USB_DEVICE_NODE -2
int usb_get_if_number(
dev_info_t *dip);
dev_info_t *dip);
/*
* ***************************************************************************
* Pipe Management definitions and functions
* ***************************************************************************
*/
/*
*
* usb_pipe_state:
*
* PIPE_STATE_IDLE:
* The pipe's policy is set, but the pipe currently isn't transferring
* data.
*
* PIPE_STATE_ACTIVE:
* The pipe's policy has been set, and the pipe is able to transmit data.
* When a control or bulk pipe is opened, the pipe's state is
* automatically set to PIPE_STATE_ACTIVE. For an interrupt or
* isochronous pipe, the pipe state becomes PIPE_STATE_ACTIVE once
* the polling on the pipe has been initiated.
*
* PIPE_STATE_ERROR:
* The device has generated a error on the pipe. The client driver
* must call usb_pipe_reset() to clear any leftover state that's associated
* with the pipe, clear the data toggle, and reset the state of the pipe.
*
* Calling usb_pipe_reset() on a control or bulk pipe resets the state to
* PIPE_STATE_ACTIVE. Calling usb_pipe_reset() on an interrupt or
* isochronous pipe, resets the state to PIPE_STATE_IDLE.
*
*
* +-<--normal completion------------------<-------^
* | |
* V |
* usb_pipe_open-->[PIPE_STATE_IDLE]-usb_pipe_*_xfer->[PIPE_STATE_ACTIVE]
* ^ |
* | v
* - usb_pipe_reset<-[PIPE_STATE_ERROR]<-device error
*
* State Diagram for Interrupt/Isochronous IN
*
* +-<--usb_pipe_stop_isoc/intr_polling----<-------^
* | |
* V |
* usb_pipe_open-->[PIPE_STATE_IDLE]-usb_pipe_*_xfer->[PIPE_STATE_ACTIVE]
* ^ |
* | v
* + usb_pipe_reset<-[PIPE_STATE_ERROR]<-device error
*
* State Diagram for Interrupt/Isochronous OUT
*
* +-<--normal completion------------------<-------^
* | |
* V |
* usb_pipe_open-->[PIPE_STATE_IDLE]-usb_pipe_*_xfer->[PIPE_STATE_ACTIVE]
* ^ |
* | v
* + usb_pipe_reset<-[PIPE_STATE_ERROR]<-device error
*
*
* The following table indicates which operations are allowed with each
* pipe state:
*
* -------------------------------------------------------------------------+
* -------------------------------------------------------------------------+
* pipe xfer | OK |queue (USBA)| reject | reject | reject |
* pipe reset | no-op | OK | OK | reject | reject |
* pipe close | OK | wait&close | OK | no-op | no-op |
* -------------------------------------------------------------------------+
*
* -------------------------------------------------------------------------+
* -------------------------------------------------------------------------+
* pipe xfer | OK | reject | reject | reject | reject |
* pipe stoppoll| no-op | OK | no-op | reject | reject |
* pipe reset | no-op | OK | OK | reject | reject |
* pipe close | OK | wait&close | OK | no-op | no-op |
* -------------------------------------------------------------------------+
*
* -------------------------------------------------------------------------+
* -------------------------------------------------------------------------+
* pipe xfer | OK |queue (HCD) | reject | reject | reject |
* pipe stoppoll| reject| reject | reject | reject | reject |
* pipe reset | no-op | OK | OK | reject | reject |
* pipe close | OK | wait&close | OK | no-op | no-op |
* -------------------------------------------------------------------------+
*/
typedef enum {
USB_PIPE_STATE_IDLE = 1,
USB_PIPE_STATE_ERROR = 3,
/*
* pipe state control:
*
* return values:
* USB_SUCCESS - success
* USB_FAILURE - unspecified failure
*/
int usb_pipe_get_state(
/*
* usb_pipe_policy
*
* Pipe policy specifies how a pipe to an endpoint should be used
* by the client driver and the HCD.
*/
typedef struct usb_pipe_policy {
/*
* This is a hint indicating how many asynchronous operations
* requiring a kernel thread will be concurrently active.
* Allow at least one for synch exception callback handling
* and another for asynchronous closing of pipes.
*/
/*
* usb_pipe_open():
*
* Before using any pipe including the default pipe, it must be opened.
* On success, a pipe handle is returned for use in other usb_pipe_*()
* functions.
*
* The default pipe can only be opened by the hub driver.
*
* For isochronous and interrupt pipes, bandwidth has been allocated and
* guaranteed.
*
* Only the default pipe can be shared. All other control pipes are
* excusively opened by default. A pipe policy and endpoint descriptor
* must always be provided except for default pipe.
*
* Arguments:
* dip - devinfo ptr.
* ep - endpoint descriptor pointer.
* pipe_policy - pointer to pipe policy which provides hints on how
* the pipe will be used.
* flags - USB_FLAGS_SLEEP wait for resources to become
* available.
* pipe_handle - a pipe handle pointer. on a successful open,
* a pipe_handle is returned in this pointer.
*
* Return values:
* USB_SUCCESS - open succeeded.
* USB_FAILURE - unspecified open failure or pipe is already open.
* USB_NO_RESOURCES - no resources were available to complete the open.
* USB_* - refer to list of all possible return values in
* this file
*/
int usb_pipe_open(
/*
* usb_pipe_close():
*
* Closes the pipe, releases resources and frees the pipe_handle.
* Automatic polling, if active, will be terminated.
*
* Arguments:
* dip - devinfo ptr.
* pipe_handle - pipe handle.
* flags - USB_FLAGS_SLEEP:
* wait for resources, pipe
* to become free, and all callbacks completed.
* cb - If USB_FLAGS_SLEEP has not been specified, a
* callback will be performed.
* cb_arg - the 2nd argument of the callback. Note that the
* pipehandle will be zeroed and therefore not passed.
*
* Notes:
*
* Pipe close always succeeds regardless whether USB_FLAGS_SLEEP has been
* specified or not. An async close will always succeed if the hint in the
* pipe policy has been correct about the max number of async requests
* required.
* In the unlikely event that no async requests can be queued, this
* function will continue retrying before returning
*
* USBA prevents the client from submitting subsequent requests to a pipe
* that is being closed.
* Additional usb_pipe_close() requests on the same pipe causes USBA to
* wait for the previous close(s) to complete.
*
* The pipe will not be destroyed until all activity on the pipe has
* been drained, including outstanding request callbacks, async requests,
* and other usb_pipe_*() calls.
*
* Calling usb_pipe_close() from a deferred callback (in kernel context)
* with USB_FLAGS_SLEEP set, will cause deadlock
*/
void usb_pipe_close(
void (*cb)(
int rval,
/*
* usb_pipe_drain_reqs
* this function blocks until there are no more requests
* owned by this dip on the pipe
*
* Arguments:
* dip - devinfo pointer
* pipe_handle - opaque pipe handle
* timeout - timeout in seconds
* flags - USB_FLAGS_SLEEP:
* wait for completion.
* cb - if USB_FLAGS_SLEEP has not been specified
* this callback function will be called on
* completion. This callback may be NULL
* and no notification of completion will then
* be provided.
* cb_arg - 2nd argument to callback function.
*
* callback and callback_arg should be NULL if USB_FLAGS_SLEEP has
* been specified
*
* Returns:
* USB_SUCCESS - pipe successfully reset or request queued
* USB_FAILURE - timeout
* USB_INVALID_PIPE - pipe is invalid or already closed
* USB_INVALID_CONTEXT - called from interrupt context
* USB_INVALID_ARGS - invalid arguments
* USB_* - refer to return values defines in this file
*/
int usb_pipe_drain_reqs(
void (*cb)(
int rval,
/*
* Resetting a pipe: Refer to USB 2.0/10.5.2.2
* The pipe's requests are retired and the pipe is cleared. The host state
* is moved to active. If the reflected endpoint state needs to be changed,
* that must be explicitly requested by the client driver. The reset
* completes after all request callbacks have been completed.
*
* Arguments:
* dip - devinfo pointer.
* pipe_handle - pipe handle.
* flags - USB_FLAGS_SLEEP:
* wait for completion.
* cb - if USB_FLAGS_SLEEP has not been specified
* this callback function will be called on
* completion. This callback may be NULL
* and no notification of completion will then
* be provided.
* cb_arg - 2nd argument to callback function.
*
* callback and callback_arg should be NULL if USB_FLAGS_SLEEP has
* been specified
*
* Note: Completion notification may be *before* all async request threads
* have completed but *after* all immediate callbacks have completed.
*/
void usb_pipe_reset(
void (*cb)(
int rval,
/*
* The client driver can store a private data pointer in the
* pipe_handle.
*
* return values:
* USB_SUCCESS - success
* USB_FAILURE - unspecified failure
*/
int usb_pipe_set_private(
/*
* ***************************************************************************
* Transfer request definitions and functions
* ***************************************************************************
*/
/*
* USB xfer request attributes.
* Set by the client driver, more than one may be set
*
* SHORT_XFER_OK if less data is transferred than specified, no error is
* returned.
* AUTOCLEARING if there is an exception, the pipe will be reset first
* and a functional stall cleared before a callback is done.
* PIPE_RESET if there is an exception, the pipe will be reset only
* ONE_XFER polling will automatically stop on the first callback.
* ISOC_START_FRAME use startframe specified.
* USB_ATTRS_ISOC_XFER_ASAP let the host controller decide on the first
* available frame.
*
* USB_ATTRS_ISOC_START_FRAME and USB_ATTRS_ISOC_XFER_ASAP are mutually
* exclusive
*
* combinations of flag and attributes:
*
* usb_flags usb_req_attrs semantics
* ---------------------------------------------------------
* SLEEP USB_ATTRS_SHORT_XFER_OK legal for IN pipes
* SLEEP USB_ATTRS_AUTOCLEARING legal
* SLEEP USB_ATTRS_PIPE_RESET legal
* SLEEP USB_ATTRS_ONE_XFER legal for interrupt IN pipes
* SLEEP USB_ATTRS_ISOC_START_FRAME illegal
* SLEEP USB_ATTRS_ISOC_XFER_ASAP illegal
*
* noSLEEP USB_ATTRS_SHORT_XFER_OK legal for all IN pipes
* noSLEEP USB_ATTRS_AUTOCLEARING legal
* noSLEEP USB_ATTRS_PIPE_RESET legal
* noSLEEP USB_ATTRS_ONE_XFER legal
* noSLEEP USB_ATTRS_ISOC_START_FRAME legal
* noSLEEP USB_ATTRS_ISOC_XFER_ASAP legal
*/
typedef enum {
USB_ATTRS_NONE = 0,
/* intr pipes only: one poll with data */
USB_ATTRS_ONE_XFER = 0x100,
/* only for isoch pipe */
/*
* Note: client drivers are required to provide data buffers (mblks) for most
* requests
* IN OUT
* ctlr request if wLength > 0 if wLength > 0
* bulk request yes yes
* intr request no yes
* isoc request no yes
*/
/*
* ===========================================================================
* USB control request management
* ===========================================================================
*/
/*
* A client driver allocates and uses the usb_ctrl_req_t for all control
* pipe requests.
*
* Direction of the xfer will be determined based on the bmRequestType.
*
* NULL callbacks are permitted, timeout = 0 indicates infinite timeout.
* All timeouts are in seconds.
*
* All fields are initialized by client except for data on IN request
* in which case the client is responsible for deallocating.
*
* Control requests may be reused. The client driver is responsible
*
* Control requests can be queued.
*/
typedef struct usb_ctrl_req {
/* IN: allocated by HCD */
/* OUT: allocated by client */
/*
* callback function for control pipe requests
*
* a normal callback will be done upon:
* - successful completion of a control pipe request
*
* callback arguments are:
* - the pipe_handle
* - usb_ctrl_req_t pointer
*/
struct usb_ctrl_req *req);
/*
* exception callback function for control pipe
*
* a exception callback will be done upon:
* - partial xfer of data unless SHORT_XFER_OK has been set
*
* callback arguments are:
* - the pipe_handle
* - usb_ctrl_req_t pointer
*
* if USB_ATTRS_AUTOCLEARING was set, autoclearing will be attempted
* and usb_cb_flags_t in usb_ctrl_req may indicate what was done
*/
struct usb_ctrl_req *req);
/*
* In the setup packet, the descriptor type is passed in the high byte of the
* wValue field.
* descriptor types:
*/
#define USB_DESCR_TYPE_SETUP_DEV 0x0100
#define USB_DESCR_TYPE_SETUP_CFG 0x0200
#define USB_DESCR_TYPE_SETUP_STRING 0x0300
#define USB_DESCR_TYPE_SETUP_IF 0x0400
#define USB_DESCR_TYPE_SETUP_EP 0x0500
#define USB_DESCR_TYPE_SETUP_DEV_QLF 0x0600
#define USB_DESCR_TYPE_SETUP_OTHER_SPEED_CFG 0x0700
#define USB_DESCR_TYPE_SETUP_IF_PWR 0x0800
#define USB_DESCR_TYPE_DEV 0x01
#define USB_DESCR_TYPE_CFG 0x02
#define USB_DESCR_TYPE_STRING 0x03
#define USB_DESCR_TYPE_IF 0x04
#define USB_DESCR_TYPE_EP 0x05
#define USB_DESCR_TYPE_DEV_QLF 0x06
#define USB_DESCR_TYPE_OTHER_SPEED_CFG 0x07
#define USB_DESCR_TYPE_IF_PWR 0x08
#define USB_DESCR_TYPE_IA 0x0B
#define USB_DESCR_TYPE_WA 0x21
#define USB_DESCR_TYPE_RPIPE 0x22
/* Wireless USB extension, refer to WUSB 1.0/7.4 */
#define USB_DESCR_TYPE_SECURITY 0x0c
#define USB_DESCR_TYPE_KEY 0x0d
#define USB_DESCR_TYPE_ENCRYPTION 0x0e
#define USB_DESCR_TYPE_BOS 0x0f
#define USB_DESCR_TYPE_DEV_CAPABILITY 0x10
#define USB_DESCR_TYPE_WIRELESS_EP_COMP 0x11
#define USB_WA_DESCR_SIZE 14
#define USB_RPIPE_DESCR_SIZE 28
/*
* device request type
*/
#define USB_DEV_REQ_HOST_TO_DEV 0x00
#define USB_DEV_REQ_DEV_TO_HOST 0x80
#define USB_DEV_REQ_DIR_MASK 0x80
#define USB_DEV_REQ_TYPE_STANDARD 0x00
#define USB_DEV_REQ_TYPE_CLASS 0x20
#define USB_DEV_REQ_TYPE_VENDOR 0x40
#define USB_DEV_REQ_TYPE_MASK 0x60
#define USB_DEV_REQ_RCPT_DEV 0x00
#define USB_DEV_REQ_RCPT_IF 0x01
#define USB_DEV_REQ_RCPT_EP 0x02
#define USB_DEV_REQ_RCPT_OTHER 0x03
#define USB_DEV_REQ_RCPT_MASK 0x03
/* Wire adapter class extension for request recipient */
#define USB_DEV_REQ_RCPT_PORT 0x04
#define USB_DEV_REQ_RCPT_RPIPE 0x05
/*
* device request
*/
#define USB_REQ_GET_STATUS 0x00
#define USB_REQ_CLEAR_FEATURE 0x01
#define USB_REQ_SET_FEATURE 0x03
#define USB_REQ_SET_ADDRESS 0x05
#define USB_REQ_GET_DESCR 0x06
#define USB_REQ_SET_DESCR 0x07
#define USB_REQ_GET_CFG 0x08
#define USB_REQ_SET_CFG 0x09
#define USB_REQ_GET_IF 0x0a
#define USB_REQ_SET_IF 0x0b
#define USB_REQ_SYNC_FRAME 0x0c
/* Wireless USB extension, refer to WUSB 1.0/7.3.1 */
#define USB_REQ_SET_ENCRYPTION 0x0d
#define USB_REQ_GET_ENCRYPTION 0x0e
#define USB_REQ_RPIPE_ABORT 0x0e
#define USB_REQ_SET_HANDSHAKE 0x0f
#define USB_REQ_RPIPE_RESET 0x0f
#define USB_REQ_GET_HANDSHAKE 0x10
#define USB_REQ_SET_CONNECTION 0x11
#define USB_REQ_SET_SECURITY_DATA 0x12
#define USB_REQ_GET_SECURITY_DATA 0x13
#define USB_REQ_SET_WUSB_DATA 0x14
#define USB_REQ_LOOPBACK_DATA_WRITE 0x15
#define USB_REQ_LOOPBACK_DATA_READ 0x16
#define USB_REQ_SET_INTERFACE_DS 0x17
/* language ID for string descriptors */
#define USB_LANG_ID 0x0409
/*
* Standard Feature Selectors
*/
#define USB_EP_HALT 0x0000
#define USB_DEV_REMOTE_WAKEUP 0x0001
#define USB_DEV_TEST_MODE 0x0002
/* Wireless USB extension, refer to WUSB 1.0/7.3.1 */
#define USB_DEV_WUSB 0x0003
/*
* Allocate usb control request
*
* Arguments:
* dip - dev_info pointer of the client driver
* len - length of "data" for this control request.
* if 0, no mblk is alloc'ed
* flags - USB_FLAGS_SLEEP: Sleep if resources are not available
*
* Return Values:
* usb_ctrl_req_t pointer on success, NULL on failure
*
* Implementation NOTE: the dip allows checking on detach for memory leaks
*/
/*
* free USB control request
*/
void usb_free_ctrl_req(
/*
* usb_pipe_ctrl_xfer();
* Client driver calls this function to issue the control
* request to the USBA which will queue or transport it to the device
*
* Arguments:
* pipe_handle - control pipe pipehandle (obtained via usb_pipe_open()
* reqp - pointer to control request
* flags - USB_FLAGS_SLEEP:
* wait for the request to complete
*
* Return values:
* USB_SUCCESS - successfully queued (no sleep) or successfully
* completed (with sleep specified)
* USB_FAILURE - failure
* USB_NO_RESOURCES - no resources
*/
/*
* ---------------------------------------------------------------------------
* Wrapper function which allocates and deallocates a request structure, and
* performs a control transfer.
* ---------------------------------------------------------------------------
*/
/*
* Setup arguments for usb_pipe_ctrl_xfer_wait:
*
* bmRequestType - characteristics of request
* bRequest - specific request
* wValue - varies according to request
* wIndex - index or offset
* wLength - number of bytes to xfer
* attrs - required request attributes
* data - pointer to pointer to data
* IN: HCD will allocate data
* OUT: clients driver allocates data
*/
typedef struct usb_ctrl_setup {
/*
* usb_pipe_ctrl_xfer_wait():
* for simple synchronous control transactions this wrapper function
* will perform the allocation, xfer, and deallocation.
* USB_ATTRS_AUTOCLEARING will be enabled
*
* Arguments:
* pipe_handle - control pipe pipehandle (obtained via usb_pipe_open())
* setup - contains pointer to client's devinfo,
* setup descriptor params, attributes and data
* completion_reason - completion status.
* cb_flags - request completions flags.
* flags - none.
*
* Return Values:
* USB_SUCCESS - request successfully executed.
* USB_FAILURE - request failed.
* USB_* - refer to list of all possible return values in
* this file
*
* NOTES:
* - in the case of failure, the client should check completion_reason and
* and cb_flags and determine further recovery action
* - the client should check data and if non-zero, free the data on
* completion
*/
/*
* ---------------------------------------------------------------------------
* Some utility defines and wrapper functions for standard control requests.
* ---------------------------------------------------------------------------
*/
/*
*
* Status bits returned by a usb_get_status().
*/
#define USB_IF_STATUS 0 /* Interface Status is 0 */
/* length of data returned by USB_REQ_GET_STATUS */
#define USB_GET_STATUS_LEN 2
/*
* wrapper function returning status of device, interface, or endpoint
*
* Arguments:
* dip - devinfo pointer.
* ph - pipe handle
* type - bmRequestType to be used
* what - 0 for device, otherwise interface or ep number
* status - pointer to returned status.
* flags - USB_FLAGS_SLEEP (mandatory)
*
* Return Values:
* valid usb_status_t or USB_FAILURE
*
*/
int usb_get_status(
/*
* function for clearing feature of device, interface, or endpoint
*
* Arguments:
* dip - devinfo pointer.
* type - bmRequestType to be used
* feature - feature to be cleared
* what - 0 for device, otherwise interface or ep number
* flags - USB_FLAGS_SLEEP (mandatory)
* cb - if USB_FLAGS_SLEEP has not been specified
* this callback function will be called on
* completion. This callback may be NULL
* and no notification of completion will then
* be provided.
* cb_arg - 2nd argument to callback function.
*
* Return Values:
* USB_SUCCESS clearing feature succeeded
* USB_FAILURE clearing feature failed
* USB_* refer to list of all possible return values in
* this file
*/
int usb_clr_feature(
void (*cb)(
int rval,
/*
* usb_set_cfg():
* Sets the configuration. Use this function with caution as
* the framework is normally responsible for configuration changes.
* Changing configuration will fail if pipes are still open or
* when invoked from a driver bound to an interface on a composite
* device. This function access the device and blocks.
*
* Arguments:
* dip - devinfo pointer.
* cfg_index - Index of configuration to set. Corresponds to
* index in the usb_client_dev_data_t tree of
* configurations. See usb_client_dev_data_t(9F).
* usb_flags - USB_FLAGS_SLEEP:
* wait for completion.
* cb - if USB_FLAGS_SLEEP has not been specified
* this callback function will be called on
* completion. This callback may be NULL
* and no notification of completion will then
* be provided.
* cb_arg - 2nd argument to callback function.
*
* callback and callback_arg should be NULL if USB_FLAGS_SLEEP has
* been specified
*
* Return Values:
* USB_SUCCESS: new configuration was set or async request
* submitted successfully.
* USB_FAILURE: new configuration could not be set because
* it may been illegal configuration or this
* caller was not allowed to change configs or
* pipes were still open or async request
* could not be submitted.
* USB_* refer to list of all possible return values in
* this file
*
* the pipe handle argument in the callback will be the default pipe handle
*/
int usb_set_cfg(
void (*cb)(
int rval,
/*
* usb_get_cfg:
* dip - pointer to devinfo node
* cfgval - pointer to cfgval
* usb_flags - none, will always block
*
* return values:
* USB_SUCCESS - current cfg value is returned to cfgval
* USB_* - refer to list of all possible return values in
* this file
*/
int usb_get_cfg(
/*
* The following functions set or get the alternate interface
* setting.
*
* usb_set_alt_if:
* dip - pointer to devinfo node
* interface - interface
* alt_number - alternate to set to
* usb_flags - USB_FLAGS_SLEEP:
* wait for completion.
* cb - if USB_FLAGS_SLEEP has not been specified
* this callback function will be called on
* completion. This callback may be NULL
* and no notification of completion will then
* be provided.
* cb_arg - 2nd argument to callback function.
*
* callback and callback_arg should be NULL if USB_FLAGS_SLEEP has
* been specified
*
* the pipe handle argument in the callback will be the default pipe handle
*
* return values:
* USB_SUCCESS: alternate was set or async request was
* submitted.
* USB_FAILURE: alternate could not be set because pipes
* were still open or some access error occurred
* or an invalid alt if value was passed or
* async request could not be submitted
* USB_INVALID_PERM the driver does not own the device or the interface
* USB_* refer to list of all possible return values in
* this file
*/
int usb_set_alt_if(
void (*cb)(
int rval,
/* flags must be USB_FLAGS_SLEEP, and this function will block */
int usb_get_alt_if(
/*
* ===========================================================================
* USB bulk request management
* ===========================================================================
*/
/*
*
* NOTES:
* - bulk pipe sharing is not supported
* - semantics of combinations of flag and attributes:
*
* flags Type attributes data timeout semantics
* ----------------------------------------------------------------
* x x x == NULL x illegal
*
* no sleep IN x != NULL 0 fill buffer, no timeout
* callback when xfer-len has
* been xferred
* no sleep IN x != NULL > 0 fill buffer, with timeout
* callback when xfer-len has
* been xferred
*
* sleep IN x != NULL 0 fill buffer, no timeout
* unblock when xfer-len has
* been xferred
* no callback
* sleep IN x != NULL > 0 fill buffer, with timeout
* unblock when xfer-len has
* been xferred or timeout
* no callback
*
* X OUT SHORT_XFER_OK x x illegal
*
* no sleep OUT x != NULL 0 empty buffer, no timeout
* callback when xfer-len has
* been xferred
* no sleep OUT x != NULL > 0 empty buffer, with timeout
* callback when xfer-len has
* been xferred or timeout
*
* sleep OUT x != NULL 0 empty buffer, no timeout
* unblock when xfer-len has
* been xferred
* no callback
* sleep OUT x != NULL > 0 empty buffer, with timeout
* unblock when xfer-len has
* been xferred or timeout
* no callback
*
* - bulk_len and bulk_data must be > 0. SHORT_XFER_OK is not applicable.
*
* - multiple bulk requests can be queued
*
* - Splitting large Bulk xfer:
* The HCD driver, due to internal constraints, can only do a limited size bulk
* data xfer per request. The current limitations are 32K for UHCI and 128K
* for OHCI. So, a client driver may first determine this limitation (by
* calling the USBA interface usb_pipe_bulk_transfer_size()); and restrict
* itself to doing xfers in multiples of this fixed size. This forces a client
* driver to do data xfers in a loop for a large request, splitting it into
* multiple chunks of fixed size.
*/
typedef struct usb_bulk_req {
/* IN: allocated by HCD */
/* OUT: allocated by client */
/* Normal Callback function (For synch xfers) */
struct usb_bulk_req *req);
/* Exception Callback function (For asynch xfers) */
struct usb_bulk_req *req);
/*
*
* Arguments:
* dip - pointer to dev_info_t of the client driver
* len - 0 or length of mblk to be allocated
* flags - USB_FLAGS_SLEEP:
* wait for resources
*
* Return Values:
* usb_bulk_req_t on success, NULL on failure
*/
void usb_free_bulk_req(
/*
* usb_pipe_bulk_xfer():
*
* Client drivers call this function to issue the bulk xfer to the USBA
* which will queue or transfer it to the device
*
* Arguments:
* pipe_handle - bulk pipe handle (obtained via usb_pipe_open()
* reqp - pointer to bulk data xfer request (IN or OUT)
* flags - USB_FLAGS_SLEEP:
* wait for the request to complete
*
* Return Values:
* USB_SUCCESS - success
* USB_FAILURE - unspecified failure
* USB_NO_RESOURCES - no resources
*
*/
int usb_pipe_bulk_xfer(
/* Get maximum bulk transfer size */
/*
* ===========================================================================
* USB interrupt pipe request management
* ===========================================================================
*/
/*
* A client driver allocates and uses the usb_intr_req_t for
* all interrupt pipe transfers.
*
* USB_FLAGS_SLEEP indicates here just to wait for resources except
* for ONE_XFER where we also wait for completion
*
* semantics flags and attribute combinations:
*
* Notes:
* none attributes indicates neither ONE_XFER nor SHORT_XFER_OK
*
* flags Type attributes data timeout semantics
* ----------------------------------------------------------------
* x IN x != NULL x illegal
* x IN ONE_XFER=0 x !=0 illegal
*
* x IN ONE_XFER=0 NULL 0 continuous polling,
* many callbacks
* request is returned on
* stop polling
*
* no sleep IN ONE_XFER NULL 0 one time poll, no timeout,
* one callback
* no sleep IN ONE_XFER NULL !=0 one time poll, with
* timeout, one callback
*
* sleep IN ONE_XFER NULL 0 one time poll, no timeout,
* no callback,
* block for completion
* sleep IN ONE_XFER NULL !=0 one time poll, with timeout,
* no callback
* block for completion
*
* x OUT x NULL x illegal
* x OUT ONE_XFER x x illegal
* x OUT SHORT_XFER_OK x x illegal
*
* x OUT none != NULL 0 xfer until data exhausted,
* no timeout, one callback
* x OUT none != NULL !=0 xfer until data exhausted,
* with timeout, one callback
*
* - Reads (IN):
*
* The client driver does *not* provide a data buffer.
* By default, a READ request would mean continuous polling for data IN. The
* HCD typically reads "wMaxPacketSize" amount of 'periodic data'. A client
* driver may force the HCD to read instead intr_len
* amount of 'periodic data' (See section 1).
*
* The HCD issues a callback to the client after each polling interval if
* it has read in some data. Note that the amount of data read IN is either
* intr_len or 'wMaxPacketSize' in length.
*
* Normally, the HCD keeps polling interrupt pipe forever even if there is
* no data to be read IN. A client driver may stop this polling by
* calling usb_pipe_stop_intr_polling().
*
* If a client driver chooses to pass USB_ATTRS_ONE_XFER as
* 'xfer_attributes' the HCD will poll for data until some data is received.
* HCD reads in the data and does a callback and stops polling for any more
* data. In this case, the client driver need not explicitly call
* usb_pipe_stop_intr_polling().
*
* When continuous polling is stopped, the original request is returned with
* USB_CR_STOPPED_POLLING.
*
* - Writes (OUT):
*
* A client driver provides the data buffer, and data, needed for intr write.
* There is no continuous write mode, a la read (See previous section).
* The USB_ATTRS_ONE_XFER attribute is illegal.
* By default USBA keeps writing intr data until the provided data buffer
* has been written out. The HCD does ONE callback to the client driver.
* Queueing is supported.
* Max size is 8k
*/
typedef struct usb_intr_req {
/* IN : packet size */
/* IN: allocated by HCD */
/* OUT: allocated by client */
/* Normal callback function (For synch transfers) */
struct usb_intr_req *req);
/* Exception callback function (For asynch transfers) */
struct usb_intr_req *req);
/*
*
* Arguments:
* dip - pointer to dev_info_t of the client driver
* reqp - pointer to request structure
* len - 0 or length of mblk for this interrupt request
* flags - USB_FLAGS_SLEEP:
* Sleep if resources are not available
*
* Return Values:
* usb_intr_req_t on success, NULL on failure
*/
void usb_free_intr_req(
/*
* usb_pipe_intr_xfer():
*
* which starts polling the device
*
* Arguments:
* pipe_handle - interrupt pipe handle (obtained via usb_pipe_open()
* reqp - pointer tothe interrupt pipe xfer request (IN or OUT)
* flags - USB_FLAGS_SLEEP:
* wait for resources to be available
*
* return values:
* USB_SUCCESS - success
* USB_FAILURE - unspecified failure
* USB_NO_RESOURCES - no resources
*
* NOTE: start polling on an IN pipe that is already being polled is a NOP.
* We don't queue requests on OUT pipe
*/
int usb_pipe_intr_xfer(
/*
* usb_pipe_stop_intr_polling():
*
* without closing the pipe.
*
* If USB_FLAGS_SLEEP has been specified then this function will block until
* polling has been stopped and all callbacks completed. If USB_FLAGS_SLEEP
* has NOT been specified then polling is terminated when the original
* request that started the polling has been returned with
* USB_CR_STOPPED_POLLING
*
* Stop polling should never fail.
*
* Args:-
* pipe_handle - interrupt pipe handle (obtained via usb_pipe_open()).
* flags - USB_FLAGS_SLEEP:
* wait for the resources to be available.
*/
/*
* ===========================================================================
* USB isochronous xfer management
* ===========================================================================
*/
/*
* The usb frame number is an absolute number since boot and incremented
* every 1 ms.
*/
typedef uint64_t usb_frame_number_t;
/*
* USB ischronous packet descriptor
*
* An array of structures of type usb_isoc_pkt_descr_t must be allocated and
* initialized by the client driver using usb_alloc_isoc_req(). The client
* driver must set isoc_pkt_length in each packet descriptor before submitting
* the request.
*/
typedef struct usb_isoc_pkt_descr {
/*
* Set by the client driver, for all isochronous requests, to the
* number of bytes to transfer in a frame.
*/
/*
*/
/*
* Per frame status set by HCD both for the isochronous IN and OUT
* requests. If any status is non-zero then isoc_error_count in the
* isoc_req will be non-zero.
*/
/*
* USB isochronous request
*
* The client driver allocates the usb_isoc_req_t before sending an
* isochronous requests.
*
* USB_FLAGS_SLEEP indicates here just to wait for resources but not
* to wait for completion
*
* Semantics of various combinations for data xfers:
*
* Note: attributes considered in this table are ONE_XFER, START_FRAME,
* XFER_ASAP, SHORT_XFER
*
*
* flags Type attributes data semantics
* ---------------------------------------------------------------------
* x x x NULL illegal
*
* x x ONE_XFER x illegal
*
* x IN x !=NULL continuous polling,
* many callbacks
*
* x IN ISOC_START_FRAME !=NULL invalid if Current_frame# >
* "isoc_frame_no"
* x IN ISOC_XFER_ASAP !=NULL "isoc_frame_no" ignored.
* HCD determines when to
* insert xfer
*
* x OUT ONE_XFER x illegal
* x OUT SHORT_XFER_OK x illegal
*
* x OUT ISOC_START_FRAME !=NULL invalid if Current_frame# >
* "isoc_frame_no"
* x OUT ISOC_XFER_ASAP !=NULL "isoc_frame_no" ignored.
* HCD determines when to
* insert xfer
*/
typedef struct usb_isoc_req {
/*
* Starting frame number will be set by the client driver in which
* to begin this request. This frame number is used to synchronize
* requests queued to different isochronous pipes. The frame number
* is optional and client driver can skip starting frame number by
* setting USB_ISOC_ATTRS_ASAP. In this case, HCD will decide starting
* frame number for this isochronous request. If this field is 0,
* then this indicates an invalid frame number.
*/
/*
* Number of isochronous data packets.
* The first field is set by client driver and may not exceed
* the maximum number of entries in the usb isochronous packet
* descriptors.
*/
/*
* The sum of all pkt lengths in the isoc request. Recommend to
* set it to zero, so the sum of isoc_pkt_length in the
* isoc_pkt_descr list will be used automatically and no check
* will be apply to this element.
*/
/*
* This field will be set by HCD and this field indicates the number
* of packets that completed with errors.
*/
/*
* Attributes specific to particular usb isochronous request.
* Supported values are: USB_ATTRS_ISOC_START_FRAME,
* USB_ATTRS_ISOC_XFER_ASAP.
*/
/*
* Isochronous OUT:
* allocated and set by client driver, freed and zeroed by HCD
* on successful completion
* Isochronous IN:
* allocated and set by HCD, freed by client driver
*/
/*
* The client driver specific private information.
*/
/*
* Isochronous OUT:
* must be allocated & initialized by client driver
* Isochronous IN:
* must be allocated by client driver
*/
struct usb_isoc_pkt_descr *isoc_pkt_descr;
/* Normal callback function (For synch transfers) */
struct usb_isoc_req *req);
/* Exception callback function (For asynch transfers) */
struct usb_isoc_req *req);
/* Callback context / handling flgs */
/*
*
* isoc_pkts_count must be > 0
*
* Arguments:
* dip - client driver's devinfo pointer
* isoc_pkts_count - number of pkts required
* len - 0 or size of mblk to allocate
* flags - USB_FLAGS_SLEEP:
* wait for resources
*
* Return Values:
* usb_isoc_req pointer or NULL
*/
void usb_free_isoc_req(
/*
* Returns current usb frame number.
*/
dev_info_t *dip);
/*
* Get maximum isochronous packets per usb isochronous request
*/
dev_info_t *dip);
/*
* usb_pipe_isoc_xfer()
*
* Client drivers call this to issue the isoch xfer (IN and OUT) to the USBA
* which starts polling the device.
*
* Arguments:
* pipe_handle - isoc pipe handle (obtained via usb_pipe_open().
* reqp - pointer to the isochronous pipe IN xfer request
* allocated by the client driver.
* flags - USB_FLAGS_SLEEP:
* wait for the resources to be available.
*
* return values:
* USB_SUCCESS - success.
* USB_FAILURE - unspecified failure.
* USB_NO_RESOURCES - no resources.
* USB_NO_FRAME_NUMBER - START_FRAME, ASAP flags not specified.
* USB_INVALID_START_FRAME - Starting USB frame number invalid.
*
* Notes:
* - usb_pipe_isoc_xfer on an IN pipe that is already being polled is a NOP.
* - requests can be queued on an OUT pipe.
*/
int usb_pipe_isoc_xfer(
/*
* usb_pipe_stop_isoc_polling():
*
* transfers without closing the isoc pipe.
*
* If USB_FLAGS_SLEEP has been specified then this function will block until
* polling has been stopped and all callbacks completed. If USB_FLAGS_SLEEP
* has NOT been specified then polling is terminated when the original
* request that started the polling has been returned with
* USB_CR_STOPPED_POLLING
*
* Stop polling should never fail.
*
* Arguments:
* pipe_handle - isoc pipe handle (obtained via usb_pipe_open().
* flags - USB_FLAGS_SLEEP:
* wait for polling to be stopped and all
* callbacks completed.
*/
/*
* ***************************************************************************
* USB device power management:
* ***************************************************************************
*/
/*
*
* As any usb device will have a max of 4 possible power states
* the #define for them are provided below with mapping to the
* corresponding OS power levels.
*/
#define USB_DEV_PWR_D0 USB_DEV_OS_FULL_PWR
#define USB_DEV_PWR_D1 5
#define USB_DEV_PWR_D2 6
#define USB_DEV_PWR_D3 USB_DEV_OS_PWR_OFF
#define USB_DEV_OS_PWR_0 0
#define USB_DEV_OS_PWR_1 1
#define USB_DEV_OS_PWR_2 2
#define USB_DEV_OS_PWR_3 3
#define USB_DEV_OS_PWR_OFF USB_DEV_OS_PWR_0
#define USB_DEV_OS_FULL_PWR USB_DEV_OS_PWR_3
/* Bit Masks for Power States */
#define USB_DEV_OS_PWRMASK_D0 1
#define USB_DEV_OS_PWRMASK_D1 2
#define USB_DEV_OS_PWRMASK_D2 4
#define USB_DEV_OS_PWRMASK_D3 8
/* conversion for OS to Dx levels */
#define USB_DEV_OS_PWR2USB_PWR(l) (USB_DEV_OS_FULL_PWR - (l))
/* from OS level to Dx mask */
/* Macro to check valid power level */
int cmd);
/* argument to usb_handle_remote wakeup function */
#define USB_REMOTE_WAKEUP_ENABLE 1
#define USB_REMOTE_WAKEUP_DISABLE 2
/*
* ***************************************************************************
* System event registration
* ***************************************************************************
*/
/* Functions for registering hotplug callback functions. */
/*
* Reset_level determines the extent to which the device is reset,
* It has the following values:
*
* USB_RESET_LVL_REATTACH - The device is reset, the original driver is
* detached and a new driver attaching process
* is started according to the updated
* compatible name. This reset level applies to
* the firmware download with the descriptors
* changing, or other situations in which the
* device needs to be reenumerated.
*
* USB_RESET_LVL_DEFAULT - Default reset level. The device is reset, all
* error status is cleared, the device state
* machines and registers are also cleared and
* need to be reinitialized in the driver. The
* current driver remains attached. This reset
* level applies to hardware error recovery, or
* firmware download without descriptors
* changing.
*/
typedef enum {
/*
* usb_reset_device:
*
* Client drivers call this function to request hardware reset for themselves,
* which may be required in some situations such as:
*
* 1) Some USB devices need the driver to upload firmware into devices' RAM
* and initiate a hardware reset in order to activate the new firmware.
* 2) Hardware reset may help drivers to recover devices from an error state
* caused by physical or firmware defects.
*
* Arguments:
* dip - pointer to devinfo of the client
* reset_level - see above
*
* Return values:
* USB_SUCCESS - With USB_RESET_LVL_DEFAULT: the device was reset
* successfully.
* - With USB_RESET_LVL_REATTACH: reenumeration was
* started successfully or a previous reset is still
* in progress.
* USB_FAILURE - The state of the device's parent hub is invalid
* (disconnected or suspended).
* - Called when the driver being detached.
* - The device failed to be reset with
* USB_RESET_LVL_DEFAULT specified.
* - Reenumeration failed to start up with
* - USB_RESET_LVL_REATTACH specified.
* USB_INVALID_ARGS - Invalid arguments.
* USB_INVALID_PERM - The driver of the dip doesn't own entire device.
* USB_BUSY - One or more pipes other than the default control
* pipe are open on the device with
* USB_RESET_LVL_DEFAULT specified.
* USB_INVALID_CONTEXT - Called from interrupt context with
* USB_RESET_LVL_DEFAULT specified.
*/
int usb_reset_device(
/*
* **************************************************************************
* USB device driver registration and callback functions remaining
* Contracted Project Private (for VirtualBox USB Device Capture)
* **************************************************************************
*/
/*
* 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 */
/*
* It is the callback function type for capture driver.
* Arguments:
* dev_descr - pointer to device descriptor
* dev_str - pointer to device strings
* path - pointer to device physical path
* bus - USB bus address
* port - USB port number
* drv - capture driver name.
* It is returned by the callback func.
* Return Values:
* USB_SUCCESS - VirtualBox will capture the device
* USB_FAILURE - VirtualBox will not capture the device
*/
typedef int (*usb_dev_driver_callback_t)(
char *path,
int bus,
int port,
char **drv,
void *reserved);
/*
* Register the callback function in the usba.
* Argument:
* dip - client driver's devinfo pointer
* cb - callback function
*
* Return Values:
* USB_SUCCESS - the registeration was successful
* USB_FAILURE - the registeration failed
*/
/*
* Unregister the callback function in the usba.
*/
/*
* ***************************************************************************
* USB Device and interface class, subclass and protocol codes
* ***************************************************************************
*/
/*
* Available device and interface class codes.
* Those which are device class codes are noted.
*/
#define USB_CLASS_AUDIO 1
#define USB_CLASS_HID 3
#define USB_CLASS_PHYSICAL 5
#define USB_CLASS_IMAGE 6
#define USB_CLASS_PRINTER 7
#define USB_CLASS_MASS_STORAGE 8
#define USB_CLASS_CDC_DATA 10
#define USB_CLASS_CCID 11
#define USB_CLASS_SECURITY 13
#define USB_CLASS_VIDEO 14
#define USB_CLASS_WIRELESS 224
#define USB_CLASS_APP 254
#define USB_CLASS_PER_INTERFACE 0 /* Class info is at interface level */
/* Audio subclass. */
#define USB_SUBCLS_AUD_CONTROL 0x01
#define USB_SUBCLS_AUD_STREAMING 0x02
#define USB_SUBCLS_AUD_MIDI_STREAMING 0x03
/* Comms subclass. */
#define USB_SUBCLS_CDCC_DIRECT_LINE 0x01
#define USB_SUBCLS_CDCC_ABSTRCT_CTRL 0x02
#define USB_SUBCLS_CDCC_PHONE_CTRL 0x03
#define USB_SUBCLS_CDCC_MULTCNL_ISDN 0x04
#define USB_SUBCLS_CDCC_ISDN 0x05
#define USB_SUBCLS_CDCC_ETHERNET 0x06
#define USB_SUBCLS_CDCC_ATM_NETWORK 0x07
/* HID subclass and protocols. */
#define USB_SUBCLS_HID_1 1
/* Printer subclass and protocols. */
#define USB_SUBCLS_PRINTER_1 1
/* Mass storage subclasses and protocols. */
/* Application subclasses. */
/* Video subclasses */
/* Wireless controller subclasses and protocols, refer to WUSB 1.0 chapter 8 */
/* Association subclass and protocol, Association Model Supplement to WUSB1.0 */
/* Misc subclasses and protocols, refer to WUSB 1.0 chapter 8 */
#ifdef __cplusplus
}
#endif
#endif /* _SYS_USB_USBAI_H */