Line data Source code
1 1 : /* usb_dc.h - USB device controller driver interface */
2 :
3 : /*
4 : * Copyright (c) 2016 Intel Corporation.
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 :
9 : /**
10 : * @file
11 : * @brief USB device controller APIs
12 : *
13 : * This file contains the USB device controller APIs. All device controller
14 : * drivers should implement the APIs described in this file.
15 : */
16 :
17 : #ifndef ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_
18 : #define ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_
19 :
20 : #include <zephyr/device.h>
21 :
22 : /**
23 : * @brief USB Device Controller API
24 : * @defgroup _usb_device_controller_api USB Device Controller API
25 : * @since 1.5
26 : * @version 1.0.0
27 : * @{
28 : */
29 :
30 : /**
31 : * @brief USB Driver Status Codes
32 : *
33 : * Status codes reported by the registered device status callback.
34 : */
35 1 : enum usb_dc_status_code {
36 : /** USB error reported by the controller */
37 : USB_DC_ERROR,
38 : /** USB reset */
39 : USB_DC_RESET,
40 : /** USB connection established, hardware enumeration is completed */
41 : USB_DC_CONNECTED,
42 : /** USB configuration done */
43 : USB_DC_CONFIGURED,
44 : /** USB connection lost */
45 : USB_DC_DISCONNECTED,
46 : /** USB connection suspended by the HOST */
47 : USB_DC_SUSPEND,
48 : /** USB connection resumed by the HOST */
49 : USB_DC_RESUME,
50 : /** USB interface selected */
51 : USB_DC_INTERFACE,
52 : /** Set Feature ENDPOINT_HALT received */
53 : USB_DC_SET_HALT,
54 : /** Clear Feature ENDPOINT_HALT received */
55 : USB_DC_CLEAR_HALT,
56 : /** Start of Frame received */
57 : USB_DC_SOF,
58 : /** Initial USB connection status */
59 : USB_DC_UNKNOWN
60 : };
61 :
62 : /**
63 : * @brief USB Endpoint Callback Status Codes
64 : *
65 : * Status Codes reported by the registered endpoint callback.
66 : */
67 1 : enum usb_dc_ep_cb_status_code {
68 : /** SETUP received */
69 : USB_DC_EP_SETUP,
70 : /** Out transaction on this EP, data is available for read */
71 : USB_DC_EP_DATA_OUT,
72 : /** In transaction done on this EP */
73 : USB_DC_EP_DATA_IN
74 : };
75 :
76 : /**
77 : * @brief USB Endpoint Transfer Type
78 : */
79 1 : enum usb_dc_ep_transfer_type {
80 : /** Control type endpoint */
81 : USB_DC_EP_CONTROL = 0,
82 : /** Isochronous type endpoint */
83 : USB_DC_EP_ISOCHRONOUS,
84 : /** Bulk type endpoint */
85 : USB_DC_EP_BULK,
86 : /** Interrupt type endpoint */
87 : USB_DC_EP_INTERRUPT
88 : };
89 :
90 : /**
91 : * @brief USB Endpoint Synchronization Type
92 : *
93 : * @note Valid only for Isochronous Endpoints
94 : */
95 1 : enum usb_dc_ep_synchronozation_type {
96 : /** No Synchronization */
97 : USB_DC_EP_NO_SYNCHRONIZATION = (0U << 2U),
98 : /** Asynchronous */
99 : USB_DC_EP_ASYNCHRONOUS = (1U << 2U),
100 : /** Adaptive */
101 : USB_DC_EP_ADAPTIVE = (2U << 2U),
102 : /** Synchronous*/
103 : USB_DC_EP_SYNCHRONOUS = (3U << 2U)
104 : };
105 :
106 : /**
107 : * @brief USB Endpoint Configuration.
108 : *
109 : * Structure containing the USB endpoint configuration.
110 : */
111 1 : struct usb_dc_ep_cfg_data {
112 : /** The number associated with the EP in the device
113 : * configuration structure
114 : * IN EP = 0x80 | \<endpoint number\>
115 : * OUT EP = 0x00 | \<endpoint number\>
116 : */
117 1 : uint8_t ep_addr;
118 : /** Endpoint max packet size */
119 1 : uint16_t ep_mps;
120 : /** Endpoint Transfer Type.
121 : * May be Bulk, Interrupt, Control or Isochronous
122 : */
123 1 : enum usb_dc_ep_transfer_type ep_type;
124 : };
125 :
126 : /**
127 : * Callback function signature for the USB Endpoint status
128 : */
129 1 : typedef void (*usb_dc_ep_callback)(uint8_t ep,
130 : enum usb_dc_ep_cb_status_code cb_status);
131 :
132 : /**
133 : * Callback function signature for the device
134 : */
135 1 : typedef void (*usb_dc_status_callback)(enum usb_dc_status_code cb_status,
136 : const uint8_t *param);
137 :
138 : /**
139 : * @brief Attach USB for device connection
140 : *
141 : * @deprecated Use @ref udc_api instead
142 : *
143 : * Function to attach USB for device connection. Upon success, the USB PLL
144 : * is enabled, and the USB device is now capable of transmitting and receiving
145 : * on the USB bus and of generating interrupts.
146 : *
147 : * @return 0 on success, negative errno code on fail.
148 : */
149 1 : __deprecated int usb_dc_attach(void);
150 :
151 : /**
152 : * @brief Detach the USB device
153 : *
154 : * @deprecated Use @ref udc_api instead
155 : *
156 : * Function to detach the USB device. Upon success, the USB hardware PLL
157 : * is powered down and USB communication is disabled.
158 : *
159 : * @return 0 on success, negative errno code on fail.
160 : */
161 1 : __deprecated int usb_dc_detach(void);
162 :
163 : /**
164 : * @brief Reset the USB device
165 : *
166 : * @deprecated Use @ref udc_api instead
167 : *
168 : * This function returns the USB device and firmware back to it's initial state.
169 : * N.B. the USB PLL is handled by the usb_detach function
170 : *
171 : * @return 0 on success, negative errno code on fail.
172 : */
173 1 : __deprecated int usb_dc_reset(void);
174 :
175 : /**
176 : * @brief Set USB device address
177 : *
178 : * @deprecated Use @ref udc_api instead
179 : *
180 : * @param[in] addr Device address
181 : *
182 : * @return 0 on success, negative errno code on fail.
183 : */
184 1 : __deprecated int usb_dc_set_address(const uint8_t addr);
185 :
186 : /**
187 : * @brief Set USB device controller status callback
188 : *
189 : * @deprecated Use @ref udc_api instead
190 : *
191 : * Function to set USB device controller status callback. The registered
192 : * callback is used to report changes in the status of the device controller.
193 : * The status code are described by the usb_dc_status_code enumeration.
194 : *
195 : * @param[in] cb Callback function
196 : */
197 1 : __deprecated void usb_dc_set_status_callback(const usb_dc_status_callback cb);
198 :
199 : /**
200 : * @brief check endpoint capabilities
201 : *
202 : * @deprecated Use @ref udc_api instead
203 : *
204 : * Function to check capabilities of an endpoint. usb_dc_ep_cfg_data structure
205 : * provides the endpoint configuration parameters: endpoint address,
206 : * endpoint maximum packet size and endpoint type.
207 : * The driver should check endpoint capabilities and return 0 if the
208 : * endpoint configuration is possible.
209 : *
210 : * @param[in] cfg Endpoint config
211 : *
212 : * @return 0 on success, negative errno code on fail.
213 : */
214 1 : __deprecated int usb_dc_ep_check_cap(const struct usb_dc_ep_cfg_data * const cfg);
215 :
216 : /**
217 : * @brief Configure endpoint
218 : *
219 : * @deprecated Use @ref udc_api instead
220 : *
221 : * Function to configure an endpoint. usb_dc_ep_cfg_data structure provides
222 : * the endpoint configuration parameters: endpoint address, endpoint maximum
223 : * packet size and endpoint type.
224 : *
225 : * @param[in] cfg Endpoint config
226 : *
227 : * @return 0 on success, negative errno code on fail.
228 : */
229 1 : __deprecated int usb_dc_ep_configure(const struct usb_dc_ep_cfg_data * const cfg);
230 :
231 : /**
232 : * @brief Set stall condition for the selected endpoint
233 : *
234 : * @deprecated Use @ref udc_api instead
235 : *
236 : * @param[in] ep Endpoint address corresponding to the one
237 : * listed in the device configuration table
238 : *
239 : * @return 0 on success, negative errno code on fail.
240 : */
241 1 : __deprecated int usb_dc_ep_set_stall(const uint8_t ep);
242 :
243 : /**
244 : * @brief Clear stall condition for the selected endpoint
245 : *
246 : * @deprecated Use @ref udc_api instead
247 : *
248 : * @param[in] ep Endpoint address corresponding to the one
249 : * listed in the device configuration table
250 : *
251 : * @return 0 on success, negative errno code on fail.
252 : */
253 1 : __deprecated int usb_dc_ep_clear_stall(const uint8_t ep);
254 :
255 : /**
256 : * @brief Check if the selected endpoint is stalled
257 : *
258 : * @deprecated Use @ref udc_api instead
259 : *
260 : * @param[in] ep Endpoint address corresponding to the one
261 : * listed in the device configuration table
262 : * @param[out] stalled Endpoint stall status
263 : *
264 : * @return 0 on success, negative errno code on fail.
265 : */
266 1 : __deprecated int usb_dc_ep_is_stalled(const uint8_t ep, uint8_t *const stalled);
267 :
268 : /**
269 : * @brief Halt the selected endpoint
270 : *
271 : * @deprecated Use @ref udc_api instead
272 : *
273 : * @param[in] ep Endpoint address corresponding to the one
274 : * listed in the device configuration table
275 : *
276 : * @return 0 on success, negative errno code on fail.
277 : */
278 1 : __deprecated int usb_dc_ep_halt(const uint8_t ep);
279 :
280 : /**
281 : * @brief Enable the selected endpoint
282 : *
283 : * @deprecated Use @ref udc_api instead
284 : *
285 : * Function to enable the selected endpoint. Upon success interrupts are
286 : * enabled for the corresponding endpoint and the endpoint is ready for
287 : * transmitting/receiving data.
288 : *
289 : * @param[in] ep Endpoint address corresponding to the one
290 : * listed in the device configuration table
291 : *
292 : * @return 0 on success, negative errno code on fail.
293 : */
294 1 : __deprecated int usb_dc_ep_enable(const uint8_t ep);
295 :
296 : /**
297 : * @brief Disable the selected endpoint
298 : *
299 : * @deprecated Use @ref udc_api instead
300 : *
301 : * Function to disable the selected endpoint. Upon success interrupts are
302 : * disabled for the corresponding endpoint and the endpoint is no longer able
303 : * for transmitting/receiving data.
304 : *
305 : * @param[in] ep Endpoint address corresponding to the one
306 : * listed in the device configuration table
307 : *
308 : * @return 0 on success, negative errno code on fail.
309 : */
310 1 : __deprecated int usb_dc_ep_disable(const uint8_t ep);
311 :
312 : /**
313 : * @brief Flush the selected endpoint
314 : *
315 : * @deprecated Use @ref udc_api instead
316 : *
317 : * This function flushes the FIFOs for the selected endpoint.
318 : *
319 : * @param[in] ep Endpoint address corresponding to the one
320 : * listed in the device configuration table
321 : *
322 : * @return 0 on success, negative errno code on fail.
323 : */
324 1 : __deprecated int usb_dc_ep_flush(const uint8_t ep);
325 :
326 : /**
327 : * @brief Write data to the specified endpoint
328 : *
329 : * @deprecated Use @ref udc_api instead
330 : *
331 : * This function is called to write data to the specified endpoint. The
332 : * supplied usb_ep_callback function will be called when data is transmitted
333 : * out.
334 : *
335 : * @param[in] ep Endpoint address corresponding to the one
336 : * listed in the device configuration table
337 : * @param[in] data Pointer to data to write
338 : * @param[in] data_len Length of the data requested to write. This may
339 : * be zero for a zero length status packet.
340 : * @param[out] ret_bytes Bytes scheduled for transmission. This value
341 : * may be NULL if the application expects all
342 : * bytes to be written
343 : *
344 : * @return 0 on success, negative errno code on fail.
345 : */
346 1 : __deprecated int usb_dc_ep_write(const uint8_t ep, const uint8_t *const data,
347 : const uint32_t data_len, uint32_t * const ret_bytes);
348 :
349 : /**
350 : * @brief Read data from the specified endpoint
351 : *
352 : * @deprecated Use @ref udc_api instead
353 : *
354 : * This function is called by the endpoint handler function, after an OUT
355 : * interrupt has been received for that EP. The application must only call this
356 : * function through the supplied usb_ep_callback function. This function clears
357 : * the ENDPOINT NAK, if all data in the endpoint FIFO has been read,
358 : * so as to accept more data from host.
359 : *
360 : * @param[in] ep Endpoint address corresponding to the one
361 : * listed in the device configuration table
362 : * @param[in] data Pointer to data buffer to write to
363 : * @param[in] max_data_len Max length of data to read
364 : * @param[out] read_bytes Number of bytes read. If data is NULL and
365 : * max_data_len is 0 the number of bytes
366 : * available for read should be returned.
367 : *
368 : * @return 0 on success, negative errno code on fail.
369 : */
370 1 : __deprecated int usb_dc_ep_read(const uint8_t ep, uint8_t *const data,
371 : const uint32_t max_data_len, uint32_t *const read_bytes);
372 :
373 : /**
374 : * @brief Set callback function for the specified endpoint
375 : *
376 : * @deprecated Use @ref udc_api instead
377 : *
378 : * Function to set callback function for notification of data received and
379 : * available to application or transmit done on the selected endpoint,
380 : * NULL if callback not required by application code. The callback status
381 : * code is described by usb_dc_ep_cb_status_code.
382 : *
383 : * @param[in] ep Endpoint address corresponding to the one
384 : * listed in the device configuration table
385 : * @param[in] cb Callback function
386 : *
387 : * @return 0 on success, negative errno code on fail.
388 : */
389 1 : __deprecated int usb_dc_ep_set_callback(const uint8_t ep, const usb_dc_ep_callback cb);
390 :
391 : /**
392 : * @brief Read data from the specified endpoint
393 : *
394 : * @deprecated Use @ref udc_api instead
395 : *
396 : * This is similar to usb_dc_ep_read, the difference being that, it doesn't
397 : * clear the endpoint NAKs so that the consumer is not bogged down by further
398 : * upcalls till he is done with the processing of the data. The caller should
399 : * reactivate ep by invoking usb_dc_ep_read_continue() do so.
400 : *
401 : * @param[in] ep Endpoint address corresponding to the one
402 : * listed in the device configuration table
403 : * @param[in] data Pointer to data buffer to write to
404 : * @param[in] max_data_len Max length of data to read
405 : * @param[out] read_bytes Number of bytes read. If data is NULL and
406 : * max_data_len is 0 the number of bytes
407 : * available for read should be returned.
408 : *
409 : * @return 0 on success, negative errno code on fail.
410 : */
411 1 : __deprecated int usb_dc_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len,
412 : uint32_t *read_bytes);
413 :
414 : /**
415 : * @brief Continue reading data from the endpoint
416 : *
417 : * @deprecated Use @ref udc_api instead
418 : *
419 : * Clear the endpoint NAK and enable the endpoint to accept more data
420 : * from the host. Usually called after usb_dc_ep_read_wait() when the consumer
421 : * is fine to accept more data. Thus these calls together act as a flow control
422 : * mechanism.
423 : *
424 : * @param[in] ep Endpoint address corresponding to the one
425 : * listed in the device configuration table
426 : *
427 : * @return 0 on success, negative errno code on fail.
428 : */
429 1 : __deprecated int usb_dc_ep_read_continue(uint8_t ep);
430 :
431 : /**
432 : * @brief Get endpoint max packet size
433 : *
434 : * @deprecated Use @ref udc_api instead
435 : *
436 : * @param[in] ep Endpoint address corresponding to the one
437 : * listed in the device configuration table
438 : *
439 : * @return Endpoint max packet size (mps)
440 : */
441 1 : __deprecated int usb_dc_ep_mps(uint8_t ep);
442 :
443 : /**
444 : * @brief Start the host wake up procedure.
445 : *
446 : * @deprecated Use @ref udc_api instead
447 : *
448 : * Function to wake up the host if it's currently in sleep mode.
449 : *
450 : * @return 0 on success, negative errno code on fail.
451 : */
452 1 : __deprecated int usb_dc_wakeup_request(void);
453 :
454 : /**
455 : * @}
456 : */
457 :
458 : #endif /* ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_ */
|
