source: mainline/uspace/lib/usb/hcd.h@ af894a21

lfn serial ticket/834-toolchain-update topic/msim-upgrade topic/simplify-dev-export
Last change on this file since af894a21 was fa2a361, checked in by Vojtech Horky <vojtechhorky@…>, 15 years ago

Add missing comments
  • Property mode set to 100644
File size: 10.8 KB
Line 
1/*
2 * Copyright (c) 2010 Vojtech Horky
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/** @addtogroup libusb usb
30 * @{
31 */
32/** @file
33 * @brief USB Host Controller Driver.
34 */
35#ifndef LIBUSB_HCD_H_
36#define LIBUSB_HCD_H_
37
38#include "usb.h"
39
40#include <ipc/ipc.h>
41#include <async.h>
42
43/** Maximum size of transaction payload. */
44#define USB_MAX_PAYLOAD_SIZE 1020
45
46/** Opaque handle of active USB transaction.
47 * This handle is when informing about transaction outcome (or status).
48 */
49typedef ipcarg_t usb_transaction_handle_t;
50
51/** USB transaction outcome. */
52typedef enum {
53 USB_OUTCOME_OK,
54 USB_OUTCOME_CRCERROR,
55 USB_OUTCOME_BABBLE
56} usb_transaction_outcome_t;
57
58/** USB packet identifier. */
59typedef enum {
60#define _MAKE_PID_NIBBLE(tag, type) \
61 ((uint8_t)(((tag) << 2) | (type)))
62#define _MAKE_PID(tag, type) \
63 ( \
64 _MAKE_PID_NIBBLE(tag, type) \
65 | ((~_MAKE_PID_NIBBLE(tag, type)) << 4) \
66 )
67 USB_PID_OUT = _MAKE_PID(0, 1),
68 USB_PID_IN = _MAKE_PID(2, 1),
69 USB_PID_SOF = _MAKE_PID(1, 1),
70 USB_PID_SETUP = _MAKE_PID(3, 1),
71
72 USB_PID_DATA0 = _MAKE_PID(0 ,3),
73 USB_PID_DATA1 = _MAKE_PID(2 ,3),
74
75 USB_PID_ACK = _MAKE_PID(0 ,2),
76 USB_PID_NAK = _MAKE_PID(2 ,2),
77 USB_PID_STALL = _MAKE_PID(3 ,2),
78
79 USB_PID_PRE = _MAKE_PID(3 ,0),
80 /* USB_PID_ = _MAKE_PID( ,), */
81#undef _MAKE_PID
82#undef _MAKE_PID_NIBBLE
83} usb_packet_id;
84
85const char * usb_str_transaction_outcome(usb_transaction_outcome_t o);
86
87/** IPC methods for HCD.
88 *
89 * Notes for async methods:
90 *
91 * Methods for sending data to device (OUT transactions)
92 * - e.g. IPC_M_USB_HCD_INTERRUPT_OUT_ASYNC -
93 * always use the same semantics:
94 * - first, IPC call with given method is made
95 * - argument #1 is target address
96 * - argument #2 is target endpoint
97 * - argument #3 is buffer size
98 * - this call is immediately followed by IPC data write (from caller)
99 * - the initial call (and the whole transaction) is answer after the
100 * transaction is scheduled by the HC and acknowledged by the device
101 * or immediatelly after error is detected
102 * - the answer carries only the error code
103 *
104 * Methods for retrieving data from device (IN transactions)
105 * - e.g. IPC_M_USB_HCD_INTERRUPT_IN_ASYNC -
106 * also use the same semantics:
107 * - first, IPC call with given method is made
108 * - argument #1 is target address
109 * - argument #2 is target endpoint
110 * - argument #3 is buffer size
111 * - the call is not answered until the device returns some data (or until
112 * error occurs)
113 * - if the call is answered with EOK, first argument of the answer is buffer
114 * hash that could be used to retrieve the actual data
115 *
116 * Some special methods (NO-DATA transactions) do not send any data. These
117 * might behave as both OUT or IN transactions because communication parts
118 * where actual buffers are exchanged are ommitted.
119 *
120 * The mentioned data retrieval can be done any time after receiving EOK
121 * answer to IN method.
122 * This retrieval is done using the IPC_M_USB_HCD_GET_BUFFER_ASYNC where
123 * the first argument is buffer hash from call answer.
124 * This call must be immediatelly followed by data read-in and after the
125 * data are transferred, the initial call (IPC_M_USB_HCD_GET_BUFFER_ASYNC)
126 * is answered. Each buffer can be retrieved only once.
127 *
128 * For all these methods, wrap functions exists. Important rule: functions
129 * for IN transactions have (as parameters) buffers where retrieved data
130 * will be stored. These buffers must be already allocated and shall not be
131 * touch until the transaction is completed
132 * (e.g. not before calling usb_hcd_async_wait_for() with appropriate handle).
133 * OUT transactions buffers can be freed immediatelly after call is dispatched
134 * (i.e. after return from wrapping function).
135 *
136 * Async methods for retrieving data from device:
137 */
138typedef enum {
139 /** Send data over USB to a function.
140 * This method initializes large data transfer that must follow
141 * immediatelly.
142 * The recipient of this method must issue immediately data reception
143 * and answer this call after data buffer was transfered.
144 *
145 * Arguments of the call:
146 * - USB address of the function
147 * - endpoint of the function
148 * - transfer type
149 * - flags (not used)
150 *
151 * Answer:
152 * - EOK - ready to accept the data buffer
153 * - ELIMIT - too many transactions for current connection
154 * - ENOENT - callback connection does not exist
155 * - EINVAL - other kind of error
156 *
157 * Arguments of the answer:
158 * - opaque transaction handle (used in callbacks)
159 */
160 IPC_M_USB_HCD_SEND_DATA = IPC_FIRST_USER_METHOD,
161
162 /** Initiate data receive from a function.
163 * This method announces the HCD that some data will come.
164 * When this data arrives, the HCD will call back with
165 * IPC_M_USB_HCD_DATA_RECEIVED.
166 *
167 * Arguments of the call:
168 * - USB address of the function
169 * - endpoint of the function
170 * - transfer type
171 * - buffer size
172 * - flags (not used)
173 *
174 * Answer:
175 * - EOK - HCD accepted the request
176 * - ELIMIT - too many transactions for current connection
177 * - ENOENT - callback connection does not exist
178 *
179 * Arguments of the answer:
180 * - opaque transaction handle (used in callbacks)
181 */
182 IPC_M_USB_HCD_RECEIVE_DATA,
183
184 /** Tell maximum size of the transaction buffer (payload).
185 *
186 * Arguments of the call:
187 * (none)
188 *
189 * Answer:
190 * - EOK - always
191 *
192 * Arguments of the answer:
193 * - buffer size (in bytes):
194 */
195 IPC_M_USB_HCD_TRANSACTION_SIZE,
196
197
198 IPC_M_USB_HCD_INTERRUPT_OUT,
199 IPC_M_USB_HCD_INTERRUPT_IN,
200
201 IPC_M_USB_HCD_CONTROL_WRITE_SETUP,
202 IPC_M_USB_HCD_CONTROL_WRITE_DATA,
203 IPC_M_USB_HCD_CONTROL_WRITE_STATUS,
204
205 IPC_M_USB_HCD_CONTROL_READ_SETUP,
206 IPC_M_USB_HCD_CONTROL_READ_DATA,
207 IPC_M_USB_HCD_CONTROL_READ_STATUS,
208
209 /* async methods */
210
211 /** Asks for data buffer.
212 * See explanation at usb_hcd_method_t.
213 */
214 IPC_M_USB_HCD_GET_BUFFER_ASYNC,
215
216
217
218 /** Send interrupt data to device.
219 * See explanation at usb_hcd_method_t (OUT transaction).
220 */
221 IPC_M_USB_HCD_INTERRUPT_OUT_ASYNC,
222
223 /** Get interrupt data from device.
224 * See explanation at usb_hcd_method_t (IN transaction).
225 */
226 IPC_M_USB_HCD_INTERRUPT_IN_ASYNC,
227
228
229 /** Start WRITE control transfer.
230 * See explanation at usb_hcd_method_t (OUT transaction).
231 */
232 IPC_M_USB_HCD_CONTROL_WRITE_SETUP_ASYNC,
233
234 /** Send control-transfer data to device.
235 * See explanation at usb_hcd_method_t (OUT transaction).
236 */
237 IPC_M_USB_HCD_CONTROL_WRITE_DATA_ASYNC,
238
239 /** Terminate WRITE control transfer.
240 * See explanation at usb_hcd_method_t (NO-DATA transaction).
241 */
242 IPC_M_USB_HCD_CONTROL_WRITE_STATUS_ASYNC,
243
244
245
246 /** Start READ control transfer.
247 * See explanation at usb_hcd_method_t (OUT transaction).
248 */
249 IPC_M_USB_HCD_CONTROL_READ_SETUP_ASYNC,
250
251 /** Get control-transfer data from device.
252 * See explanation at usb_hcd_method_t (IN transaction).
253 */
254 IPC_M_USB_HCD_CONTROL_READ_DATA_ASYNC,
255
256 /** Terminate READ control transfer.
257 * See explanation at usb_hcd_method_t (NO-DATA transaction).
258 */
259 IPC_M_USB_HCD_CONTROL_READ_STATUS_ASYNC,
260
261
262 /* IPC_M_USB_HCD_ */
263} usb_hcd_method_t;
264
265/** IPC methods for callbacks from HCD. */
266typedef enum {
267 /** Confimation after data sent.
268 *
269 * Arguments of the call:
270 * - transaction handle
271 * - transaction outcome
272 */
273 IPC_M_USB_HCD_DATA_SENT = IPC_FIRST_USER_METHOD,
274
275 /** Notification of data received.
276 * This call initiates sending a data buffer from HCD to the client.
277 * See IPC_M_USB_HCD_SEND_DATA for details for buffer transfer is
278 * done.
279 *
280 * Arguments of the call:
281 * - transaction handle
282 * - transaction outcome
283 * - actual data length
284 */
285 IPC_M_USB_HCD_DATA_RECEIVED,
286
287 /** Notification about a serious trouble with HC.
288 */
289 IPC_M_USB_HCD_CONTROLLER_FAILURE,
290
291 /* IPC_M_USB_HCD_ */
292} usb_hcd_callback_method_t;
293
294
295int usb_hcd_create_phones(const char *, async_client_conn_t);
296int usb_hcd_send_data_to_function(int, usb_target_t, usb_transfer_type_t,
297 void *, size_t, usb_transaction_handle_t *);
298int usb_hcd_prepare_data_reception(int, usb_target_t, usb_transfer_type_t,
299 size_t, usb_transaction_handle_t *);
300
301
302int usb_hcd_transfer_interrupt_out(int, usb_target_t,
303 void *, size_t, usb_transaction_handle_t *);
304int usb_hcd_transfer_interrupt_in(int, usb_target_t,
305 size_t, usb_transaction_handle_t *);
306
307int usb_hcd_transfer_control_write_setup(int, usb_target_t,
308 void *, size_t, usb_transaction_handle_t *);
309int usb_hcd_transfer_control_write_data(int, usb_target_t,
310 void *, size_t, usb_transaction_handle_t *);
311int usb_hcd_transfer_control_write_status(int, usb_target_t,
312 usb_transaction_handle_t *);
313
314int usb_hcd_transfer_control_read_setup(int, usb_target_t,
315 void *, size_t, usb_transaction_handle_t *);
316int usb_hcd_transfer_control_read_data(int, usb_target_t,
317 size_t, usb_transaction_handle_t *);
318int usb_hcd_transfer_control_read_status(int, usb_target_t,
319 usb_transaction_handle_t *);
320
321int usb_hcd_async_transfer_interrupt_out(int, usb_target_t,
322 void *, size_t, usb_handle_t *);
323int usb_hcd_async_transfer_interrupt_in(int, usb_target_t,
324 void *, size_t, size_t *, usb_handle_t *);
325
326int usb_hcd_async_transfer_control_write_setup(int, usb_target_t,
327 void *, size_t, usb_handle_t *);
328int usb_hcd_async_transfer_control_write_data(int, usb_target_t,
329 void *, size_t, usb_handle_t *);
330int usb_hcd_async_transfer_control_write_status(int, usb_target_t,
331 usb_handle_t *);
332
333int usb_hcd_async_transfer_control_read_setup(int, usb_target_t,
334 void *, size_t, usb_handle_t *);
335int usb_hcd_async_transfer_control_read_data(int, usb_target_t,
336 void *, size_t, size_t *, usb_handle_t *);
337int usb_hcd_async_transfer_control_read_status(int, usb_target_t,
338 usb_handle_t *);
339
340int usb_hcd_async_wait_for(usb_handle_t);
341
342#endif
343/**
344 * @}
345 */
Note: See TracBrowser for help on using the repository browser.