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__ */