Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
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. */
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. */
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. */
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. */
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  */
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__ */
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
USB connection resumed by the HOST.
Definition: qm_usb.h:27
Interrupt type endpoint.
Definition: qm_usb.h:45
Bulk type endpoint.
Definition: qm_usb.h:44
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
uint16_t max_packet_size
Endpoint max packet size.
Definition: qm_usb.h:53
void * callback_data
Callback user data.
Definition: qm_usb.h:71
Out transaction on this EP.
Definition: qm_usb.h:35
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
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
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
USB Endpoint type.
Definition: qm_usb.h:42
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
USB connection lost.
Definition: qm_usb.h:25
Control endpoint.
Definition: qm_usb.h:43
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
USB Endpoint Configuration.
Definition: qm_usb.h:51
USB reset.
Definition: qm_usb.h:22
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
SETUP received.
Definition: qm_usb.h:34
USB connection suspended by the HOST.
Definition: qm_usb.h:26
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
USB connection ready and enumeration done.
Definition: qm_usb.h:23
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
int qm_usb_attach(const qm_usb_t usb)
Attach the USB device.
Definition: qm_usb.c:416
qm_usb_ep_status_t
USB Endpoint Callback Status Codes.
Definition: qm_usb.h:33
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
Number of USB controllers.
Definition: qm_soc_regs.h:1944
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_type_t type
Endpoint type.
Definition: qm_usb.h:52
int qm_usb_set_address(const qm_usb_t usb, const uint8_t addr)
Set USB device address.
Definition: qm_usb.c:482
USB configuration completed.
Definition: qm_usb.h:24
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
int qm_usb_detach(const qm_usb_t usb)
Detach the USB device.
Definition: qm_usb.c:458
In transaction on this EP.
Definition: qm_usb.h:36
qm_usb_status_t
USB Driver Status Codes.
Definition: qm_usb.h:21