Data Structures for Drivers usb_client_dev_data(9S)
NAME
usb_client_dev_data - Device configuration information
SYNOPSIS
#include
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)DESCRIPTION
The usb_client_dev_data_t structure carries all device con-
figuration information. It is provided to a USB clientdriver through a call to usb_get_dev_data(9F). Most USBA
functions require information which comes from this struc-
ture.The usb_client_dev_data_t structure fields are:
usb_pipe_handle_t dev_default_ph; /* deflt ctrl pipe handle */
ddi_iblock_cookie_t dev_iblock_cookie;/* for calls to mutex_init */
/* for mutexes used by intr */ /* context callbacks. */usb_dev_descr_t *dev_descr; /* parsed* dev. descriptor */
char *dev_mfg; /* manufacturer's ID string */
char *dev_product; /* product ID string */
char *dev_serial; /* serial num. string */
usb_reg_parse_lvl_t dev_parse_level; /* Parse level */
/* reflecting the tree */ /* (if any) returned through *//* the dev_cfg array. */
usb_cfg_data_t *dev_cfg; /* parsed* descr tree.*/
uint_t dev_n_cfg; /* num cfgs in parsed descr. */
/* tree, dev_cfg array below.*/
usb_cfg_data_t *dev_curr_cfg; /* Pointer to the tree config*/
/* corresponding to the cfg */ /* active at the time of the *//* usb_get_dev_data() call */
int dev_curr_if; /* First active interface in */
/* tree under driver's control.*/SunOS 5.11 Last change: 5 Jan 2004 1
Data Structures for Drivers usb_client_dev_data(9S)
/* Always zero when driver */ /* controls whole device. */ * A parsed descriptor is in a struct whose fields' have been adjusted to the host processor. This may include endianness adjustment (the USBstandard defines that devices report in little-endian bit order) or
structure padding as necessary.dev_parse_level represents the extent of the device
represented by the tree returned by the dev_cfg field and
has the following possible values:USB_PARSE_LVL_NONE Build no tree. dev_n_cfg returns 0,
dev_cfg and dev_curr_cfg are returned
NULL, the dev_curr_xxx fields are
invalid.USB_PARSE_LVL_IF Parse configured interface only, if
configuration# and interface proper-
ties are set (as when different inter-
faces are viewed by the OS as dif-
ferent device instances). If an OS device instance is set up to represent an entire physical device, this workslike USB_PARSE_LVL_ALL.
USB_PARSE_LVL_CFG Parse entire configuration of config-
ured interface only. This is likeUSB_PARSE_LVL_IF except entire confi-
guration is returned.USB_PARSE_LVL_ALL Parse entire device (all configura-
tions), even when driver is bound to asingle interface of a single confi-
guration. The default control pipe handle is used mainly for control commands and device setup.The dev_iblock_cookie is used to initialize client driver
mutexes which are used in interrupt-context callback
handlers. (All callback handlers called withUSB_CB_INTR_CONTEXT in their usb_cb_flags_t arg execute in
interrupt context.) This cookie is used in lieu of oneSunOS 5.11 Last change: 5 Jan 2004 2
Data Structures for Drivers usb_client_dev_data(9S)
returned by ddi_get_iblock_cookie(9F). Mutexes used in other
handlers or under other conditions should initialize permutex_init(9F).
The parsed standard USB device descriptor is used for device type identification. The several ID strings, including the manufacturer's ID, product ID, and serial number may be used to identify the device in messages or to compare it to other devices.The descriptor tree, returned by dev_cfg, makes a device's
parsed standard USB descriptors available to the driver. The tree is designed to be easily traversed to get any or all standard USB 2.0 descriptors. (See the "Tree Structure"section of this manpage below.) dev_n_cfg returns the
number of configurations in the tree. Note that this value may differ from the number of configurations returned in the device descriptor.A returned parse_level field of USB_PARSE_LVL_ALL indicates
that all configurations are represented in the tree. Thisresults when USB_PARSE_LVL_ALL is explicitly requested by
the caller in the flags argument to usb_get_dev_data(), or
when the whole device is seen by the system for the current OS device node (as opposed to only a single configurationfor that OS device node). USB_PARSE_LVL_CFG is returned when
one entire configuration is returned in the tree.USB_PARSE_LVL_IF is returned when one interface of one con-
figuration is returned in the tree. In the latter two cases, the returned configuration is atdev_cfg[USB_DEV_DEFAULT_CONFIG_INDEX]. USB_PARSE_LVL_NONE is
returned when no tree is returned. Note that the value ofthis field can differ from the parse_level requested as an
argument to usb_get_dev_data().
TREE STRUCTUREThe root of the tree is dev_cfg, an array of usb_cfg_data_t
configuration nodes, each representing one device configura-
tion. The array index does not correspond to a configuration's value; use the bConfigurationValue field of the configuration descriptor within to find out the proper number for a given configuration.The size of the array is returned in dev_n_cfg. The array
itself is not NULL terminated.SunOS 5.11 Last change: 5 Jan 2004 3
Data Structures for Drivers usb_client_dev_data(9S)
When USB_PARSE_LVL_ALL is returned in dev_parse_level, index
0 pertains to the first valid configuration. This pertains to device configuration 1 as USB configuration 0 is notdefined. When dev_parse_level returns USB_PARSE_LVL_CFG or
USB_PARSE_LVL_IF, index 0 pertains to the device's one con-
figuration recognized by the system. (Note that the confi-
guration level is the only descriptor level in the tree where the index value does not correspond to the descriptor's value.)Each usb_cfg_data_t configuration node contains a parsed usb
configuration descriptor (usb_cfg_descr_t cfg_descr) a
pointer to its string description (char *cfg_str) and string
size (cfg_strsize), a pointer to an array of interface nodes
(usb_if_data_t *cfg_if), and a pointer to an array of
class/vendor (cv) descriptor nodes (usb_cvs_data_t
*cfg_cvs). The interface node array size is kept in
cfg_n_if, and the cv node array size is kept in cfg_n_cvs;
neither array is NULL terminated. When USB_PARSE_LVL_IF is
returned in dev_parse_level, the only interface (or alter-
nate group) included in the tree is that which is recognized by the system for the current OS device node. Each interface can present itself potentially in one of several alternate ways. An alternate tree node(usb_alt_if_data_t) represents an alternate
representation. Each usb_if_data_t interface node points to
an array of alternate nodes (usb_alt_if_data_t *if_alt)
and contains the size of the array (if_n_alt).
Each interface alternate node holds an interface descriptor(usb_if_descr_t altif_descr), a pointer to its string
description (char *altif_str), and has its own set of end-
points and bound cv descriptors. The pointer to the array ofendpoints is usb_ep_data_t *altif_ep); the endpoint array
size is altif_n_ep. The pointer to the array of cv descrip-
tors is usb_cvs_data_t *altif_cvs; the cv descriptor array
size is altif_n_cvs.
Each endpoint node holds an endpoint descriptor(usb_ep_descr_t ep_descr), a pointer to an array of cv
descriptors for that endpoint (usb_cvs_data_t *ep_cvs), and
the size of that array (ep_n_cvs). An endpoint descriptor
may be passed to usb_pipe_open(9F) to establish a logical
connection for data transfer.SunOS 5.11 Last change: 5 Jan 2004 4
Data Structures for Drivers usb_client_dev_data(9S)
Class and vendor descriptors (cv descriptors) are grouped with the configuration, interface or endpoint descriptorsthey immediately follow in the raw data returned by the dev-
ice. Tree nodes representing such descriptors(usb_cvs_data_t) contain a pointer to the raw data (uchar_t
*cvs_buf) and the size of the data (uint_t cvs_buf_len).
Configuration and interface alternate nodes return string descriptions. Note that all string descriptions returnedhave a maximum length of USB_MAXSTRINGLEN bytes and are in
English ASCII.EXAMPLES
In the following example, a device's configuration data, including the following descriptor tree, is retrieved byusb_get_dev_data(9F) into usb_client_dev_data_t *reg_data:
config 1 iface 0 alt 0 endpt 0 config 2 iface 0 iface 1 alt 0 endpt 0 cv 0 alt 1 endpt 0 endpt 1 cv 0 endpt 2 alt 2 endpt 0 cv 0and suppose that the C/V data is of the following format:
typedef struct cv_data {
char char1; short short1; char char2;} cv_data_t;
Parse the data of C/V descriptor 0, second configuration (index 1), iface 1, alt 2, endpt 0.
usb_client_dev_data_t reg_data;
usb_cvs_data_t *cv_node;
cv_data_t parsed_data;
SunOS 5.11 Last change: 5 Jan 2004 5
Data Structures for Drivers usb_client_dev_data(9S)
cv_node =
®_data->dev_cfg[1].cfg_if[1].if_alt[2].altif_ep[0].ep_cvs[0];
(void)usb_parse_data("csc",
(void *)(&cv_node->cvs_buf), cv_node->cvs_buf_len,
&parsed_data, sizeof(cv_data_t));
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | PCI-based systems |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| Availability | driver/usb ||_____________________________|_____________________________|
SEE ALSO
usb_get_alt_if(9F), usb_get_cfg(9F), usb_get_dev_data(9F),
usb_get_string_descr(9F), usb_lookup_ep_data(9F),
usb_parse_data(9F), usb_pipe_open(9F), usb_cfg_descr(9S),
usb_if_descr(9S), usb_ep_descr(9S), usb_string_descr(9S)
SunOS 5.11 Last change: 5 Jan 2004 6