1usb_callback_flags(9S) Data Structures for Drivers usb_callback_flags(9S)
2
6 usb_callback_flags - USB callback flag definitions
7
9 #include <sys/usb/usba.h>
10
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 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 The usb_cb_flags_t enumerated type contains the following definitions:
34 USB_CB_NO_INFO No additional errors discovered or recovery
36 actions taken.
37 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 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 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 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 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 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 USB_CB_NO_RESOURCES Insufficient resources were available for
96 recovery to proceed.
97 USB_CB_INTR_CONTEXT Callback is executing in interrupt context
100 and should not block.
101 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 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 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 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 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 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 Transfer completion callbacks (normal completion and exception):
145 Most transfer completion callbacks are allowed to block, but only under
148 certain conditions:
149 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 2. Any callback except for isochronous normal completion can
158 block for resources (for example to allocate memory).
159 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 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 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 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 7. Note that if a callback blocks, other callbacks awaiting
183 processing can backup behind it, impacting system resources.
184 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 All request-callbacks take as arguments a usb_pipe_handle_t and a
197 pointer to the request:
198 xxxx_cb(usb_pipe_handle_t ph, struct usb_ctrl_req *req);
200 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 Request information follows. In the data below, xxxx below represents
210 the type of request (ctrl, intr, isoc or bulk.)
211 Request structure name is usb_xxxx_req_t.
213 Normal completion callback handler field is xxxx_cb.
215 Exception callback handler field is xxxx_exc_cb.
217 Completion reason field is xxxx_completion_reason.
219 Callback flags field is xxxx_cb_flags.
221 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 The signature of a command completion callback is as follows:
231 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 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 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 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 ┌─────────────────────────────┬─────────────────────────────┐
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)
278SunOS 5.11 5 Jan 2004 usb_callback_flags(9S)