1usb_callback_flags(9S) Data Structures for Drivers usb_callback_flags(9S)
2
3
4
6 usb_callback_flags - USB callback flag definitions
7
9 #include <sys/usb/usba.h>
10
11
13 Solaris DDI specific (Solaris DDI)
14
16 If the USB framework detects an error during a request execution, it
17 calls the client driver's exception callback handler to report what
18 happened. Callback flags (which are set prior to calling the exception
19 callback handler) detail errors discovered during the exception recov‐
20 ery process, and summarize recovery actions taken by the USBA frame‐
21 work.
22
23
24 Information from the callback flags supplements information from the
25 original transport error. For transfers, the original transport error
26 status is returned to the callback handler through the original request
27 (whose completion reason field contains any transport error indica‐
28 tion). For command completion callbacks, the callback's rval argument
29 contains the transport error status. A completion reason of USB_CR_OK
30 means the transfer completed with no errors detected.
31
32
33 The usb_cb_flags_t enumerated type contains the following definitions:
34
35 USB_CB_NO_INFO No additional errors discovered or recovery
36 actions taken.
37
38
39 USB_CB_FUNCTIONAL_STALL A functional stall occurred during the
40 transfer. A functional stall is usually
41 caused by a hardware error, and must be
42 explicitly cleared. A functional stall is
43 fatal if it cannot be cleared. The default
44 control pipe never shows a functional stall.
45
46
47 USB_CB_STALL_CLEARED A functional stall has been cleared by the
48 USBA framework. This can happen
49 if USB_ATTRS_AUTOCLEARING is set in the
50 request's xxxx_attributes field.
51
52
53 USB_CB_PROTOCOL_STALL A protocol stall has occurred during the
54 transfer. A protocol stall is caused usually
55 by an invalid or misunderstood command. It
56 is cleared automatically when the device is
57 given its next command. The USBA
58 framework treats stalls detected on default
59 pipe transfers as protocol stalls.
60
61
62 USB_CB_RESET_PIPE A pipe with a stall has been reset automati‐
63 cally via autoclearing, or via an explicit
64 call to usb_pipe_reset(9F). Resetting a pipe
65 consists of stopping all transactions on a
66 pipe, setting the pipe to the idle state,
67 and if the pipe is not the default pipe,
68 flushing all pending requests. The request
69 which has the error, plus all pending
70 requests which are flushed, show
71 USB_CB_RESET_PIPE set in the usb_cb_flags_t
72 when their exception callback is called.
73
74
75 USB_CB_ASYNC_REQ_FAILED Resources could not be allocated to process
76 callbacks asynchronously. Call‐
77 backs receiving this flag must not block,
78 since those callbacks are executing in a
79 context which holds resources shared by the
80 rest of the system. Note that exception
81 callbacks with USB_CB_ASYNC_REQ_FAILED set
82 may execute out of order from the requests
83 which preceded them. Normal callbacks may be
84 already queued when an exception hits that
85 the USBA is unable to queue.
86
87
88 USB_CB_SUBMIT_FAILED A queued request was submitted to the host
89 controller driver and was
90 rejected. The usb_completion_reason shows
91 why the request was rejected by the host
92 controller.
93
94
95 USB_CB_NO_RESOURCES Insufficient resources were available for
96 recovery to proceed.
97
98
99 USB_CB_INTR_CONTEXT Callback is executing in interrupt context
100 and should not block.
101
102
103
104 The usb_cb_flags_t enumerated type defines a bitmask. Multiple bits can
105 be set, reporting back multiple statuses to the exception callback han‐
106 dler.
107
108 CALLBACK HANDLER
109 The USBA framework supports callback handling as a way of asynchronous
110 client driver notification. There are three kinds of callbacks: Normal
111 completion transfer callback, exception (error) completion transfer
112 callback, and command completion callback, each described below.
113
114
115 Callback handlers are called whenever they are specified in a request
116 or command, regardless of whether or not that request or command speci‐
117 fies the USB_FLAGS_SLEEP flag. (USB_FLAGS_SLEEP tells the request or
118 command to block until completed.) Callback handlers must be specified
119 whenever an asynchronous transfer is requested.
120
121 PIPE POLICY
122 Each pipe is associated with a pool of threads that are used to run
123 callbacks associated with requests on that pipe. All transfer comple‐
124 tion callbacks for a particular pipe are run serially by a single
125 thread.
126
127
128 Pipes taking requests with callbacks which can block must have their
129 pipe policy properly initialized. If a callback blocks on a condition
130 that is only met by another thread associated with the same pipe, there
131 must be sufficient threads available. Otherwise that callback thread
132 will block forever. Similarly, problems will ensue when callbacks over‐
133 lap and there are not enough threads to handle the number of overlap‐
134 ping callbacks.
135
136
137 The pp_max_async_reqs field of the pipe_policy provides a hint of how
138 many threads to allocate for asynchronous processing of request call‐
139 backs on a pipe. Set this value high enough per pipe to accommodate
140 all of the pipe's possible asynchronous conditions. The pipe_policy is
141 passed to usb_pipe_open(9F).
142
143
144 Transfer completion callbacks (normal completion and exception):
145
146
147 Most transfer completion callbacks are allowed to block, but only under
148 certain conditions:
149
150 1. No callback is allowed to block if the callback flags show
151 USB_CB_INTR_CONTEXT set, since that flag indicates that the
152 callback is running in interrupt context instead of kernel
153 context. Isochronous normal completion callbacks, plus
154 those with USB_CB_ASYNC_REQ_FAILED set, execute in inter‐
155 rupt context.
156
157 2. Any callback except for isochronous normal completion can
158 block for resources (for example to allocate memory).
159
160 3. No callback can block for synchronous completion of a com‐
161 mand (for example, a call to usb_pipe_close(9F) with the
162 USB_FLAGS_SLEEP flag passed) done on the same pipe. The com‐
163 mand could wait for all callbacks to complete, including the
164 callback which issued that command, causing all operations
165 on the pipe to deadlock. Note that asynchronous commands can
166 start from a callback, providing that the pipe's policy
167 pp_max_async_reqs field is initialized to accommodate them.
168
169 4. Avoid callbacks that block for synchronous completion of
170 commands done on other pipes. Such conditions can cause com‐
171 plex dependencies and unpredictable results.
172
173 5. No callback can block waiting for a synchronous transfer
174 request to complete. (Note that making an asynchronous
175 request to start a new transfer or start polling does not
176 block, and is OK.)
177
178 6. No callback can block waiting for another callback to com‐
179 plete. (This is because all callbacks are done by a single
180 thread.)
181
182 7. Note that if a callback blocks, other callbacks awaiting
183 processing can backup behind it, impacting system resources.
184
185
186 A transfer request can specify a non-null normal-completion callback.
187 Such requests conclude by calling the normal-completion callback when
188 the transfer completes normally. Similarly, a transfer request can
189 specify a non-null exception callback. Such requests conclude by call‐
190 ing the exception callback when the transfer completes abnormally. Note
191 that the same callback can be used for both normal completion and
192 exception callback handling. A completion reason of USB_CR_OK defines
193 normal completion.
194
195
196 All request-callbacks take as arguments a usb_pipe_handle_t and a
197 pointer to the request:
198
199 xxxx_cb(usb_pipe_handle_t ph, struct usb_ctrl_req *req);
200
201
202
203 Such callbacks can retrieve saved state or other information from the
204 private area of the pipe handle. (See usb_pipe_set_private(9F).) Han‐
205 dlers also have access to the completion reason (usb_cr_t) and callback
206 flags (usb_cb_flags_t) through the request argument they are passed.
207
208
209 Request information follows. In the data below, xxxx below represents
210 the type of request (ctrl, intr, isoc or bulk.)
211
212 Request structure name is usb_xxxx_req_t.
213
214 Normal completion callback handler field is xxxx_cb.
215
216 Exception callback handler field is xxxx_exc_cb.
217
218 Completion reason field is xxxx_completion_reason.
219
220 Callback flags field is xxxx_cb_flags.
221
222
223 COMMAND COMPLETION CALLBACKS
224 Calls to some non-transfer functions can be set up for callback notifi‐
225 cation. These include usb_pipe_close(9F), usb_pipe_reset(9F),
226 usb_pipe_drain_reqs(9F), usb_set_cfg(9F), usb_set_alt_if(9F) and
227 usb_clr_feature(9F).
228
229
230 The signature of a command completion callback is as follows:
231
232 command_cb(
233 usb_pipe_handle_t cb_pipe_handle,
234 usb_opaque_t arg,
235 int rval,
236 usb_cb_flags_t flags);
237
238
239
240 As with transfer completion callbacks, command completion callbacks
241 take a usb_pipe_handle_t to retrieve saved state or other information
242 from the pipe's private area. Also, command completion callbacks are
243 provided with an additional user-definable argument (usb_opaque_t arg),
244 the return status of the executed command (int rval), and the callback
245 flags (usb_cb_flags_t flags).
246
247
248 The rval argument is roughly equivalent to the completion reason of a
249 transfer callback, indicating the overall status. See the return val‐
250 ues of the relevant function for possible rval values which can be
251 passed to the callback.
252
253
254 The callback flags can be checked when rval indicates failure status.
255 Just as for transfer completion callbacks, callback flags return addi‐
256 tional information on execution events.
257
259 See attributes(5) for descriptions of the following attributes:
260
261
262
263
264 ┌─────────────────────────────┬─────────────────────────────┐
265 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
266 ├─────────────────────────────┼─────────────────────────────┤
267 │Architecture │PCI-based systems │
268 ├─────────────────────────────┼─────────────────────────────┤
269 │Interface stability │Committed │
270 ├─────────────────────────────┼─────────────────────────────┤
271 │Availability │SUNWusb, SUNWusbu │
272 └─────────────────────────────┴─────────────────────────────┘
273
275 usb_alloc_request(9F), usb_pipe_bulk_xfer(9F), usb_pipe_ctrl_xfer(9F),
276 usb_pipe_intr_xfer(9F), usb_pipe_isoc_xfer(9F), usb_bulk_request(9S),
277 usb_ctrl_request(9S), usb_intr_request(9S), usb_isoc_request(9S)
278
279
280
281SunOS 5.11 5 Jan 2004 usb_callback_flags(9S)