usb_client_dev_data(9S) Data Structures for Drivers usb_client_dev_data(9S)NAMEusb_client_dev_data - Device configuration information
SYNOPSIS
#include <sys/usb/usba.h>
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)
DESCRIPTION
The usb_client_dev_data_t structure carries all device configuration
information. It is provided to a USB client driver through a call to
usb_get_dev_data(9F). Most USBA functions require information which
comes from this structure.
The usb_client_dev_data_t structure fields are:
usb_pipe_handle_t dev_default_ph; /* deflt control pipe handle */
ddi_iblock_cookie_t dev_iblock_cookie;/* for calling mutex_init */
/* for mutexes used by intr */
/* context callbacks. */
usb_dev_descr_t *dev_descr; /* parsed* device descriptor */
char *dev_mfg; /* manufacturer's ID string */
char *dev_product; /* product ID string */
char *dev_serial; /* serial number 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* descriptor 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 */
/* the tree which is under */
/* this driver's control. */
/* 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 USB
standard 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 val‐
ues:
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
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.
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 han‐
dlers called with USB_CB_INTR_CONTEXT in their usb_cb_flags_t arg exe‐
cute in interrupt context.) This cookie is used in lieu of one returned
by ddi_get_iblock_cookie(9F). Mutexes used in other handlers or under
other conditions should initialize per mutex_init(9F).
The parsed standard USB device descriptor is used for device type iden‐
tification.
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 stan‐
dard 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. This results 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 con‐
figuration for 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 configuration is returned in the
tree. In the latter two cases, the returned configuration is at
dev_cfg[USB_DEV_DEFAULT_CONFIG_INDEX]. USB_PARSE_LVL_NONE is returned
when no tree is returned. Note that the value of this field can differ
from the parse_level requested as an argument to usb_get_dev_data().
TREE STRUCTURE
The root of the tree is dev_cfg, an array of usb_cfg_data_t configura‐
tion nodes, each representing one device configuration. 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.
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 not defined. When dev_parse_level returns
USB_PARSE_LVL_CFG or USB_PARSE_LVL_IF, index 0 pertains to the device's
one configuration recognized by the system. (Note that the configura‐
tion 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 configura‐
tion 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 termi‐
nated. When USB_PARSE_LVL_IF is returned in dev_parse_level, the only
interface (or alternate 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 alter‐
nate ways. An alternate tree node (usb_alt_if_data_t) repre‐
sents 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 endpoints and bound cv descriptors.
The pointer to the array of endpoints is usb_ep_data_t *altif_ep); the
endpoint array size is altif_n_ep. The pointer to the array of cv
descriptors 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.
Class and vendor descriptors (cv descriptors) are grouped with the con‐
figuration, interface or endpoint descriptors they immediately follow
in the raw data returned by the device. 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 returned have 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 by usb_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 0
and 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;
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 attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Architecture │PCI-based systems │
├─────────────────────────────┼─────────────────────────────┤
│Interface stability │Evolving │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWusb │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOusb_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.10 5 Jan 2004 usb_client_dev_data(9S)
