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