Intel® Quark™ Microcontroller Software Interface 1.4.0 Intel® Quark™ Microcontroller BSP

- Main Page
- Modules
- Data Structures
- Files

- File List

qm_usb.h
1 /*
2 * {% copyright %}
3 */
4
5 #ifndef __QM_USB_H__
6 #define __QM_USB_H__
7
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10
11 /**
12 * USB peripheral driver for Quark Microcontrollers.
13 *
14 * @defgroup groupUSB USB
15 * @{
16 */
17
18 /**
19 * USB Driver Status Codes.
20 */
21 typedef enum {
22 QM_USB_RESET, /**< USB reset. */
23 QM_USB_CONNECTED, /**< USB connection ready and enumeration done. */
24 QM_USB_CONFIGURED, /**< USB configuration completed. */
25 QM_USB_DISCONNECTED, /**< USB connection lost. */
26 QM_USB_SUSPEND, /**< USB connection suspended by the HOST. */
27 QM_USB_RESUME, /**< USB connection resumed by the HOST. */
28 } qm_usb_status_t;
29
30 /**
31 * USB Endpoint Callback Status Codes.
32 */
33 typedef enum {
34 QM_USB_EP_SETUP, /**< SETUP received. */
35 QM_USB_EP_DATA_OUT, /**< Out transaction on this EP. */
36 QM_USB_EP_DATA_IN /**< In transaction on this EP. */
37 } qm_usb_ep_status_t;
38
39 /**
40 * USB Endpoint type.
41 */
42 typedef enum {
43 QM_USB_EP_CONTROL = 0, /**< Control endpoint. */
44 QM_USB_EP_BULK = 2, /**< Bulk type endpoint. */
45 QM_USB_EP_INTERRUPT = 3 /**< Interrupt type endpoint. */
46 } qm_usb_ep_type_t;
47
48 /**
49 * USB Endpoint Configuration.
50 */
51 typedef struct {
52 qm_usb_ep_type_t type; /**< Endpoint type. */
53 uint16_t max_packet_size; /**< Endpoint max packet size. */
54
55 qm_usb_ep_idx_t ep;
56
57 /**
58 * Callback for the USB Endpoint status.
59 *
60 * Called for notifying of data received and available to application
61 * on this endpoint.
62 *
63 * @param[in] data The callback user data.
64 * @param[in] error 0 on success.
65 * Negative @ref errno for possible error codes.
66 * @param[in] ep Endpoint index.
67 * @param[in] status USB Endpoint status.
68 */
69 void (*callback)(void *data, int error, qm_usb_ep_idx_t ep,
70 qm_usb_ep_status_t status);
71 void *callback_data; /**< Callback user data. */
72 } qm_usb_ep_config_t;
73
74 /**
75 * Callback function signature for the device status.
76 *
77 * @param[in] data The callback user data.
78 * @param[in] error 0 on success.
79 * Negative @ref errno for possible error codes.
80 * @param[in] status USB Controller Driver status.
81 */
82 typedef void (*qm_usb_status_callback_t)(void *data, int error,
83 qm_usb_status_t status);
84
85 /**
86 * Attach the USB device.
87 *
88 * Upon success, the USB PLL is enabled, and the USB device is now capable
89 * of transmitting and receiving on the USB bus and of generating interrupts.
90 *
91 * @param[in] usb Which USB module to perform action.
92 *
93 * @return Standard errno return type for QMSI.
94 * @retval 0 on success.
95 * @retval Negative @ref errno for possible error codes.
96 */
97 int qm_usb_attach(const qm_usb_t usb);
98
99 /**
100 * Detach the USB device.
101 *
102 * Upon success, the USB hardware PLL is powered down and USB communication
103 * is disabled.
104 *
105 * @param[in] usb Which USB module to perform action.
106 *
107 * @return Standard errno return type for QMSI.
108 * @retval 0 on success.
109 * @retval Negative @ref errno for possible error codes.
110 */
111 int qm_usb_detach(const qm_usb_t usb);
112
113 /**
114 * Reset the USB device controller back to it's initial state.
115 *
116 * Performs the Core Soft Reset from the USB controller.
117 * This means that all internal state machines are reset to the IDLE state,
118 * all FIFOs are flushed and all ongoing transactions are terminated.
119 *
120 * @note This function does NOT disable the USB clock PLL.
121 *
122 * @param[in] usb Which USB module to perform action.
123 *
124 * @return Standard errno return type for QMSI.
125 * @retval 0 on success.
126 * @retval Negative @ref errno for possible error codes.
127 */
128 int qm_usb_reset(const qm_usb_t usb);
129
130 /**
131 * Set USB device address.
132 *
133 * @param[in] usb Which USB module to perform action.
134 * @param[in] addr USB Device Address.
135 *
136 * @return Standard errno return type for QMSI.
137 * @retval 0 on success.
138 * @retval Negative @ref errno for possible error codes.
139 */
140 int qm_usb_set_address(const qm_usb_t usb, const uint8_t addr);
141
142 /**
143 * Set USB device controller status callback.
144 *
145 * @param[in] usb Which USB module to perform action.
146 * @param[in] cb USB Device Status callback.
147 *
148 * @return Standard errno return type for QMSI.
149 * @retval 0 on success.
150 * @retval Negative @ref errno for possible error codes.
151 */
152 int qm_usb_set_status_callback(const qm_usb_t usb,
153 const qm_usb_status_callback_t cb);
154
155 /**
156 * Configure endpoint.
157 *
158 * @param[in] usb Which USB module to perform action.
159 * @param[in] cfg Endpoint configuration.
160 *
161 * @return Standard errno return type for QMSI.
162 * @retval 0 on success.
163 * @retval Negative @ref errno for possible error codes.
164 */
165 int qm_usb_ep_set_config(const qm_usb_t usb,
166 const qm_usb_ep_config_t *const cfg);
167
168 /**
169 * Set / Clear stall condition for the selected endpoint.
170 *
171 * @param[in] usb Which USB module to perform action.
172 * @param[in] ep Endpoint index corresponding to the one listed in the
173 * device configuration table.
174 * @param[in] is_stalled Endpoint stall state to be set.
175 *
176 * @return Standard errno return type for QMSI.
177 * @retval 0 on success.
178 * @retval Negative @ref errno for possible error codes.
179 */
180 int qm_usb_ep_set_stall_state(const qm_usb_t usb, const qm_usb_ep_idx_t ep,
181 const bool is_stalled);
182
183 /**
184 * Check stall condition for the selected endpoint.
185 *
186 * @param[in] usb Which USB module to perform action.
187 * @param[in] ep Endpoint index corresponding to the one listed in the
188 * device configuration table.
189 * @param[out] stalled Endpoint stall state. Must not be NULL.
190 *
191 * @return Standard errno return type for QMSI.
192 * @retval 0 on success.
193 * @retval Negative @ref errno for possible error codes.
194 */
195 int qm_usb_ep_is_stalled(const qm_usb_t usb, const qm_usb_ep_idx_t ep,
196 bool *const stalled);
197
198 /**
199 * Halt the selected endpoint.
200 *
201 * @param[in] usb Which USB module to perform action.
202 * @param[in] ep Endpoint index corresponding to the one listed in the
203 * device configuration table.
204 *
205 * @return Standard errno return type for QMSI.
206 * @retval 0 on success.
207 * @retval Negative @ref errno for possible error codes.
208 */
209 int qm_usb_ep_halt(const qm_usb_t usb, const qm_usb_ep_idx_t ep);
210
211 /**
212 * Enable the selected endpoint.
213 *
214 * @param[in] usb Which USB module to perform action.
215 * @param[in] ep Endpoint index corresponding to the one listed in the
216 * device configuration table.
217 *
218 * @return Standard errno return type for QMSI.
219 * @retval 0 on success.
220 * @retval Negative @ref errno for possible error codes.
221 */
222 int qm_usb_ep_enable(const qm_usb_t usb, const qm_usb_ep_idx_t ep);
223
224 /**
225 * Disable the selected endpoint.
226 *
227 * @param[in] usb Which USB module to perform action.
228 * @param[in] ep Endpoint index corresponding to the one listed in the
229 * device configuration table.
230 *
231 * @return Standard errno return type for QMSI.
232 * @retval 0 on success.
233 * @retval Negative @ref errno for possible error codes.
234 */
235 int qm_usb_ep_disable(const qm_usb_t usb, const qm_usb_ep_idx_t ep);
236
237 /**
238 * Flush the selected IN endpoint TX FIFO.
239 *
240 * RX FIFO is global and cannot be flushed per endpoint. Thus, this function
241 * only applies to endpoints of direction IN.
242 *
243 * @param[in] usb Which USB module to perform action.
244 * @param[in] ep Endpoint index corresponding to the one listed in the
245 * device configuration table. Must be of IN direction.
246 *
247 * @return Standard errno return type for QMSI.
248 * @retval 0 on success.
249 * @retval Negative @ref errno for possible error codes.
250 */
251 int qm_usb_ep_flush(const qm_usb_t usb, const qm_usb_ep_idx_t ep);
252
253 /**
254 * Write data to the specified IN endpoint.
255 *
256 * @param[in] usb Which USB module to perform action.
257 * @param[in] ep Endpoint index corresponding to the one listed in the
258 * device configuration table. Must be of IN direction.
259 * @param[in] data Pointer to data to write.
260 * @param[in] len Length of data requested to write. This may be zero for
261 * a zero length status packet.
262 * @param[out] ret_bytes Bytes scheduled for transmission. This value may be
263 * NULL if the application expects all bytes to be
264 * written.
265 *
266 * @return Standard errno return type for QMSI.
267 * @retval 0 on success.
268 * @retval Negative @ref errno for possible error codes.
269 */
270 int qm_usb_ep_write(const qm_usb_t usb, const qm_usb_ep_idx_t ep,
271 const uint8_t *const data, const uint32_t len,
272 uint32_t *const ret_bytes);
273
274 /**
275 * Read data from OUT endpoint.
276 *
277 * This function is called by the Endpoint handler function, after an OUT
278 * interrupt has been received for that EP.
279 *
280 * @param[in] usb Which USB module to perform action.
281 * @param[in] ep Endpoint index corresponding to the one listed in the
282 * device configuration table. Must be of OUT direction.
283 * @param[in] data Pointer to data to read to. Must not be null.
284 * @param[in] max_len Length of data requested to be read.
285 * @param[out] read_bytes Number of bytes read.
286 *
287 * @return Standard errno return type for QMSI.
288 * @retval 0 on success.
289 * @retval Negative @ref errno for possible error codes.
290 */
291 int qm_usb_ep_read(const qm_usb_t usb, const qm_usb_ep_idx_t ep,
292 uint8_t *const data, const uint32_t max_len,
293 uint32_t *const read_bytes);
294
295 /**
296 * Check how many bytes are available on OUT endpoint.
297 *
298 * @param[in] usb Which USB module to perform action.
299 * @param[in] ep Endpoint index corresponding to the one listed in the
300 * device configuration table. Must be of OUT direction.
301 * @param[out] read_bytes Number of bytes read. Must not be null.
302 *
303 * @return Standard errno return type for QMSI.
304 * @retval 0 on success.
305 * @retval Negative @ref errno for possible error codes.
306 */
307 int qm_usb_ep_get_bytes_read(const qm_usb_t usb, const qm_usb_ep_idx_t ep,
308 uint32_t *const read_bytes);
309
310 /**
311 * @}
312 */
313 #endif /* __QM_USB_H__ */
qm_usb_ep_enable
int qm_usb_ep_enable(const qm_usb_t usb, const qm_usb_ep_idx_t ep)
Enable the selected endpoint.
Definition: qm_usb.c:664
QM_USB_RESUME
USB connection resumed by the HOST.
Definition: qm_usb.h:27
QM_USB_EP_INTERRUPT
Interrupt type endpoint.
Definition: qm_usb.h:45
QM_USB_EP_BULK
Bulk type endpoint.
Definition: qm_usb.h:44
qm_usb_ep_flush
int qm_usb_ep_flush(const qm_usb_t usb, const qm_usb_ep_idx_t ep)
Flush the selected IN endpoint TX FIFO.
Definition: qm_usb.c:727
qm_usb_ep_config_t::max_packet_size
uint16_t max_packet_size
Endpoint max packet size.
Definition: qm_usb.h:53
qm_usb_ep_config_t::callback_data
void * callback_data
Callback user data.
Definition: qm_usb.h:71
QM_USB_EP_DATA_OUT
Out transaction on this EP.
Definition: qm_usb.h:35
qm_usb_ep_is_stalled
int qm_usb_ep_is_stalled(const qm_usb_t usb, const qm_usb_ep_idx_t ep, bool *const stalled)
Check stall condition for the selected endpoint.
Definition: qm_usb.c:640
qm_usb_ep_get_bytes_read
int qm_usb_ep_get_bytes_read(const qm_usb_t usb, const qm_usb_ep_idx_t ep, uint32_t *const read_bytes)
Check how many bytes are available on OUT endpoint.
Definition: qm_usb.c:857
qm_usb_status_callback_t
void(* qm_usb_status_callback_t)(void *data, int error, qm_usb_status_t status)
Callback function signature for the device status.
Definition: qm_usb.h:82
qm_usb_ep_type_t
qm_usb_ep_type_t
USB Endpoint type.
Definition: qm_usb.h:42
qm_usb_ep_halt
int qm_usb_ep_halt(const qm_usb_t usb, const qm_usb_ep_idx_t ep)
Halt the selected endpoint.
Definition: qm_usb.c:609
QM_USB_DISCONNECTED
USB connection lost.
Definition: qm_usb.h:25
QM_USB_EP_CONTROL
Control endpoint.
Definition: qm_usb.h:43
qm_usb_ep_set_config
int qm_usb_ep_set_config(const qm_usb_t usb, const qm_usb_ep_config_t *const cfg)
Configure endpoint.
Definition: qm_usb.c:495
qm_usb_ep_config_t
USB Endpoint Configuration.
Definition: qm_usb.h:51
QM_USB_RESET
USB reset.
Definition: qm_usb.h:22
qm_usb_reset
int qm_usb_reset(const qm_usb_t usb)
Reset the USB device controller back to it's initial state.
Definition: qm_usb.c:476
QM_USB_EP_SETUP
SETUP received.
Definition: qm_usb.h:34
QM_USB_SUSPEND
USB connection suspended by the HOST.
Definition: qm_usb.h:26
qm_usb_ep_read
int qm_usb_ep_read(const qm_usb_t usb, const qm_usb_ep_idx_t ep, uint8_t *const data, const uint32_t max_len, uint32_t *const read_bytes)
Read data from OUT endpoint.
Definition: qm_usb.c:791
QM_USB_CONNECTED
USB connection ready and enumeration done.
Definition: qm_usb.h:23
qm_usb_set_status_callback
int qm_usb_set_status_callback(const qm_usb_t usb, const qm_usb_status_callback_t cb)
Set USB device controller status callback.
Definition: qm_usb.c:848
qm_usb_attach
int qm_usb_attach(const qm_usb_t usb)
Attach the USB device.
Definition: qm_usb.c:416
qm_usb_ep_status_t
qm_usb_ep_status_t
USB Endpoint Callback Status Codes.
Definition: qm_usb.h:33
qm_usb_ep_set_stall_state
int qm_usb_ep_set_stall_state(const qm_usb_t usb, const qm_usb_ep_idx_t ep, const bool is_stalled)
Set / Clear stall condition for the selected endpoint.
Definition: qm_usb.c:578
qm_usb_t
qm_usb_t
Number of USB controllers.
Definition: qm_soc_regs.h:1944
qm_usb_ep_disable
int qm_usb_ep_disable(const qm_usb_t usb, const qm_usb_ep_idx_t ep)
Disable the selected endpoint.
Definition: qm_usb.c:697
qm_usb_ep_config_t::type
qm_usb_ep_type_t type
Endpoint type.
Definition: qm_usb.h:52
qm_usb_set_address
int qm_usb_set_address(const qm_usb_t usb, const uint8_t addr)
Set USB device address.
Definition: qm_usb.c:482
QM_USB_CONFIGURED
USB configuration completed.
Definition: qm_usb.h:24
qm_usb_ep_write
int qm_usb_ep_write(const qm_usb_t usb, const qm_usb_ep_idx_t ep, const uint8_t *const data, const uint32_t len, uint32_t *const ret_bytes)
Write data to the specified IN endpoint.
Definition: qm_usb.c:761
qm_usb_detach
int qm_usb_detach(const qm_usb_t usb)
Detach the USB device.
Definition: qm_usb.c:458
QM_USB_EP_DATA_IN
In transaction on this EP.
Definition: qm_usb.h:36
qm_usb_status_t
qm_usb_status_t
USB Driver Status Codes.
Definition: qm_usb.h:21