Tribblix: manual page: usb_request

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) {
...
}