MT2523 API Reference  LinkIt SDK v4
hal_usb.h
1 /* Copyright Statement:
2  *
3  * (C) 2005-2016 MediaTek Inc. All rights reserved.
4  *
5  * This software/firmware and related documentation ("MediaTek Software") are
6  * protected under relevant copyright laws. The information contained herein
7  * is confidential and proprietary to MediaTek Inc. ("MediaTek") and/or its licensors.
8  * Without the prior written permission of MediaTek and/or its licensors,
9  * any reproduction, modification, use or disclosure of MediaTek Software,
10  * and information contained herein, in whole or in part, shall be strictly prohibited.
11  * You may only use, reproduce, modify, or distribute (as applicable) MediaTek Software
12  * if you have agreed to and been bound by the applicable license agreement with
13  * MediaTek ("License Agreement") and been granted explicit permission to do so within
14  * the License Agreement ("Permitted User"). If you are not a Permitted User,
15  * please cease any access or use of MediaTek Software immediately.
16  * BY OPENING THIS FILE, RECEIVER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES
17  * THAT MEDIATEK SOFTWARE RECEIVED FROM MEDIATEK AND/OR ITS REPRESENTATIVES
18  * ARE PROVIDED TO RECEIVER ON AN "AS-IS" BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL
19  * WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
20  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT.
21  * NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE
22  * SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY, INCORPORATED IN, OR
23  * SUPPLIED WITH MEDIATEK SOFTWARE, AND RECEIVER AGREES TO LOOK ONLY TO SUCH
24  * THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO. RECEIVER EXPRESSLY ACKNOWLEDGES
25  * THAT IT IS RECEIVER'S SOLE RESPONSIBILITY TO OBTAIN FROM ANY THIRD PARTY ALL PROPER LICENSES
26  * CONTAINED IN MEDIATEK SOFTWARE. MEDIATEK SHALL ALSO NOT BE RESPONSIBLE FOR ANY MEDIATEK
27  * SOFTWARE RELEASES MADE TO RECEIVER'S SPECIFICATION OR TO CONFORM TO A PARTICULAR
28  * STANDARD OR OPEN FORUM. RECEIVER'S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK'S ENTIRE AND
29  * CUMULATIVE LIABILITY WITH RESPECT TO MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE,
30  * AT MEDIATEK'S OPTION, TO REVISE OR REPLACE MEDIATEK SOFTWARE AT ISSUE,
31  * OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY RECEIVER TO
32  * MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE.
33  */
34 
35 #ifndef __HAL_USB_H__
36 #define __HAL_USB_H__
37 
38 #include "hal_platform.h"
39 
40 #ifdef HAL_USB_MODULE_ENABLED
41 
296 #ifdef __cplusplus
297 extern "C" {
298 #endif
299 
303 #define HAL_USB_MAX_NUMBER_ENDPOINT 4
304 
305 #define HAL_USB_MAX_NUMBER_ENDPOINT_TX 4
306 
307 #define HAL_USB_MAX_NUMBER_ENDPOINT_RX 2
308 
309 #define HAL_USB_MAX_NUMBER_DMA 4
310 
311 #define HAL_USB_MAX_PACKET_SIZE_ENDPOINT_0 64
312 
313 #define HAL_USB_MAX_PACKET_SIZE_ENDPOINT_BULK_HIGH_SPEED 512
314 
315 #define HAL_USB_MAX_PACKET_SIZE_ENDPOINT_BULK_FULL_SPEED 64
316 
317 #define HAL_USB_MAX_PACKET_SIZE_ENDPOINT_ISOCHRONOUS_HIGH_SPEED 1024
318 
319 #define HAL_USB_MAX_PACKET_SIZE_ENDPOINT_ISOCHRONOUS_FULL_SPEED 512
320 
321 #define HAL_USB_MAX_PACKET_SIZE_ENDPOINT_INTERRUPT_HIGH_SPEED 64
322 
323 #define HAL_USB_MAX_PACKET_SIZE_ENDPOINT_INTERRUPT_FULL_SPEED 64
324 
339 typedef void (*hal_usb_dma_handler_t)(void);
349 typedef enum {
354 
357 typedef enum {
361 
362 
364 typedef enum {
368 
370 typedef enum {
374 
376 typedef enum {
383 
385 typedef enum {
389 
391 typedef enum {
397 
398 
400 typedef enum {
405 
407 typedef enum {
413 
414 
416 typedef enum {
424 
428 typedef enum {
447 extern hal_usb_status_t hal_usb_init(void);
456 
466 extern hal_usb_status_t hal_usb_register_driver_callback(hal_usb_driver_handler_type_t type, uint32_t ep_num, hal_usb_driver_interrupt_handler_t hdlr);
496 extern hal_usb_status_t hal_usb_deinit(void);
509 extern hal_usb_status_t hal_usb_set_address(uint8_t addr, hal_usb_set_address_state_t state);
521 extern hal_usb_status_t hal_usb_init_tx_endpoint(uint32_t ep_num, uint16_t data_size, hal_usb_endpoint_transfer_type_t type, bool double_fifo);
532 extern hal_usb_status_t hal_usb_init_rx_endpoint(uint32_t ep_num, uint16_t data_size, hal_usb_endpoint_transfer_type_t type, bool double_fifo);
543 extern hal_usb_status_t hal_usb_enable_tx_endpoint(uint32_t ep_num, hal_usb_endpoint_transfer_type_t ep_type, hal_usb_dma_usage_t dma_usage_type, bool is_flush);
554 extern hal_usb_status_t hal_usb_enable_rx_endpoint(uint32_t ep_num, hal_usb_endpoint_transfer_type_t ep_type, hal_usb_dma_usage_t dma_usage_type, bool is_flush);
569 extern hal_usb_status_t hal_usb_disable_tx_endpoint(uint32_t ep_num);
584 extern hal_usb_status_t hal_usb_disable_rx_endpoint(uint32_t ep_num);
627 extern hal_usb_status_t hal_usb_read_endpoint_fifo(uint32_t ep_num, uint16_t nBytes, void *pDst);
638 extern hal_usb_status_t hal_usb_write_endpoint_fifo(uint32_t ep_num, uint16_t nBytes, void *pSrc);
649 extern hal_usb_status_t hal_usb_set_endpoint_stall(uint32_t ep_num, hal_usb_endpoint_direction_t direction, bool stall_enable);
668 extern bool hal_usb_get_endpoint_stall_status(uint32_t ep_num, hal_usb_endpoint_direction_t direction);
689 extern hal_usb_status_t hal_usb_get_endpoint_0_status(bool *p_transaction_end, bool *p_sent_stall);
722 extern hal_usb_status_t hal_usb_update_endpoint_0_state(hal_usb_endpoint_0_driver_state_t state, bool stall, bool end);
730 extern uint32_t hal_usb_get_rx_packet_length(uint32_t ep_num);
740 extern hal_usb_status_t hal_usb_set_endpoint_tx_ready(uint32_t ep_num);
750 extern hal_usb_status_t hal_usb_set_endpoint_rx_ready(uint32_t ep_num);
769 extern hal_usb_status_t hal_usb_clear_tx_endpoint_fifo(uint32_t ep_num, hal_usb_endpoint_transfer_type_t ep_type, bool b_reset_toggle);
788 extern hal_usb_status_t hal_usb_clear_rx_endpoint_fifo(uint32_t ep_num, hal_usb_endpoint_transfer_type_t ep_type, bool b_reset_toggle);
800 extern hal_usb_status_t hal_usb_get_dma_channel(uint32_t ep_tx_num, uint32_t ep_rx_num, hal_usb_endpoint_direction_t direction, bool same_chan);
812 extern hal_usb_status_t hal_usb_release_dma_channel(uint32_t ep_tx_num, uint32_t ep_rx_num, hal_usb_endpoint_direction_t direction, bool same_chan);
827 extern hal_usb_status_t hal_usb_start_dma_channel(uint32_t ep_num, hal_usb_endpoint_direction_t direction, hal_usb_endpoint_transfer_type_t ep_type, void *addr, uint32_t length, hal_usb_dma_handler_t callback, bool callback_upd_run, hal_usb_dma_type_t dma_type);
837 extern hal_usb_status_t hal_usb_stop_dma_channel(uint32_t ep_num, hal_usb_endpoint_direction_t direction);
846 extern bool hal_usb_is_dma_running(uint32_t ep_num, hal_usb_endpoint_direction_t direction);
862 extern bool hal_usb_is_high_speed(void);
881 extern bool hal_usb_is_endpoint_tx_empty(uint32_t ep_num);
900 extern bool hal_usb_is_endpoint_rx_empty(uint32_t ep_num);
920 extern hal_usb_status_t hal_usb_enter_test_mode(hal_usb_test_mode_type_t test_selector);
921 
922 
923 #ifdef __cplusplus
924 }
925 #endif
926 
927 
933 #endif /* HAL_USB_MODULE_ENABLED */
934 #endif /* __HAL_USB_H__ */
935 
The maximum current consumption cannot exceed 2.5mA in HAL_USB_POWER_STATE_SUSPEND state...
Definition: hal_usb.h:359
The transfer type defined in USB 2.0 Specification, interrupt pipe.
Definition: hal_usb.h:394
hal_usb_status_t hal_usb_set_address(uint8_t addr, hal_usb_set_address_state_t state)
This function configures the USB address.
Multiple packets operation.
Definition: hal_usb.h:366
NOT in test mode.
Definition: hal_usb.h:377
USB bus suspended callback function.
Definition: hal_usb.h:418
hal_usb_endpoint_direction_t
This is the direction of USB endpoint.
Definition: hal_usb.h:385
hal_usb_status_t hal_usb_set_endpoint_rx_ready(uint32_t ep_num)
This function sets the USB packet ready once the data is fully read from FIFO.
bool hal_usb_is_dma_running(uint32_t ep_num, hal_usb_endpoint_direction_t direction)
This function queries the DMA execution status.
hal_usb_dma_usage_t
USB DMA usage.
Definition: hal_usb.h:370
hal_usb_status_t hal_usb_set_endpoint_stall(uint32_t ep_num, hal_usb_endpoint_direction_t direction, bool stall_enable)
This function sets the USB endpoint n to stall, flush or clear data toggle.
hal_usb_status_t hal_usb_clear_rx_endpoint_fifo(uint32_t ep_num, hal_usb_endpoint_transfer_type_t ep_type, bool b_reset_toggle)
This function flushes data packet in RX FIFO and clears the data toggle by request.
The function call was successful.
Definition: hal_usb.h:352
The function call failed.
Definition: hal_usb.h:351
hal_usb_status_t hal_usb_clear_rx_endpoint_data_toggle(uint32_t ep_num)
This function clears the TX endpoint data toggle.
The endpoint operates in the DMA mode.
Definition: hal_usb.h:403
Control pipe received a SET_ADDRESS data.
Definition: hal_usb.h:429
hal_usb_endpoint_0_driver_state_t
Endpoint 0 hardware control state.
Definition: hal_usb.h:407
The endpoint is disabled.
Definition: hal_usb.h:401
Endpoint use with DMA mode.
Definition: hal_usb.h:372
hal_usb_status_t hal_usb_pull_up_dp_line(void)
This function pulls the USB DP pin to high.
PC IN, such as BULK_IN is HAL_USB_EP_TX_DIR.
Definition: hal_usb.h:386
hal_usb_status_t hal_usb_read_endpoint_fifo(uint32_t ep_num, uint16_t nBytes, void *pDst)
This function reads the USB data from FIFO.
hal_usb_status_t hal_usb_start_dma_channel(uint32_t ep_num, hal_usb_endpoint_direction_t direction, hal_usb_endpoint_transfer_type_t ep_type, void *addr, uint32_t length, hal_usb_dma_handler_t callback, bool callback_upd_run, hal_usb_dma_type_t dma_type)
This function sets up the USB DMA channel to transfer data.
The transfer type defined in USB 2.0 Specification, bulk pipe.
Definition: hal_usb.h:393
hal_usb_power_state_t
USB power state.
Definition: hal_usb.h:357
hal_usb_status_t hal_usb_enable_rx_endpoint(uint32_t ep_num, hal_usb_endpoint_transfer_type_t ep_type, hal_usb_dma_usage_t dma_usage_type, bool is_flush)
This function enables the USB endpoint RX interrupt.
hal_usb_status_t hal_usb_write_endpoint_fifo(uint32_t ep_num, uint16_t nBytes, void *pSrc)
This function writes the USB data to FIFO.
hal_usb_endpoint_transfer_type_t
Endpoint type defined in USB 2.0 Specification.
Definition: hal_usb.h:391
hal_usb_set_address_state_t
The set address action may be different for different hardware.
Definition: hal_usb.h:428
bool hal_usb_is_endpoint_tx_empty(uint32_t ep_num)
This function checks if the TX endpoint FIFO is empty or not.
USB endpoint n TX callback function.
Definition: hal_usb.h:421
hal_usb_status_t hal_usb_release_dma_channel(uint32_t ep_tx_num, uint32_t ep_rx_num, hal_usb_endpoint_direction_t direction, bool same_chan)
This function frees a USB DMA channel resource.
bool hal_usb_is_endpoint_rx_empty(uint32_t ep_num)
This function checks if the RX endpoint FIFO is empty or not.
USB bus reset callback function.
Definition: hal_usb.h:417
The Test_J test mode.
Definition: hal_usb.h:378
hal_usb_test_mode_type_t
USB Test Mode.
Definition: hal_usb.h:376
uint32_t hal_usb_get_rx_packet_length(uint32_t ep_num)
This function gets the data packet length at the RX endpoint.
hal_usb_driver_handler_type_t
Interrupt handler type.
Definition: hal_usb.h:416
Control pipe acknowledged the SET_ADDRESS command status.
Definition: hal_usb.h:430
PC OUT, such as BULK_OUT is HAL_USB_EP_RX_DIR.
Definition: hal_usb.h:387
hal_usb_status_t hal_usb_configure_driver(void)
This function initializes the USB HAL driver.
hal_usb_status_t hal_usb_register_driver_callback(hal_usb_driver_handler_type_t type, uint32_t ep_num, hal_usb_driver_interrupt_handler_t hdlr)
This function registers a callback function.
The transfer type defined in USB 2.0 Specification, control pipe.
Definition: hal_usb.h:392
hal_usb_status_t hal_usb_reset_fifo(void)
This function applies USB FIFO address reset at all endpoints.
hal_usb_status_t hal_usb_clear_tx_endpoint_data_toggle(uint32_t ep_num)
This function clears the TX endpoint data toggle.
hal_usb_status_t hal_usb_init(void)
This function initializes the USB hardware module.
hal_usb_status_t hal_usb_init_tx_endpoint(uint32_t ep_num, uint16_t data_size, hal_usb_endpoint_transfer_type_t type, bool double_fifo)
This function initializes the USB endpoint in TX direction.
The maximum current consumption cannot exceed 500mA in HAL_USB_POWER_STATE_NORMAL state...
Definition: hal_usb.h:358
hal_usb_status_t hal_usb_init_rx_endpoint(uint32_t ep_num, uint16_t data_size, hal_usb_endpoint_transfer_type_t type, bool double_fifo)
This function initialize the USB endpoint in RX direction.
hal_usb_status_t hal_usb_enter_test_mode(hal_usb_test_mode_type_t test_selector)
This function sets the USB hardware into test mode.
void(* hal_usb_driver_interrupt_handler_t)(void)
Interrupt handler function type.
Definition: hal_usb.h:335
hal_usb_status_t hal_usb_stop_dma_channel(uint32_t ep_num, hal_usb_endpoint_direction_t direction)
This function stops the USB DMA channel and clears pending DMA interrupts.
void(* hal_usb_dma_handler_t)(void)
Application DMA callback function type.
Definition: hal_usb.h:339
The endpoint operates in the PIO mode.
Definition: hal_usb.h:402
The contol pipe transaction is complete.
Definition: hal_usb.h:410
hal_usb_status_t hal_usb_deinit(void)
This function releases the USB hardware resource.
hal_usb_status_t hal_usb_clear_tx_endpoint_fifo(uint32_t ep_num, hal_usb_endpoint_transfer_type_t ep_type, bool b_reset_toggle)
This function flushes data packet in the TX FIFO and clears data toggle by request.
hal_usb_status_t hal_usb_get_endpoint_0_status(bool *p_transaction_end, bool *p_sent_stall)
This function gets the USB control pipe hardware status.
USB bus resumed callback function.
Definition: hal_usb.h:419
hal_usb_dma_type_t
USB DMA usage type.
Definition: hal_usb.h:364
hal_usb_endpoint_state_t
Endpoint state.
Definition: hal_usb.h:400
Data is sent to the USB FIFO.
Definition: hal_usb.h:409
Clear contol pipe stall status.
Definition: hal_usb.h:411
hal_usb_status_t
USB status.
Definition: hal_usb.h:349
USB endpoint n RX callback function.
Definition: hal_usb.h:422
hal_usb_status_t hal_usb_update_endpoint_0_state(hal_usb_endpoint_0_driver_state_t state, bool stall, bool end)
This function sets the USB control pipe hardware status.
Endpoint use with PIO mode.
Definition: hal_usb.h:371
hal_usb_status_t hal_usb_enable_tx_endpoint(uint32_t ep_num, hal_usb_endpoint_transfer_type_t ep_type, hal_usb_dma_usage_t dma_usage_type, bool is_flush)
This function enables the USB endpoint TX interrupt.
Single packet operation.
Definition: hal_usb.h:365
USB endpoint 0 callback function.
Definition: hal_usb.h:420
The Test_K test mode.
Definition: hal_usb.h:379
hal_usb_status_t hal_usb_set_endpoint_tx_ready(uint32_t ep_num)
This function sets the USB packet ready once the data is fully written into FIFO. ...
Control pipe data is received.
Definition: hal_usb.h:408
hal_usb_status_t hal_usb_disable_rx_endpoint(uint32_t ep_num)
This function disables the USB endpoint RX interrupt.
hal_usb_status_t hal_usb_disable_tx_endpoint(uint32_t ep_num)
This function disables the USB endpoint TX interrupt.
hal_usb_status_t hal_usb_reset_hardware(void)
This function applies the USB hardware soft reset.
hal_usb_status_t hal_usb_get_dma_channel(uint32_t ep_tx_num, uint32_t ep_rx_num, hal_usb_endpoint_direction_t direction, bool same_chan)
This function allocates a USB DMA channel For more information on the number of DMA channels on the L...
bool hal_usb_get_endpoint_stall_status(uint32_t ep_num, hal_usb_endpoint_direction_t direction)
This function queries the stall status of the USB endpoint n.
The Test_SE0_NAK test mode.
Definition: hal_usb.h:380
bool hal_usb_is_high_speed(void)
This function queries current USB speed.
An invalid parameter was given.
Definition: hal_usb.h:350
The Test_Packet test mode.
Definition: hal_usb.h:381
The transfer type defined in USB 2.0 Specification, isochronous pipe.
Definition: hal_usb.h:395