1usb_bulk_request(9S)      Data Structures for Drivers     usb_bulk_request(9S)
2
3
4

NAME

6       usb_bulk_request - USB bulk request structure
7

SYNOPSIS

9       #include  <sys/usb/usba.h>
10
11

INTERFACE LEVEL

13       Solaris DDI specific (Solaris DDI)
14

DESCRIPTION

16       A bulk request (that is, a request sent through a bulk pipe) is used to
17       transfer large amounts of data in reliable but non-time-critical  fash‐
18       ion.  Please  refer  to  Section  5.8  of the USB 2.0 specification for
19       information on bulk transfers. (The USB 2.0 specification is  available
20       at www.usb.org.)
21
22
23       The  fields  in  the  usb_bulk_req_t are used to format a bulk request.
24       Please  see  below   for   acceptable   combinations   of   flags   and
25       attributes.
26
27
28       The usb_bulk_req_t fields are:
29
30         uint_t          bulk_len;       /* number of bytes to xfer      */
31                                         /* Please see */
32                                         /* usb_pipe_get_max_bulk_xfer_size(9F) */
33                                         /* for maximum size */
34         mblk_t          *bulk_data;     /* the data for the data phase  */
35                                         /* IN or OUT: allocated by client */
36         uint_t          bulk_timeout;   /* xfer timeout value in secs   */
37                                         /* If set to zero, defaults to 5 sec */
38         usb_opaque_t    bulk_client_private; /* Client specific information */
39         usb_req_attrs_t bulk_attributes; /* xfer-attributes     */
40
41         /* Normal callback function, called upon completion. */
42         void            (*bulk_cb)(
43                             usb_pipe_handle_t ph, struct usb_bulk_req *req);
44
45         /* Exception callback function, for error handling. */
46         void            (*bulk_exc_cb)(
47                             usb_pipe_handle_t ph, struct usb_bulk_req *req);
48
49         /* set by USBA/HCD framework on completion */
50         usb_cr_t        bulk_completion_reason; /* overall success status */
51                                            /* See usb_completion_reason(9S) */
52         usb_cb_flags_t  bulk_cb_flags; /* recovery done by callback hndlr */
53                                            /* See usb_callback_flags(9S) */
54
55
56
57       Request attributes define special handling for transfers. The following
58       attributes are valid for bulk requests:
59
60       USB_ATTRS_SHORT_XFER_OK    USB framework accepts transfers  where  less
61                                  data is received than expected.
62
63
64       USB_ATTRS_AUTOCLEARING     USB  framework  resets pipe and clears func‐
65                                  tional stalls automatically on exception.
66
67
68       USB_ATTRS_PIPE_RESET       USB framework resets pipe  automatically  on
69                                  exception.
70
71
72
73       Please see usb_request_attributes(9S) for more information.
74
75
76       Bulk  transfers/requests  are  subject to the following constraints and
77       caveats:
78
79
80       1) The following table indicates combinations  of  usb_pipe_bulk_xfer()
81       flags  argument  and fields of the usb_bulk_req_t request argument (X =
82       don't care).
83
84
85         Flags     Type  Attributes       Data   Timeout Semantics
86         ---------------------------------------------------------------
87          X         X     X                ==NULL X      illegal
88
89          X         X     ONE_XFER         X      X      illegal
90
91          no sleep  IN    !SHORT_XFER_OK   !=NULL 0      See  note (A)
92
93          no sleep  IN    !SHORT_XFER_OK   !=NULL > 0    See  note (B)
94
95          sleep     IN    !SHORT_XFER_OK   !=NULL 0      See  note (C)
96
97          sleep     IN    !SHORT_XFER_OK   !=NULL > 0    See  note (D)
98
99          no sleep  IN    SHORT_XFER_OK    !=NULL 0      See  note (E)
100
101          no sleep  IN    SHORT_XFER_OK    !=NULL > 0    See  note (F)
102
103          sleep     IN    SHORT_XFER_OK    !=NULL 0      See  note (G)
104
105          sleep     IN    SHORT_XFER_OK    !=NULL > 0    See  note (H)
106
107          X         OUT   SHORT_XFER_OK   X       X      illegal
108
109          no sleep  OUT   X               !=NULL  0      See  note (I)
110
111          no sleep  OUT   X               !=NULL  > 0    See  note (J)
112
113          sleep     OUT   X               !=NULL  0      See  note (K)
114
115          sleep     OUT   X               !=NULL  > 0    See  note (L)
116
117
118
119       Table notes:
120         A). Fill buffer, no timeout, callback when bulk_len is transferred.
121         B). Fill buffer, with timeout; callback when bulk_len is transferred.
122         C). Fill buffer, no timeout, unblock when bulk_len is transferred; no
123         callback.
124         D).  Fill  buffer, with timeout; unblock when bulk_len is transferred
125         or a timeout occurs; no callback.
126         E) Fill buffer, no timeout, callback when bulk_len is transferred  or
127         first short packet is received.
128         F).  Fill buffer, with timeout; callback when bulk_len is transferred
129         or first short packet is received.
130         G). Fill buffer, no timeout, unblock when bulk_len is transferred  or
131         first short packet is received; no callback.
132         H).  Fill buffer, with timeout; unblock when bulk_len is transferred,
133         first short packet is received, or a timeout occurs; no callback.
134         I). Empty buffer, no timeout; callback when bulk_len is transferred.
135         J) Empty buffer, with timeout; callback when bulk_len is  transferred
136         or a timeout occurs.
137         K).  Empty  buffer, no timeout; unblock when bulk_len is transferred;
138         no callback.
139         L). Empty buffer, with timeout; unblock when bulk_len is  transferred
140         or a timeout occurs; no callback.
141
142
143       2) bulk_len must be > 0. bulk_data must not be NULL.
144
145
146       3)  Bulk_residue  is set for both READ and WRITE. If it is set to 0, it
147       means that all of the data was transferred successfully.   In  case  of
148       WRITE  it contains data not written and in case of READ it contains the
149       data NOT read so far. A residue can only occur because  of  timeout  or
150       bus/device  error.  (Note that a short transfer for a request where the
151       USB_ATTRS_SHORT_XFER_OK attribute is not set  is  considered  a  device
152       error.)   An  exception  callback is made and completion_reason will be
153       non-zero.
154
155
156       4) Splitting large Bulk xfers: Due to internal  constraints,  the  USBA
157       framework  can  only  do  a limited size bulk data xfer per request.  A
158       client driver may first determine this limitation by calling  the  USBA
159       interface   (usb_pipe_get_max_bulk_xfer_size(9F))   and  then  restrict
160       itself to doing transfers in multiples of this fixed size. This  forces
161       a  client driver to do data xfers in a loop for a large request, split‐
162       ting it into multiple chunks of fixed size.
163
164
165       The bulk_completion_reason indicates the status of the  transfer.   See
166       usb_completion_reason(9S) for usb_cr_t definitions.
167
168
169       The  bulk_cb_flags are set prior to calling the exception callback han‐
170       dler to summarize recovery actions taken and errors encountered  during
171       recovery. See usb_callback_flags(9S) for usb_cb_flags_t definitions.
172
173
174       --- Callback handling ---
175
176
177       All  usb  request types share the same callback handling. See usb_call‐
178       back_flags(9S) for details.
179

ATTRIBUTES

181       See attributes(5) for descriptions of the following attributes:
182
183
184
185
186       ┌─────────────────────────────┬─────────────────────────────┐
187       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
188       ├─────────────────────────────┼─────────────────────────────┤
189       │Architecture                 │PCI-based systems            │
190       ├─────────────────────────────┼─────────────────────────────┤
191       │Interface stability          │Committed                    │
192       ├─────────────────────────────┼─────────────────────────────┤
193       │Availability                 │SUNWusbu                     │
194       └─────────────────────────────┴─────────────────────────────┘
195

SEE ALSO

197       usb_alloc_request(9F), usb_pipe_bulk_xfer(9F),  usb_pipe_ctrl_xfer(9F),
198       usb_pipe_get_max_bulk_transfer_size(9F),        usb_pipe_intr_xfer(9F),
199       usb_pipe_isoc_xfer(9F),   usb_callback_flags(9S),   usb_completion_rea‐
200       son(9S),           usb_ctrl_request(9S),          usb_intr_request(9S),
201       usb_isoc_request(9S), usb_request_attributes(9S)
202
203
204
205SunOS 5.11                        5 Jan 2004              usb_bulk_request(9S)
Impressum