Kernel Functions for Drivers usbgetdevdata(9F)
NAME
usbgetdevdata, usbfreedevdata, usbfreedescrtree,
usbprintdescrtree - Retrieve device configuration infor-
mation
SYNOPSIS
#include
int usbgetdevdata(devinfot *dip, usbclientdevdatat **devdata,
usbregparselvlt parselevel, usbflagst flags);
void usbfreedevdata(devinfot *dip, usbclientdevdatat *devdata);
void usbfreedescrtree(devinfot *dip, usbclientdevdatat *devdata);
int usbprintdescrtree(devinfot *dip, usbclientdevdatat *devdata);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
For usbgetdevdata():
dip Pointer to device's devinfo structure.
devdata Address in which pointer to info is returned.
parselevel Portion of device represented in the tree of
parsed descriptors. See below for possible
usbregparselvlt values and explanations.
flags Not used.
For usbfreedevdata():
dip Pointer to device's devinfo structure.
devdata Pointer to usbclientdevdatat to be freed.
SunOS 5.11 Last change: 5 Jan 2004 1
Kernel Functions for Drivers usbgetdevdata(9F)
For usbfreedescrtree():
dip Pointer to device's devinfo structure.
devdata Pointer to usbclientdevdatat containing the
descriptor tree to free.
For usbprintdescrtree():
dip Pointer to device's devinfo structure.
devdata Pointer to usbclientdevdatat containing the
descriptor tree to display on-screen.
DESCRIPTION
The usbgetdevdata() function interrogates a device and
returns its configuration information in a
usbclientdevdatat structure. Most USBA functions require
information which comes from a usbclientdevdatat, and
all other functions in this man page operate on this struc-
ture. Please see usbclientdevdata(9S) for a full content
description. Pass the usbclientdevdatat structure to
usbclientdetach(9F) to completely deallocate it.
A descriptor tree is included in the information returned.
The usbregparselvlt type represents the extent of the
device to be represented by the returned tree (2nd arg
to usbgetdevdata) or what is actually represented in the
returned tree (devparselevel field of the returned
usbclientdevdatat). It has the following possible
values:
USBPARSELVLNONE Build no tree. devncfg returns 0,
devcfg and devcurrcfg are returned
NUL, and the devcurrxxx fields are
invalid.
USBPARSELVLIF If configuration number and interface
properties are set (as when different
interfaces are viewed by the OS as
different device instances), parse
configured interface only. If an OS
device instance is set up to represent
an entire physical device,
USBPARSELVLIF works like
SunOS 5.11 Last change: 5 Jan 2004 2
Kernel Functions for Drivers usbgetdevdata(9F)
USBPARSELVLAL.
USBPARSELVLCFG Parse entire configuration of config-
ured interface only. Behaves similarly
to USBPARSELVLIF, except that
entire configuration is returned.
USBPARSELVLAL Parse entire device (all configura-
tions), even when driver is bound to a
single interface of a single confi-
guration.
The usbfreedevdata() function undoes what
usbgetdevdata() set up. It releases memory for all
strings, descriptors, and trees set up by
usbgetdevdata().
The usbfreedescrtree() function frees the descriptor tree
of its usbclientdevdatat argument, while leaving the
rest of the information intact. The intent is for drivers to
free memory after copying needed descriptor information from
the tree. Upon return, the following usbclientdevdatat
fields are modified as follows: devcfg is NUL, devncfg
is zero and devparselevel is USBPARSELVLNONE. Addi-
tionally, devcurrcfg is NUL and devcurrif is invalid.
The usbprintdescrtree() function is an easy-to-use diag-
nostic aid which dumps the descriptor tree to the screen
when the system is verbose booted (boot -v). Output is
spaced with blank lines for readability and provides you
with an on-screen look at what a device has to offer.
RETURN VALUES
For usbgetdevdata():
USBSUCES Registration is successful.
USBINVALIDARGS dip or devdata is NUL. parselevel
is invalid.
USBINVALIDCONTEXT Called from interrupt context.
SunOS 5.11 Last change: 5 Jan 2004 3
Kernel Functions for Drivers usbgetdevdata(9F)
USBINVALIDVERSION usbclientattach(9F) was not called
first.
USBFAILURE Bad descriptor info or other internal
error.
For usbfreedevdata(): None
For usbfreedescrtree(): None, but no operation occurs if
dip and/or devdata are NUL.
For usbprintdescrtree():
USBSUCES Descriptor tree dump is successful.
USBINVALIDARGS devdata or dip are NUL.
USBINVALIDCONTEXT Called from interrupt context.
USBFAILURE Other error.
CONTEXT
The usbgetdevdata() and usbprintdescrtree() functions
may be called from user or kernel context.
The usbfreedevdata() and usbfreedescrtree() functions
may be called from user, kernel or interrupt context.
EXAMPLES
In this example, assume a device has the configuration shown
below, and the endpoint of config 2, iface 1, alt 1
which supports intr IN transfers needs to be found.
Config 2, iface 1 is the "default" config/iface for the
current OS device node.
config 1
iface 0
endpt 0
config 2
iface 0
iface 1
alt 0
SunOS 5.11 Last change: 5 Jan 2004 4
Kernel Functions for Drivers usbgetdevdata(9F)
endpt 0
cv 0
alt 1
endpt 0
endpt 1
cv 0
endpt 2
alt 2
endpt 0
cv 0
usbclientdevdatat *devdata;
usbepdescrt epdescr;
usbepdatat *eptreenode;
uint8t interface = 1;
uint8t alternate = 1;
uint8t firstepnumber = 0;
/*
* We want default config/iface, so specify USBPARSELVLIF.
* Default config will be returned as devcfg[0].
/
if (usbgetdevdata(dip, &devdata,
USBPARSELVLIF, 0) != USBSUCES) {
cmnerr (CEWARN,
"%s%d: Couldn't get USB configuration descr tree",
ddidrivername(dip), ddigetinstance(dip));
return (USBFAILURE);
}
eptreenode = usblookupepdata(dip, devdata, interface,
alternate, firstepnumber, USBEPATRINTR, USBEPDIRIN);
if (eptreenode != NUL) {
epdescr = eptreenode->epdescr;
} else {
cmnr (CEWARN,
"%s%d: Device is missing intr-IN endpoint",
ddidrivername(dip), ddigetinstance(dip));
usbfreedescrtree(dip, &devdata);
return (USBFAILURE);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Jan 2004 5
Kernel Functions for Drivers usbgetdevdata(9F)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture PCI-based systems
Interface stability Committed
Availability SUNWusb
SEE ALSO
attributes(5), usbclientattach(9F), usbgetaltif(9F),
usbgetcfg(9F), usbgetstringdescr(9F),
usblookupepdata(9F), usbparsedata(9F),
usbpipeopen(9F), usbcfgdescr(9S),
usbclientdevdata(9S), usbepdescr(9S), usbifdescr(9S),
usbstringdescr(9S)
SunOS 5.11 Last change: 5 Jan 2004 6
|
