1usb_intr_request(9S) Data Structures for Drivers usb_intr_request(9S)
2
6 usb_intr_request - USB interrupt request structure
7
9 #include <sys/usb/usba.h>
10
13 Solaris DDI specific (Solaris DDI)
14
16 An interrupt request (that is, a request sent through an interrupt
17 pipe), is used to transfer small amounts of data infrequently, but
18 with bounded service periods. (Data flows in either direction.) Please
19 refer to Section 5.7 of the USB 2.0 specification for information on
20 interrupt transfers. (The USB 2.0 specification is available at
21 www.usb.org.)
22 The fields in the usb_intr_req_t are used to format an interrupt
25 request. Please see below for acceptable combinations of flags and
26 attributes.
27 The usb_intr_req_t fields are:
30 ushort_t intr_len; /* Size of pkt. Must be set */
32 /* Max size is 8K for low/full speed */
33 /* Max size is 20K for high speed */
34 mblk_t *intr_data; /* Data for the data phase */
35 /* IN: zero-len mblk alloc by client */
36 /* OUT: allocated by client */
37 usb_opaque_t intr_client_private; /* client specific information */
38 uint_t intr_timeout; /* only with ONE TIME POLL, in secs */
39 /* If set to zero, defaults to 5 sec */
40 usb_req_attrs_t intr_attributes;
41 /* Normal callback function, called upon completion. */
43 void (*intr_cb)(
44 usb_pipe_handle_t ph, struct usb_intr_req *req);
45 /* Exception callback function, for error handling. */
47 void (*intr_exc_cb)(
48 usb_pipe_handle_t ph, struct usb_intr_req *req);
49 /* set by USBA/HCD on completion */
51 usb_cr_t intr_completion_reason; /* overall completion status */
52 /* See usb_completion_reason(9S) */
53 usb_cb_flags_t intr_cb_flags; /* recovery done by callback hndlr */
54 /* See usb_callback_flags(9S) */
55 Request attributes define special handling for transfers. The following
59 attributes are valid for interrupt requests:
60 USB_ATTRS_SHORT_XFER_OK Accept transfers where less data is received
62 than expected.
63 USB_ATTRS_AUTOCLEARING Have USB framework reset pipe and clear
66 functional stalls automatically on excep‐
67 tion.
68 USB_ATTRS_PIPE_RESET Have USB framework reset pipe automatically
71 on exception.
72 USB_ATTRS_ONE_XFER Perform a single IN transfer. Do not start
75 periodic transfers with this request.
76 Please see usb_request_attributes(9S) for more information.
80 Interrupt transfers/requests are subject to the following
82 constraints and caveats:
83 1) The following table indicates combinations of
85 usb_pipe_intr_xfer() flags argument and fields
86 of the usb_intr_req_t request argument (X = don't care):
87 "none" as attributes in the table below indicates
89 neither ONE_XFER nor SHORT_XFER_OK
90 flags Type attributes data timeout semantics
92 ----------------------------------------------------------------
93 X IN X !=NULL X illegal
94 X IN !ONE_XFER X !=0 illegal
96 X IN !ONE_XFER NULL 0 See table note (A)
98 no sleep IN ONE_XFER NULL 0 See table note (B)
100 no sleep IN ONE_XFER NULL !=0 See table note (C)
102 sleep IN ONE_XFER NULL 0 See table note (D)
104 sleep IN ONE_XFER NULL !=0 See table note (E)
106 X OUT X NULL X illegal
108 X OUT ONE_XFER X X illegal
110 X OUT SHORT_XFER_OK X X illegal
112 no sleep OUT none !=NULL 0 See table note (F)
114 no sleep OUT none !=NULL !=0 See table note (G)
116 sleep OUT none !=NULL 0 See table note (H)
118 sleep OUT none !=NULL !=0 See table note (I)
120 Table notes:
122 A) Continuous polling, new data is returned in cloned request
124 structures via continous callbacks, original request is
125 returned on stop polling.
126 B) One time poll, no timeout, callback when data is
128 received.
129 C) One time poll, with timeout, callback when data
131 is received.
132 D) One time poll, no timeout, one callback, unblock
134 when transfer completes.
135 E) One time poll, timeout, one callback, unblock when
137 transfer completes or timeout occurs.
138 F) Transfer until data exhausted, no timeout, callback
140 when done.
141 G) Transfer until data exhausted, timeout, callback
143 when done.
144 H) Transfer until data exhausted, no timeout, unblock
146 when data is received.
147 I) Transfer until data exhausted, timeout, unblock
149 when data is received.
150 2) USB_FLAGS_SLEEP indicates here just to wait for
153 resources, except when ONE_XFER is set, in which case it
154 also waits for completion before returning.
155 3) Reads (IN):
157 a) The client driver does *not* provide a data buffer.
159 By default, a READ request would mean continuous
160 polling for data IN. The USBA framework allocates a
161 new data buffer for each poll. intr_len specifies
162 the amount of 'periodic data' for each poll.
163 b) The USBA framework issues a callback to the client
165 at the end of a polling interval when there is data to
166 return. Each callback returns its data in a new request
167 cloned from the original. Note that the amount of data
168 read IN is either intr_len or "wMaxPacketSize" in length.
169 c) Normally, the HCD keeps polling the interrupt endpoint
171 forever even if there is no data to be read IN. A
172 client driver may stop this polling by calling
173 usb_pipe_stop_intr_polling(9F).
174 d) If a client driver chooses to pass USB_ATTRS_ONE_XFER
176 as 'xfer_attributes' the HCD polls for data until
177 some data is received. The USBA framework reads in
178 the data, does a callback, and stops polling for any
179 more data. In this case, the client
180 driver need not explicitly call
181 usb_pipe_stop_intr_polling().
182 e) All requests with USB_ATTRS_ONE_XFER require callbacks
184 to be specified.
185 f) When continuous polling is stopped, the original
187 request is returned with USB_CR_STOPPED_POLLING.
188 g) If the USB_ATTRS_SHORT_XFER_OK attribute is not set
190 and a short transfer is received while polling,
191 an error is assumed and polling is stopped. In this
192 case or the case of other errors, the error must be cleared
193 and polling restarted by the client driver. Setting the
194 USB_ATTRS_AUTOCLEARING attribute will clear the error
195 but not restart polling. (NOTE: Polling can be
196 restarted from an exception callback corresponding to
197 an original request. Please see usb_pipe_intr_xfer(9F)
198 for more information.
199 4) Writes (OUT):
201 a) A client driver provides the data buffer, and
203 data, needed for intr write.
204 b) Unlike read (see previous section), there
206 is no continuous write mode.
207 c) The USB_ATTRS_ONE_XFER attribute is illegal.
209 By default USBA keeps writing intr data until
210 the provided data buffer has been
211 written out. The USBA framework does ONE
212 callback to the client driver.
213 d) Queueing is supported.
215 The intr_completion_reason indicates the status
217 of the transfer. See usb_completion_reason(9S) for
218 usb_cr_t definitions.
219 The intr_cb_flags are set prior to calling the
221 exception callback handler, to summarize recovery actions
222 taken and errors encountered during
223 recovery. See usb_callback_flags(9S) for
224 usb_cb_flags_t definitions.
225 --- Callback handling ---
227 All usb request types share the same callback
229 handling. Please see usb_callback_flags(9S) for a
230 description of use and operation.
231
234 See attributes(5) for descriptions of the following attributes:
235 ┌─────────────────────────────┬─────────────────────────────┐
240 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
241 ├─────────────────────────────┼─────────────────────────────┤
242 │Architecture │PCI-based systems │
243 ├─────────────────────────────┼─────────────────────────────┤
244 │Interface stability │Committed │
245 ├─────────────────────────────┼─────────────────────────────┤
246 │Availability │SUNWusbu │
247 └─────────────────────────────┴─────────────────────────────┘
248
250 usb_alloc_request(9F), usb_pipe_ctrl_xfer(9F), usb_pipe_bulk_xfer(9F),
251 usb_pipe_intr_xfer(9F), usb_pipe_isoc_xfer(9F), usb_bulk_request(9S),
252 usb_callback_flags(9S), usb_completion_reason(9S),
253 usb_ctrl_request(9S), usb_isoc_request(9S), usb_request_attributes(9S)
254SunOS 5.11 5 Jan 2004 usb_intr_request(9S)