USB

This section introduces the USB APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enumerations, structures and functions. More...

Overview

This section introduces the USB APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enumerations, structures and functions.

Terms	Details
USB	Universal Serial Bus. USB was designed to standardize the connection of computer peripherals (including keyboards, pointing devices, digital cameras, printers, portable media players, disk drives and network adapters) to personal computers, both to communicate and to supply electric power. It has become commonplace on other devices, such as smart phones, PDAs and video game consoles.[3] USB has effectively replaced a variety of earlier interfaces, such as serial and parallel ports, as well as separate power chargers for portable devices. For more information, please refer to an introduction to the USB in Wikipedia.
PIO	Programmed Input / Output. It is a transmission mode to use CPU to move data.

Supported features.

• USB 2.0 High-Speed Device Controller
  In High-Speed mode, the USB controller is configured for supporting two endpoints to receive packets and four endpoints to send packets except for endpoint 0. These endpoints can be individually configured in the software to handle bulk transfers, interrupt transfers or isochronous transfers. There are four DMA channels and the embedded RAM size is 2,304 bytes. The embedded RAM can be dynamically configured for each endpoint.

Software architecture of the USB driver.

The software architecture of the USB driver is shown in the diagram below.

How to use this driver.

• Initialize the USB hardware.
  
  • Step1: Call hal_usb_init() to initialize the USB hardware if it has not been initialized after powering on.
  • Step2: Call hal_usb_configure_driver() to set up the HAL driver and register the callback functions.
  • Step3: Call hal_usb_reset_hardware() and hal_usb_reset_fifo() to soft reset the hardware.
  • Step4: Call hal_usb_pull_up_dp_line() to pull USB D+ to 3.3v and start USB connection.
  • sample code:

    usb_hw_init(void)
    {
        //USB hardware initialization.
        hal_usb_init();
    
        //Register reset and ep0 interrupt handlers for the driver settings.
        hal_usb_configure_driver();
        hal_usb_register_driver_callback(HAL_USB_DRV_HDLR_RESET, 0, USB_Reset);
        hal_usb_register_driver_callback(HAL_USB_DRV_HDLR_EP0, 0, USB_Endpoint0_Hdlr);
        hal_usb_register_driver_callback(HAL_USB_DRV_HDLR_SUSPEND, 0, USB_Suspend);
    
        //USB hardware soft reset.
        hal_usb_reset_hardware();
        //USB FIFO data reset.
        hal_usb_reset_fifo();
        //Set D+ to high.
        hal_usb_pull_up_dp_line();
    }

• De-initialize the USB hardware.
  
  • Step1: Call hal_usb_deinit() to power the USB hardware off.

    usb_hw_deinit(void)
    {
        //Power off the USB hardware.
        hal_usb_deinit();
    }

• Set up the USB endpoint.
  
  • Step1: Call hal_usb_init_tx_endpoint() to initialize the basic settings for the endpoint.
  • Step2: Call hal_usb_enable_tx_endpoint() to enable the endpoint interrupt.

    usb_ep_init(void)
    {
        int ep_num = 1;
        int wMaxPacketSize = 512;
        bool double_fifo = false;
        bool flush_fifo = true;
    
        //Initialize enpoint as BULK.
        hal_usb_init_tx_endpoint(ep_num, wMaxPacketSize, HAL_USB_ENDPT_BULK, double_fifo);
        hal_usb_init_rx_endpoint(ep_num, wMaxPacketSize, HAL_USB_ENDPT_BULK, double_fifo);
        hal_usb_enable_tx_endpoint(ep_num, HAL_USB_ENDPT_BULK, HAL_USB_EP_USE_NO_DMA, flush_fifo);
        hal_usb_enable_rx_endpoint(ep_num, HAL_USB_ENDPT_BULK, HAL_USB_EP_USE_NO_DMA, flush_fifo);
    }

• USB PIO data read.
  
  • Step1: Call hal_usb_get_rx_packet_length() to get the data length in the USB FIFO.
  • Step2: Call hal_usb_read_endpoint_fifo() to read the USB FIFO data and save in a buffer.
  • Step3: Call hal_usb_set_endpoint_rx_ready() to notify that the RX is ready to receive data packet.

    usb_fifo_read(void)
    {
       int nCount;
       int ep_num = 1;
       char data_buffer[512];
    
       //Read data count in FIFO.
       nCount = hal_usb_get_rx_packet_length(ep_num);
    
       //Read data from FIFO to data_buffer.
       hal_usb_read_endpoint_fifo(ep_num, nCount, data_buffer);
    
       //Notify the USB hardware that the RX is ready to receive the data packet.
       hal_usb_set_endpoint_rx_ready(ep_num);
    }

• USB PIO data write.
  
  • Step1: Call hal_usb_write_endpoint_fifo() to write data to the USB FIFO.
  • Step2: Call hal_usb_set_endpoint_tx_ready() to notify that the data packet is ready to send.

    #define DATA_LENGTH 10
    usb_fifo_write(void)
    {
       int nCount = DATA_LENGTH;
       int ep_num = 1;
       char data_buffer[DATA_LENGTH];
    
       //Write data to USB FIFO.
       hal_usb_write_endpoint_fifo(ep_num, nCount, data_buffer);
    
       //Notify the USB hardware that the data packet is ready to send.
       hal_usb_set_endpoint_tx_ready(ep_num);
    }

• USB Endpoint0 Handler.
  
  • Step1: Call hal_usb_read_endpoint_fifo() to read USB FIFO data and save in a buffer.
  • Step2: Check parameter usb_cmd.bRequest Call hal_usb_set_address() to set the USB Address data or call hal_usb_set_endpoint_stall() to set/clear the endpoint stall.

    void USB_Endpoint0_Handler (void)
    {
       bool stall = false;
       //Read ep0 data.
       hal_usb_read_endpoint_fifo(0, 8, &usb_cmd);
       if ((usb_cmd.bmRequestType & USB_CMD_TYPEMASK) == USB_CMD_STDREQ)
       {
           switch(usb_cmd.bRequest)
           {
            case USB_SET_ADDRESS:
                 hal_usb_set_address(usb_cmd.FAddr, HAL_USB_SET_ADDR_DATA);
                 break;
            case USB_SET_FEATURE:
                 if(usb_cmd.wValue) == USB_FTR_EPHALT)
                 {
                     stall = true;
                     if(pcmd->wIndex&0x80)
                        hal_usb_set_endpoint_stall((usb_cmd.wIndex& 0x0f), HAL_USB_EP_TX_DIR, stall);
                     else
                        hal_usb_set_endpoint_stall((usb_cmd.wIndex& 0x0f), HAL_USB_EP_RX_DIR, stall);
                 }
                 break;
            case USB_CLEAR_FEATURE:
                 if((usb_cmd.wValue) == USB_FTR_EPHALT))
                 {
                     if(pcmd->wIndex&0x80)
                        hal_usb_set_endpoint_stall((usb_cmd.wIndex& 0x0f), HAL_USB_EP_TX_DIR, stall);
                     else
                        hal_usb_set_endpoint_stall((usb_cmd.wIndex& 0x0f), HAL_USB_EP_RX_DIR, stall);
                 }
                 break;
           }
       }
    }

• USB DMA Usage.
  
  • Step1: Call hal_usb_get_dma_channel() to get a DMA channel.
  • Step2: Call hal_usb_start_dma_channel() to start the DMA.
  • Step3: Call hal_usb_stop_dma_channel() to stop the DMA.
  • Step4: Call hal_usb_release_dma_channel() to free the DMA channel.

    void USB_DMA_Example(void)
    {
        int ep_tx_num = 1;
        int ep_rx_num = 1;
        int ep_num = 0;
        int nCount= hal_usb_get_rx_packet_length(ep_num);
        uint8_t data[512];
        bool tx_rx_use_the_same_dma_channel = false;
        bool clear_dma_running_by_myself = false;
        hal_usb_dma_handler_t callback_fun = NULL;
    
        //============================================
        //Allocate DMA channels and configure the DMA.
        //============================================
        //Get TX channel.
        hal_usb_get_dma_channel(ep_tx_num, NULL, HAL_USB_EP_TX_DIR, tx_rx_use_the_same_dma_channel);
        //Get RX channel.
        hal_usb_get_dma_channel(NULL, ep_rx_num, HAL_USB_EP_RX_DIR, tx_rx_use_the_same_dma_channel);
        //Setup the DMA.
        hal_usb_start_dma_channel(ep_num, HAL_USB_EP_TX_DIR, HAL_USB_ENDPT_BULK, data, nCount, callback_fun, clear_dma_running_by_myself, HAL_USB_DMA1_TYPE);
    
    
        //Do something if you need
        //.............
    
    
        //====================================
        //Query the DMA status.
        //====================================
        if (hal_usb_is_dma_running())
             printf("USB DMA is in progress.\n");
        else
             printf("USB DMA is complete.\n");
    
    
    
    
        //Do something if you need
        //.............
    
    
        //==================================
        //Stop and release DMA channels.
        //==================================
        //Stop the DMA.
        hal_usb_stop_dma_channel(ep_num, HAL_USB_EP_TX_DIR);
        //Free the TX channel.
        hal_usb_release_dma_channel(ep_tx_num, NULL, HAL_USB_EP_TX_DIR, tx_rx_use_the_same_dma_channel);
        //Free the RX channel.
        hal_usb_release_dma_channel(NULL, ep_rx_num, HAL_USB_EP_RX_DIR, tx_rx_use_the_same_dma_channel);
    }

Functions
hal_usb_status_t	hal_usb_init (void)
	This function initializes the USB hardware module. More...
hal_usb_status_t	hal_usb_configure_driver (void)
	This function initializes the USB HAL driver. More...
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. More...
hal_usb_status_t	hal_usb_pull_up_dp_line (void)
	This function pulls the USB DP pin to high. More...
hal_usb_status_t	hal_usb_reset_hardware (void)
	This function applies the USB hardware soft reset. More...
hal_usb_status_t	hal_usb_reset_fifo (void)
	This function applies USB FIFO address reset at all endpoints. More...
hal_usb_status_t	hal_usb_deinit (void)
	This function releases the USB hardware resource. More...
hal_usb_status_t	hal_usb_set_address (uint8_t addr, hal_usb_set_address_state_t state)
	This function configures the USB address. More...
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. More...
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. More...
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. More...
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. More...
hal_usb_status_t	hal_usb_disable_tx_endpoint (uint32_t ep_num)
	This function disables the USB endpoint TX interrupt. More...
hal_usb_status_t	hal_usb_disable_rx_endpoint (uint32_t ep_num)
	This function disables the USB endpoint RX interrupt. More...
hal_usb_status_t	hal_usb_clear_tx_endpoint_data_toggle (uint32_t ep_num)
	This function clears the TX endpoint data toggle. More...
hal_usb_status_t	hal_usb_clear_rx_endpoint_data_toggle (uint32_t ep_num)
	This function clears the TX endpoint data toggle. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
uint32_t	hal_usb_get_rx_packet_length (uint32_t ep_num)
	This function gets the data packet length at the RX endpoint. More...
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. More...
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. More...
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. More...
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. More...
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 LinkIt platform for RTOS, please refer to HAL_USB_MAX_NUMBER_ENDPOINT. More...
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. More...
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. More...
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. More...
bool	hal_usb_is_dma_running (uint32_t ep_num, hal_usb_endpoint_direction_t direction)
	This function queries the DMA execution status. More...
bool	hal_usb_is_high_speed (void)
	This function queries current USB speed. More...
bool	hal_usb_is_endpoint_tx_empty (uint32_t ep_num)
	This function checks if the TX endpoint FIFO is empty or not. More...
bool	hal_usb_is_endpoint_rx_empty (uint32_t ep_num)
	This function checks if the RX endpoint FIFO is empty or not. More...
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. More...

Modules
	Define
	Enum.
	Typedefs.

Function Documentation

hal_usb_status_t hal_usb_clear_rx_endpoint_data_toggle

(

uint32_t

ep_num

)

This function clears the TX endpoint data toggle.

It's to force the endpoint data toggle to switch and the data packet to be cleared from the FIFO, regardless if the acknowledgement was received.

Parameters

[in]

ep_num

is the endpoint number to clear data toggle.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

void USB_endpoint_disable (void)
{
  int ep_num = 1;
  hal_usb_clear_rx_endpoint_data_toggle(ep_num);
}

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.

Parameters

[in]	ep_num	is the endpoint number.
[in]	ep_type	is the endpoint type defined in USB 2.0 Specification, such as CTRL, BULK, INTR, ISO endpoint.
[in]	b_reset_toggle	is set to true to execute clear data toggle.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

void usb_fifo_flush(void)
{
       int ep_num = 1;
       bool clear_data_toggle = false;

       hal_usb_clear_rx_endpoint_fifo(ep_num, HAL_USB_ENDPT_BULK, clear_data_toggle);
}

hal_usb_status_t hal_usb_clear_tx_endpoint_data_toggle

(

uint32_t

ep_num

)

This function clears the TX endpoint data toggle.

It's to force the endpoint data toggle to switch and the data packet to be cleared from the FIFO, regardless if the acknowledgement was received.

Parameters

[in]

ep_num

is the endpoint number to clear data toggle.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

void USB_endpoint_disable (void)
{
  int ep_num = 1;
  hal_usb_clear_tx_endpoint_data_toggle(ep_num);
}

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.

Parameters

[in]	ep_num	is the endpoint number.
[in]	ep_type	is the endpoint type defined in USB 2.0 Specification, such as CTRL, BULK, INTR, ISO endpoint.
[in]	b_reset_toggle	is set to true to execute clear data toggle.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

void usb_fifo_flush(void)
{
       int ep_num = 1;
       bool clear_data_toggle = false;

       hal_usb_clear_tx_endpoint_fifo(ep_num, HAL_USB_ENDPT_BULK, clear_data_toggle);
}

hal_usb_status_t hal_usb_configure_driver

(

void

)

This function initializes the USB HAL driver.

This function will initialize all required parameters, callback function and endpoint information in USB HAL driver.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "Initial USB hardware" in How to use this driver..

hal_usb_status_t hal_usb_deinit

(

void

)

This function releases the USB hardware resource.

This function deinitializes the USB hardware, sets the USB hardware in low power mode and releases the USB related clock tree and power source.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "De-initialize the USB hardware" in How to use this driver..

hal_usb_status_t hal_usb_disable_rx_endpoint

(

uint32_t

ep_num

)

This function disables the USB endpoint RX interrupt.

Parameters

[in]

ep_num

is the endpoint number to disable.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

void USB_endpoint_disable (void)
{
  int ep_num = 1;
  hal_usb_disable_rx_endpoint(ep_num);
}

hal_usb_status_t hal_usb_disable_tx_endpoint

(

uint32_t

ep_num

)

This function disables the USB endpoint TX interrupt.

Parameters

[in]

ep_num

is the endpoint number to disable.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

void USB_endpoint_disable (void)
{
  int ep_num = 1;
  hal_usb_disable_tx_endpoint(ep_num);
}

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.

Parameters

[in]	ep_num	is the endpoint to initialize.
[in]	ep_type	is the endpoint type defined in USB 2.0 Specification. Such as CTRL, BULK, INTR, ISO endpoint.
[in]	dma_usage_type	is set to PIO or DMA mode.
[in]	is_flush	flushes the USB FIFO data when the function is executed.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "USB endpoint setup" in How to use this driver..

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.

Parameters

[in]	ep_num	is the endpoint to initialize.
[in]	ep_type	is the endpoint type defined in USB 2.0 Specification, such as CTRL, BULK, INTR, ISO endpoint.
[in]	dma_usage_type	is set to PIO or DMA mode.
[in]	is_flush	flushes the USB FIFO data when the function is executed.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "USB endpoint setup" in How to use this driver..

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.

To activate a test mode, the USB 2.0 Specification defines the SET_FEATURE command as the desired interface. The USB-IF offers a free High Speed electrical Test Tool (HSET) for Microsoft Windows OS, to activate the various test modes and operations

Parameters

[in]

test_selector

select the test function.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

void usb_test_mode(void)
{
       hal_usb_enter_test_mode(HAL_USB_TEST_MODE_TYPE_J);
       hal_usb_enter_test_mode(HAL_USB_TEST_MODE_TYPE_K);
       hal_usb_enter_test_mode(HAL_USB_TEST_MODE_TYPE_SE0_NAK);
       hal_usb_enter_test_mode(HAL_USB_TEST_MODE_TYPE_PACKET);
 }

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 LinkIt platform for RTOS, please refer to HAL_USB_MAX_NUMBER_ENDPOINT.

Parameters

[in]	ep_tx_num	is the endpoint number in TX direction.
[in]	ep_rx_num	is the endpoint number in RX direction.
[in]	direction	is the USB endpoint direction. This parameter is ignored, if the same channel is used.
[in]	same_chan	the TX and RX use the same DMA channel.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

An example implementation can be found in "USB DMA Usage." in How to use this driver..

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.

p_transaction_end: This bit is set when a control transaction ends before the DataEnd bit is set. An interrupt will be generated and the FIFO flushed. p_sent_stall: This bit is set when a STALL handshake is transmitted.

Parameters

[out]	p_transaction_end	is the result of control pipe transaction end.
[out]	p_sent_stall	is the result of control pipe sent stall.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

void USB_Endpoint0_Hdlr(void)
{
   bool b_transaction_end;
   bool b_sent_stall;

   hal_usb_get_endpoint_0_status(&b_transaction_end, &b_sent_stall);
}

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.

It is usually used to response to the host endpoint 0 command: GET_STATUS

Parameters

[in]	ep_num	is the endpoint number.
[in]	direction	is the USB endpoint direction.

Returns

True, if stall is enabled.

Example

Sample code please refers to "USB Endpoint0 Handler" in How to use this driver..

void USB_Endpoint0_Hdlr(void)
{
  int ep_num = 1;
  bool status;

  status = (uint16_t)hal_usb_get_endpoint_stall_status(ep_num, HAL_USB_EP_TX_DIR);
}

uint32_t hal_usb_get_rx_packet_length

(

uint32_t

ep_num

)

This function gets the data packet length at the RX endpoint.

Parameters

[in]

ep_num

is the endpoint number.

Returns

the length of packet size in bytes.

Example

For an example implementation, please refer to "USB PIO data read" in How to use this driver..

hal_usb_status_t hal_usb_init

(

void

)

This function initializes the USB hardware module.

Call this function before using the USB service. It also enables the USB related clock tree and power source.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "Initialize the USB hardware" in How to use this driver..

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.

Parameters

[in]	ep_num	is the endpoint to initialize.
[in]	data_size	is the maximum packet size at this endpoint. For more details about maximum packet size, please refer to USB 2.0 Specification.
[in]	type	is the endpoint type defined in USB 2.0 Specification, such as CTRL, BULK, INTR, ISO endpoint.
[in]	double_fifo	allocates two FIFO buffers, if double_fifo is enabled.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "USB endpoint setup" in How to use this driver..

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.

Parameters

[in]	ep_num	is the endpoint to initialize.
[in]	data_size	is the maximum packet size at this endpoint. For more details about maximum packet size, please refer to USB 2.0 Specification.
[in]	type	is the endpoint type defined in USB 2.0 Specification, such as CTRL, BULK, INTR, ISO endpoint.
[in]	double_fifo	two FIFO buffers are allocated, if double_fifo is enabled. It may cost more FIFO SRAM.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "USB endpoint setup" in How to use this driver..

bool hal_usb_is_dma_running	(	uint32_t	ep_num,
		hal_usb_endpoint_direction_t	direction
	)

This function queries the DMA execution status.

Parameters

[in]	ep_num	is the endpoint number.
[in]	direction	is the USB endpoint direction.

Returns

True, if the DMA is running.

Example

An example implementation can be found in "USB DMA Usage." in How to use this driver..

bool hal_usb_is_endpoint_rx_empty

(

uint32_t

ep_num

)

This function checks if the RX endpoint FIFO is empty or not.

Parameters

[in]

ep_num

is the endpoint number.

Returns

False, if there is data in FIFO pending to read.

Example

Sample code:

void query_fifo_status(void)
{
       int ep_num = 1;

       if (hal_usb_is_endpoint_rx_empty(ep_num))
          printf("USB rx FIFO is empty\n");
       else
          printf("USB rx FIFO still has data\n");
}

bool hal_usb_is_endpoint_tx_empty

(

uint32_t

ep_num

)

This function checks if the TX endpoint FIFO is empty or not.

Parameters

[in]

ep_num

is the endpoint number.

Returns

False, if there is data in FIFO pending to send.

Example

Sample code:

void query_fifo_status(void)
{
       int ep_num = 1;

       if (hal_usb_is_endpoint_tx_empty(ep_num))
          printf("USB tx FIFO is empty\n");
       else
          printf("USB tx FIFO still has data\n");
}

bool hal_usb_is_high_speed

(

void

)

This function queries current USB speed.

Returns

True, if using high-speed USB.

Example

Sample code:

void get_usb_speed(void)
{
       if (hal_usb_is_high_speed())
          printf("USB is high speed mode\n");
       else
          printf("USB is full speed mode\n");
}

hal_usb_status_t hal_usb_pull_up_dp_line

(

void

)

This function pulls the USB DP pin to high.

It starts the USB connection flow. For more details on DP, please refer to the USB 2.0 Specification.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "Initialize the USB hardware" in How to use this driver..

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.

Reading from these addresses unloads data from the RX FIFO for the corresponding endpoint.

Parameters

[in]	ep_num	is the endpoint number.
[in]	nBytes	is the number of bytes to read.
[in]	pDst	is a pointer to the destination.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code please refers to "USB PIO data read." in How to use this 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.

Parameters

[in]	type	is the interrupt handler type. Please refer to hal_usb_driver_handler_type_t.
[in]	ep_num	is the endpoint number. The interrupt handler must be binding to a specific endpoint number if it uses HAL_USB_DRV_HDLR_EP_TX and HAL_USB_DRV_HDLR_EP_RX.
[in]	hdlr	is the callback function. Please refer to hal_usb_driver_interrupt_handler_t.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "Initialize the USB hardware" in How to use this driver..

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.

For more information on the number of DMA channels on the LinkIt platform for RTOS, please refer to HAL_USB_MAX_NUMBER_ENDPOINT.

Parameters

[in]	ep_tx_num	is the endpoint number in TX direction.
[in]	ep_rx_num	is the endpoint number in RX direction.
[in]	direction	is the USB endpoint direction. This parameter is ignored, if the same channel is used.
[in]	same_chan	the TX and RX use the same DMA channel.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

An example implementation can be found in "USB DMA Usage." in How to use this driver..

hal_usb_status_t hal_usb_reset_fifo

(

void

)

This function applies USB FIFO address reset at all endpoints.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "Initialize the USB hardware" in How to use this driver..

hal_usb_status_t hal_usb_reset_hardware

(

void

)

This function applies the USB hardware soft reset.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "Initialize the USB hardware" in How to use this driver..

hal_usb_status_t hal_usb_set_address	(	uint8_t	addr,
		hal_usb_set_address_state_t	state
	)

This function configures the USB address.

In the USB 2.0 Specifications, the USB address is set by the USB control pipe. The address is 1~127(7-bits). This address should be written with the address received through a SET_ADDRESS command, which will then be used for decoding the function address in subsequent token packets.

Parameters

[in]	addr	the USB address set by the USB control pipe through a SET_ADDRESS command.
[in]	state	the current state for the set address function. The address writes to hardware only in HAL_USB_SET_ADDR_STATUS state. It must make sure the SET_ADDRESS command is completed.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Please refer to "USB Endpoint0 Handler" in How to use this driver..

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.

Hardware issues an interrupt if RX endpoint received a packet. Hardware will start to receive the next packet if data is read from FIFO and RX packet is set to ready.

Parameters

[in]

ep_num

is the endpoint number.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

For an example implementation, please refer to "USB PIO data read." in How to use this driver..

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.

This function is used to execute (1) endpoint stall, (2) FIFO flush and (3) clear data toggle.

Parameters

[in]	ep_num	is the endpoint number.
[in]	direction	is the USB endpoint direction.
[in]	stall_enable	enables or disables the stall operation.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code please refers to "USB Endpoint0 Handler" in How to use this driver..

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.

Hardware will send the packet out if data is written to the FIFO and the TX packet is set to ready. Null length packet (ZLP) will be sent if the data is not written to the FIFO.

Parameters

[in]

ep_num

is the endpoint number.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code please refers to "USB PIO data write." in How to use this driver..

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.

Parameters

[in]	ep_num	is the endpoint number.
[in]	direction	is the USB endpoint direction.
[in]	ep_type	is the endpoint type defined in USB 2.0 Specification. Such as CTRL, BULK, INTR, ISO endpoint.
[in]	addr	is a pointer to the address to apply the DMA transaction.
[in]	length	is the data length in bytes.
[in]	callback	is called once the DMA transaction is complete.
[in]	callback_upd_run	configures the DMA running state. Set true, if application callback function requests to clear the DMA running by itself.
[in]	dma_type	executes a single packet operation or multiple packets operation, hal_usb_dma_type_t.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

An example implementation can be found in "USB DMA Usage." in How to use this driver..

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.

After that, drop data in FIFO.

Parameters

[in]	ep_num	is the endpoint number.
[in]	direction	is the USB endpoint direction.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

An example implementation can be found in "USB DMA Usage." in How to use this driver..

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.

Parameters

[in]	state	is the endpoint0 hardware control state. Please refer to hal_usb_endpoint_0_driver_state_t.
[in]	stall	is set to true to execute endpoint stall.
[in]	end	is set to true to execute transaction end.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code:

// It shows 3 examples in this function call.
void USB_Endpoint0_State(void)
{
   bool transaction_end;
   bool sent_stall;

   //example1: read data end and stall this transaction.
   sent_stall = true;
   transaction_end = false;
   hal_usb_update_endpoint_0_state(HAL_USB_EP0_DRV_STATE_READ_END, sent_stall, transaction_end);

   //example2: write data ready and set this transaction completed.
   sent_stall = false;
   transaction_end = true;
   hal_usb_update_endpoint_0_state(HAL_USB_EP0_DRV_STATE_WRITE_RDY, sent_stall, transaction_end);

   //example3: transaction end and clear the transaction_end hardware status.
   sent_stall = false;
   transaction_end = true;
   hal_usb_update_endpoint_0_state(HAL_USB_EP0_DRV_STATE_TRANSACTION_END, sent_stall, transaction_end);
}

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.

Writing to these addresses loads data into the TX FIFO for the corresponding endpoint.

Parameters

[in]	ep_num	is the endpoint number.
[in]	nBytes	is the number of bytes to write.
[in]	pSrc	is a pointer to the source.

Returns

HAL_USB_STATUS_OK, if the operation completed successfully.

Example

Sample code please refers to "USB PIO data write." in How to use this driver..