usb_bulk_request

- USB bulk request structure

Synopsis

#include <sys/usb/usba.h>

Interface Level

Solaris DDI specific (Solaris DDI)

Description

A bulk request (that is, a request sent through a bulk pipe)
is used to transfer large amounts of data in reliable but non-time-critical
fashion. Please refer to Section 5.8 of the USB 2.0 specification for information
on bulk transfers. (The USB 2.0 specification is available at www.usb.org.)

The fields in the usb_bulk_req_t are used to format a bulk request.
Please see below for acceptable combinations of flags and
attributes.

C). Fill buffer, no timeout,
unblock when bulk_len is transferred; no callback.

D). Fill buffer, with timeout; unblock
when bulk_len is transferred or a timeout occurs; no callback.

E) Fill buffer,
no timeout, callback when bulk_len is transferred or first short packet is
received.

F). Fill buffer, with timeout; callback when bulk_len is transferred or first
short packet is received.

G). Fill buffer, no timeout, unblock when bulk_len is
transferred or first short packet is received; no callback.

H). Fill buffer, with
timeout; unblock when bulk_len is transferred, first short packet is received, or
a timeout occurs; no callback.

I). Empty buffer, no timeout; callback when bulk_len
is transferred.

J) Empty buffer, with timeout; callback when bulk_len is transferred or
a timeout occurs.

K). Empty buffer, no timeout; unblock when bulk_len is transferred;
no callback.

L). Empty buffer, with timeout; unblock when bulk_len is transferred or
a timeout occurs; no callback.

2) bulk_len must be > 0. bulk_data must not be NULL.

3) Bulk_residue is set for both READ and WRITE. If it is
set to 0, it means that all of the data was transferred
successfully. In case of WRITE it contains data not written and
in case of READ it contains the data NOT read so far.
A residue can only occur because of timeout or bus/device error. (Note that
a short transfer for a request where the USB_ATTRS_SHORT_XFER_OK attribute is not
set is considered a device error.) An exception callback is made
and completion_reason will be non-zero.

4) Splitting large Bulk xfers: Due to internal constraints, the USBA framework
can only do a limited size bulk data xfer per request.
A client driver may first determine this limitation by calling the USBA
interface (usb_pipe_get_max_bulk_xfer_size(9F)) and then restrict itself to doing transfers in multiples of this
fixed size. This forces a client driver to do data xfers in
a loop for a large request, splitting it into multiple chunks of
fixed size.

The bulk_cb_flags are set prior to calling the exception callback handler to
summarize recovery actions taken and errors encountered during recovery. See usb_callback_flags(9S) for usb_cb_flags_t
definitions.