ChibiOS/HAL  6.1.0
hal_usb_lld.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 /**
18  * @file hal_usb_lld.h
19  * @brief PLATFORM USB subsystem low level driver header.
20  *
21  * @addtogroup USB
22  * @{
23  */
24 
25 #ifndef HAL_USB_LLD_H
26 #define HAL_USB_LLD_H
27 
28 #if (HAL_USE_USB == TRUE) || defined(__DOXYGEN__)
29 
30 /*===========================================================================*/
31 /* Driver constants. */
32 /*===========================================================================*/
33 
34 /**
35  * @brief Maximum endpoint address.
36  */
37 #define USB_MAX_ENDPOINTS 4
38 
39 /**
40  * @brief Status stage handling method.
41  */
42 #define USB_EP0_STATUS_STAGE USB_EP0_STATUS_STAGE_SW
43 
44 /**
45  * @brief The address can be changed immediately upon packet reception.
46  */
47 #define USB_SET_ADDRESS_MODE USB_LATE_SET_ADDRESS
48 
49 /**
50  * @brief Method for set address acknowledge.
51  */
52 #define USB_SET_ADDRESS_ACK_HANDLING USB_SET_ADDRESS_ACK_SW
53 
54 /*===========================================================================*/
55 /* Driver pre-compile time settings. */
56 /*===========================================================================*/
57 
58 /**
59  * @name PLATFORM configuration options
60  * @{
61  */
62 /**
63  * @brief USB driver enable switch.
64  * @details If set to @p TRUE the support for USB1 is included.
65  * @note The default is @p FALSE.
66  */
67 #if !defined(PLATFORM_USB_USE_USB1) || defined(__DOXYGEN__)
68 #define PLATFORM_USB_USE_USB1 FALSE
69 #endif
70 /** @} */
71 
72 /*===========================================================================*/
73 /* Derived constants and error checks. */
74 /*===========================================================================*/
75 
76 /*===========================================================================*/
77 /* Driver data structures and types. */
78 /*===========================================================================*/
79 
80 /**
81  * @brief Type of an IN endpoint state structure.
82  */
83 typedef struct {
84  /**
85  * @brief Requested transmit transfer size.
86  */
87  size_t txsize;
88  /**
89  * @brief Transmitted bytes so far.
90  */
91  size_t txcnt;
92  /**
93  * @brief Pointer to the transmission linear buffer.
94  */
95  const uint8_t *txbuf;
96 #if (USB_USE_WAIT == TRUE) || defined(__DOXYGEN__)
97  /**
98  * @brief Waiting thread.
99  */
101 #endif
102  /* End of the mandatory fields.*/
104 
105 /**
106  * @brief Type of an OUT endpoint state structure.
107  */
108 typedef struct {
109  /**
110  * @brief Requested receive transfer size.
111  */
112  size_t rxsize;
113  /**
114  * @brief Received bytes so far.
115  */
116  size_t rxcnt;
117  /**
118  * @brief Pointer to the receive linear buffer.
119  */
120  uint8_t *rxbuf;
121 #if (USB_USE_WAIT == TRUE) || defined(__DOXYGEN__)
122  /**
123  * @brief Waiting thread.
124  */
126 #endif
127  /* End of the mandatory fields.*/
129 
130 /**
131  * @brief Type of an USB endpoint configuration structure.
132  * @note Platform specific restrictions may apply to endpoints.
133  */
134 typedef struct {
135  /**
136  * @brief Type and mode of the endpoint.
137  */
138  uint32_t ep_mode;
139  /**
140  * @brief Setup packet notification callback.
141  * @details This callback is invoked when a setup packet has been
142  * received.
143  * @post The application must immediately call @p usbReadPacket() in
144  * order to access the received packet.
145  * @note This field is only valid for @p USB_EP_MODE_TYPE_CTRL
146  * endpoints, it should be set to @p NULL for other endpoint
147  * types.
148  */
150  /**
151  * @brief IN endpoint notification callback.
152  * @details This field must be set to @p NULL if the IN endpoint is not
153  * used.
154  */
156  /**
157  * @brief OUT endpoint notification callback.
158  * @details This field must be set to @p NULL if the OUT endpoint is not
159  * used.
160  */
162  /**
163  * @brief IN endpoint maximum packet size.
164  * @details This field must be set to zero if the IN endpoint is not
165  * used.
166  */
167  uint16_t in_maxsize;
168  /**
169  * @brief OUT endpoint maximum packet size.
170  * @details This field must be set to zero if the OUT endpoint is not
171  * used.
172  */
173  uint16_t out_maxsize;
174  /**
175  * @brief @p USBEndpointState associated to the IN endpoint.
176  * @details This structure maintains the state of the IN endpoint.
177  */
179  /**
180  * @brief @p USBEndpointState associated to the OUT endpoint.
181  * @details This structure maintains the state of the OUT endpoint.
182  */
184  /* End of the mandatory fields.*/
186 
187 /**
188  * @brief Type of an USB driver configuration structure.
189  */
190 typedef struct {
191  /**
192  * @brief USB events callback.
193  * @details This callback is invoked when an USB driver event is registered.
194  */
196  /**
197  * @brief Device GET_DESCRIPTOR request callback.
198  * @note This callback is mandatory and cannot be set to @p NULL.
199  */
201  /**
202  * @brief Requests hook callback.
203  * @details This hook allows to be notified of standard requests or to
204  * handle non standard requests.
205  */
207  /**
208  * @brief Start Of Frame callback.
209  */
211  /* End of the mandatory fields.*/
212 } USBConfig;
213 
214 /**
215  * @brief Structure representing an USB driver.
216  */
217 struct USBDriver {
218  /**
219  * @brief Driver state.
220  */
222  /**
223  * @brief Current configuration data.
224  */
226  /**
227  * @brief Bit map of the transmitting IN endpoints.
228  */
229  uint16_t transmitting;
230  /**
231  * @brief Bit map of the receiving OUT endpoints.
232  */
233  uint16_t receiving;
234  /**
235  * @brief Active endpoints configurations.
236  */
238  /**
239  * @brief Fields available to user, it can be used to associate an
240  * application-defined handler to an IN endpoint.
241  * @note The base index is one, the endpoint zero does not have a
242  * reserved element in this array.
243  */
245  /**
246  * @brief Fields available to user, it can be used to associate an
247  * application-defined handler to an OUT endpoint.
248  * @note The base index is one, the endpoint zero does not have a
249  * reserved element in this array.
250  */
252  /**
253  * @brief Endpoint 0 state.
254  */
256  /**
257  * @brief Next position in the buffer to be transferred through endpoint 0.
258  */
259  uint8_t *ep0next;
260  /**
261  * @brief Number of bytes yet to be transferred through endpoint 0.
262  */
263  size_t ep0n;
264  /**
265  * @brief Endpoint 0 end transaction callback.
266  */
268  /**
269  * @brief Setup packet buffer.
270  */
271  uint8_t setup[8];
272  /**
273  * @brief Current USB device status.
274  */
275  uint16_t status;
276  /**
277  * @brief Assigned USB address.
278  */
279  uint8_t address;
280  /**
281  * @brief Current USB device configuration.
282  */
283  uint8_t configuration;
284  /**
285  * @brief State of the driver when a suspend happened.
286  */
288 #if defined(USB_DRIVER_EXT_FIELDS)
289  USB_DRIVER_EXT_FIELDS
290 #endif
291  /* End of the mandatory fields.*/
292 };
293 
294 /*===========================================================================*/
295 /* Driver macros. */
296 /*===========================================================================*/
297 
298 /**
299  * @brief Returns the current frame number.
300  *
301  * @param[in] usbp pointer to the @p USBDriver object
302  * @return The current frame number.
303  *
304  * @notapi
305  */
306 #define usb_lld_get_frame_number(usbp) 0
307 
308 /**
309  * @brief Returns the exact size of a receive transaction.
310  * @details The received size can be different from the size specified in
311  * @p usbStartReceiveI() because the last packet could have a size
312  * different from the expected one.
313  * @pre The OUT endpoint must have been configured in transaction mode
314  * in order to use this function.
315  *
316  * @param[in] usbp pointer to the @p USBDriver object
317  * @param[in] ep endpoint number
318  * @return Received data size.
319  *
320  * @notapi
321  */
322 #define usb_lld_get_transaction_size(usbp, ep) \
323  ((usbp)->epc[ep]->out_state->rxcnt)
324 
325 /**
326  * @brief Connects the USB device.
327  *
328  * @api
329  */
330 #define usb_lld_connect_bus(usbp)
331 
332 /**
333  * @brief Disconnect the USB device.
334  *
335  * @api
336  */
337 #define usb_lld_disconnect_bus(usbp)
338 
339 /**
340  * @brief Start of host wake-up procedure.
341  *
342  * @notapi
343  */
344 #define usb_lld_wakeup_host(usbp)
345 
346 /*===========================================================================*/
347 /* External declarations. */
348 /*===========================================================================*/
349 
350 #if (PLATFORM_USB_USE_USB1 == TRUE) && !defined(__DOXYGEN__)
351 extern USBDriver USBD1;
352 #endif
353 
354 #ifdef __cplusplus
355 extern "C" {
356 #endif
357  void usb_lld_init(void);
358  void usb_lld_start(USBDriver *usbp);
359  void usb_lld_stop(USBDriver *usbp);
360  void usb_lld_reset(USBDriver *usbp);
361  void usb_lld_set_address(USBDriver *usbp);
362  void usb_lld_init_endpoint(USBDriver *usbp, usbep_t ep);
366  void usb_lld_read_setup(USBDriver *usbp, usbep_t ep, uint8_t *buf);
367  void usb_lld_prepare_receive(USBDriver *usbp, usbep_t ep);
369  void usb_lld_start_out(USBDriver *usbp, usbep_t ep);
370  void usb_lld_start_in(USBDriver *usbp, usbep_t ep);
371  void usb_lld_stall_out(USBDriver *usbp, usbep_t ep);
372  void usb_lld_stall_in(USBDriver *usbp, usbep_t ep);
373  void usb_lld_clear_out(USBDriver *usbp, usbep_t ep);
374  void usb_lld_clear_in(USBDriver *usbp, usbep_t ep);
375 #ifdef __cplusplus
376 }
377 #endif
378 
379 #endif /* HAL_USE_USB == TRUE */
380 
381 #endif /* HAL_USB_LLD_H */
382 
383 /** @} */
USBOutEndpointState * out_state
USBEndpointState associated to the OUT endpoint.
Definition: hal_usb_lld.h:183
void usb_lld_prepare_receive(USBDriver *usbp, usbep_t ep)
Prepares for a receive operation.
Definition: hal_usb_lld.c:276
uint16_t in_maxsize
IN endpoint maximum packet size.
Definition: hal_usb_lld.h:167
USBDriver USBD1
USB1 driver identifier.
Definition: hal_usb_lld.c:41
Type of an OUT endpoint state structure.
Definition: hal_usb_lld.h:108
void usb_lld_init(void)
Low level USB driver initialization.
Definition: hal_usb_lld.c:99
usbstate_t state
Driver state.
Definition: hal_usb_lld.h:221
size_t rxcnt
Received bytes so far.
Definition: hal_usb_lld.h:116
const USBEndpointConfig * epc[USB_MAX_ENDPOINTS+1]
Active endpoints configurations.
Definition: hal_usb_lld.h:237
uint8_t setup[8]
Setup packet buffer.
Definition: hal_usb_lld.h:271
void usb_lld_init_endpoint(USBDriver *usbp, usbep_t ep)
Enables an endpoint.
Definition: hal_usb_lld.c:186
void usb_lld_clear_out(USBDriver *usbp, usbep_t ep)
Brings an OUT endpoint in the active state.
Definition: hal_usb_lld.c:366
usbeventcb_t event_cb
USB events callback.
Definition: hal_usb_lld.h:195
size_t txsize
Requested transmit transfer size.
Definition: hal_usb_lld.h:87
void usb_lld_clear_in(USBDriver *usbp, usbep_t ep)
Brings an IN endpoint in the active state.
Definition: hal_usb_lld.c:381
void usb_lld_start(USBDriver *usbp)
Configures and activates the USB peripheral.
Definition: hal_usb_lld.c:114
void usb_lld_disable_endpoints(USBDriver *usbp)
Disables all the active endpoints except the endpoint zero.
Definition: hal_usb_lld.c:200
void usb_lld_start_out(USBDriver *usbp, usbep_t ep)
Starts a receive operation on an OUT endpoint.
Definition: hal_usb_lld.c:306
void usb_lld_stall_in(USBDriver *usbp, usbep_t ep)
Brings an IN endpoint in the stalled state.
Definition: hal_usb_lld.c:351
usbstate_t
Type of a driver state machine possible states.
Definition: hal_usb.h:269
uint8_t configuration
Current USB device configuration.
Definition: hal_usb_lld.h:283
void usb_lld_start_in(USBDriver *usbp, usbep_t ep)
Starts a transmit operation on an IN endpoint.
Definition: hal_usb_lld.c:321
usbepcallback_t in_cb
IN endpoint notification callback.
Definition: hal_usb_lld.h:155
const USBConfig * config
Current configuration data.
Definition: hal_usb_lld.h:225
Structure representing an USB driver.
Definition: hal_usb_lld.h:217
void usb_lld_read_setup(USBDriver *usbp, usbep_t ep, uint8_t *buf)
Reads a setup packet from the dedicated packet buffer.
Definition: hal_usb_lld.c:260
uint8_t address
Assigned USB address.
Definition: hal_usb_lld.h:279
void * out_params[USB_MAX_ENDPOINTS]
Fields available to user, it can be used to associate an application-defined handler to an OUT endpoi...
Definition: hal_usb_lld.h:251
size_t ep0n
Number of bytes yet to be transferred through endpoint 0.
Definition: hal_usb_lld.h:263
void(* usbcallback_t)(USBDriver *usbp)
Type of an USB generic notification callback.
Definition: hal_usb.h:333
void usb_lld_stall_out(USBDriver *usbp, usbep_t ep)
Brings an OUT endpoint in the stalled state.
Definition: hal_usb_lld.c:336
uint16_t receiving
Bit map of the receiving OUT endpoints.
Definition: hal_usb_lld.h:233
void(* usbeventcb_t)(USBDriver *usbp, usbevent_t event)
Type of an USB event notification callback.
Definition: hal_usb.h:351
uint32_t ep_mode
Type and mode of the endpoint.
Definition: hal_usb_lld.h:138
usbcallback_t sof_cb
Start Of Frame callback.
Definition: hal_usb_lld.h:210
thread_reference_t thread
Waiting thread.
Definition: hal_usb_lld.h:100
const uint8_t * txbuf
Pointer to the transmission linear buffer.
Definition: hal_usb_lld.h:95
usbreqhandler_t requests_hook_cb
Requests hook callback.
Definition: hal_usb_lld.h:206
uint8_t * rxbuf
Pointer to the receive linear buffer.
Definition: hal_usb_lld.h:120
usbep0state_t
Type of an endpoint zero state machine states.
Definition: hal_usb.h:290
size_t txcnt
Transmitted bytes so far.
Definition: hal_usb_lld.h:91
bool(* usbreqhandler_t)(USBDriver *usbp)
Type of a requests handler callback.
Definition: hal_usb.h:363
void usb_lld_reset(USBDriver *usbp)
USB low level reset routine.
Definition: hal_usb_lld.c:156
size_t rxsize
Requested receive transfer size.
Definition: hal_usb_lld.h:112
const USBDescriptor *(* usbgetdescriptor_t)(USBDriver *usbp, uint8_t dtype, uint8_t dindex, uint16_t lang)
Type of an USB descriptor-retrieving callback.
Definition: hal_usb.h:368
uint16_t transmitting
Bit map of the transmitting IN endpoints.
Definition: hal_usb_lld.h:229
void * thread_reference_t
Type of a thread reference.
Definition: osal.h:180
usbepstatus_t usb_lld_get_status_out(USBDriver *usbp, usbep_t ep)
Returns the status of an OUT endpoint.
Definition: hal_usb_lld.c:218
void * in_params[USB_MAX_ENDPOINTS]
Fields available to user, it can be used to associate an application-defined handler to an IN endpoin...
Definition: hal_usb_lld.h:244
uint16_t status
Current USB device status.
Definition: hal_usb_lld.h:275
usbepcallback_t setup_cb
Setup packet notification callback.
Definition: hal_usb_lld.h:149
Type of an IN endpoint state structure.
Definition: hal_usb_lld.h:83
uint8_t * ep0next
Next position in the buffer to be transferred through endpoint 0.
Definition: hal_usb_lld.h:259
void(* usbepcallback_t)(USBDriver *usbp, usbep_t ep)
Type of an USB endpoint callback.
Definition: hal_usb.h:342
usbgetdescriptor_t get_descriptor_cb
Device GET_DESCRIPTOR request callback.
Definition: hal_usb_lld.h:200
usbcallback_t ep0endcb
Endpoint 0 end transaction callback.
Definition: hal_usb_lld.h:267
usbepstatus_t usb_lld_get_status_in(USBDriver *usbp, usbep_t ep)
Returns the status of an IN endpoint.
Definition: hal_usb_lld.c:238
uint8_t usbep_t
Type of an endpoint identifier.
Definition: hal_usb.h:264
Type of an USB driver configuration structure.
Definition: hal_usb_lld.h:190
uint16_t out_maxsize
OUT endpoint maximum packet size.
Definition: hal_usb_lld.h:173
void usb_lld_stop(USBDriver *usbp)
Deactivates the USB peripheral.
Definition: hal_usb_lld.c:135
usbepcallback_t out_cb
OUT endpoint notification callback.
Definition: hal_usb_lld.h:161
Type of an USB endpoint configuration structure.
Definition: hal_usb_lld.h:134
usbstate_t saved_state
State of the driver when a suspend happened.
Definition: hal_usb_lld.h:287
USBInEndpointState * in_state
USBEndpointState associated to the IN endpoint.
Definition: hal_usb_lld.h:178
void usb_lld_prepare_transmit(USBDriver *usbp, usbep_t ep)
Prepares for a transmit operation.
Definition: hal_usb_lld.c:291
thread_reference_t thread
Waiting thread.
Definition: hal_usb_lld.h:125
void usb_lld_set_address(USBDriver *usbp)
Sets the USB address.
Definition: hal_usb_lld.c:172
usbep0state_t ep0state
Endpoint 0 state.
Definition: hal_usb_lld.h:255
#define USB_MAX_ENDPOINTS
Maximum endpoint address.
Definition: hal_usb_lld.h:37
usbepstatus_t
Type of an endpoint status.
Definition: hal_usb.h:281