Data Structures for Drivers usbclientdevdata(9S)
NAME
usbclientdevdata - Device configuration information
SYNOPSIS
#include
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
DESCRIPTION
The usbclientdevdatat structure carries all device con-
figuration information. It is provided to a USB client
driver through a call to usbgetdevdata(9F). Most USBA
functions require information which comes from this struc-
ture.
The usbclientdevdatat structure fields are:
usbpipehandlet devdefaultph; /* deflt ctrl pipe handle */
ddiiblockcookiet deviblockcookie;/* for calls to mutexinit */
/* for mutexes used by intr */
/* context callbacks. */
usbdevdescrt *devdescr; /* parsed* dev. descriptor */
char *devmfg; /* manufacturer's ID string */
char *devproduct; /* product ID string */
char *devserial; /* serial num. string */
usbregparselvlt devparselevel; /* Parse level */
/* reflecting the tree */
/* (if any) returned through */
/* the devcfg array. */
usbcfgdatat *devcfg; /* parsed* descr tree.*/
uintt devncfg; /* num cfgs in parsed descr. */
/* tree, devcfg array below.*/
usbcfgdatat *devcurrcfg; /* Pointer to the tree config*/
/* corresponding to the cfg */
/* active at the time of the */
/* usbgetdevdata() call */
int devcurrif; /* First active interface in */
/* tree under driver's control.*/
SunOS 5.11 Last change: 5 Jan 2004 1
Data Structures for Drivers usbclientdevdata(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 USB
standard defines that devices report in little-endian bit order) or
structure padding as necessary.
devparselevel represents the extent of the device
represented by the tree returned by the devcfg field and
has the following possible values:
USBPARSELVLNONE Build no tree. devncfg returns 0,
devcfg and devcurrcfg are returned
NUL, the devcurrxxx fields are
invalid.
USBPARSELVLIF 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 works
like USBPARSELVLAL.
USBPARSELVLCFG Parse entire configuration of config-
ured interface only. This is like
USBPARSELVLIF except entire confi-
guration is returned.
USBPARSELVLAL Parse entire device (all configura-
tions), even when driver is bound to a
single interface of a single confi-
guration.
The default control pipe handle is used mainly for control
commands and device setup.
The deviblockcookie is used to initialize client driver
mutexes which are used in interrupt-context callback
handlers. (All callback handlers called with
USBCBINTRCONTEXT in their usbcbflagst arg execute in
interrupt context.) This cookie is used in lieu of one
SunOS 5.11 Last change: 5 Jan 2004 2
Data Structures for Drivers usbclientdevdata(9S)
returned by ddigetiblockcookie(9F). Mutexes used in other
handlers or under other conditions should initialize per
mutexinit(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 devcfg, 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.) devncfg 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 parselevel field of USBPARSELVLAL indicates
that all configurations are represented in the tree. This
results when USBPARSELVLAL is explicitly requested by
the caller in the flags argument to usbgetdevdata(), or
when the whole device is seen by the system for the current
OS device node (as opposed to only a single configuration
for that OS device node). USBPARSELVLCFG is returned when
one entire configuration is returned in the tree.
USBPARSELVLIF is returned when one interface of one con-
figuration is returned in the tree. In the latter two cases,
the returned configuration is at
devcfg[USBDEVDEFAULTCONFIGINDEX]. USBPARSELVLNONE is
returned when no tree is returned. Note that the value of
this field can differ from the parselevel requested as an
argument to usbgetdevdata().
TRE STRUCTURE
The root of the tree is devcfg, an array of usbcfgdatat
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 devncfg. The array
itself is not NUL terminated.
SunOS 5.11 Last change: 5 Jan 2004 3
Data Structures for Drivers usbclientdevdata(9S)
When USBPARSELVLAL is returned in devparselevel, index
0 pertains to the first valid configuration. This pertains
to device configuration 1 as USB configuration 0 is not
defined. When devparselevel returns USBPARSELVLCFG or
USBPARSELVLIF, 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 usbcfgdatat configuration node contains a parsed usb
configuration descriptor (usbcfgdescrt cfgdescr) a
pointer to its string description (char *cfgstr) and string
size (cfgstrsize), a pointer to an array of interface nodes
(usbifdatat *cfgif), and a pointer to an array of
class/vendor (cv) descriptor nodes (usbcvsdatat
*cfgcvs). The interface node array size is kept in
cfgnif, and the cv node array size is kept in cfgncvs;
neither array is NUL terminated. When USBPARSELVLIF is
returned in devparselevel, 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
(usbaltifdatat) represents an alternate
representation. Each usbifdatat interface node points to
an array of alternate nodes (usbaltifdatat *ifalt)
and contains the size of the array (ifnalt).
Each interface alternate node holds an interface descriptor
(usbifdescrt altifdescr), a pointer to its string
description (char *altifstr), and has its own set of end-
points and bound cv descriptors. The pointer to the array of
endpoints is usbepdatat *altifep); the endpoint array
size is altifnep. The pointer to the array of cv descrip-
tors is usbcvsdatat *altifcvs; the cv descriptor array
size is altifncvs.
Each endpoint node holds an endpoint descriptor
(usbepdescrt epdescr), a pointer to an array of cv
descriptors for that endpoint (usbcvsdatat *epcvs), and
the size of that array (epncvs). An endpoint descriptor
may be passed to usbpipeopen(9F) to establish a logical
connection for data transfer.
SunOS 5.11 Last change: 5 Jan 2004 4
Data Structures for Drivers usbclientdevdata(9S)
Class and vendor descriptors (cv descriptors) are grouped
with the configuration, interface or endpoint descriptors
they immediately follow in the raw data returned by the dev-
ice. Tree nodes representing such descriptors
(usbcvsdatat) contain a pointer to the raw data (uchart
*cvsbuf) and the size of the data (uintt cvsbuflen).
Configuration and interface alternate nodes return string
descriptions. Note that all string descriptions returned
have a maximum length of USBMAXSTRINGLEN bytes and are in
English ASCI.
EXAMPLES
In the following example, a device's configuration data,
including the following descriptor tree, is retrieved by
usbgetdevdata(9F) into usbclientdevdatat *regdata:
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 cvdata {
char char1;
short short1;
char char2;
} cvdatat;
Parse the data of C/V descriptor 0, second configuration
(index 1), iface 1, alt 2, endpt 0.
usbclientdevdatat regdata;
usbcvsdatat *cvnode;
cvdatat parseddata;
SunOS 5.11 Last change: 5 Jan 2004 5
Data Structures for Drivers usbclientdevdata(9S)
cvnode =
®data->devcfg[1].cfgif[1].ifalt[2].altifep[0].epcvs[0];
(void)usbparsedata("csc",
(void *)(&cvnode->cvsbuf), cvnode->cvsbuflen,
&parseddata, sizeof(cvdatat));
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture PCI-based systems
Interface stability Committed
Availability SUNWusb
SEE ALSO
usbgetaltif(9F), usbgetcfg(9F), usbgetdevdata(9F),
usbgetstringdescr(9F), usblookupepdata(9F),
usbparsedata(9F), usbpipeopen(9F), usbcfgdescr(9S),
usbifdescr(9S), usbepdescr(9S), usbstringdescr(9S)
SunOS 5.11 Last change: 5 Jan 2004 6
|
