Kernel Functions for Drivers usbgetcfg(9F)
NAME
usbgetcfg, usbsetcfg - Get and set current USB device
configuration
SYNOPSIS
#include
int usbgetcfg(devinfot *dip, uintt cfgval, usbflagst flags);
int usbsetcfg(devinfot *dip, uintt cfgindex, usbflagst flags,
void (*callback)(usbpipehandlet pipehandle, usbopaquet
callbackarg, int rval, usbcbflagst flags), usbopaquet
callbackarg);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
For usbgetcfg():
dip Pointer to device's devinfo structure.
cfgval Pointer to returned configuration value.
flags Not used. Always waits for completion.
For usbsetcfg():
dip Pointer to device's devinfo structure.
cfgindex Desired device configuration index. Set to
USBDEVDEFAULTCONFIGINDEX to restore
default configuration.
flags Only USBFLAGSLEP is recognized. Wait for
completion and do not call callback.
callback Callback handler to notify of asynchronous
completion.
SunOS 5.11 Last change: 5 Jan 2004 1
Kernel Functions for Drivers usbgetcfg(9F)
callbackarg Second argument passed to callback handler.
DESCRIPTION
The usbgetcfg() function retrieves the current configura-
tion. It ignores the flags argument and always blocks while
contacting the device.
The usbsetcfg() function sets a new configuration. Because
this call changes the device's mode of operation, the device
must be quiescent and have all pipes, with the exception of
the default control pipe, closed. The driver must have con-
trol over the entire device and cannot own just a single
interface on a composite device. Additionally, its device
node must not be a parent to other device nodes that can be
operated by other drivers. The driver must own the device
exclusively, otherwise drivers managing other parts of the
device would be affected without their knowledge or control.
This call updates all internal USBA framework data struc-
tures, whereas issuing a raw USBREQSETCFG device request
does not. The usbsetcfg() function is the only supported
programmatic way to change device configuration.
This call blocks if USBFLAGSLEP is set in flags. It
returns immediately and calls the callback on completion if
USBFLAGSLEP is not set.
RETURN VALUES
For usbgetcfg():
USBSUCES New configuration is retrieved.
USBINVALIDARGS cfgval or dip is NUL.
USBFAILURE Configuration cannot be retrieved.
For usbsetcfg():
USBSUCES New configuration is set.
USBINVALIDARGS dip is NUL.
USBFLAGSLEP is clear and callback
SunOS 5.11 Last change: 5 Jan 2004 2
Kernel Functions for Drivers usbgetcfg(9F)
is NUL.
USBINVALIDCONTEXT Called from interrupt context with
USBFLAGSLEP specified.
USBINVALIDPERM Caller does not own entire device or
device is a parent to child devices.
USBUSY One or more pipes other than the
default control pipe are open on the
device.
USBINVALIDPIPE Pipe handle is NUL or invalid, or
pipe is closing or closed.
USBFAILURE An illegal configuration is speci-
fied.
One or more pipes other than the
default control pipe are open on the
device.
CONTEXT
The usbgetcfg() function may be called from user or kernel
context.
The usbsetcfg() function may be called from user or kernel
context always. It may be called from interrupt context only
if USBFLAGSLEP is not set in flags.
If the USBCBASYNCREQFAILED bit is clear in
usbcbflagst, the callback, if supplied, can block because
it is executing in kernel context. Otherwise the callback
cannot block. Please see usbcallbackflags(9S) for more
information on callbacks.
EXAMPLES
Setting the configuration to the one at index 1 (in the
array of usbcfgdatat configuration nodes as returned
by usbgetdevdata()), and verifying what the configuration
is at that index. (See usbgetdevdata(9F)).
uintt cfgindex = 1;
SunOS 5.11 Last change: 5 Jan 2004 3
Kernel Functions for Drivers usbgetcfg(9F)
/*
* Assume all pipes other than the default control pipe
* are closed and make sure all requests to the default
* control pipe have completed. /
*/
if (usbsetcfg(dip, cfgindex, USBFLAGSLEP, NUL, 0)
!= USBSUCES) {
cmnerr (CEWARN,
"%s%d: Error setting USB device to configuration #%d",
ddidrivername(dip), ddigetinstance(dip), cfgindex);
}
if (usbgetcfg(dip, &bConfigurationValue, 0) == USBSUCES) {
cmnerr (CEWARN, "%s%d: USB device active configuration is %d",
ddidrivername(dip), ddigetinstance(dip),
bConfigurationValue);
} else {
...
...
}
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
attributes(5), usbgetaltif(9F), usbgetdevdata(9F),
usbgetstringdescr(9F), usbpipeopen(9F),
usbcallbackflags(9S), usbcfgdescr(9S), usbepdescr(9S),
usbifdescr(9S)
SunOS 5.11 Last change: 5 Jan 2004 4
|
