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 : * Function to attach USB for device connection. Upon success, the USB PLL
142 : * is enabled, and the USB device is now capable of transmitting and receiving
143 : * on the USB bus and of generating interrupts.
144 : *
145 : * @return 0 on success, negative errno code on fail.
146 : */
147 1 : int usb_dc_attach(void);
148 :
149 : /**
150 : * @brief Detach the USB device
151 : *
152 : * Function to detach the USB device. Upon success, the USB hardware PLL
153 : * is powered down and USB communication is disabled.
154 : *
155 : * @return 0 on success, negative errno code on fail.
156 : */
157 1 : int usb_dc_detach(void);
158 :
159 : /**
160 : * @brief Reset the USB device
161 : *
162 : * This function returns the USB device and firmware back to it's initial state.
163 : * N.B. the USB PLL is handled by the usb_detach function
164 : *
165 : * @return 0 on success, negative errno code on fail.
166 : */
167 1 : int usb_dc_reset(void);
168 :
169 : /**
170 : * @brief Set USB device address
171 : *
172 : * @param[in] addr Device address
173 : *
174 : * @return 0 on success, negative errno code on fail.
175 : */
176 1 : int usb_dc_set_address(const uint8_t addr);
177 :
178 : /**
179 : * @brief Set USB device controller status callback
180 : *
181 : * Function to set USB device controller status callback. The registered
182 : * callback is used to report changes in the status of the device controller.
183 : * The status code are described by the usb_dc_status_code enumeration.
184 : *
185 : * @param[in] cb Callback function
186 : */
187 1 : void usb_dc_set_status_callback(const usb_dc_status_callback cb);
188 :
189 : /**
190 : * @brief check endpoint capabilities
191 : *
192 : * Function to check capabilities of an endpoint. usb_dc_ep_cfg_data structure
193 : * provides the endpoint configuration parameters: endpoint address,
194 : * endpoint maximum packet size and endpoint type.
195 : * The driver should check endpoint capabilities and return 0 if the
196 : * endpoint configuration is possible.
197 : *
198 : * @param[in] cfg Endpoint config
199 : *
200 : * @return 0 on success, negative errno code on fail.
201 : */
202 1 : int usb_dc_ep_check_cap(const struct usb_dc_ep_cfg_data * const cfg);
203 :
204 : /**
205 : * @brief Configure endpoint
206 : *
207 : * Function to configure an endpoint. usb_dc_ep_cfg_data structure provides
208 : * the endpoint configuration parameters: endpoint address, endpoint maximum
209 : * packet size and endpoint type.
210 : *
211 : * @param[in] cfg Endpoint config
212 : *
213 : * @return 0 on success, negative errno code on fail.
214 : */
215 1 : int usb_dc_ep_configure(const struct usb_dc_ep_cfg_data * const cfg);
216 :
217 : /**
218 : * @brief Set stall condition for the selected endpoint
219 : *
220 : * @param[in] ep Endpoint address corresponding to the one
221 : * listed in the device configuration table
222 : *
223 : * @return 0 on success, negative errno code on fail.
224 : */
225 1 : int usb_dc_ep_set_stall(const uint8_t ep);
226 :
227 : /**
228 : * @brief Clear stall condition for the selected endpoint
229 : *
230 : * @param[in] ep Endpoint address corresponding to the one
231 : * listed in the device configuration table
232 : *
233 : * @return 0 on success, negative errno code on fail.
234 : */
235 1 : int usb_dc_ep_clear_stall(const uint8_t ep);
236 :
237 : /**
238 : * @brief Check if the selected endpoint is stalled
239 : *
240 : * @param[in] ep Endpoint address corresponding to the one
241 : * listed in the device configuration table
242 : * @param[out] stalled Endpoint stall status
243 : *
244 : * @return 0 on success, negative errno code on fail.
245 : */
246 1 : int usb_dc_ep_is_stalled(const uint8_t ep, uint8_t *const stalled);
247 :
248 : /**
249 : * @brief Halt the selected endpoint
250 : *
251 : * @param[in] ep Endpoint address corresponding to the one
252 : * listed in the device configuration table
253 : *
254 : * @return 0 on success, negative errno code on fail.
255 : */
256 1 : int usb_dc_ep_halt(const uint8_t ep);
257 :
258 : /**
259 : * @brief Enable the selected endpoint
260 : *
261 : * Function to enable the selected endpoint. Upon success interrupts are
262 : * enabled for the corresponding endpoint and the endpoint is ready for
263 : * transmitting/receiving data.
264 : *
265 : * @param[in] ep Endpoint address corresponding to the one
266 : * listed in the device configuration table
267 : *
268 : * @return 0 on success, negative errno code on fail.
269 : */
270 1 : int usb_dc_ep_enable(const uint8_t ep);
271 :
272 : /**
273 : * @brief Disable the selected endpoint
274 : *
275 : * Function to disable the selected endpoint. Upon success interrupts are
276 : * disabled for the corresponding endpoint and the endpoint is no longer able
277 : * for transmitting/receiving data.
278 : *
279 : * @param[in] ep Endpoint address corresponding to the one
280 : * listed in the device configuration table
281 : *
282 : * @return 0 on success, negative errno code on fail.
283 : */
284 1 : int usb_dc_ep_disable(const uint8_t ep);
285 :
286 : /**
287 : * @brief Flush the selected endpoint
288 : *
289 : * This function flushes the FIFOs for the selected endpoint.
290 : *
291 : * @param[in] ep Endpoint address corresponding to the one
292 : * listed in the device configuration table
293 : *
294 : * @return 0 on success, negative errno code on fail.
295 : */
296 1 : int usb_dc_ep_flush(const uint8_t ep);
297 :
298 : /**
299 : * @brief Write data to the specified endpoint
300 : *
301 : * This function is called to write data to the specified endpoint. The
302 : * supplied usb_ep_callback function will be called when data is transmitted
303 : * out.
304 : *
305 : * @param[in] ep Endpoint address corresponding to the one
306 : * listed in the device configuration table
307 : * @param[in] data Pointer to data to write
308 : * @param[in] data_len Length of the data requested to write. This may
309 : * be zero for a zero length status packet.
310 : * @param[out] ret_bytes Bytes scheduled for transmission. This value
311 : * may be NULL if the application expects all
312 : * bytes to be written
313 : *
314 : * @return 0 on success, negative errno code on fail.
315 : */
316 1 : int usb_dc_ep_write(const uint8_t ep, const uint8_t *const data,
317 : const uint32_t data_len, uint32_t * const ret_bytes);
318 :
319 : /**
320 : * @brief Read data from the specified endpoint
321 : *
322 : * This function is called by the endpoint handler function, after an OUT
323 : * interrupt has been received for that EP. The application must only call this
324 : * function through the supplied usb_ep_callback function. This function clears
325 : * the ENDPOINT NAK, if all data in the endpoint FIFO has been read,
326 : * so as to accept more data from host.
327 : *
328 : * @param[in] ep Endpoint address corresponding to the one
329 : * listed in the device configuration table
330 : * @param[in] data Pointer to data buffer to write to
331 : * @param[in] max_data_len Max length of data to read
332 : * @param[out] read_bytes Number of bytes read. If data is NULL and
333 : * max_data_len is 0 the number of bytes
334 : * available for read should be returned.
335 : *
336 : * @return 0 on success, negative errno code on fail.
337 : */
338 1 : int usb_dc_ep_read(const uint8_t ep, uint8_t *const data,
339 : const uint32_t max_data_len, uint32_t *const read_bytes);
340 :
341 : /**
342 : * @brief Set callback function for the specified endpoint
343 : *
344 : * Function to set callback function for notification of data received and
345 : * available to application or transmit done on the selected endpoint,
346 : * NULL if callback not required by application code. The callback status
347 : * code is described by usb_dc_ep_cb_status_code.
348 : *
349 : * @param[in] ep Endpoint address corresponding to the one
350 : * listed in the device configuration table
351 : * @param[in] cb Callback function
352 : *
353 : * @return 0 on success, negative errno code on fail.
354 : */
355 1 : int usb_dc_ep_set_callback(const uint8_t ep, const usb_dc_ep_callback cb);
356 :
357 : /**
358 : * @brief Read data from the specified endpoint
359 : *
360 : * This is similar to usb_dc_ep_read, the difference being that, it doesn't
361 : * clear the endpoint NAKs so that the consumer is not bogged down by further
362 : * upcalls till he is done with the processing of the data. The caller should
363 : * reactivate ep by invoking usb_dc_ep_read_continue() do so.
364 : *
365 : * @param[in] ep Endpoint address corresponding to the one
366 : * listed in the device configuration table
367 : * @param[in] data Pointer to data buffer to write to
368 : * @param[in] max_data_len Max length of data to read
369 : * @param[out] read_bytes Number of bytes read. If data is NULL and
370 : * max_data_len is 0 the number of bytes
371 : * available for read should be returned.
372 : *
373 : * @return 0 on success, negative errno code on fail.
374 : */
375 1 : int usb_dc_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len,
376 : uint32_t *read_bytes);
377 :
378 : /**
379 : * @brief Continue reading data from the endpoint
380 : *
381 : * Clear the endpoint NAK and enable the endpoint to accept more data
382 : * from the host. Usually called after usb_dc_ep_read_wait() when the consumer
383 : * is fine to accept more data. Thus these calls together act as a flow control
384 : * mechanism.
385 : *
386 : * @param[in] ep Endpoint address corresponding to the one
387 : * listed in the device configuration table
388 : *
389 : * @return 0 on success, negative errno code on fail.
390 : */
391 1 : int usb_dc_ep_read_continue(uint8_t ep);
392 :
393 : /**
394 : * @brief Get endpoint max packet size
395 : *
396 : * @param[in] ep Endpoint address corresponding to the one
397 : * listed in the device configuration table
398 : *
399 : * @return Endpoint max packet size (mps)
400 : */
401 1 : int usb_dc_ep_mps(uint8_t ep);
402 :
403 : /**
404 : * @brief Start the host wake up procedure.
405 : *
406 : * Function to wake up the host if it's currently in sleep mode.
407 : *
408 : * @return 0 on success, negative errno code on fail.
409 : */
410 1 : int usb_dc_wakeup_request(void);
411 :
412 : /**
413 : * @}
414 : */
415 :
416 : #endif /* ZEPHYR_INCLUDE_DRIVERS_USB_USB_DC_H_ */
|
