Kernel Functions for Drivers usbgetaltif(9F)
NAME
usbgetaltif, usbsetaltif, usbgetifnumber,
usbownsdevice - Get and set alternate interface values
SYNOPSIS
#include
int usbgetaltif(devinfot *dip, uintt interfacenumber,
uintt *alternatenumber, usbflagst flags);
int usbsetaltif(devinfot *dip, uintt interfacenumber,
uintt alternatenumber, usbflagst flags,
void (*callback)(usbpipehandlet pipehandle,
usbopaquet callbackarg, int rval, usbcbflagst flags),
usbopaquet callbackarg);
int usbgetifnumber(devinfot *dip);
booleant usbownsdevice(devinfot *dip);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
For usbgetaltif():
dip Pointer to device's devinfo structure.
interfacenumber Interface of the desired alternate.
alternatenumber Address where current alternate setting
is returned.
flags No flags are recognized. Reserved for
future expansion.
For usbsetaltif():
dip Pointer to device's devinfo structure.
SunOS 5.11 Last change: 29 Dec 2006 1
Kernel Functions for Drivers usbgetaltif(9F)
interfacenumber Interface of the desired alternate.
alternatenumber Alternate interface number to be set.
flags Only USBFLAGSLEP is recognized. Wait
for completion and do not call callback.
callback Callback handler to notify of asynchro-
nous completion.
callbackarg Second argument passed to callback
handler.
For usbgetifnumber():
dip Pointer to device's devinfo structure.
For usbownsdevice():
dip Pointer to device's devinfo structure.
DESCRIPTION
USB devices can have multiple configurations, each with many
interfaces. Within interfaces are alternate settings, and
within alternate settings are endpoints.
Each interface within a configuration may be represented by
the kernel as a device node. Only one set of device nodes
(interfaces as determined by the configuration) can be
active at one time.
Alternates to an interface represent different ways the ker-
nel sees a device node. Only one alternate setting within an
interface can be active (or selected) at one time. The
functions presented in this man page get or set interface or
alternate setting information.
The usbgetaltif() function requests the device to return
the current alternate setting of the given interface. This
function ignores the flags argument and always blocks.
SunOS 5.11 Last change: 29 Dec 2006 2
Kernel Functions for Drivers usbgetaltif(9F)
The usbsetaltif() function requests the device to set the
interface and its alternate setting as specified. Because
this call changes the current device's interface and sets
the new interface's mode of operation as seen by the system,
the driver must insure that all pipes other than the default
control pipe are closed and quiescent. To avoid contending
with another driver for a different part of the device, the
driver must be bound to: the entire device, the interface-
association which includes the alternative interface, or to
the interface whose number is interfacenumber.
If USBFLAGSLEP is set in flags, usbsetaltif() blocks
until completed. Otherwise, usbsetaltif() returns immedi-
ately and calls the callback handler when completed.
callback is the asynchronous callback handler and takes the
following arguments:
usbpipehandlet pipehandle
Handle of the default control pipe used to perform the
request.
usbopaquet callbackarg
Callbackarg specified to usbsetaltif().
int rval
Request status.
usbcbflagst callbackflags:
Status of the queueing operation. Can be:
USBCBNOINFO - Callback was uneventful.
USBCBASYNCREQFAILED - Error queueing request.
USBCBNORESOURCES - Error allocating resources.
The usbgetifnumber() function returns the interface
number, or USBCOMBINEDNODE or USBDEVICENODE node indi-
cating that the driver is bound to the entire device.
SunOS 5.11 Last change: 29 Dec 2006 3
Kernel Functions for Drivers usbgetaltif(9F)
The usbownsdevice() function returns BTRUE if the driver
of the dip argument owns the entire device, or BFALSE if
it owns just a particular interface.
RETURN VALUES
For usbgetaltif():
USBSUCES Interface's alternate setting was
successfully obtained.
USBINVALIDARGS Pointer to alternatenumber and/or
dip are NUL.
USBINVALIDCONTEXT Called from interrupt context.
USBFAILURE The interface number is invalid.
An access error occurred.
For usbsetaltif():
USBSUCES Alternate interface was successfully
set.
USBINVALIDARGS dip is NUL. USBFLAGSLEP is clear
and callback is NUL.
USBINVALIDPERM dip does not own the interface to be
set.
USBINVALIDCONTEXT Called from interrupt context with
USBFLAGSLEP specified.
USBINVALIDPIPE Pipe handle is NUL, invalid, or
refers to a pipe that is closing or
closed.
USBFAILURE The interface number and/or alternate
setting are invalid.
Pipes were open.
SunOS 5.11 Last change: 29 Dec 2006 4
Kernel Functions for Drivers usbgetaltif(9F)
An access error occurred.
For usbgetifnumber():
USBCOMBINEDNODE if the driver is responsible for the
entire active device configuration. The dip doesn't
correspond to an entire physical device.
USBDEVICENODE if the driver is responsible for the entire
device. The dip corresponds to an entire physical device.
interface number: otherwise.
For usbownsdevice():
BTRUE Driver of the dip argument owns the entire dev-
ice.
BFALSE Driver of the dip argument owns only the current
interface.
CONTEXT
The usbgetifnumber() and usbownsdevice() functions may
be called from user or kernel context.
The usbsetaltif() function may always be called from user
or kernel context. 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. See
usbcallbackflags(9S) for more information on callbacks.
The usbgetaltif() function may be called from user or
kernel context.
EXAMPLES
/* Change alternate setting of interface 0. Wait for completion. */
if (usbsetaltif(
dip, 0, newalternatesettingnum, USBFLAGSLEP, NUL, 0) !=
USBSUCES) {
cmnerr (CEWARN,
SunOS 5.11 Last change: 29 Dec 2006 5
Kernel Functions for Drivers usbgetaltif(9F)
"%s%d: Error setting alternate setting on pipe",
ddidrivername(dip), ddigetinstance(dip));
}
}
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), usbpipectrlxfer(9F), usbgetdevdata(9F),
usbgetstringdescr(9F), usbgetcfg(9F)
SunOS 5.11 Last change: 29 Dec 2006 6
|
