MT7687 API Reference  LinkIt SDK v4
UART

This section introduces the Universal Asynchronous Receiver/Transmitter(UART) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, UART function groups, enums, structures and functions. More...

Overview

This section introduces the Universal Asynchronous Receiver/Transmitter(UART) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, UART function groups, enums, structures and functions.

Terms and acronyms

Terms Details
CTS This UART pin is used to indicate if the device can transmit data. It is used only when the UART hardware flow control is enabled.
GPIO General Purpose Input Output is a generic pin on an integrated circuit defined as an input or output pin, and controlled by the user at runtime.
MCU Micro Controller Unit is a small computer on a single integrated circuit containing a processor core, memory and programmable input/output peripherals.
NVIC The Nested Vectored Interrupt Controller (NVIC) is the interrupt controller of ARM Cortex-M.
RTS This UART pin is used to indicate if the device can receive data. It is used only when the UART hardware flow control is enabled.
RXD This UART pin is used for receiving data.
TX/RX Abbreviation of Transmit/Receive.
TXD This UART pin is used for sending data.
UART Universal Asynchronous Receiver/Transmitter is usually an individual (or part of an) integrated circuit (IC) used for serial communications over a micro-controller unit(MCU) or peripheral device serial port. For an introduction to UART, please refer to UART in Wikipedia .
VFIFO DMA Virtual First In First Out Direct Memory Access is a special DMA used to transfer data between memory and UART without MCU's handle.

Supported features

Software architecture of UART

How to use this driver

Functions

hal_uart_status_t hal_uart_init (hal_uart_port_t uart_port, hal_uart_config_t *uart_config)
 This function initializes the UART hardware with basic functionality. More...
 
hal_uart_status_t hal_uart_deinit (hal_uart_port_t uart_port)
 This function deinitializes the UART hardware to its default status. More...
 
void hal_uart_put_char (hal_uart_port_t uart_port, char byte)
 This function places one character at a time to the UART port in a poll mode. More...
 
char hal_uart_get_char (hal_uart_port_t uart_port)
 This function gets one character from UART port in a poll mode. More...
 
uint32_t hal_uart_send_polling (hal_uart_port_t uart_port, const uint8_t *data, uint32_t size)
 This function sends user data byte by byte in a poll mode. More...
 
uint32_t hal_uart_send_dma (hal_uart_port_t uart_port, const uint8_t *data, uint32_t size)
 This function sends user data in a VFIFO DMA mode. More...
 
uint32_t hal_uart_receive_polling (hal_uart_port_t uart_port, uint8_t *buffer, uint32_t size)
 This function receives data byte by byte in a poll mode. More...
 
uint32_t hal_uart_receive_dma (hal_uart_port_t uart_port, uint8_t *buffer, uint32_t size)
 This function receives user data in a VFIFO DMA mode. More...
 
uint32_t hal_uart_get_available_send_space (hal_uart_port_t uart_port)
 This function queries available space in the VFIFO TX buffer. More...
 
uint32_t hal_uart_get_available_receive_bytes (hal_uart_port_t uart_port)
 This function queries available data in the VFIFO RX buffer. More...
 
hal_uart_status_t hal_uart_register_callback (hal_uart_port_t uart_port, hal_uart_callback_t user_callback, void *user_data)
 This function registers user's callback in the UART driver. More...
 
hal_uart_status_t hal_uart_set_hardware_flowcontrol (hal_uart_port_t uart_port)
 This function sets and enables hardware flow control of the UART. More...
 
hal_uart_status_t hal_uart_set_software_flowcontrol (hal_uart_port_t uart_port, uint8_t xon, uint8_t xoff, uint8_t escape_character)
 This function sets and enables software flow control of the UART. More...
 
hal_uart_status_t hal_uart_disable_flowcontrol (hal_uart_port_t uart_port)
 This function disables flow control of the UART. More...
 
hal_uart_status_t hal_uart_set_baudrate (hal_uart_port_t uart_port, hal_uart_baudrate_t baudrate)
 This function sets a baud rate for the UART frame. More...
 
hal_uart_status_t hal_uart_set_format (hal_uart_port_t uart_port, const hal_uart_config_t *config)
 This function sets the UART's frame parameter. More...
 
hal_uart_status_t hal_uart_set_dma (hal_uart_port_t uart_port, const hal_uart_dma_config_t *dma_config)
 This function sets the VFIFO DMA hardware relative to the UART. More...
 
hal_uart_status_t hal_uart_set_dma_timeout (hal_uart_port_t uart_port, uint32_t timeout)
 This function sets timeout value for the UART VFIFO DMA. More...
 

Modules

 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_uart_status_t hal_uart_deinit ( hal_uart_port_t  uart_port)

This function deinitializes the UART hardware to its default status.

Parameters
[in]uart_portinitializes the specified UART port number.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
HAL_UART_STATUS_ERROR_UNINITIALIZED if UART has not been initialized.
Note
user must call this function when they don't use this UART port.
hal_uart_status_t hal_uart_disable_flowcontrol ( hal_uart_port_t  uart_port)

This function disables flow control of the UART.

It disables the UART hardware to notify about a peer flow control event by automatically activating or deactivating an RTS output. The UART hardware is disabled to detect flow control indicator from peer based on the CTS input pin. This function will also disable the software flow control.

Parameters
[in]uart_portinitializes the specified UART port number.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
HAL_UART_STATUS_ERROR_UNINITIALIZED if the UART has not been initialized.
uint32_t hal_uart_get_available_receive_bytes ( hal_uart_port_t  uart_port)

This function queries available data in the VFIFO RX buffer.

Parameters
[in]uart_portinitializes the specified UART port number.
Returns
Available data of the VFIFO RX buffer.
Note
This function is used only in DMA mode.
uint32_t hal_uart_get_available_send_space ( hal_uart_port_t  uart_port)

This function queries available space in the VFIFO TX buffer.

Parameters
[in]uart_portinitializes the specified UART port number.
Returns
Available space of the VFIFO TX buffer.
Note
This function is used only in a DMA mode.
char hal_uart_get_char ( hal_uart_port_t  uart_port)

This function gets one character from UART port in a poll mode.

In this function, driver first polls the status of a UART receive operation in a loop until it's ready. Then driver get the character from UART receive register and return it.

Parameters
[in]uart_portinitializes the specified UART port number.
Returns
the characters received from the UART port.
hal_uart_status_t hal_uart_init ( hal_uart_port_t  uart_port,
hal_uart_config_t uart_config 
)

This function initializes the UART hardware with basic functionality.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]uart_configspecifies configure parameters for UART hardware initialization.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_BUSY if the UART hardware has been initialized before.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
void hal_uart_put_char ( hal_uart_port_t  uart_port,
char  byte 
)

This function places one character at a time to the UART port in a poll mode.

In this function, driver first poll the status of UART transmit in a loop until it's ready. Then driver places the character in the UART transmit register and returns from this function.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]bytespecifies the data to send.
uint32_t hal_uart_receive_dma ( hal_uart_port_t  uart_port,
uint8_t *  buffer,
uint32_t  size 
)

This function receives user data in a VFIFO DMA mode.

In this function, driver first polls the available data in the VFIFO RX buffer. Then driver receives user data from the VFIFO RX buffer and places to the available free space. If the driver can't get all user data from VFIFO RX buffer, it will turn the VFIFO DMA RX interrupt on so that user is notified when VFIFO RX buffer becomes available again. At last, the driver returns the bytes that are received from the VFIFO RX buffer. User should check the outcome to make sure that data is completely received from the VFIFO RX buffer.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]bufferspecifies pointer to the user's data buffer.
[in]sizespecifies size of the user's data buffer.
Returns
the characters received from the UART port.
uint32_t hal_uart_receive_polling ( hal_uart_port_t  uart_port,
uint8_t *  buffer,
uint32_t  size 
)

This function receives data byte by byte in a poll mode.

In this function, driver first polls the status of a UART receive operation in a loop until it's ready. Then the driver gets the character from the UART transmit register and continues this operation until all user data is received. The final output is to get the character from the UART receive register and return it.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]bufferspecifies pointer to the user's data buffer.
[in]sizespecifies size of the user's data buffer.
Returns
the characters received from the UART port.
hal_uart_status_t hal_uart_register_callback ( hal_uart_port_t  uart_port,
hal_uart_callback_t  user_callback,
void *  user_data 
)

This function registers user's callback in the UART driver.

This callback is used when the UART operates in a VFIFO DMA mode, then notifies the user if the UART Transmit is ready again. Also this callback is called in the UART VFIFO DMA interrupt handler.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]user_callbackspecifies user's callback
[in]user_dataspecifies user's data for this callback
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_BUSY if the UART port has been registered by others before.
HAL_UART_STATUS_ERROR_UNINITIALIZED if the UART has not been initialized.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
uint32_t hal_uart_send_dma ( hal_uart_port_t  uart_port,
const uint8_t *  data,
uint32_t  size 
)

This function sends user data in a VFIFO DMA mode.

In this function, driver first polls the free space in the VFIFO TX buffer. Then driver puts user data into the VFIFO TX buffer, that fits into the free space. If driver can't put all user data into VFIFO TX buffer, it will turn the VFIFO DMA TX interrupt on so that user is notified when VFIFO TX buffer becomes available again. At last, the driver returns the bytes that are placed in the VFIFO TX buffer. User should check the outcome to make sure that data is completely placed in the VFIFO TX buffer.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]dataspecifies pointer to the user's data buffer.
[in]sizespecifies size of the user's data buffer.
Returns
bytes of transmitted data.
Note
User must call hal_uart_init() before calling this function.
uint32_t hal_uart_send_polling ( hal_uart_port_t  uart_port,
const uint8_t *  data,
uint32_t  size 
)

This function sends user data byte by byte in a poll mode.

In this function, driver first poll status of UART transmit in a loop until it's ready. Then driver put the character into UART transmit register. Driver continues this operation until all user data is sent out, then it returns the transmitted bytes.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]dataspecifies pointer to the user's data buffer.
[in]sizespecifies size of the user's data buffer.
Returns
bytes of transmitted data.
hal_uart_status_t hal_uart_set_baudrate ( hal_uart_port_t  uart_port,
hal_uart_baudrate_t  baudrate 
)

This function sets a baud rate for the UART frame.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]baudratespecifies baud rate for the UART frame.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
HAL_UART_STATUS_ERROR_UNINITIALIZED if the UART has not been initialized.
Example
1 hal_uart_set_baudrate(HAL_UART_0, HAL_UART_BAUDRATE_115200);
hal_uart_status_t hal_uart_set_dma ( hal_uart_port_t  uart_port,
const hal_uart_dma_config_t dma_config 
)

This function sets the VFIFO DMA hardware relative to the UART.

With the help of the VFIFO DMA hardware, MCU doesn't need to copy data between the user buffer and the UART FIFO byte by byte. The MCU will be open to other tasks while the VFIFO DMA is copying data. The user is required to set threshold, address and size of the VFIFO TX/RX buffer for its proper operation.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]dma_configspecifies a user defined VFIFO DMA configuration parameter.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
HAL_UART_STATUS_ERROR_UNINITIALIZED if UART has not been initialized.
Note
This function must be called after hal_uart_init().
hal_uart_status_t hal_uart_set_dma_timeout ( hal_uart_port_t  uart_port,
uint32_t  timeout 
)

This function sets timeout value for the UART VFIFO DMA.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]timeoutspecifies time out value for UART VFIFO DMA. The unit is us.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
HAL_UART_STATUS_ERROR_UNINITIALIZED if the UART has not been initialized.
Example
1 hal_uart_set_dma_timeout(HAL_UART_0, 100); // set time out of VFIFO DMA to 100us.
hal_uart_status_t hal_uart_set_format ( hal_uart_port_t  uart_port,
const hal_uart_config_t config 
)

This function sets the UART's frame parameter.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]configspecifies a user defined frame parameter.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
HAL_UART_STATUS_ERROR_UNINITIALIZED if the UART has not been initialized.
Example
1 hal_uart_config_t uart_config;
2 
3 uart_config.baudrate = HAL_UART_BAUDRATE_921600;
4 uart_config.parity = HAL_UART_PARITY_NONE;
5 uart_config.stop_bit = HAL_UART_STOP_BIT_1;
6 uart_config.word_length = HAL_UART_WORD_LENGTH_8;
7 
8 hal_uart_set_format(HAL_UART_0, &uart_config);
hal_uart_status_t hal_uart_set_hardware_flowcontrol ( hal_uart_port_t  uart_port)

This function sets and enables hardware flow control of the UART.

It enables the UART hardware to notify about a peer flow control event by automatically activating or deactivating an RTS output. Also the UART hardware can detect flow control indicator from peer based on the CTS input pin. For both RTS and CTS events, the UART hardware triggers interrupts.

Parameters
[in]uart_portinitializes the specified UART port number.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
HAL_UART_STATUS_ERROR_UNINITIALIZED if the UART has not been initialized.
hal_uart_status_t hal_uart_set_software_flowcontrol ( hal_uart_port_t  uart_port,
uint8_t  xon,
uint8_t  xoff,
uint8_t  escape_character 
)

This function sets and enables software flow control of the UART.

It enables the UART hardware to notify about a peer flow control event by sending an automatic XON or XOFF output. Also the UART hardware can issue flow control events if it receives XON or XOFF characters. For both transmit and receive operations, the UART hardware triggers interrupts. For transmit operation, escape characters are inserted before XON, XOFF and itself. For receive operation, if the UART hardware receives an escape character, it then reverses the consecutive byte and places it in the receive FIFO.

Parameters
[in]uart_portinitializes the specified UART port number.
[in]xonspecifies user defined XON character that indicates if the data transmission is turned on.
[in]xoffspecifies user defined XOFF character that indicates if the data transmission is turned off.
[in]escape_characterspecifies a user defined escape character.
Returns
HAL_UART_STATUS_OK if OK.
HAL_UART_STATUS_ERROR_PARAMETER if parameter is invalid.
HAL_UART_STATUS_ERROR_UNINITIALIZED if the UART has not been initialized.
Example
1 uint8_t xon = 0x01;
2 uint8_t xoff = 0x02;
3 uint8_t escape_character = 0x77;
4 
5 hal_uart_set_software_flowcontrol(HAL_UART_0, xon, xoff, escape_character);