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