1 //***************************************************************************** 2 // 3 //! @file am_hal_usb.h 4 //! 5 //! @brief Functions for USB module 6 //! 7 //! @addtogroup usb_4p USB Functionality 8 //! @ingroup apollo4p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2023, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision stable-7da8bae71f of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 48 #ifndef AM_HAL_USB_H_ 49 #define AM_HAL_USB_H_ 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 //***************************************************************************** 56 // 57 //! @brief This is Used to select the HFRC2 configuration for HighSpeed USB 58 //! used in function am_hal_usb_setHFRC2 arguments 59 // 60 //***************************************************************************** 61 62 typedef enum 63 { 64 AM_HAL_USB_HS_CLK_DISABLE, ///< hfrc2 will be disabled, default off method 65 AM_HAL_USB_HS_CLK_DISABLE_HFRC2_ADJ, ///< hfrc2 will be disabled, not default 66 AM_HAL_USB_HS_CLK_HFRC2, ///< default HFRC2 will be enabled 67 AM_HAL_USB_HS_CLK_HFRC2_ADJ, ///< HFRC2 adjust based on the internal 32Mhz 68 AM_HAL_USB_HS_CLK_HFRC2_ADJ_EXTERN_CLK, ///< HFRC2 adjust based on external clock 69 AM_HAL_USB_HS_CLK_X32 = 0x7FFFFFF, ///< force vars derived from this enum to 4 bytes 70 } 71 am_hal_usb_hs_clock_type ; 72 73 //***************************************************************************** 74 // 75 //! @brief Enum for the USB speed type. 76 //! 77 //! These macros correspond to the defintions in the USB specification. 78 //! They may be used with the \e am_hal_usb_set_dev_speed() function. 79 // 80 //***************************************************************************** 81 typedef enum 82 { 83 AM_HAL_USB_SPEED_LOW, 84 AM_HAL_USB_SPEED_FULL, 85 AM_HAL_USB_SPEED_HIGH, 86 AM_HAL_USB_SPEED_UNKNOWN 87 } 88 am_hal_usb_dev_speed_e; 89 90 //***************************************************************************** 91 // 92 //! @brief Enum for the USB device state. 93 //! 94 //! These macros partially correspond to the defintions in the USB specification. 95 //! They may be used with the \e am_hal_usb_set_dev_state() function. 96 //! 97 // 98 //***************************************************************************** 99 typedef enum 100 { 101 AM_HAL_USB_DEV_STATE_INIT, 102 AM_HAL_USB_DEV_STATE_ADDRESSED, 103 AM_HAL_USB_DEV_STATE_CONFIGED, 104 AM_HAL_USB_DEV_STATE_RESUMING, 105 AM_HAL_USB_DEV_STATE_ACTIVE, 106 AM_HAL_USB_DEV_STATE_SUSPENDING, 107 AM_HAL_USB_DEV_STATE_SUSPENDED 108 } 109 am_hal_usb_dev_state_e; 110 111 //***************************************************************************** 112 // 113 //! @brief Enum for the USB device bus event. 114 //! 115 //! These macros correspond to the defintions in the USB specification. 116 //! They may be used with the \e am_hal_usb_dev_evt_callback callback function 117 //! provided by upper layer USB stack. 118 //! 119 // 120 //***************************************************************************** 121 typedef enum 122 { 123 AM_HAL_USB_DEV_EVT_BUS_RESET, 124 AM_HAL_USB_DEV_EVT_SOF, 125 AM_HAL_USB_DEV_EVT_RESUME, 126 AM_HAL_USB_DEV_EVT_SUSPEND, 127 AM_HAL_USB_DEV_EVT_NUM 128 } 129 am_hal_usb_dev_event_e; 130 131 //***************************************************************************** 132 // 133 //! @brief Enum for the USB transfer status. 134 //! 135 //! These macros is used to indicate how the USB transfer is completed. 136 //! They may be used with the \e am_hal_usb_ep_xfer_complete_callback callback 137 //! function provided by upper layer USB stack. 138 //! 139 // 140 //***************************************************************************** 141 typedef enum 142 { 143 // Transfer is done without error, for ctrl it means status packet done 144 USB_XFER_DONE, 145 // For control transfer only, data stage is done without error 146 USB_XFER_DATA, 147 // Endpoint stall is set 148 USB_XFER_STALL, 149 // Endpoint stall is cleared 150 USB_XFER_UNSTALL, 151 // Transfer is aborted 152 USB_XFER_ABORT, 153 // Transfer is aborted because endpoint reset/disable 154 USB_XFER_RESET, 155 // There was an error 156 USB_XFER_ERROR 157 } 158 am_hal_usb_xfer_code_e; 159 160 //***************************************************************************** 161 // 162 //! @brief Enum for the USB control call 163 //! 164 //! The macros defined here are used to specify how the void * parameter(s) 165 //! passed into the control function are interpreted. 166 //! 167 // 168 //***************************************************************************** 169 typedef enum 170 { 171 // 172 //! this is used when the XTAL freq is not the default 32mhz and 173 //! high speed USB mode is needed. This will allow the caller to set a 174 //! non 32Mhz HF_XTAL freq. (The default value is 32Mhz) 175 // 176 AM_HAL_CLKGEN_CONTROL_SET_XTAL_FREQ, 177 // 178 //! this is controller by an argument of type am_hal_usb_hs_clock_type 179 //! this is how modules configure the HFRC2 180 AM_HAL_CLKGEN_CONTROL_SET_HFRC2_TYPE, 181 182 } am_hal_usb_control_e; 183 184 //***************************************************************************** 185 // 186 //! @brief device event callback function pointer type 187 //! 188 //! Upper layer USB stack uses it to define a callback function to receive the 189 //! the USB bus events and registers it by 'am_hal_usb_register_dev_evt_callback' 190 //! function. 191 // 192 //***************************************************************************** 193 typedef void (*am_hal_usb_dev_evt_callback)(am_hal_usb_dev_event_e eDevState); 194 195 //***************************************************************************** 196 // 197 //! @brief ep0 setup request callback function pointer type 198 //! 199 //! Upper layer USB stack uses it to define a callback function to receive 200 //! setup requst from the USB host and registers it by 201 //! 'am_hal_usb_register_ep0_setup_received_callback' function. 202 // 203 //***************************************************************************** 204 typedef void (*am_hal_usb_ep0_setup_received_callback)(uint8_t *pui8Setup); 205 206 //***************************************************************************** 207 // 208 //! @brief ctrl/bulk/intr/iso transfer callback function pointer type 209 //! 210 //! Upper layer USB stack uses it to define a callback function to receive a 211 //! confirm for the USB HAL driver about how many bytes has been tranfered and 212 //! the transfer status. 213 // 214 //***************************************************************************** 215 typedef void (*am_hal_usb_ep_xfer_complete_callback)(uint8_t ui8EpAddr, uint16_t ui16XferLen, am_hal_usb_xfer_code_e eXferCode, void *param); 216 217 //***************************************************************************** 218 // 219 //! @brief register a USB bus event callback function 220 //! 221 //! @param pHandle - handle for the module instance. 222 //! @param cb - a USB bus event callback function. 223 //! 224 //! This function registers a USB bus event callback function defined in the upper layer 225 //! USB stack. 226 //! 227 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 228 // 229 //***************************************************************************** 230 extern uint32_t am_hal_usb_register_dev_evt_callback(void *pHandle, am_hal_usb_dev_evt_callback cb); 231 232 //***************************************************************************** 233 // 234 //! @brief register a setup requst callback function 235 //! 236 //! @param pHandle - handle for the module instance. 237 //! @param cb - setup request callback function. 238 //! 239 //! This function registers a setup request callback function defined in the upper layer 240 //! USB stack. 241 //! 242 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 243 // 244 //***************************************************************************** 245 extern uint32_t am_hal_usb_register_ep0_setup_received_callback(void *pHandle, am_hal_usb_ep0_setup_received_callback cb); 246 247 //***************************************************************************** 248 // 249 //! @brief register a transfer completion callback function 250 //! 251 //! @param pHandle - handle for the module instance. 252 //! @param cb - transfer completion callback function. 253 //! 254 //! This function registers a bulk/intr/iso transfer completion callback function. 255 //! 256 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 257 // 258 //***************************************************************************** 259 extern uint32_t am_hal_usb_register_ep_xfer_complete_callback(void *pHandle, am_hal_usb_ep_xfer_complete_callback cb); 260 261 //***************************************************************************** 262 // 263 //! @brief set the USB device state 264 //! 265 //! @param pHandle - handle for the module instance. 266 //! @param eDevState - device states like suspended, resuming, etc. 267 //! 268 //! This function is used by upper layer USB stack to set the device state. 269 //! 270 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 271 // 272 //***************************************************************************** 273 extern uint32_t am_hal_usb_set_dev_state(void *pHandle, am_hal_usb_dev_state_e eDevState); 274 275 //***************************************************************************** 276 // 277 //! @brief start the remote wakeup 278 //! 279 //! @param pHandle - handle for the module instance. 280 //! 281 //! This function is used by upper layer USB stack to start a remote wakeup action. 282 //! 283 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 284 // 285 //***************************************************************************** 286 extern uint32_t am_hal_usb_start_remote_wakeup(void *pHandle); 287 288 //***************************************************************************** 289 // 290 //! @brief stop the remote wakeup 291 //! 292 //! @param pHandle - handle for the module instance. 293 //! 294 //! This function is used by upper layer USB stack to end a remote wakeup action. 295 //! 296 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 297 // 298 //***************************************************************************** 299 extern uint32_t am_hal_usb_end_remote_wakeup(void *pHandle); 300 301 //***************************************************************************** 302 // 303 //! @brief set the USB device address 304 //! 305 //! @param pHandle - handle for the module instance. 306 //! @param ui8EpAddr - set the USB device address 307 //! 308 //! This function is used by upper layer USB stack to set the device address allocated 309 //! by the USB host during the enumeration. 310 //! 311 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 312 // 313 //***************************************************************************** 314 extern uint32_t am_hal_usb_set_addr(void *pHandle, uint8_t ui8EpAddr); 315 316 //***************************************************************************** 317 // 318 //! @brief soft connect to the USB host 319 //! 320 //! @param pHandle - handle for the module instance. 321 //! 322 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 323 // 324 //***************************************************************************** 325 extern uint32_t am_hal_usb_attach(void *pHandle); 326 327 //***************************************************************************** 328 // 329 //! @brief soft disconnect to the USB host 330 //! 331 //! @param pHandle - handle for the module instance. 332 //! 333 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 334 // 335 //***************************************************************************** 336 extern uint32_t am_hal_usb_detach(void *pHandle); 337 338 //***************************************************************************** 339 // 340 //! @brief get the USB frame number 341 //! 342 //! @param pHandle - handle for the module instance. 343 //! 344 //! This function is used by upper layer USB stack to get the USB frame number. 345 //! 346 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 347 // 348 //***************************************************************************** 349 extern uint32_t am_hal_get_frame_number(void *pHandle); 350 351 //***************************************************************************** 352 // 353 //! @brief enable the SOF interrupt 354 //! 355 //! @param pHandle - handle for the module instance. 356 //! 357 //! This function is used by upper layer USB stack to enable the SOF interrupt. 358 //! 359 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 360 // 361 //***************************************************************************** 362 extern uint32_t am_hal_usb_enable_sof_intr(void *pHandle); 363 364 //***************************************************************************** 365 // 366 //! @brief disable the SOF interrupt 367 //! 368 //! @param pHandle - handle for the module instance. 369 //! 370 //! This function is used by upper layer USB stack to disable the SOF interrupt. 371 //! 372 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 373 // 374 //***************************************************************************** 375 extern uint32_t am_hal_usb_disable_sof_intr(void *pHandle); 376 377 #define AM_HAL_USB_GET_HW_INFO_ENABLED 378 #ifdef AM_HAL_USB_GET_HW_INFO_ENABLED 379 380 //***************************************************************************** 381 // 382 //! @brief Macro definitions for the USB hardware information. 383 //! 384 //! These macros correspond to the definitions in the datasheet of 385 //! apollo4 USB peripheral. 386 //! They may be used with the \e am_hal_usb_get_hw_infor function. 387 //! 388 // 389 //***************************************************************************** 390 typedef struct 391 { 392 // the major version number 393 uint8_t ui8Major; 394 // the minor version number 395 uint16_t ui16Minor; 396 // the number of OUT endpoints 397 uint8_t ui8OutEpNum; 398 // the number of IN endpoints 399 uint8_t ui8InEpNum; 400 // the width of RAM bus address 401 uint8_t ui8RamBits; 402 } am_hal_usb_hw_info; 403 404 //***************************************************************************** 405 // 406 //! @brief get the hardware information 407 //! 408 //! @param pHandle - handle for the module instance. 409 //! @param sHWInfo - the information about the USB device hardware configuration. 410 //! 411 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 412 // 413 //***************************************************************************** 414 extern uint32_t am_hal_usb_get_hw_infor(void *pHandle, am_hal_usb_hw_info *sHWInfo); 415 416 #endif 417 418 #define AM_HAL_USB_TEST_MODE_ENABLED 419 #ifdef AM_HAL_USB_TEST_MODE_ENABLED 420 421 //***************************************************************************** 422 // 423 //! @brief Macro definitions for the USB devie test mode. 424 //! 425 //! These macros correspond to the defintions in the USB specification. 426 //! They may be used with the \e am_hal_usb_test_mode function. 427 //! 428 // 429 //***************************************************************************** 430 typedef enum 431 { 432 AM_HAL_USB_TEST_SE0_NAK, 433 AM_HAL_USB_TEST_J, 434 AM_HAL_USB_TEST_K, 435 AM_HAL_USB_TEST_PACKET 436 } 437 am_hal_usb_test_mode_e; 438 439 // 440 // Upper layer USB stack should call below functions 441 // when receive TEST_MODE request 442 // 443 //***************************************************************************** 444 // 445 //! @brief set the USB test mode flag 446 //! 447 //! @param pHandle - handle for the module instance. 448 //! 449 //! set a flag in the handle to indicate the current USB device in the test mode. 450 //! 451 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 452 // 453 //***************************************************************************** 454 extern uint32_t am_hal_usb_enter_test_mode(const void *pHandle); 455 456 //***************************************************************************** 457 // 458 //! @brief do the USB test 459 //! 460 //! @param pHandle - handle for the module instance. 461 //! @param eTestMode - one of the test mode like TEST_SE0_NAK, TEST_J, TEST_K and TEST_PACKET. 462 //! 463 //! This function is used by upper layer USB stack to order the USB device controller 464 //! to send the specific USB packet or signals to verify the timing and signal quaility. 465 //! 466 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 467 // 468 //***************************************************************************** 469 extern uint32_t am_hal_usb_test_mode(const void *pHandle, const am_hal_usb_test_mode_e eTestMode); 470 #endif 471 472 //***************************************************************************** 473 // 474 //! @brief initialize the endpoint 475 //! 476 //! @param pHandle - handle for the module instance. 477 //! @param ui8EpAddr - endpoint address including the endpoint direction 478 //! @param ui8EpAttr - the type of endpoint (bulk/intr/iso/control) 479 //! @param ui16MaxPacket - the max packet length of the endpoint 480 //! 481 //! This function is used by upper layer USB stack to initialize the endpoints 482 //! when USB host sets the configuration of the USB device. 483 //! 484 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 485 // 486 //***************************************************************************** 487 extern uint32_t am_hal_usb_ep_init(void *pHandle, uint8_t ui8EpAddr, uint8_t ui8EpAttr, uint16_t ui16MaxPacket); 488 489 //***************************************************************************** 490 // 491 //! @brief stall the endpoint 492 //! 493 //! @param pHandle - handle for the module instance. 494 //! @param ui8EpAddr - endpoint address including the endpoint direction 495 //! 496 //! This function is used by upper layer USB stack to stall the endpoint when 497 //! some unknown requests can't be handled or transfer can't continue. 498 //! 499 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 500 // 501 //***************************************************************************** 502 extern uint32_t am_hal_usb_ep_stall(void *pHandle, uint8_t ui8EpAddr); 503 504 //***************************************************************************** 505 // 506 //! @brief clear the endpoint stall 507 //! 508 //! @param pHandle - handle for the module instance. 509 //! @param ui8EpAddr - endpoint address including the endpoint direction 510 //! 511 //! This function is used by upper layer USB stack to clear the endpoint stall 512 //! when USB device stack can recovry from some error status or USB host sends 513 //! the clear feature request to clear the stall of the endpoint. 514 //! 515 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 516 // 517 //***************************************************************************** 518 extern uint32_t am_hal_usb_ep_clear_stall(void *pHandle, uint8_t ui8EpAddr); 519 520 //***************************************************************************** 521 // 522 //! @brief submit a USB transfer 523 //! 524 //! @param pHandle - handle for the module instance. 525 //! @param ui8EpAddr - endpoint address including the endpoint direction 526 //! @param pui8Buf - the buffer for receiving the data from USB host or 527 //! sending data to the USB host. 528 //! @param ui16Len - the length of the buffer. 529 //! 530 //! This function is used by the upper layer USB stack to submit a transfer requst 531 //! to the USB device controller. 532 //! 533 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 534 // 535 //***************************************************************************** 536 extern uint32_t am_hal_usb_ep_xfer(void *pHandle, uint8_t ui8EpAddr, uint8_t *pui8Buf, uint16_t ui16Len); 537 538 //***************************************************************************** 539 // 540 //! @brief get the current USB speed 541 //! 542 //! @param pHandle - handle for the module instance. 543 //! 544 //! This function is used by the upper layer USB stack to get the current USB 545 //! speed type 546 //! like full-speed or high-speed. 547 //! 548 //! @return one of am_hal_usb_dev_speed_e like 549 //! AM_HAL_USB_SPEED_FULL 550 //! AM_HAL_USB_SPEED_HIGH, etc. 551 // 552 //***************************************************************************** 553 extern am_hal_usb_dev_speed_e am_hal_get_usb_dev_speed(void *pHandle); 554 555 //***************************************************************************** 556 // 557 //! @brief set the USB speed 558 //! 559 //! @param pHandle - handle for the module instance. 560 //! @param eSpeed - speed type of the USB device 561 //! 562 //! This function is used by the upper layer USB stack to force USB device controller 563 //! to run under a certain speed, for example full-speed by ignoring the controller 564 //! high-speed capability. 565 //! 566 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 567 // 568 //***************************************************************************** 569 extern uint32_t am_hal_usb_set_dev_speed(void *pHandle, am_hal_usb_dev_speed_e eSpeed); 570 571 //***************************************************************************** 572 // 573 //! @brief initialize the USB device controller module 574 //! 575 //! @param ui32Module - the index to the USB module 576 //! @param ppHandle - the handle of initialized USB instance 577 //! 578 //! This function should be called firstly before we use any other USB HAL driver 579 //! functions. 580 //! 581 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 582 // 583 //***************************************************************************** 584 extern uint32_t am_hal_usb_initialize(uint32_t ui32Module, void **ppHandle); 585 586 //***************************************************************************** 587 // 588 //! @brief uninitialize the USB device controller module 589 //! 590 //! @param pHandle - the handle of initialized USB instance 591 //! 592 //! This function should be called finally after we want to shutdown the USB 593 //! device controller. 594 //! 595 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 596 // 597 //***************************************************************************** 598 extern uint32_t am_hal_usb_deinitialize(void *pHandle); 599 600 //***************************************************************************** 601 // 602 //! @brief power on/off the USB device controller 603 //! 604 //! @param pHandle - the handle of initialized USB instance 605 //! @param ePowerState - the power state of USB device controller 606 //! @param bRetainState - wether retain the USB registers or not 607 //! 608 //! This function should be called after USB device controller has been initalized 609 //! successfully by 'am_hal_usb_initialize'. 610 //! 611 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 612 // 613 //***************************************************************************** 614 extern uint32_t am_hal_usb_power_control(void *pHandle, am_hal_sysctrl_power_state_e ePowerState, bool bRetainState); 615 616 //***************************************************************************** 617 // 618 //! @brief enable the IN endpoints' interrupt 619 //! 620 //! @param pHandle - the handle of initialized USB instance 621 //! @param ui32IntMask - the bit mask of IN endpoints' interrupt 622 //! 623 //! This function is used to enable the IN endpoints' interrupt. 624 //! 625 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 626 // 627 //***************************************************************************** 628 extern uint32_t am_hal_usb_intr_ep_in_enable(void *pHandle, uint32_t ui32IntMask); 629 630 //***************************************************************************** 631 // 632 //! @brief disable the IN endpoints' interrupt 633 //! 634 //! @param pHandle - the handle of initialized USB instance 635 //! @param ui32IntMask - the bit mask of IN endpoints' interrupt 636 //! 637 //! This function is used to disable the IN endpoints' interrupt. 638 //! 639 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 640 // 641 //***************************************************************************** 642 extern uint32_t am_hal_usb_intr_ep_in_disable(void *pHandle, uint32_t ui32IntMask); 643 644 //***************************************************************************** 645 // 646 //! @brief clear the IN endpoints' interrupt status 647 //! 648 //! @param pHandle - the handle of initialized USB instance 649 //! 650 //! This function is used to clear the IN endpoints' interrupt status. 651 //! 652 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 653 // 654 //***************************************************************************** 655 extern uint32_t am_hal_usb_intr_ep_in_clear(void *pHandle); 656 657 //***************************************************************************** 658 // 659 //! @brief get the IN endpoints' interrupt status 660 //! 661 //! @param pHandle - the handle of initialized USB instance 662 //! @param ui32IntStatus - the IN endpoints' interrupt status 663 //! @param bEnabledOnly - only check enabled IN endpoint interrupt or not 664 //! 665 //! This function is used to get IN endpoints' interrupt status. 666 //! 667 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 668 // 669 //***************************************************************************** 670 extern uint32_t am_hal_usb_intr_ep_in_status_get(void *pHandle, uint32_t *ui32IntStatus, bool bEnabledOnly); 671 672 //***************************************************************************** 673 // 674 //! @brief enable the OUT endpoints' interrupt 675 //! 676 //! @param pHandle - the handle of initialized USB instance 677 //! @param ui32IntMask - the bit mask of OUT endpoints' interrupt 678 //! 679 //! This function is used to enable the OUT endpoints' interrupt. 680 //! 681 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 682 // 683 //***************************************************************************** 684 extern uint32_t am_hal_usb_intr_ep_out_enable(void *pHandle, uint32_t ui32IntMask); 685 686 //***************************************************************************** 687 // 688 //! @brief disable the endpoints' interrupt 689 //! 690 //! @param pHandle - the handle of initialized USB instance 691 //! @param ui32IntMask - the bit mask of OUT endpoints' interrupt 692 //! 693 //! This function is used to disable the OUT endpoints' interrupt. 694 //! 695 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 696 // 697 //***************************************************************************** 698 extern uint32_t am_hal_usb_intr_ep_out_disable(void *pHandle, uint32_t ui32IntMask); 699 700 //***************************************************************************** 701 // 702 //! @brief clear the OUT endpoints' interrupt status 703 //! 704 //! @param pHandle - the handle of initialized USB instance 705 //! 706 //! This function is used to clear the OUT endpoints' interrupt. 707 //! 708 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 709 // 710 //***************************************************************************** 711 extern uint32_t am_hal_usb_intr_ep_out_clear(void *pHandle); 712 713 //***************************************************************************** 714 // 715 //! @brief get the OUT endpoints' interrupt status 716 //! 717 //! @param pHandle - the handle of initialized USB instance 718 //! @param pui32IntStatus - pointer to the OUT endpoints' interrupt status 719 //! @param bEnabledOnly - only check enabled OUT endpoint interrupt or not 720 //! 721 //! This function is used to get the OUT endpoints' interrupt status. 722 //! 723 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 724 // 725 //***************************************************************************** 726 extern uint32_t am_hal_usb_intr_ep_out_status_get(void *pHandle, uint32_t *pui32IntStatus, bool bEnabledOnly); 727 728 //***************************************************************************** 729 // 730 //! @brief enable the USB bus's interrupts 731 //! 732 //! @param pHandle - the handle of initialized USB instance 733 //! @param ui32IntMask - the bit mask of enabled USB bus interrupts 734 //! 735 //! This function is used to enable the USB bus interrupts. 736 //! 737 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 738 // 739 //***************************************************************************** 740 extern uint32_t am_hal_usb_intr_usb_enable(void *pHandle, uint32_t ui32IntMask); 741 742 //***************************************************************************** 743 // 744 //! @brief disable the USB bus's interrupts 745 //! 746 //! @param pHandle - the handle of initialized USB instance 747 //! @param ui32IntMask - the bit mask of USB bus interrupts. 748 //! 749 //! This function is used to disable the USB bus interrupts. 750 //! 751 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 752 // 753 //***************************************************************************** 754 extern uint32_t am_hal_usb_intr_usb_disable(void *pHandle, uint32_t ui32IntMask); 755 756 //***************************************************************************** 757 // 758 //! @brief clear the USB bus interrupts 759 //! 760 //! @param pHandle - the handle of initialized USB instance 761 //! 762 //! This function is used to clear the USB bus interrupt status. 763 //! 764 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 765 // 766 //***************************************************************************** 767 extern uint32_t am_hal_usb_intr_usb_clear(void *pHandle); 768 769 //***************************************************************************** 770 // 771 //! @brief get the USB bus interrupt status 772 //! 773 //! This function is used to get the USB bus interrupt status. 774 //! 775 //! @param pHandle - the handle of initialized USB instance 776 //! @param ui32IntStatus - the USB bus interrupt status 777 //! @param bEnabledOnly - only check enabled USB bus interrupt or not 778 //! 779 //! This function is used to get the USB bus interrupt status. 780 //! 781 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 782 // 783 //***************************************************************************** 784 extern uint32_t am_hal_usb_intr_usb_status_get(void *pHandle, uint32_t *ui32IntStatus, bool bEnabledOnly); 785 786 //***************************************************************************** 787 // 788 //! @brief Enum for the USB device bus event mask bit. 789 //! 790 //! This Enum are just some convenient utility for easing the programming. 791 // 792 //***************************************************************************** 793 enum 794 { 795 USB_INTRUSB_Suspend_Msk = 0x1, 796 USB_INTRUSB_Resume_Msk = 0x2, 797 USB_INTRUSB_Reset_Msk = 0x4, 798 USB_INTRUSB_SOF_Msk = 0x8, 799 USB_INTRIN_EP0_Msk = 0x1, 800 }; 801 802 //***************************************************************************** 803 // 804 //! @brief get all USB related interrupt status 805 //! 806 //! This function is used to get all USB related interrupt status. 807 //! 808 //! @param pHandle - the handle of initialized USB instance 809 //! @param ui32IntrUsbStatus - the USB bus interrupt status 810 //! @param ui32IntrInStatus - the USB IN endpoint interrupt status 811 //! @param ui32IntrOutStatus - the USB OUT endpoint interrupt status 812 //! 813 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 814 // 815 //***************************************************************************** 816 extern uint32_t am_hal_usb_intr_status_get(void *pHandle, uint32_t *ui32IntrUsbStatus, uint32_t *ui32IntrInStatus, uint32_t *ui32IntrOutStatus); 817 818 //***************************************************************************** 819 // 820 //! @brief USB interrupt service routine 821 //! 822 //! This function is USB interrupt service routine function. 823 //! 824 //! @param pHandle - the handle of initialized USB instance 825 //! @param ui32IntrUsbStatus - the USB bus interrupt status 826 //! @param ui32IntrInStatus - the USB IN endpoint interrupt status 827 //! @param ui32IntrOutStatus - the USB OUT endpoint interrupt status 828 //! 829 // 830 //***************************************************************************** 831 extern void am_hal_usb_interrupt_service(void *pHandle, 832 uint32_t ui32IntrUsbStatus, 833 uint32_t ui32IntrInStatus, 834 uint32_t ui32IntrOutStatus); 835 836 837 838 //***************************************************************************** 839 // 840 //! @brief Apply various specific commands / controls to the USB module 841 //! 842 //! @param eControl control enum 843 //! @param pArgs data used. This differs for each enum 844 //! 845 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 846 // 847 //***************************************************************************** 848 extern uint32_t am_hal_usb_control(am_hal_usb_control_e eControl, void *pArgs); 849 850 //***************************************************************************** 851 // 852 //! @brief set and enable HFRC2 FLL for 24Mhz speed usb 853 //! 854 //! @note this is used for HIGH-SPEED usb 855 //! 856 //! @param tUsbHsClockType - enable or disable the HFRC2 857 //! 858 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 859 // 860 //***************************************************************************** 861 extern uint32_t am_hal_usb_setHFRC2(am_hal_usb_hs_clock_type tUsbHsClockType); 862 863 //***************************************************************************** 864 // 865 //! @brief Reset EP State 866 //! 867 //! @param pHandle - handle for the module instance. 868 //! @param ui8EpAddr - USB endpoint address for state reset 869 //! 870 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 871 // 872 //***************************************************************************** 873 extern uint32_t am_hal_usb_ep_state_reset(void *pHandle, uint8_t ui8EpAddr); 874 875 #ifdef __cplusplus 876 } 877 #endif 878 879 #endif /* AM_HAL_USB_H_ */ 880 881 //***************************************************************************** 882 // 883 // End Doxygen group. 884 //! @} 885 // 886 //***************************************************************************** 887
