Kernel Functions for Drivers usbpipectrlxfer(9F)
NAME
usbpipectrlxfer, usbpipectrlxferwait - USB control
pipe transfer functions
SYNOPSIS
#include
int usbpipectrlxfer(usbpipehandlet pipehandle,
usbctrlreqt *request,
usbflagst flags);
int usbpipectrlxferwait(usbpipehandlet pipehandle,
usbctrlsetupt *setup,
mblkt **data, usbcrt * completionreason,
usbcbflagst *cbflags,
usbflagst flags);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
For usbpipectrlxfer():
pipehandle Control pipe handle on which request is made.
request Pointer to control transfer request.
flags USBFLAGSLEP is the only flag recognized.
Wait for all pending request callbacks to
complete.
For usbpipectrlxferwait():
pipehandle Control pipe handle on which request is
made.
setup Pointer to setup parameters. (See
below.)
data Pointer to mblk containing data bytes
to transfer with command. Ignored if
NUL.
SunOS 5.11 Last change: 5 Jan 2004 1
Kernel Functions for Drivers usbpipectrlxfer(9F)
completionreason Returns overall completion status.
Ignored if NUL. Please see
usbcallbackflags(9S) for more infor-
mation.
callbackflags Returns flags set either during auto-
clearing or some other callback, which
indicate recovery handling done in
callback. Ignored if NUL.
flags No flags are recognized. Reserved for
future expansion.
DESCRIPTION
The usbpipectrlxfer() function requests the USBA frame-
work to perform a transfer through a USB control pipe. The
request is passed to the host controller driver (HCD), which
performs the necessary transactions to complete the request.
Requests are synchronous when USBFLAGSLEP is specified
in flags; calls for synchronous requests do not return until
their transaction is completed. Asynchronous requests (made
without specifying the USBFLAGSLEP flag) notifies the
caller of their completion via a callback function.
The usbpipectrlxferwait() function is a wrapper around
usbpipectrlxfer() that performs allocation and dealloca-
tion of all required data structures, and a synchronous
control-pipe transfer. It takes a usbctrlsetupt contain-
ing most usb setup parameters as an argument:
uchart bmRequestType /* characteristics of request. */
/* (See USB 2.0 spec, section 9.3). */
/* Combine one direction of: */
/* USBDEVREQHOSTODEV */
/* USBDEVREQDEVTOHOST */
/* with one request type of: */
/* USBDEVREQTYPESTANDARD */
/* USBDEVREQTYPECLAS */
/* USBDEVREQTYPEVENDOR */
/* with one recipient type of: */
/* USBDEVREQRCPTDEV */
/* USBDEVREQRCPTIF */
/* USBDEVREQRCPTEP */
/* USBDEVREQRCPTOTHER. */
uchart bRequest /* request or command. */
/* (See USB 2.0 spec, section */
/* 9.3 for standard commands.) */
SunOS 5.11 Last change: 5 Jan 2004 2
Kernel Functions for Drivers usbpipectrlxfer(9F)
uint16t wValue /* value which varies according to */
/* the command (bRequest). */
uint16t wIndex /* value which varies according to */
/* the command, typically used to */
/* pass an index or offset. */
uint16t wLength /* number of data bytes to transfer */
/* with command, if any. Same as */
/* size of mblk "data" below. */
usbreqattrst attrs; /* required request attributes */
Please see usbrequestattributes(9S), or refer to Section
5.5 of the USB 2.0 specification for more information on
these parameters. (The USB 2.0 specification is available at
www.usb.org.)
Mblks for data are allocated optionally when a request is
allocated via usballocctrlreq(9F) by passing a positive
value for the len argument. Control requests passing or
receiving no supplemental data need not allocate an mblk.
RETURN VALUES
For usbpipectrlxfer():
USBSUCES Transfer was successful.
USBINVALIDARGS Request is NUL.
USBINVALIDCONTEXT Called from interrupt context with
the USBFLAGSLEP flag set.
USBINVALIDREQUEST The request has been freed or oth-
erwise invalidated.
A set of conflicting attributes
were specified. See
usbrequestattributes(9S).
The normal and/or exception call-
back is NUL and USBFLAGSLEP is
not set.
Data space not provided to a con-
trol request while ctrlwLength is
SunOS 5.11 Last change: 5 Jan 2004 3
Kernel Functions for Drivers usbpipectrlxfer(9F)
nonzero.
USBINVALIDPIPE Pipe handle is NUL or invalid.
Pipe is closing or closed.
USBNORESOURCES Memory, descriptors or other
resources unavailable.
USBHCHARDWAREROR Host controller is in error state.
USBFAILURE An asynchronous transfer failed or
an internal error occurred.
The pipe is in an unsuitable state
(error, busy, not ready).
Additional status information may be available in the
ctrlcompletionreason and ctrlcbflags fields of the
request. Please see usbcallbackflags(9S) and
usbcompletionreason(9S) for more information.
For usbpipectrlxferwait():
USBSUCES Request was successful.
USBINVALIDCONTEXT Called from interrupt context.
USBINVALIDARGS dip is NUL.
Any error code returned by usbpipectrlxfer().
Additional status information may be available in the
ctrlcompletionreason and ctrlcbflags fields of the
request. Please see usbcallbackflags(9S) and
usbcompletionreason(9S) for more information.
CONTEXT
The usbpipectrlxfer() function may be called from kernel
or user context without regard to arguments and from the
SunOS 5.11 Last change: 5 Jan 2004 4
Kernel Functions for Drivers usbpipectrlxfer(9F)
interrupt context only when the USBFLAGSLEP flag is
clear.
The usbpipectrlxferwait() function may be called from
kernel or user context.
EXAMPLES
/* Allocate, initialize and issue a synchronous control request. */
usbctrlreqt ctrlreq;
void controlpipeexceptioncallback(
usbpipehandlet, usbctrlreqt*);
ctrlreq = usballocctrlreq(dip, 0, USBFLAGSLEP);
ctrlreq->ctrlbmRequestType = USBDEVREQHOSTODEV
USBDEVREQTYPECLAS USBDEVREQRCPTOTHER;
ctrlreq->ctrlbRequest = (uint8t)USBPRINTERSOFTRESET;
ctrlreq->ctrlexccb = controlpipeexceptioncallback;
...
...
if ((rval = usbpipectrlxfer(pipe, ctrlreq, USBFLAGSLEP))
!= USBSUCES) {
cmnerr (CEWARN, "%s%d: Error issuing USB cmd.",
ddidrivername(dip), ddigetinstance(dip));
}
-------
/*
* Allocate, initialize and issue an asynchronous control request to
* read a configuration descriptor.
*/
usbctrlreqt *ctrlreq;
void controlpipenormalcallback(
usbpipehandlet, usbctrlreqt*);
void controlpipeexceptioncallback(
usbpipehandlet, usbctrlreqt*);
struct buf *bp = ...;
ctrlreq =
usballocctrlreq(dip, sizeof(usbcfgdescrt), USBFLAGSLEP);
ctrlreq->ctrlbmRequestType = USBDEVREQDEVTOHOST
USBDEVREQTYPESTANDARD USBDEVREQRCPTDEV;
ctrlreq->ctrlwLength = sizeof(usbcfgdescrt);
ctrlreq->ctrlwValue = USBDESCRTYPESETUPCFG 0;
ctrlreq->ctrlbRequest = (uint8t)USBREQGETDESCR;
SunOS 5.11 Last change: 5 Jan 2004 5
Kernel Functions for Drivers usbpipectrlxfer(9F)
ctrlreq->ctrlcb = controlpipenormalcallback;
ctrlreq->ctrlexccb = controlpipeexceptioncallback;
/* Make buf struct available to callback handler. */
ctrlreq->ctrlclientprivate = (usbopaquet)bp;
...
...
if ((rval = usbpipectrlxfer(pipe, ctrlreq, USBFLAGSNOSLEP))
!= USBSUCES) {
cmnerr (CEWARN, "%s%d: Error issuing USB cmd.",
ddidrivername(dip), ddigetinstance(dip));
}
-------
/* Call usbpipectrlxferwait() to get device status. */
mblkt *data;
usbcrt completionreason;
usbcbflagst callbackflags;
usbctrlsetupt setupparams = {
USBDEVREQDEVTOHOST /* bmRequestType */
USBDEVREQTYPESTANDARD USBDEVREQRCPTDEV,
USBREQGETSTATUS, /* bRequest */
0, /* wValue */
0, /* wIndex */
USBGETSTATUSLEN, /* wLength */
0 /* attributes. */
};
if (usbpipectrlxferwait(
pipe,
&setupparams,
&data,
&compleetionreason,
&callbackflags,
0) != USBSUCES) {
cmnerr (CEWARN,
"%s%d: USB get status command failed: "
"reason=%d callbackflags=0x%x",
ddidrivername(dip), ddigetinstance(dip),
completionreason, callbackflags);
return (EIO);
}
/* Check data length. Should be USBGETSTATUSLEN (2 bytes). */
lengthreturned = data->bwptr - data->brptr;
if (lengthreturned != USBGETSTATUSLEN) {
cmnerr (CEWARN,
"%s%d: USB get status command returned %d bytes of data.",
ddidrivername(dip), ddigetinstance(dip), lengthreturned);
return (EIO);
SunOS 5.11 Last change: 5 Jan 2004 6
Kernel Functions for Drivers usbpipectrlxfer(9F)
}
/* Retrieve data in endian neutral way. */
status = (*(data->brptr ] 1) << 8) *(data->brptr);
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), usballocrequest(9F), usbgetcfg(9F),
usbgetstatus(9F). usbpipebulkxfer(9F),
usbpipeintrxfer(9F), usbpipeisocxfer(9F),
usbpipeopen(9F), usbpipereset(9F),
usbpipegetstate(9F), usbbulkrequest(9S),
usbcallbackflags(9S), usbctrlrequest(9S),
usbcompletionreason(9S), usbintrrequest(9S),
usbisocrequest(9S)
SunOS 5.11 Last change: 5 Jan 2004 7
|
