USB_REQUEST_ATTRIBUTES(9S) Data Structures for Drivers

NAME


usb_request_attributes - Definition of USB request attributes

SYNOPSIS


#include <sys/usb/usba.h>


INTERFACE LEVEL


illumos DDI specific (illumos DDI)

DESCRIPTION


Request attributes specify how the USBA framework handles request
execution. Request attributes are specified in the request's
*_attributes field and belong to the enumerated type usb_req_attrs_t.


Supported request attributes are:

USB_ATTRS_SHORT_XFER_OK
Use this attribute when the maximum
transfer size is known, but it is
possible for the request to receive a
smaller amount of data. This attribute
tells the USBA framework to accept without
error transfers which are shorter than
expected.


USB_ATTRS_PIPE_RESET
Have the USB framework reset the pipe
automatically if an error occurs during
the transfer. Do not attempt to clear any
stall. The USB_CB_RESET_PIPE callback flag
is passed to the client driver's exception
handler to show the pipe has been reset.
Pending requests on pipes which are reset
are flushed unless the pipe is the default
pipe.


USB_ATTRS_AUTOCLEARING
Have the USB framework reset the pipe and
clear functional stalls automatically if an
error occurs during the transfer. The
callback flags passed to the client
driver's exception handler show the status
after the attempt to clear the stall.

USB_CB_FUNCTIONAL_STALL is set in the
callback flags to indicate that a
functional stall occurred.
USB_CB_STALL_CLEARED is also set if the
stall is cleared. The default pipe never
shows a functional stall if the
USB_ATTRS_AUTOCLEARING attribute is set. If
USB_CB_FUNCTIONAL_STALL is seen when
autoclearing is enabled, the device has a
fatal error.

USB_CB_PROTOCOL_STALL is set without
USB_CB_STALL_CLEARED in the callback flags
to indicate that a protocol stall was seen
but was not explicitly cleared. Protocol
stalls are cleared automatically when a
subsequent command is issued.

Autoclearing a stalled default pipe is not
allowed. The USB_CB_PROTOCOL_STALL callback
flag is set in the callback flags to
indicate the default pipe is stalled.

Autoclearing is not allowed when the
request is USB_REQ_GET_STATUS on the
default pipe.


USB_ATTRS_ONE_XFER
Applies only to interrupt-IN requests.
Without this flag, interrupt-IN requests
start periodic polling of the interrupt
pipe. This flag specifies to perform only a
single transfer. Do not start periodic
transfers with this request.


USB_ATTRS_ISOC_START_FRAME
Applies only to isochronous requests and
specifies that a request be started at a
given frame number. The starting frame
number is provided in the isoc_frame_no
field of the usb_isoc_req_t. Please see
usb_isoc_request(9S) for more information
about isochronous requests.

USB_ATTRS_ISOC_START_FRAME can be used to
delay a transfer by a few frames, allowing
transfers to an endpoint to sync up with
another source. (For example, synching up
audio endpoints to a video source.) The
number of a suitable starting frame in the
near future can be found by adding an
offset number of frames (usually between
four and ten) to the current frame number
returned from
usb_get_current_frame_number(9F). Note that
requests with starting frames which have
passed are rejected.


USB_ATTRS_ISOC_XFER_ASAP
Applies only to isochronous requests and
specifies that a request start as soon as
possible. The host controller driver picks
a starting frame number which immediately
follows the last frame of the last queued
request. The isoc_frame_no of the
usb_isoc_req_t is ignored. Please see
usb_isoc_request(9S) for more information
about isochronous requests.


EXAMPLES


/*
* Allocate, initialize and issue a synchronous bulk-IN request.
* Allow for short transfers.
*/

struct buf *bp;
usb_bulk_req_t bulk_req;
mblk_t *mblk;

bulk_req = usb_alloc_bulk_req(dip, bp->b_bcount, USB_FLAGS_SLEEP);

bulk_req->bulk_attributes =
USB_ATTRS_AUTOCLEARING | USB_ATTRS_SHORT_XFER_OK;

if ((rval = usb_pipe_bulk_xfer(pipe, bulk_req, USB_FLAGS_SLEEP)) !=
USB_SUCCESS) {
cmn_err (CE_WARN, "%s%d: Error reading bulk data.",
ddi_driver_name(dip), ddi_get_instance(dip));
}

mblk = bulk_req->bulk_data;
bcopy(mblk->rptr, buf->b_un.b_addr, mblk->wptr - mblk->rptr);
bp->b_resid = bp->b_count - (mblk->wptr = mblk->rptr);
...
...

----

usb_pipe_handle_t handle;
usb_frame_number_t offset = 10;
usb_isoc_req_t *isoc_req;

isoc_req = usb_alloc_isoc_req(...);
...
...
isoc_req->isoc_frame_no = usb_get_current_frame_number(dip) + offset;
isoc_req->isoc_attributes = USB_ATTRS_ISOC_START_FRAME;
...
...
if (usb_pipe_isoc_xfer(handle, isoc_req, 0) != USB_SUCCESS) {
...
}


ATTRIBUTES


See attributes(7) for descriptions of the following attributes:


+--------------------+-------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------+
|Architecture | PCI-based systems |
+--------------------+-------------------+
|Interface stability | Committed |
+--------------------+-------------------+

SEE ALSO


usb_alloc_request(9F), usb_get_current_frame_number(9F),
usb_pipe_bulk_xfer(9F), usb_pipe_ctrl_xfer(9F), usb_pipe_intr_xfer(9F),
usb_pipe_isoc_xfer(9F), usb_bulk_request(9S), usb_callback_flags(9S),
usb_completion_reason(9S), usb_ctrl_request(9S), usb_intr_request(9S),
usb_isoc_request(9S)

illumos January 5, 2004 USB_REQUEST_ATTRIBUTES(9S)