usb_host.h 34 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787
  1. /*
  2. * Copyright (c) 2015 - 2016, Freescale Semiconductor, Inc.
  3. * Copyright 2016 - 2019 NXP
  4. * All rights reserved.
  5. *
  6. * SPDX-License-Identifier: BSD-3-Clause
  7. */
  8. #ifndef _USB_HOST_H_
  9. #define _USB_HOST_H_
  10. #include <usb/include/usb.h>
  11. #include <usb/include/usb_misc.h>
  12. #include <usb/include/usb_spec.h>
  13. /*******************************************************************************
  14. * Definitions
  15. ******************************************************************************/
  16. struct _usb_host_transfer; /* for cross reference */
  17. /*!
  18. * @addtogroup usb_host_drv
  19. * @{
  20. */
  21. /*! @brief USB host class handle type define */
  22. typedef void *usb_host_class_handle;
  23. /*! @brief USB host controller handle type define */
  24. typedef void *usb_host_controller_handle;
  25. /*! @brief USB host configuration handle type define */
  26. typedef void *usb_host_configuration_handle;
  27. /*! @brief USB host interface handle type define */
  28. typedef void *usb_host_interface_handle;
  29. /*! @brief USB host pipe handle type define */
  30. typedef void *usb_host_pipe_handle;
  31. /*! @brief Event codes for device attach/detach */
  32. typedef enum _usb_host_event
  33. {
  34. kUSB_HostEventAttach = 1U, /*!< Device is attached */
  35. kUSB_HostEventDetach, /*!< Device is detached */
  36. kUSB_HostEventEnumerationDone, /*!< Device's enumeration is done and the device is supported */
  37. kUSB_HostEventNotSupported, /*!< Device's enumeration is done and the device is not supported */
  38. /*! Device's enumeration failed due to errors
  39. * fail reason is put in the high 2 bytes of callback event code.
  40. * kStatus_USB_TransferFailed - the transfer failed.
  41. * kStatus_USB_TransferCancel - transfer is canceled by application.
  42. * kStatus_USB_Error - parsing descriptor failed, the power cannot satisfy device's requirement,
  43. * device addresss allocation failed, transfer is not enough
  44. * or the transfer API failed.
  45. * kStatus_USB_AllocFail - malloc failed.
  46. */
  47. kUSB_HostEventEnumerationFail,
  48. #if ((defined(USB_HOST_CONFIG_LOW_POWER_MODE)) && (USB_HOST_CONFIG_LOW_POWER_MODE > 0U))
  49. kUSB_HostEventNotSuspended, /*!< Suspend failed */
  50. kUSB_HostEventSuspended, /*!< Suspend successful */
  51. kUSB_HostEventNotResumed, /*!< Resume failed */
  52. kUSB_HostEventDetectResume, /*!< Detect resume signal */
  53. kUSB_HostEventResumed, /*!< Resume successful */
  54. kUSB_HostEventL1Sleeped, /*!< L1 Sleep successful,state transition was successful (ACK) */
  55. kUSB_HostEventL1SleepNYET, /*!< Device was unable to enter the L1 state at this time (NYET) */
  56. kUSB_HostEventL1SleepNotSupport, /*!< Device does not support the L1 state (STALL) */
  57. kUSB_HostEventL1SleepError, /*!< Device failed to respond or an error occurred */
  58. kUSB_HostEventL1NotResumed, /*!< Resume failed */
  59. kUSB_HostEventL1DetectResume, /*!< Detect resume signal */
  60. kUSB_HostEventL1Resumed, /*!< Resume successful */
  61. #endif
  62. } usb_host_event_t;
  63. /*! @brief USB host device information code */
  64. typedef enum _usb_host_dev_info
  65. {
  66. kUSB_HostGetDeviceAddress = 1U, /*!< Device's address */
  67. kUSB_HostGetDeviceHubNumber, /*!< Device's first hub address */
  68. kUSB_HostGetDevicePortNumber, /*!< Device's first hub port number */
  69. kUSB_HostGetDeviceSpeed, /*!< Device's speed */
  70. kUSB_HostGetDeviceHSHubNumber, /*!< Device's first high-speed hub address */
  71. kUSB_HostGetDeviceHSHubPort, /*!< Device's first high-speed hub number */
  72. kUSB_HostGetDeviceLevel, /*!< Device's hub level */
  73. kUSB_HostGetHostHandle, /*!< Device's host handle */
  74. kUSB_HostGetDeviceControlPipe, /*!< Device's control pipe handle */
  75. kUSB_HostGetDevicePID, /*!< Device's PID */
  76. kUSB_HostGetDeviceVID, /*!< Device's VID */
  77. kUSB_HostGetHubThinkTime, /*!< Device's hub total think time */
  78. kUSB_HostGetDeviceConfigIndex, /*!< Device's running zero-based config index */
  79. kUSB_HostGetConfigurationDes, /*!< Device's configuration descriptor pointer */
  80. kUSB_HostGetConfigurationLength, /*!< Device's configuration descriptor pointer */
  81. } usb_host_dev_info_t;
  82. /*! @brief Request type */
  83. typedef enum _usb_host_request_type
  84. {
  85. kRequestDevice = 1U, /*!< Control request object is device */
  86. kRequestInterface, /*!< Control request object is interface */
  87. kRequestEndpoint, /*!< Control request object is endpoint */
  88. } usb_host_request_type_t;
  89. /*! @brief For USB_REQUEST_STANDARD_GET_DESCRIPTOR and USB_REQUEST_STANDARD_SET_DESCRIPTOR */
  90. typedef struct _usb_host_process_descriptor_param
  91. {
  92. uint8_t descriptorType; /*!< See the usb_spec.h, such as the USB_DESCRIPTOR_TYPE_DEVICE */
  93. uint8_t descriptorIndex; /*!< The descriptor index is used to select a specific descriptor (only for configuration
  94. and string descriptors) when several descriptors of the same type are implemented in a
  95. device */
  96. uint8_t languageId; /*!< It specifies the language ID for string descriptors or is reset to zero for other
  97. descriptors */
  98. uint8_t *descriptorBuffer; /*!< Buffer pointer */
  99. uint16_t descriptorLength; /*!< Buffer data length */
  100. } usb_host_process_descriptor_param_t;
  101. /*! @brief For USB_REQUEST_STANDARD_CLEAR_FEATURE and USB_REQUEST_STANDARD_SET_FEATURE */
  102. typedef struct _usb_host_process_feature_param
  103. {
  104. uint8_t requestType; /*!< See the #usb_host_request_type_t */
  105. uint8_t featureSelector; /*!< Set/cleared feature */
  106. uint8_t interfaceOrEndpoint; /*!< Interface or end pointer */
  107. } usb_host_process_feature_param_t;
  108. /*! @brief For USB_REQUEST_STANDARD_GET_INTERFACE */
  109. typedef struct _usb_host_get_interface_param
  110. {
  111. uint8_t interface; /*!< Interface number */
  112. uint8_t *alternateInterfaceBuffer; /*!< Save the transfer result */
  113. } usb_host_get_interface_param_t;
  114. /*! @brief For USB_REQUEST_STANDARD_GET_STATUS */
  115. typedef struct _usb_host_get_status_param
  116. {
  117. uint16_t statusSelector; /*!< Interface number, the end pointer number or OTG status selector */
  118. uint8_t requestType; /*!< See the #usb_host_request_type_t */
  119. uint8_t *statusBuffer; /*!< Save the transfer result */
  120. } usb_host_get_status_param_t;
  121. /*! @brief For USB_REQUEST_STANDARD_SET_INTERFACE */
  122. typedef struct _usb_host_set_interface_param
  123. {
  124. uint8_t alternateSetting; /*!< Alternate setting value */
  125. uint8_t interface; /*!< Interface number */
  126. } usb_host_set_interface_param_t;
  127. /*! @brief For USB_REQUEST_STANDARD_SYNCH_FRAME */
  128. typedef struct _usb_host_synch_frame_param
  129. {
  130. uint8_t endpoint; /*!< Endpoint number */
  131. uint8_t *frameNumberBuffer; /*!< Frame number data buffer */
  132. } usb_host_synch_frame_param_t;
  133. /*!
  134. * @brief Host callback function typedef.
  135. *
  136. * This callback function is used to notify application device attach/detach event.
  137. * This callback pointer is passed when initializing the host.
  138. *
  139. * @param deviceHandle The device handle, which indicates the attached device.
  140. * @param configurationHandle The configuration handle contains the attached device's configuration information.
  141. * @param event_code The callback event code; See the enumeration host_event_t.
  142. *
  143. * @return A USB error code or kStatus_USB_Success.
  144. * @retval kStatus_USB_Success Application handles the attached device successfully.
  145. * @retval kStatus_USB_NotSupported Application don't support the attached device.
  146. * @retval kStatus_USB_Error Application handles the attached device falsely.
  147. */
  148. typedef usb_status_t (*host_callback_t)(usb_device_handle deviceHandle,
  149. usb_host_configuration_handle configurationHandle,
  150. uint32_t eventCode);
  151. /*!
  152. * @brief Transfer callback function typedef.
  153. *
  154. * This callback function is used to notify the upper layer the result of the transfer.
  155. * This callback pointer is passed when calling the send/receive APIs.
  156. *
  157. * @param param The parameter pointer, which is passed when calling the send/receive APIs.
  158. * @param data The data buffer pointer.
  159. * @param data_len The result data length.
  160. * @param status A USB error code or kStatus_USB_Success.
  161. */
  162. typedef void (*transfer_callback_t)(void *param, uint8_t *data, uint32_t dataLen, usb_status_t status);
  163. /*!
  164. * @brief Host stack inner transfer callback function typedef.
  165. *
  166. * This callback function is used to notify the upper layer the result of a transfer.
  167. * This callback pointer is passed when initializing the structure usb_host_transfer_t.
  168. *
  169. * @param param The parameter pointer, which is passed when calling the send/receive APIs.
  170. * @param transfer The transfer information; See the structure usb_host_transfer_t.
  171. * @param status A USB error code or kStatus_USB_Success.
  172. */
  173. typedef void (*host_inner_transfer_callback_t)(void *param, struct _usb_host_transfer *transfer, usb_status_t status);
  174. /*! @brief USB host endpoint information structure */
  175. typedef struct _usb_host_ep
  176. {
  177. usb_descriptor_endpoint_t *epDesc; /*!< Endpoint descriptor pointer*/
  178. uint8_t *epExtension; /*!< Endpoint extended descriptor pointer*/
  179. uint16_t epExtensionLength; /*!< Extended descriptor length*/
  180. } usb_host_ep_t;
  181. /*! @brief USB host interface information structure */
  182. typedef struct _usb_host_interface
  183. {
  184. usb_host_ep_t epList[USB_HOST_CONFIG_INTERFACE_MAX_EP]; /*!< Endpoint array*/
  185. usb_descriptor_interface_t *interfaceDesc; /*!< Interface descriptor pointer*/
  186. uint8_t *interfaceExtension; /*!< Interface extended descriptor pointer*/
  187. uint16_t interfaceExtensionLength; /*!< Extended descriptor length*/
  188. uint8_t interfaceIndex; /*!< The interface index*/
  189. uint8_t alternateSettingNumber; /*!< The interface alternate setting value*/
  190. uint8_t epCount; /*!< Interface's endpoint number*/
  191. } usb_host_interface_t;
  192. /*! @brief USB host configuration information structure */
  193. typedef struct _usb_host_configuration
  194. {
  195. usb_host_interface_t interfaceList[USB_HOST_CONFIG_CONFIGURATION_MAX_INTERFACE]; /*!< Interface array*/
  196. usb_descriptor_configuration_t *configurationDesc; /*!< Configuration descriptor pointer*/
  197. uint8_t *configurationExtension; /*!< Configuration extended descriptor pointer*/
  198. uint16_t configurationExtensionLength; /*!< Extended descriptor length*/
  199. uint8_t interfaceCount; /*!< The configuration's interface number*/
  200. } usb_host_configuration_t;
  201. /*! @brief USB host pipe common structure */
  202. typedef struct _usb_host_pipe
  203. {
  204. struct _usb_host_pipe *next; /*!< Link the idle pipes*/
  205. usb_device_handle deviceHandle; /*!< This pipe's device's handle*/
  206. uint16_t currentCount; /*!< For KHCI transfer*/
  207. uint16_t nakCount; /*!< Maximum NAK count*/
  208. uint16_t maxPacketSize; /*!< Maximum packet size*/
  209. uint16_t interval; /*!< FS/LS: frame unit; HS: micro-frame unit*/
  210. uint8_t open; /*!< 0 - closed, 1 - open*/
  211. uint8_t nextdata01; /*!< Data toggle*/
  212. uint8_t endpointAddress; /*!< Endpoint address*/
  213. uint8_t direction; /*!< Pipe direction*/
  214. uint8_t pipeType; /*!< Pipe type, for example USB_ENDPOINT_BULK*/
  215. uint8_t numberPerUframe; /*!< Transaction number per micro-frame*/
  216. } usb_host_pipe_t;
  217. /*! @brief USB host transfer structure */
  218. typedef struct _usb_host_transfer
  219. {
  220. struct _usb_host_transfer *next; /*!< The next transfer structure*/
  221. uint8_t *transferBuffer; /*!< Transfer data buffer*/
  222. uint32_t transferLength; /*!< Transfer data length*/
  223. uint32_t transferSofar; /*!< Length transferred so far*/
  224. host_inner_transfer_callback_t callbackFn; /*!< Transfer callback function*/
  225. void *callbackParam; /*!< Transfer callback parameter*/
  226. usb_host_pipe_t *transferPipe; /*!< Transfer pipe pointer*/
  227. usb_setup_struct_t *setupPacket; /*!< Set up packet buffer*/
  228. uint8_t direction; /*!< Transfer direction; it's values are USB_OUT or USB_IN*/
  229. uint8_t setupStatus; /*!< Set up the transfer status*/
  230. union
  231. {
  232. uint32_t unitHead; /*!< xTD head for this transfer*/
  233. int32_t transferResult; /*!< KHCI transfer result */
  234. } union1;
  235. union
  236. {
  237. uint32_t unitTail; /*!<xTD tail for this transfer*/
  238. uint32_t frame; /*!< KHCI transfer frame number */
  239. } union2;
  240. #if USB_HOST_CONFIG_KHCI
  241. uint16_t nakTimeout; /*!< KHCI transfer NAK timeout */
  242. uint16_t retry; /*!< KHCI transfer retry */
  243. #endif
  244. } usb_host_transfer_t;
  245. /*! @brief USB host pipe information structure for opening pipe */
  246. typedef struct _usb_host_pipe_init
  247. {
  248. void *devInstance; /*!< Device instance handle*/
  249. uint16_t nakCount; /*!< Maximum NAK retry count. MUST be zero for interrupt*/
  250. uint16_t maxPacketSize; /*!< Pipe's maximum packet size*/
  251. uint8_t interval; /*!< Pipe's interval*/
  252. uint8_t endpointAddress; /*!< Endpoint address*/
  253. uint8_t direction; /*!< Endpoint direction*/
  254. uint8_t pipeType; /*!< Endpoint type, the value is USB_ENDPOINT_INTERRUPT, USB_ENDPOINT_CONTROL,
  255. USB_ENDPOINT_ISOCHRONOUS, USB_ENDPOINT_BULK*/
  256. uint8_t numberPerUframe; /*!< Transaction number for each micro-frame*/
  257. } usb_host_pipe_init_t;
  258. /*! @brief Cancel transfer parameter structure */
  259. typedef struct _usb_host_cancel_param
  260. {
  261. usb_host_pipe_handle pipeHandle; /*!< Canceling pipe handle*/
  262. usb_host_transfer_t *transfer; /*!< Canceling transfer*/
  263. } usb_host_cancel_param_t;
  264. /*******************************************************************************
  265. * API
  266. ******************************************************************************/
  267. #ifdef __cplusplus
  268. extern "C" {
  269. #endif
  270. /*!
  271. * @name USB host APIs Part 1
  272. * The following APIs are recommended for application use.
  273. * @{
  274. */
  275. /*!
  276. * @brief Initializes the USB host stack.
  277. *
  278. * This function initializes the USB host module specified by the controllerId.
  279. *
  280. * @param[in] controllerId The controller ID of the USB IP. See the enumeration usb_controller_index_t.
  281. * @param[out] hostHandle Returns the host handle.
  282. * @param[in] callbackFn Host callback function notifies device attach/detach.
  283. *
  284. * @retval kStatus_USB_Success The host is initialized successfully.
  285. * @retval kStatus_USB_InvalidHandle The hostHandle is a NULL pointer.
  286. * @retval kStatus_USB_ControllerNotFound Cannot find the controller according to the controller ID.
  287. * @retval kStatus_USB_AllocFail Allocation memory fail.
  288. * @retval kStatus_USB_Error Host mutex create fail; KHCI/EHCI mutex or KHCI/EHCI event create fail,
  289. * or, KHCI/EHCI IP initialize fail.
  290. */
  291. extern usb_status_t USB_HostInit(uint8_t controllerId, usb_host_handle *hostHandle, host_callback_t callbackFn);
  292. /*!
  293. * @brief Deinitializes the USB host stack.
  294. *
  295. * This function deinitializes the USB host module specified by the hostHandle.
  296. *
  297. * @param[in] hostHandle The host handle.
  298. *
  299. * @retval kStatus_USB_Success The host is initialized successfully.
  300. * @retval kStatus_USB_InvalidHandle The hostHandle is a NULL pointer.
  301. * @retval kStatus_USB_Error Controller deinitialization fail.
  302. */
  303. extern usb_status_t USB_HostDeinit(usb_host_handle hostHandle);
  304. /*!
  305. * @brief Gets the device information.
  306. *
  307. * This function gets the device information.
  308. *
  309. * @param[in] deviceHandle Removing device handle.
  310. * @param[in] infoCode See the enumeration host_dev_info_t.
  311. * @param[out] infoValue Return the information value.
  312. *
  313. * @retval kStatus_USB_Success Close successfully.
  314. * @retval kStatus_USB_InvalidParameter The deviceHandle or info_value is a NULL pointer.
  315. * @retval kStatus_USB_Error The info_code is not the host_dev_info_t value.
  316. */
  317. extern usb_status_t USB_HostHelperGetPeripheralInformation(usb_device_handle deviceHandle,
  318. uint32_t infoCode,
  319. uint32_t *infoValue);
  320. /*!
  321. * @brief Parses the alternate interface descriptor.
  322. *
  323. * This function parses the alternate interface descriptor and returns an interface information through the structure
  324. * usb_host_interface_t.
  325. *
  326. * @param[in] interfaceHandle The whole interface handle.
  327. * @param[in] alternateSetting Alternate setting value.
  328. * @param[out] interface Return interface information.
  329. *
  330. * @retval kStatus_USB_Success Close successfully.
  331. * @retval kStatus_USB_InvalidHandle The interfaceHandle is a NULL pointer.
  332. * @retval kStatus_USB_InvalidParameter The alternateSetting is 0.
  333. * @retval kStatus_USB_Error The interface descriptor is wrong.
  334. */
  335. extern usb_status_t USB_HostHelperParseAlternateSetting(usb_host_interface_handle interfaceHandle,
  336. uint8_t alternateSetting,
  337. usb_host_interface_t *interface);
  338. /*!
  339. * @brief Removes the attached device.
  340. *
  341. * This function removes the attached device.
  342. * This function should not be used all the time.
  343. *
  344. * @param[in] hostHandle The host handle.
  345. * @param[in] deviceHandle Removing device handle.
  346. *
  347. * @retval kStatus_USB_Success Remove successfully.
  348. * @retval kStatus_USB_InvalidHandle The hostHandle or deviceHandle is a NULL pointer.
  349. * @retval kStatus_USB_InvalidParameter The deviceHandle instance don't belong to hostHandle instance.
  350. */
  351. extern usb_status_t USB_HostRemoveDevice(usb_host_handle hostHandle, usb_device_handle deviceHandle);
  352. #if (defined(USB_HOST_CONFIG_KHCI) && (USB_HOST_CONFIG_KHCI > 0U))
  353. /*!
  354. * @brief KHCI task function.
  355. *
  356. * The function is used to handle the KHCI controller message.
  357. * In the bare metal environment, this function should be called periodically in the main function.
  358. * In the RTOS environment, this function should be used as a function entry to create a task.
  359. *
  360. * @param[in] hostHandle The host handle.
  361. */
  362. extern void USB_HostKhciTaskFunction(void *hostHandle);
  363. #endif
  364. #if (defined(USB_HOST_CONFIG_EHCI) && (USB_HOST_CONFIG_EHCI > 0U))
  365. /*!
  366. * @brief EHCI task function.
  367. *
  368. * The function is used to handle the EHCI controller message.
  369. * In the bare metal environment, this function should be called periodically in the main function.
  370. * In the RTOS environment, this function should be used as a function entry to create a task.
  371. *
  372. * @param[in] hostHandle The host handle.
  373. */
  374. extern void USB_HostEhciTaskFunction(void *hostHandle);
  375. #endif
  376. #if (defined(USB_HOST_CONFIG_OHCI) && (USB_HOST_CONFIG_OHCI > 0U))
  377. /*!
  378. * @brief OHCI task function.
  379. *
  380. * The function is used to handle the OHCI controller message.
  381. * In the bare metal environment, this function should be called periodically in the main function.
  382. * In the RTOS environment, this function should be used as a function entry to create a task.
  383. *
  384. * @param[in] hostHandle The host handle.
  385. */
  386. extern void USB_HostOhciTaskFunction(void *hostHandle);
  387. #endif
  388. #if (defined(USB_HOST_CONFIG_IP3516HS) && (USB_HOST_CONFIG_IP3516HS > 0U))
  389. /*!
  390. * @brief IP3516HS task function.
  391. *
  392. * The function is used to handle the IP3516HS controller message.
  393. * In the bare metal environment, this function should be called periodically in the main function.
  394. * In the RTOS environment, this function should be used as a function entry to create a task.
  395. *
  396. * @param[in] hostHandle The host handle.
  397. */
  398. extern void USB_HostIp3516HsTaskFunction(void *hostHandle);
  399. #endif
  400. #if (defined(USB_HOST_CONFIG_KHCI) && (USB_HOST_CONFIG_KHCI > 0U))
  401. /*!
  402. * @brief Device KHCI ISR function.
  403. *
  404. * The function is the KHCI interrupt service routine.
  405. *
  406. * @param[in] hostHandle The host handle.
  407. */
  408. extern void USB_HostKhciIsrFunction(void *hostHandle);
  409. #endif
  410. #if (defined(USB_HOST_CONFIG_EHCI) && (USB_HOST_CONFIG_EHCI > 0U))
  411. /*!
  412. * @brief Device EHCI ISR function.
  413. *
  414. * The function is the EHCI interrupt service routine.
  415. *
  416. * @param[in] hostHandle The host handle.
  417. */
  418. extern void USB_HostEhciIsrFunction(void *hostHandle);
  419. #endif
  420. #if (defined(USB_HOST_CONFIG_OHCI) && (USB_HOST_CONFIG_OHCI > 0U))
  421. /*!
  422. * @brief Device OHCI ISR function.
  423. *
  424. * The function is the OHCI interrupt service routine.
  425. *
  426. * @param[in] hostHandle The host handle.
  427. */
  428. extern void USB_HostOhciIsrFunction(void *hostHandle);
  429. #endif
  430. #if (defined(USB_HOST_CONFIG_IP3516HS) && (USB_HOST_CONFIG_IP3516HS > 0U))
  431. /*!
  432. * @brief Device IP3516HS ISR function.
  433. *
  434. * The function is the IP3516HS interrupt service routine.
  435. *
  436. * @param[in] hostHandle The host handle.
  437. */
  438. extern void USB_HostIp3516HsIsrFunction(void *hostHandle);
  439. #endif
  440. /*! @}*/
  441. /*!
  442. * @name USB host APIs Part 2.
  443. * The following APIs are not recommended for application use. They are mainly used in the class driver.
  444. * @{
  445. */
  446. /*!
  447. * @brief Opens the USB host pipe.
  448. *
  449. * This function opens a pipe according to the pipe_init_ptr parameter.
  450. *
  451. * @param[in] hostHandle The host handle.
  452. * @param[out] pipeHandle The pipe handle pointer used to return the pipe handle.
  453. * @param[in] pipeInit Used to initialize the pipe.
  454. *
  455. * @retval kStatus_USB_Success The host is initialized successfully.
  456. * @retval kStatus_USB_InvalidHandle The hostHandle or pipe_handle_ptr is a NULL pointer.
  457. * @retval kStatus_USB_Error There is no idle pipe.
  458. * Or, there is no idle QH for EHCI.
  459. * Or, bandwidth allocate fail for EHCI.
  460. */
  461. extern usb_status_t USB_HostOpenPipe(usb_host_handle hostHandle,
  462. usb_host_pipe_handle *pipeHandle,
  463. usb_host_pipe_init_t *pipeInit);
  464. /*!
  465. * @brief Closes the USB host pipe.
  466. *
  467. * This function closes a pipe and frees the related resources.
  468. *
  469. * @param[in] hostHandle The host handle.
  470. * @param[in] pipeHandle The closing pipe handle.
  471. *
  472. * @retval kStatus_USB_Success The host is initialized successfully.
  473. * @retval kStatus_USB_InvalidHandle The hostHandle or pipeHandle is a NULL pointer.
  474. */
  475. extern usb_status_t USB_HostClosePipe(usb_host_handle hostHandle, usb_host_pipe_handle pipeHandle);
  476. /*!
  477. * @brief Sends data to a pipe.
  478. *
  479. * This function requests to send the transfer to the specified pipe.
  480. *
  481. * @param[in] hostHandle The host handle.
  482. * @param[in] pipeHandle The sending pipe handle.
  483. * @param[in] transfer The transfer information.
  484. *
  485. * @retval kStatus_USB_Success Send successfully.
  486. * @retval kStatus_USB_InvalidHandle The hostHandle, pipeHandle or transfer is a NULL pointer.
  487. * @retval kStatus_USB_LackSwapBuffer There is no swap buffer for KHCI.
  488. * @retval kStatus_USB_Error There is no idle QTD/ITD/SITD for EHCI.
  489. */
  490. extern usb_status_t USB_HostSend(usb_host_handle hostHandle,
  491. usb_host_pipe_handle pipeHandle,
  492. usb_host_transfer_t *transfer);
  493. /*!
  494. * @brief Sends a setup transfer to the pipe.
  495. *
  496. * This function request to send the setup transfer to the specified pipe.
  497. *
  498. * @param[in] hostHandle The host handle.
  499. * @param[in] pipeHandle The sending pipe handle.
  500. * @param[in] transfer The transfer information.
  501. *
  502. * @retval kStatus_USB_Success Send successfully.
  503. * @retval kStatus_USB_InvalidHandle The hostHandle, pipeHandle or transfer is a NULL pointer.
  504. * @retval kStatus_USB_LackSwapBuffer There is no swap buffer for KHCI.
  505. * @retval kStatus_USB_Error There is no idle QTD/ITD/SITD for EHCI.
  506. */
  507. extern usb_status_t USB_HostSendSetup(usb_host_handle hostHandle,
  508. usb_host_pipe_handle pipeHandle,
  509. usb_host_transfer_t *transfer);
  510. /*!
  511. * @brief Receives the data from the pipe.
  512. *
  513. * This function requests to receive the transfer from the specified pipe.
  514. *
  515. * @param[in] hostHandle The host handle.
  516. * @param[in] pipeHandle The receiving pipe handle.
  517. * @param[in] transfer The transfer information.
  518. *
  519. * @retval kStatus_USB_Success Receive successfully.
  520. * @retval kStatus_USB_InvalidHandle The hostHandle, pipeHandle or transfer is a NULL pointer.
  521. * @retval kStatus_USB_LackSwapBuffer There is no swap buffer for KHCI.
  522. * @retval kStatus_USB_Error There is no idle QTD/ITD/SITD for EHCI.
  523. */
  524. extern usb_status_t USB_HostRecv(usb_host_handle hostHandle,
  525. usb_host_pipe_handle pipeHandle,
  526. usb_host_transfer_t *transfer);
  527. /*!
  528. * @brief Cancel the pipe's transfers.
  529. *
  530. * This function cancels all pipe's transfers when the parameter transfer is NULL or cancels the transfers altogether.
  531. *
  532. * @param[in] hostHandle The host handle.
  533. * @param[in] pipeHandle The receiving pipe handle.
  534. * @param[in] transfer The transfer information.
  535. *
  536. * @retval kStatus_USB_Success Cancel successfully.
  537. * @retval kStatus_USB_InvalidHandle The hostHandle or pipeHandle is a NULL pointer.
  538. */
  539. extern usb_status_t USB_HostCancelTransfer(usb_host_handle hostHandle,
  540. usb_host_pipe_handle pipeHandle,
  541. usb_host_transfer_t *transfer);
  542. /*!
  543. * @brief Allocates a transfer resource.
  544. *
  545. * This function allocates a transfer. This transfer is used to pass data information to a low level stack.
  546. *
  547. * @param[in] hostHandle The host handle.
  548. * @param[out] transfer Return the transfer.
  549. *
  550. * @retval kStatus_USB_Success Allocate successfully.
  551. * @retval kStatus_USB_InvalidHandle The hostHandle or transfer is a NULL pointer.
  552. * @retval kStatus_USB_Error There is no idle transfer.
  553. */
  554. extern usb_status_t USB_HostMallocTransfer(usb_host_handle hostHandle, usb_host_transfer_t **transfer);
  555. /*!
  556. * @brief Frees a transfer resource.
  557. *
  558. * This function frees a transfer. This transfer is used to pass data information to a low level stack.
  559. *
  560. * @param[in] hostHandle The host handle.
  561. * @param[in] transfer Release the transfer.
  562. *
  563. * @retval kStatus_USB_Success Free successfully.
  564. * @retval kStatus_USB_InvalidHandle The hostHandle or transfer is a NULL pointer.
  565. */
  566. extern usb_status_t USB_HostFreeTransfer(usb_host_handle hostHandle, usb_host_transfer_t *transfer);
  567. /*!
  568. * @brief Requests the USB standard request.
  569. *
  570. * This function sends the USB standard request packet.
  571. *
  572. * @param[in] deviceHandle The device handle for control transfer.
  573. * @param[in] usbRequest A USB standard request code. See the usb_spec.h.
  574. * @param[in] transfer The used transfer.
  575. * @param[in] param The parameter structure is different for different request, see
  576. * usb_host_framework.h.
  577. *
  578. * @retval kStatus_USB_Success Send successfully.
  579. * @retval kStatus_USB_InvalidHandle The deviceHandle is a NULL pointer.
  580. * @retval kStatus_USB_LackSwapBuffer There is no swap buffer for KHCI.
  581. * @retval kStatus_USB_Error There is no idle QTD/ITD/SITD for EHCI,
  582. * Or, the request is not standard request.
  583. */
  584. extern usb_status_t USB_HostRequestControl(usb_device_handle deviceHandle,
  585. uint8_t usbRequest,
  586. usb_host_transfer_t *transfer,
  587. void *param);
  588. /*!
  589. * @brief Opens the interface.
  590. *
  591. * This function opens the interface. It is used to notify the host driver the interface is used by APP or class driver.
  592. *
  593. * @param[in] deviceHandle Removing device handle.
  594. * @param[in] interfaceHandle Opening interface handle.
  595. *
  596. * @retval kStatus_USB_Success Open successfully.
  597. * @retval kStatus_USB_InvalidHandle The deviceHandle or interfaceHandle is a NULL pointer.
  598. */
  599. extern usb_status_t USB_HostOpenDeviceInterface(usb_device_handle deviceHandle,
  600. usb_host_interface_handle interfaceHandle);
  601. /*!
  602. * @brief Closes an interface.
  603. *
  604. * This function opens an interface. It is used to notify the host driver the interface is not used by APP or class
  605. * driver.
  606. *
  607. * @param[in] deviceHandle Removing device handle.
  608. * @param[in] interfaceHandle Opening interface handle.
  609. *
  610. * @retval kStatus_USB_Success Close successfully.
  611. * @retval kStatus_USB_InvalidHandle The deviceHandle is a NULL pointer.
  612. */
  613. extern usb_status_t USB_HostCloseDeviceInterface(usb_device_handle deviceHandle,
  614. usb_host_interface_handle interfaceHandle);
  615. /*!
  616. * @brief Gets a host stack version function.
  617. *
  618. * The function is used to get the host stack version.
  619. *
  620. * @param[out] version The version structure pointer to keep the host stack version.
  621. *
  622. */
  623. extern void USB_HostGetVersion(uint32_t *version);
  624. #if ((defined(USB_HOST_CONFIG_LOW_POWER_MODE)) && (USB_HOST_CONFIG_LOW_POWER_MODE > 0U))
  625. /*!
  626. * @brief Send a bus or device suspend request.
  627. *
  628. * This function is used to send a bus or device suspend request.
  629. *
  630. * @param[in] hostHandle The host handle.
  631. * @param[in] deviceHandle The device handle.
  632. *
  633. * @retval kStatus_USB_Success Request successfully.
  634. * @retval kStatus_USB_InvalidHandle The hostHandle is a NULL pointer. Or the controller handle is invalid.
  635. * @retval kStatus_USB_Error There is no idle transfer.
  636. * Or, the deviceHandle is invalid.
  637. * Or, the request is invalid.
  638. */
  639. extern usb_status_t USB_HostSuspendDeviceResquest(usb_host_handle hostHandle, usb_device_handle deviceHandle);
  640. /*!
  641. * @brief Send a bus or device resume request.
  642. *
  643. * This function is used to send a bus or device resume request.
  644. *
  645. * @param[in] hostHandle The host handle.
  646. * @param[in] deviceHandle The device handle.
  647. *
  648. * @retval kStatus_USB_Success Request successfully.
  649. * @retval kStatus_USB_InvalidHandle The hostHandle is a NULL pointer. Or the controller handle is invalid.
  650. * @retval kStatus_USB_Error There is no idle transfer.
  651. * Or, the deviceHandle is invalid.
  652. * Or, the request is invalid.
  653. */
  654. extern usb_status_t USB_HostResumeDeviceResquest(usb_host_handle hostHandle, usb_device_handle deviceHandle);
  655. #if ((defined(USB_HOST_CONFIG_LPM_L1)) && (USB_HOST_CONFIG_LPM_L1 > 0U))
  656. /*!
  657. * @brief Send a bus or device suspend request.
  658. *
  659. * This function is used to send a bus or device suspend request.
  660. *
  661. * @param[in] hostHandle The host handle.
  662. * @param[in] deviceHandle The device handle.
  663. *@param[in] sleeptype Bus suspend or single device suspend.
  664. *
  665. * @retval kStatus_USB_Success Request successfully.
  666. * @retval kStatus_USB_InvalidHandle The hostHandle is a NULL pointer. Or the controller handle is invalid.
  667. * @retval kStatus_USB_Error There is no idle transfer.
  668. * Or, the deviceHandle is invalid.
  669. * Or, the request is invalid.
  670. */
  671. extern usb_status_t USB_HostL1SleepDeviceResquest(usb_host_handle hostHandle,
  672. usb_device_handle deviceHandle,
  673. uint8_t sleeptype);
  674. /*!
  675. * @brief Send a bus or device resume request.
  676. *
  677. * This function is used to send a bus or device resume request.
  678. *
  679. * @param[in] hostHandle The host handle.
  680. * @param[in] deviceHandle The device handle.
  681. * *@param[in] sleeptype Bus suspend or single device suspend.
  682. *
  683. * @retval kStatus_USB_Success Request successfully.
  684. * @retval kStatus_USB_InvalidHandle The hostHandle is a NULL pointer. Or the controller handle is invalid.
  685. * @retval kStatus_USB_Error There is no idle transfer.
  686. * Or, the deviceHandle is invalid.
  687. * Or, the request is invalid.
  688. */
  689. extern usb_status_t USB_HostL1ResumeDeviceResquest(usb_host_handle hostHandle,
  690. usb_device_handle deviceHandle,
  691. uint8_t sleepType);
  692. /*!
  693. * @brief Update the lpm param.
  694. *
  695. * The function is used to configure the lpm token.
  696. *
  697. * @param[in] hostHandle The host handle.
  698. * @param[in] lpmParam HIRD value and whether enable remotewakeup.
  699. *
  700. */
  701. extern usb_status_t USB_HostL1SleepDeviceResquestConfig(usb_host_handle hostHandle, uint8_t *lpmParam);
  702. #endif
  703. /*!
  704. * @brief Update the hardware tick.
  705. *
  706. * The function is used to update the hardware tick.
  707. *
  708. * @param[in] hostHandle The host handle.
  709. * @param[in] tick Current hardware tick(uint is ms).
  710. *
  711. */
  712. extern usb_status_t USB_HostUpdateHwTick(usb_host_handle hostHandle, uint64_t tick);
  713. #endif
  714. #if ((defined(USB_HOST_CONFIG_BATTERY_CHARGER)) && (USB_HOST_CONFIG_BATTERY_CHARGER > 0U))
  715. /*!
  716. * @brief Set the charger type. It is only supported on RT600 currently.
  717. *
  718. * The set charger type becomes valid in next attach.
  719. *
  720. * @param[in] hostHandle The host handle.
  721. * @param[in] type.
  722. *
  723. */
  724. extern usb_status_t USB_HostSetChargerType(usb_host_handle hostHandle, uint8_t type);
  725. #endif
  726. /*! @}*/
  727. #ifdef __cplusplus
  728. }
  729. #endif
  730. /*! @}*/
  731. #endif /* _USB_HOST_H_ */