common: Make Logger calculate and publish pace.
[gps-watch.git] / src / common / usb_device.h
1 /*
2  * The Clear BSD License
3  * Copyright (c) 2015 - 2016, Freescale Semiconductor, Inc.
4  * Copyright 2016 NXP
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without modification,
8  * are permitted (subject to the limitations in the disclaimer below) provided
9  * that the following conditions are met:
10  *
11  * o Redistributions of source code must retain the above copyright notice, this list
12  *   of conditions and the following disclaimer.
13  *
14  * o Redistributions in binary form must reproduce the above copyright notice, this
15  *   list of conditions and the following disclaimer in the documentation and/or
16  *   other materials provided with the distribution.
17  *
18  * o Neither the name of the copyright holder nor the names of its
19  *   contributors may be used to endorse or promote products derived from this
20  *   software without specific prior written permission.
21  *
22  * NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE.
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
24  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
25  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
26  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
27  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
28  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
30  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
32  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  */
34
35 #ifndef __USB_DEVICE_H__
36 #define __USB_DEVICE_H__
37
38 /*!
39  * @addtogroup usb_device_driver
40  * @{
41  */
42
43 /*******************************************************************************
44  * Definitions
45  ******************************************************************************/
46
47 /*! @brief Defines Get/Set status Types */
48 typedef enum _usb_device_status
49 {
50     kUSB_DeviceStatusTestMode = 1U,  /*!< Test mode */
51     kUSB_DeviceStatusSpeed,          /*!< Current speed */
52     kUSB_DeviceStatusOtg,            /*!< OTG status */
53     kUSB_DeviceStatusDevice,         /*!< Device status */
54     kUSB_DeviceStatusEndpoint,       /*!< Endpoint state usb_device_endpoint_status_t */
55     kUSB_DeviceStatusDeviceState,    /*!< Device state */
56     kUSB_DeviceStatusAddress,        /*!< Device address */
57     kUSB_DeviceStatusSynchFrame,     /*!< Current frame */
58     kUSB_DeviceStatusBus,            /*!< Bus status */
59     kUSB_DeviceStatusBusSuspend,     /*!< Bus suspend */
60     kUSB_DeviceStatusBusSleep,       /*!< Bus suspend */
61     kUSB_DeviceStatusBusResume,      /*!< Bus resume */
62     kUSB_DeviceStatusRemoteWakeup,   /*!< Remote wakeup state */
63     kUSB_DeviceStatusBusSleepResume, /*!< Bus resume */
64 } usb_device_status_t;
65
66 /*! @brief Defines USB 2.0 device state */
67 typedef enum _usb_device_state
68 {
69     kUSB_DeviceStateConfigured = 0U, /*!< Device state, Configured*/
70     kUSB_DeviceStateAddress,         /*!< Device state, Address*/
71     kUSB_DeviceStateDefault,         /*!< Device state, Default*/
72     kUSB_DeviceStateAddressing,      /*!< Device state, Address setting*/
73     kUSB_DeviceStateTestMode,        /*!< Device state, Test mode*/
74 } usb_device_state_t;
75
76 #if (defined(USB_DEVICE_CHARGER_DETECT_ENABLE) && (USB_DEVICE_CHARGER_DETECT_ENABLE > 0U))
77 typedef enum _usb_dcd_detection_sequence_status
78 {
79     kUSB_DcdDetectionNotEnabled = 0x0U,
80     kUSB_DcdDataPinDetectionCompleted = 0x01U,
81     kUSB_DcdChargingPortDetectionCompleted = 0x02U,
82     kUSB_DcdChargerTypeDetectionCompleted = 0x03U,
83 } usb_dcd_detection_sequence_status_t;
84
85 typedef enum _usb_dcd_detection_sequence_results
86 {
87     kUSB_DcdDetectionNoResults = 0x0U,
88     kUSB_DcdDetectionStandardHost = 0x01U,
89     kUSB_DcdDetectionChargingPort = 0x02U,
90     kUSB_DcdDetectionDedicatedCharger = 0x03U,
91 } usb_dcd_detection_sequence_results_t;
92 #endif
93
94 /*! @brief Defines endpoint state */
95 typedef enum _usb_endpoint_status
96 {
97     kUSB_DeviceEndpointStateIdle = 0U, /*!< Endpoint state, idle*/
98     kUSB_DeviceEndpointStateStalled,   /*!< Endpoint state, stalled*/
99 } usb_device_endpoint_status_t;
100
101 /*! @brief Control endpoint index */
102 #define USB_CONTROL_ENDPOINT (0U)
103 /*! @brief Control endpoint maxPacketSize */
104 #define USB_CONTROL_MAX_PACKET_SIZE (64U)
105
106 #if (USB_DEVICE_CONFIG_EHCI && (USB_CONTROL_MAX_PACKET_SIZE != (64U)))
107 #error For high speed, USB_CONTROL_MAX_PACKET_SIZE must be 64!!!
108 #endif
109
110 /*! @brief The setup packet size of USB control transfer. */
111 #define USB_SETUP_PACKET_SIZE (8U)
112 /*! @brief  USB endpoint mask */
113 #define USB_ENDPOINT_NUMBER_MASK (0x0FU)
114
115 /*! @brief Default invalid value or the endpoint callback length of cancelled transfer */
116 #define USB_UNINITIALIZED_VAL_32 (0xFFFFFFFFU)
117
118 /*! @brief Available common EVENT types in device callback */
119 typedef enum _usb_device_event
120 {
121     kUSB_DeviceEventBusReset = 1U, /*!< USB bus reset signal detected */
122     kUSB_DeviceEventSuspend,       /*!< USB bus suspend signal detected */
123     kUSB_DeviceEventResume,    /*!< USB bus resume signal detected. The resume signal is driven by itself or a host */
124     kUSB_DeviceEventSleeped,   /*!< USB bus LPM suspend signal detected */
125     kUSB_DeviceEventLPMResume, /*!< USB bus LPM resume signal detected. The resume signal is driven by itself or a host
126                                   */
127     kUSB_DeviceEventError,     /*!< An error is happened in the bus. */
128     kUSB_DeviceEventDetach,    /*!< USB device is disconnected from a host. */
129     kUSB_DeviceEventAttach,    /*!< USB device is connected to a host. */
130     kUSB_DeviceEventSetConfiguration, /*!< Set configuration. */
131     kUSB_DeviceEventSetInterface,     /*!< Set interface. */
132
133     kUSB_DeviceEventGetDeviceDescriptor,          /*!< Get device descriptor. */
134     kUSB_DeviceEventGetConfigurationDescriptor,   /*!< Get configuration descriptor. */
135     kUSB_DeviceEventGetStringDescriptor,          /*!< Get string descriptor. */
136     kUSB_DeviceEventGetHidDescriptor,             /*!< Get HID descriptor. */
137     kUSB_DeviceEventGetHidReportDescriptor,       /*!< Get HID report descriptor. */
138     kUSB_DeviceEventGetHidPhysicalDescriptor,     /*!< Get HID physical descriptor. */
139     kUSB_DeviceEventGetBOSDescriptor,             /*!< Get configuration descriptor. */
140     kUSB_DeviceEventGetDeviceQualifierDescriptor, /*!< Get device qualifier descriptor. */
141     kUSB_DeviceEventVendorRequest,                /*!< Vendor request. */
142     kUSB_DeviceEventSetRemoteWakeup,              /*!< Enable or disable remote wakeup function. */
143     kUSB_DeviceEventGetConfiguration,             /*!< Get current configuration index */
144     kUSB_DeviceEventGetInterface,                 /*!< Get current interface alternate setting value */
145     kUSB_DeviceEventSetBHNPEnable,
146 #if (defined(USB_DEVICE_CHARGER_DETECT_ENABLE) && (USB_DEVICE_CHARGER_DETECT_ENABLE > 0U))
147     kUSB_DeviceEventDcdTimeOut,               /*!< Dcd detect result is timeout */
148     kUSB_DeviceEventDcdUnknownType,           /*!< Dcd detect result is unknown type */
149     kUSB_DeviceEventSDPDetected,              /*!< The SDP facility is detected */
150     kUSB_DeviceEventChargingPortDetected,     /*!< The charging port is detected */
151     kUSB_DeviceEventChargingHostDetected,     /*!< The CDP facility is detected */
152     kUSB_DeviceEventDedicatedChargerDetected, /*!< The DCP facility is detected */
153 #endif
154 } usb_device_event_t;
155
156 /*! @brief Endpoint callback message structure */
157 typedef struct _usb_device_endpoint_callback_message_struct
158 {
159     uint8_t *buffer; /*!< Transferred buffer */
160     uint32_t length; /*!< Transferred data length */
161     uint8_t isSetup; /*!< Is in a setup phase */
162 } usb_device_endpoint_callback_message_struct_t;
163
164 /*!
165  * @brief Endpoint callback function typedef.
166  *
167  * This callback function is used to notify the upper layer what the transfer result is.
168  * This callback pointer is passed when a specified endpoint is initialized by calling API #USB_DeviceInitEndpoint.
169  *
170  * @param handle          The device handle. It equals to the value returned from #USB_DeviceInit.
171  * @param message         The result of a transfer, which includes transfer buffer, transfer length, and whether is in a
172  * setup phase.
173  * phase for control pipe.
174  * @param callbackParam  The parameter for this callback. It is same with
175  * usb_device_endpoint_callback_struct_t::callbackParam.
176  *
177  * @return A USB error code or kStatus_USB_Success.
178  */
179 typedef usb_status_t (*usb_device_endpoint_callback_t)(usb_device_handle handle,
180                                                        usb_device_endpoint_callback_message_struct_t *message,
181                                                        void *callbackParam);
182
183 /*!
184  * @brief Device callback function typedef.
185  *
186  * This callback function is used to notify the upper layer that the device status has changed.
187  * This callback pointer is passed by calling API #USB_DeviceInit.
188  *
189  * @param handle          The device handle. It equals the value returned from #USB_DeviceInit.
190  * @param callbackEvent  The callback event type. See enumeration #usb_device_event_t.
191  * @param eventParam     The event parameter for this callback. The parameter type is determined by the callback event.
192  *
193  * @return A USB error code or kStatus_USB_Success.
194  */
195 typedef usb_status_t (*usb_device_callback_t)(usb_device_handle handle, uint32_t callbackEvent, void *eventParam);
196
197 /*! @brief Endpoint callback structure */
198 typedef struct _usb_device_endpoint_callback_struct
199 {
200     usb_device_endpoint_callback_t callbackFn; /*!< Endpoint callback function*/
201     void *callbackParam;                       /*!< Parameter for callback function*/
202     uint8_t isBusy;
203 } usb_device_endpoint_callback_struct_t;
204
205 /*! @brief Endpoint initialization structure */
206 typedef struct _usb_device_endpoint_init_struct
207 {
208     uint16_t maxPacketSize;  /*!< Endpoint maximum packet size */
209     uint8_t endpointAddress; /*!< Endpoint address*/
210     uint8_t transferType;    /*!< Endpoint transfer type*/
211     uint8_t zlt;             /*!< ZLT flag*/
212 } usb_device_endpoint_init_struct_t;
213
214 /*! @brief Endpoint status structure */
215 typedef struct _usb_device_endpoint_status_struct
216 {
217     uint8_t endpointAddress; /*!< Endpoint address */
218     uint16_t endpointStatus; /*!< Endpoint status : idle or stalled */
219 } usb_device_endpoint_status_struct_t;
220
221 #if (defined(USB_DEVICE_CHARGER_DETECT_ENABLE) && (USB_DEVICE_CHARGER_DETECT_ENABLE > 0U))
222 /*! @brief USB DCD charge timing specification structure */
223 typedef struct _usb_device_dcd_charging_time
224 {
225     uint16_t dcdSeqInitTime;      /*!< The dcd sequence init time */
226     uint16_t dcdDbncTime;         /*!< The debounce time period on DP signal */
227     uint16_t dcdDpSrcOnTime;      /*!< The time period comparator enabled */
228     uint16_t dcdTimeWaitAfterPrD; /*!< The time period between primary and secondary detection */
229     uint8_t dcdTimeDMSrcOn;       /*!< The amount of time that the modules enable the Vdm_src */
230 } usb_device_dcd_charging_time_t;
231 #endif
232
233 #if defined(__cplusplus)
234 extern "C" {
235 #endif /* __cplusplus*/
236
237 /*!
238  * @name USB device APIs
239  * @{
240  */
241
242 /*******************************************************************************
243  * API
244  ******************************************************************************/
245
246 /*!
247  * @brief Initializes the USB device stack.
248  *
249  * This function initializes the USB device module specified by the controllerId.
250  *
251  * @param[in] controllerId   The controller ID of the USB IP. See the enumeration #usb_controller_index_t.
252  * @param[in] deviceCallback Function pointer of the device callback.
253  * @param[out] handle          It is an out parameter used to return the pointer of the device handle to the caller.
254  *
255  * @retval kStatus_USB_Success              The device is initialized successfully.
256  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer.
257  * @retval kStatus_USB_Busy                 Cannot allocate a device handle.
258  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller according to the controller id.
259  * @retval kStatus_USB_InvalidControllerInterface  The controller driver interfaces is invalid. There is an empty
260  *                                                                                                      interface entity.
261  * @retval kStatus_USB_Error                The macro USB_DEVICE_CONFIG_ENDPOINTS is more than the IP's endpoint number.
262  *                                          Or, the device has been initialized.
263  *                                          Or, the mutex or message queue is created failed.
264  */
265 extern usb_status_t USB_DeviceInit(uint8_t controllerId,
266                                    usb_device_callback_t deviceCallback,
267                                    usb_device_handle *handle);
268
269 /*!
270  * @brief Enables the device functionality.
271  *
272  * The function enables the device functionality, so that the device can be recognized by the host when the device
273  * detects that it has been connected to a host.
274  *
275  * @param[in] handle The device handle got from #USB_DeviceInit.
276  *
277  * @retval kStatus_USB_Success              The device is run successfully.
278  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
279  * @retval kStatus_USB_InvalidHandle        The device handle is a NULL pointer. Or the controller handle is invalid.
280  *
281  */
282 extern usb_status_t USB_DeviceRun(usb_device_handle handle);
283
284 /*!
285  * @brief Disables the device functionality.
286  *
287  * The function disables the device functionality. After this function called, even if the device is detached to the
288  * host,
289  * it can't work.
290  *
291  * @param[in] handle The device handle received from #USB_DeviceInit.
292  *
293  * @retval kStatus_USB_Success              The device is stopped successfully.
294  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
295  * @retval kStatus_USB_InvalidHandle        The device handle is a NULL pointer or the controller handle is invalid.
296  */
297 extern usb_status_t USB_DeviceStop(usb_device_handle handle);
298
299 /*!
300  * @brief De-initializes the device controller.
301  *
302  * The function de-initializes the device controller specified by the handle.
303  *
304  * @param[in] handle The device handle got from #USB_DeviceInit.
305  *
306  * @retval kStatus_USB_Success              The device is stopped successfully.
307  * @retval kStatus_USB_InvalidHandle        The device handle is a NULL pointer or the controller handle is invalid.
308  */
309 extern usb_status_t USB_DeviceDeinit(usb_device_handle handle);
310
311 /*!
312  * @brief Sends data through a specified endpoint.
313  *
314  * The function is used to send data through a specified endpoint.
315  *
316  * @param[in] handle The device handle got from #USB_DeviceInit.
317  * @param[in] endpointAddress Endpoint index.
318  * @param[in] buffer The memory address to hold the data need to be sent. The function is not reentrant.
319  * @param[in] length The data length need to be sent.
320  *
321  * @retval kStatus_USB_Success              The send request is sent successfully.
322  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer. Or the controller handle is invalid.
323  * @retval kStatus_USB_Busy                 Cannot allocate DTDS for current transfer in EHCI driver.
324  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
325  * @retval kStatus_USB_Error                The device is doing reset.
326  *
327  * @note The return value indicates whether the sending request is successful or not. The transfer done is notified by
328  * the
329  * corresponding callback function.
330  * Currently, only one transfer request can be supported for one specific endpoint.
331  * If there is a specific requirement to support multiple transfer requests for one specific endpoint, the application
332  * should implement a queue on the application level.
333  * The subsequent transfer can begin only when the previous transfer is done (get notification through the endpoint
334  * callback).
335  */
336 extern usb_status_t USB_DeviceSendRequest(usb_device_handle handle,
337                                           uint8_t endpointAddress,
338                                           uint8_t *buffer,
339                                           uint32_t length);
340
341 /*!
342  * @brief Receives data through a specified endpoint.
343  *
344  * The function is used to receive data through a specified endpoint. The function is not reentrant.
345  *
346  * @param[in] handle The device handle got from #USB_DeviceInit.
347  * @param[in] endpointAddress Endpoint index.
348  * @param[in] buffer The memory address to save the received data.
349  * @param[in] length The data length want to be received.
350  *
351  * @retval kStatus_USB_Success              The receive request is sent successfully.
352  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer. Or the controller handle is invalid.
353  * @retval kStatus_USB_Busy                 Cannot allocate DTDS for current transfer in EHCI driver.
354  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
355  * @retval kStatus_USB_Error                The device is doing reset.
356  *
357  * @note The return value indicates whether the receiving request is successful or not. The transfer done is notified by
358  * the
359  * corresponding callback function.
360  * Currently, only one transfer request can be supported for one specific endpoint.
361  * If there is a specific requirement to support multiple transfer requests for one specific endpoint, the application
362  * should implement a queue on the application level.
363  * The subsequent transfer can begin only when the previous transfer is done (get notification through the endpoint
364  * callback).
365  */
366 extern usb_status_t USB_DeviceRecvRequest(usb_device_handle handle,
367                                           uint8_t endpointAddress,
368                                           uint8_t *buffer,
369                                           uint32_t length);
370
371 /*!
372  * @brief Cancels the pending transfer in a specified endpoint.
373  *
374  * The function is used to cancel the pending transfer in a specified endpoint.
375  *
376  * @param[in] handle The device handle got from #USB_DeviceInit.
377  * @param[in] endpointAddress Endpoint address, bit7 is the direction of endpoint, 1U - IN, and 0U - OUT.
378  *
379  * @retval kStatus_USB_Success              The transfer is cancelled.
380  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer or the controller handle is invalid.
381  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
382  */
383 extern usb_status_t USB_DeviceCancel(usb_device_handle handle, uint8_t endpointAddress);
384
385 /*!
386  * @brief Initializes a specified endpoint.
387  *
388  * The function is used to initialize a specified endpoint. The corresponding endpoint callback is also initialized.
389  *
390  * @param[in] handle The device handle received from #USB_DeviceInit.
391  * @param[in] epInit Endpoint initialization structure. See the structure usb_device_endpoint_init_struct_t.
392  * @param[in] epCallback Endpoint callback structure. See the structure
393  * usb_device_endpoint_callback_struct_t.
394  *
395  * @retval kStatus_USB_Success              The endpoint is initialized successfully.
396  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer. Or the controller handle is invalid.
397  * @retval kStatus_USB_InvalidParameter     The epInit or epCallback is NULL pointer. Or the endpoint number is
398  * more than USB_DEVICE_CONFIG_ENDPOINTS.
399  * @retval kStatus_USB_Busy                 The endpoint is busy in EHCI driver.
400  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
401  */
402 extern usb_status_t USB_DeviceInitEndpoint(usb_device_handle handle,
403                                            usb_device_endpoint_init_struct_t *epInit,
404                                            usb_device_endpoint_callback_struct_t *epCallback);
405
406 /*!
407  * @brief Deinitializes a specified endpoint.
408  *
409  * The function is used to deinitializes a specified endpoint.
410  *
411  * @param[in] handle The device handle got from #USB_DeviceInit.
412  * @param[in] endpointAddress Endpoint address, bit7 is the direction of endpoint, 1U - IN, and 0U - OUT.
413  *
414  * @retval kStatus_USB_Success              The endpoint is de-initialized successfully.
415  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer. Or the controller handle is invalid.
416  * @retval kStatus_USB_InvalidParameter     The endpoint number is more than USB_DEVICE_CONFIG_ENDPOINTS.
417  * @retval kStatus_USB_Busy                 The endpoint is busy in EHCI driver.
418  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
419  */
420 extern usb_status_t USB_DeviceDeinitEndpoint(usb_device_handle handle, uint8_t endpointAddress);
421
422 /*!
423  * @brief Stalls a specified endpoint.
424  *
425  * The function is used to stall a specified endpoint.
426  *
427  * @param[in] handle The device handle received from #USB_DeviceInit.
428  * @param[in] endpointAddress Endpoint address, bit7 is the direction of endpoint, 1U - IN, and 0U - OUT.
429  *
430  * @retval kStatus_USB_Success              The endpoint is stalled successfully.
431  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer. Or the controller handle is invalid.
432  * @retval kStatus_USB_InvalidParameter     The endpoint number is more than USB_DEVICE_CONFIG_ENDPOINTS.
433  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
434  */
435 extern usb_status_t USB_DeviceStallEndpoint(usb_device_handle handle, uint8_t endpointAddress);
436
437 /*!
438  * @brief Unstalls a specified endpoint.
439  *
440  * The function is used to unstall a specified endpoint.
441  *
442  * @param[in] handle The device handle received from #USB_DeviceInit.
443  * @param[in] endpointAddress Endpoint address, bit7 is the direction of endpoint, 1U - IN, and 0U - OUT.
444  *
445  * @retval kStatus_USB_Success              The endpoint is unstalled successfully.
446  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer. Or the controller handle is invalid.
447  * @retval kStatus_USB_InvalidParameter     The endpoint number is more than USB_DEVICE_CONFIG_ENDPOINTS.
448  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
449  */
450 extern usb_status_t USB_DeviceUnstallEndpoint(usb_device_handle handle, uint8_t endpointAddress);
451
452 /*!
453  * @brief Gets the status of the selected item.
454  *
455  * The function is used to get the status of the selected item.
456  *
457  * @param[in] handle The device handle got from #USB_DeviceInit.
458  * @param[in] type   The selected item. See the structure #usb_device_status_t.
459  * @param[out] param  The parameter type is determined by the selected item.
460  *
461  * @retval kStatus_USB_Success              Get status successfully.
462  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer. Or the controller handle is invalid.
463  * @retval kStatus_USB_InvalidParameter     The parameter is NULL pointer.
464  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
465  * @retval kStatus_USB_Error                Unsupported type.
466  */
467 extern usb_status_t USB_DeviceGetStatus(usb_device_handle handle, usb_device_status_t type, void *param);
468
469 /*!
470  * @brief Sets the status of the selected item.
471  *
472  * The function is used to set the status of the selected item.
473  *
474  * @param[in] handle The device handle got from #USB_DeviceInit.
475  * @param[in] type The selected item. See the structure #usb_device_status_t.
476  * @param[in] param The parameter type is determined by the selected item.
477  *
478  * @retval kStatus_USB_Success              Set status successfully.
479  * @retval kStatus_USB_InvalidHandle        The handle is a NULL pointer. Or the controller handle is invalid.
480  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
481  * @retval kStatus_USB_Error                Unsupported type or the parameter is NULL pointer.
482  */
483 extern usb_status_t USB_DeviceSetStatus(usb_device_handle handle, usb_device_status_t type, void *param);
484
485 #if (defined(USB_DEVICE_CHARGER_DETECT_ENABLE) && (USB_DEVICE_CHARGER_DETECT_ENABLE > 0U))
486 /*!
487  * @brief Initializes the device dcd module.
488  *
489  * The function initializes the device dcd module.
490  *
491  * @param[in] handle The device handle got from #USB_DeviceInit.
492  * @param[in] time_param The time parameter used to config the dcd timing registers.
493  *
494  * @retval kStatus_USB_Success              The device is run successfully.
495  * @retval kStatus_USB_ControllerNotFound   Cannot find the controller.
496  * @retval kStatus_USB_InvalidHandle        The device handle is a NULL pointer. Or the controller handle is invalid.
497  *
498  */
499 extern usb_status_t USB_DeviceDcdInitModule(usb_device_handle handle, void *time_param);
500
501 /*!
502  * @brief De-initializes the device dcd module.
503  *
504  * The function de-initializes the device dcd module specified by the handle.
505  *
506  * @param[in] handle The device handle got from #USB_DeviceInit.
507  *
508  * @retval kStatus_USB_Success                   The device is stopped successfully.
509  * @retval kStatus_USB_InvalidHandle             The device handle is a NULL pointer or the controller handle is invalid.
510  */
511 extern usb_status_t USB_DeviceDcdDeinitModule(usb_device_handle handle);
512 #endif
513 /*!
514  * @brief Device task function.
515  *
516  * The function is used to handle the controller message.
517  * This function should not be called in the application directly.
518  *
519  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
520  */
521 extern void USB_DeviceTaskFunction(void *deviceHandle);
522
523 #if ((defined(USB_DEVICE_CONFIG_KHCI)) && (USB_DEVICE_CONFIG_KHCI > 0U))
524 /*!
525  * @brief Device KHCI task function.
526  *
527  * The function is used to handle the KHCI controller message.
528  * In the bare metal environment, this function should be called periodically in the main function.
529  * In the RTOS environment, this function should be used as a function entry to create a task.
530  *
531  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
532  */
533 #define USB_DeviceKhciTaskFunction(deviceHandle) USB_DeviceTaskFunction(deviceHandle)
534 #endif
535
536 #if ((defined(USB_DEVICE_CONFIG_EHCI)) && (USB_DEVICE_CONFIG_EHCI > 0U))
537 /*!
538  * @brief Device EHCI task function.
539  *
540  * The function is used to handle the EHCI controller message.
541  * In the bare metal environment, this function should be called periodically in the main function.
542  * In the RTOS environment, this function should be used as a function entry to create a task.
543  *
544  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
545  */
546 #define USB_DeviceEhciTaskFunction(deviceHandle) USB_DeviceTaskFunction(deviceHandle)
547 #if (defined(USB_DEVICE_CHARGER_DETECT_ENABLE) && (USB_DEVICE_CHARGER_DETECT_ENABLE > 0U))
548 /*!
549  * @brief Device EHCI DCD ISR function.
550  *
551  * The function is the EHCI DCD interrupt service routine.
552  *
553  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
554  */
555 extern void USB_DeviceDcdHSIsrFunction(void *deviceHandle);
556 #endif
557 #endif
558
559 #if (((defined(USB_DEVICE_CONFIG_LPCIP3511FS)) && (USB_DEVICE_CONFIG_LPCIP3511FS > 0U)) || \
560      ((defined(USB_DEVICE_CONFIG_LPCIP3511HS)) && (USB_DEVICE_CONFIG_LPCIP3511HS > 0U)))
561 /*!
562  * @brief Device LPC ip3511 controller task function.
563  *
564  * The function is used to handle the LPC ip3511 controller message.
565  * In the bare metal environment, this function should be called periodically in the main function.
566  * In the RTOS environment, this function should be used as a function entry to create a task.
567  *
568  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
569  */
570 #define USB_DeviceLpcIp3511TaskFunction(deviceHandle) USB_DeviceTaskFunction(deviceHandle)
571 #endif
572
573 #if ((defined(USB_DEVICE_CONFIG_KHCI)) && (USB_DEVICE_CONFIG_KHCI > 0U))
574 /*!
575  * @brief Device KHCI ISR function.
576  *
577  * The function is the KHCI interrupt service routine.
578  *
579  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
580  */
581 extern void USB_DeviceKhciIsrFunction(void *deviceHandle);
582 #if (defined(USB_DEVICE_CHARGER_DETECT_ENABLE) && (USB_DEVICE_CHARGER_DETECT_ENABLE > 0U))
583 /*!
584  * @brief Device KHCI DCD ISR function.
585  *
586  * The function is the KHCI DCD interrupt service routine.
587  *
588  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
589  */
590 extern void USB_DeviceDcdIsrFunction(void *deviceHandle);
591 #endif
592 #endif
593
594 #if ((defined(USB_DEVICE_CONFIG_EHCI)) && (USB_DEVICE_CONFIG_EHCI > 0U))
595 /*!
596  * @brief Device EHCI ISR function.
597  *
598  * The function is the EHCI interrupt service routine.
599  *
600  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
601  */
602 extern void USB_DeviceEhciIsrFunction(void *deviceHandle);
603 #endif
604
605 #if (((defined(USB_DEVICE_CONFIG_LPCIP3511FS)) && (USB_DEVICE_CONFIG_LPCIP3511FS > 0U)) || \
606      ((defined(USB_DEVICE_CONFIG_LPCIP3511HS)) && (USB_DEVICE_CONFIG_LPCIP3511HS > 0U)))
607 /*!
608  * @brief Device LPC USB ISR function.
609  *
610  * The function is the LPC USB interrupt service routine.
611  *
612  * @param[in] deviceHandle The device handle got from #USB_DeviceInit.
613  */
614 extern void USB_DeviceLpcIp3511IsrFunction(void *deviceHandle);
615 #endif
616
617 /*!
618  * @brief Gets the device stack version function.
619  *
620  * The function is used to get the device stack version.
621  *
622  * @param[out] version The version structure pointer to keep the device stack version.
623  *
624  */
625 extern void USB_DeviceGetVersion(uint32_t *version);
626
627 #if ((defined(USB_DEVICE_CONFIG_REMOTE_WAKEUP)) && (USB_DEVICE_CONFIG_REMOTE_WAKEUP > 0U))
628 /*!
629  * @brief Update the hardware tick.
630  *
631  * The function is used to update the hardware tick.
632  *
633  * @param[in] handle The device handle got from #USB_DeviceInit.
634  * @param[in] tick Current hardware tick(uint is ms).
635  *
636  */
637 extern usb_status_t USB_DeviceUpdateHwTick(usb_device_handle handle, uint64_t tick);
638 #endif
639
640 /*! @}*/
641
642 #if defined(__cplusplus)
643 }
644 #endif /* __cplusplus*/
645
646 /*! @}*/
647
648 #endif /* __USB_DEVICE_H__ */