MCUXpresso SDK API Reference Manual: UART Driver

| MCUXpresso SDK API Reference Manual Rev 2.11.1 NXP Semiconductors

- Main Page
- Related Pages
- API Reference

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
UART Driver
UART: Universal Asynchronous Receiver/Transmitter Driver

## Overview

The MCUXpresso SDK provides a peripheral driver for the Universal Asynchronous Receiver/Transmitter (UART) module of MCUXpresso SDK devices.

The UART driver includes functional APIs and transactional APIs.

Functional APIs are used for UART initialization/configuration/operation for the purpose of optimization/customization. Using the functional API requires the knowledge of the UART peripheral and how to organize functional APIs to meet the application requirements. All functional APIs use the peripheral base address as the first parameter. UART functional operation groups provide the functional API set.

Transactional APIs can be used to enable the peripheral quickly and in the application if the code size and performance of transactional APIs can satisfy the requirements. If the code size and performance are critical requirements, see the transactional API implementation and write custom code. All transactional APIs use the uart_handle_t as the second parameter. Initialize the handle by calling the UART_TransferCreateHandle() API.

Transactional APIs support asynchronous transfer, which means that the functions UART_TransferSendNonBlocking() and UART_TransferReceiveNonBlocking() set up an interrupt for data transfer. When the transfer completes, the upper layer is notified through a callback function with the kStatus_UART_TxIdle and kStatus_UART_RxIdle.

Transactional receive APIs support the ring buffer. Prepare the memory for the ring buffer and pass in the start address and size while calling the UART_TransferCreateHandle(). If passing NULL, the ring buffer feature is disabled. When the ring buffer is enabled, the received data is saved to the ring buffer in the background. The UART_TransferReceiveNonBlocking() function first gets data from the ring buffer. If the ring buffer does not have enough data, the function first returns the data in the ring buffer and then saves the received data to user memory. When all data is received, the upper layer is informed through a callback with the kStatus_UART_RxIdle.

If the receive ring buffer is full, the upper layer is informed through a callback with the kStatus_UART_RxRingBufferOverrun. In the callback function, the upper layer reads data out from the ring buffer. If not, existing data is overwritten by the new data.

The ring buffer size is specified when creating the handle. Note that one byte is reserved for the ring buffer maintenance. When creating handle using the following code.

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/uart In this example, the buffer size is 32, but only 31 bytes are used for saving data.

# Typical use case

## UART Send/receive using a polling method

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/uart

## UART Send/receive using an interrupt method

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/uart

## UART Receive using the ringbuffer feature

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/uart

## UART automatic baud rate detect feature

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/uart

## Data Structures
struct | uart_config_t
| UART configuration structure. More...
struct | uart_transfer_t
| UART transfer structure. More...
struct | uart_handle_t
| UART handle structure. More...

## Macros
#define | UART_RETRY_TIMES 0U /* Defining to zero means to keep waiting for the flag until it is assert/deassert. */
| Retry times for waiting flag. More...

## Typedefs
typedef void(* | uart_transfer_callback_t )(UART_Type *base, uart_handle_t *handle, status_t status, void *userData)
| UART transfer callback function. More...

## Enumerations
enum | { kStatus_UART_TxBusy = MAKE_STATUS(kStatusGroup_IUART, 0), kStatus_UART_RxBusy = MAKE_STATUS(kStatusGroup_IUART, 1), kStatus_UART_TxIdle = MAKE_STATUS(kStatusGroup_IUART, 2), kStatus_UART_RxIdle = MAKE_STATUS(kStatusGroup_IUART, 3), kStatus_UART_TxWatermarkTooLarge = MAKE_STATUS(kStatusGroup_IUART, 4), kStatus_UART_RxWatermarkTooLarge = MAKE_STATUS(kStatusGroup_IUART, 5), kStatus_UART_FlagCannotClearManually, kStatus_UART_Error = MAKE_STATUS(kStatusGroup_IUART, 7), kStatus_UART_RxRingBufferOverrun = MAKE_STATUS(kStatusGroup_IUART, 8), kStatus_UART_RxHardwareOverrun = MAKE_STATUS(kStatusGroup_IUART, 9), kStatus_UART_NoiseError = MAKE_STATUS(kStatusGroup_IUART, 10), kStatus_UART_FramingError = MAKE_STATUS(kStatusGroup_IUART, 11), kStatus_UART_ParityError = MAKE_STATUS(kStatusGroup_IUART, 12), kStatus_UART_BaudrateNotSupport, kStatus_UART_BreakDetect = MAKE_STATUS(kStatusGroup_IUART, 14), kStatus_UART_Timeout = MAKE_STATUS(kStatusGroup_IUART, 15) }
| Error codes for the UART driver. More...
enum | uart_data_bits_t { kUART_SevenDataBits = 0x0U, kUART_EightDataBits = 0x1U }
| UART data bits count. More...
enum | uart_parity_mode_t { kUART_ParityDisabled = 0x0U, kUART_ParityEven = 0x2U, kUART_ParityOdd = 0x3U }
| UART parity mode. More...
enum | uart_stop_bit_count_t { kUART_OneStopBit = 0x0U, kUART_TwoStopBit = 0x1U }
| UART stop bit count. More...
enum | uart_idle_condition_t { kUART_IdleFor4Frames = 0x0U, kUART_IdleFor8Frames = 0x1U, kUART_IdleFor16Frames = 0x2U, kUART_IdleFor32Frames = 0x3U }
| UART idle condition detect. More...
enum | _uart_interrupt_enable
| This structure contains the settings for all of the UART interrupt configurations. More...
enum | { kUART_RxCharReadyFlag = 0x0000000FU, kUART_RxErrorFlag = 0x0000000EU, kUART_RxOverrunErrorFlag = 0x0000000DU, kUART_RxFrameErrorFlag = 0x0000000CU, kUART_RxBreakDetectFlag = 0x0000000BU, kUART_RxParityErrorFlag = 0x0000000AU, kUART_ParityErrorFlag = 0x0094000FU, kUART_RtsStatusFlag = 0x0094000EU, kUART_TxReadyFlag = 0x0094000DU, kUART_RtsDeltaFlag = 0x0094000CU, kUART_EscapeFlag = 0x0094000BU, kUART_FrameErrorFlag = 0x0094000AU, kUART_RxReadyFlag = 0x00940009U, kUART_AgingTimerFlag = 0x00940008U, kUART_DtrDeltaFlag = 0x00940007U, kUART_RxDsFlag = 0x00940006U, kUART_tAirWakeFlag = 0x00940005U, kUART_AwakeFlag = 0x00940004U, kUART_Rs485SlaveAddrMatchFlag = 0x00940003U, kUART_AutoBaudFlag = 0x0098000FU, kUART_TxEmptyFlag = 0x0098000EU, kUART_DtrFlag = 0x0098000DU, kUART_IdleFlag = 0x0098000CU, kUART_AutoBaudCntStopFlag = 0x0098000BU, kUART_RiDeltaFlag = 0x0098000AU, kUART_RiFlag = 0x00980009U, kUART_IrFlag = 0x00980008U, kUART_WakeFlag = 0x00980007U, kUART_DcdDeltaFlag = 0x00980006U, kUART_DcdFlag = 0x00980005U, kUART_RtsFlag = 0x00980004U, kUART_TxCompleteFlag = 0x00980003U, kUART_BreakDetectFlag = 0x00980002U, kUART_RxOverrunFlag = 0x00980001U, kUART_RxDataReadyFlag = 0x00980000U }
| UART status flags. More...

## Functions
uint32_t | UART_GetInstance (UART_Type *base)
| Get the UART instance from peripheral base address. More...

## Variables
void * | s_uartHandle []
| Pointers to uart handles for each instance. More...

## Driver version
#define | FSL_UART_DRIVER_VERSION (MAKE_VERSION(2, 3, 1))
| UART driver version. More...

## Software Reset
static void | UART_SoftwareReset (UART_Type *base)
| Resets the UART using software. More...

## Initialization and deinitialization
status_t | UART_Init (UART_Type *base, const uart_config_t *config, uint32_t srcClock_Hz)
| Initializes an UART instance with the user configuration structure and the peripheral clock. More...
void | UART_Deinit (UART_Type *base)
| Deinitializes a UART instance. More...
void | UART_GetDefaultConfig (uart_config_t *config)
| l More...
status_t | UART_SetBaudRate (UART_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz)
| Sets the UART instance baud rate. More...
static void | UART_Enable (UART_Type *base)
| This function is used to Enable the UART Module. More...
static void | UART_SetIdleCondition (UART_Type *base, uart_idle_condition_t condition)
| This function is used to configure the IDLE line condition. More...
static void | UART_Disable (UART_Type *base)
| This function is used to Disable the UART Module. More...

## Status
bool | UART_GetStatusFlag (UART_Type *base, uint32_t flag)
| This function is used to get the current status of specific UART status flag(including interrupt flag). More...
void | UART_ClearStatusFlag (UART_Type *base, uint32_t flag)
| This function is used to clear the current status of specific UART status flag. More...

## Interrupts
void | UART_EnableInterrupts (UART_Type *base, uint32_t mask)
| Enables UART interrupts according to the provided mask. More...
void | UART_DisableInterrupts (UART_Type *base, uint32_t mask)
| Disables the UART interrupts according to the provided mask. More...
uint32_t | UART_GetEnabledInterrupts (UART_Type *base)
| Gets enabled UART interrupts. More...

## Bus Operations
static void | UART_EnableTx (UART_Type *base, bool enable)
| Enables or disables the UART transmitter. More...
static void | UART_EnableRx (UART_Type *base, bool enable)
| Enables or disables the UART receiver. More...
static void | UART_WriteByte (UART_Type *base, uint8_t data)
| Writes to the transmitter register. More...
static uint8_t | UART_ReadByte (UART_Type *base)
| Reads the receiver register. More...
status_t | UART_WriteBlocking (UART_Type *base, const uint8_t *data, size_t length)
| Writes to the TX register using a blocking method. More...
status_t | UART_ReadBlocking (UART_Type *base, uint8_t *data, size_t length)
| Read RX data register using a blocking method. More...

## Transactional
void | UART_TransferCreateHandle (UART_Type *base, uart_handle_t *handle, uart_transfer_callback_t callback, void *userData)
| Initializes the UART handle. More...
void | UART_TransferStartRingBuffer (UART_Type *base, uart_handle_t *handle, uint8_t *ringBuffer, size_t ringBufferSize)
| Sets up the RX ring buffer. More...
void | UART_TransferStopRingBuffer (UART_Type *base, uart_handle_t *handle)
| Aborts the background transfer and uninstalls the ring buffer. More...
size_t | UART_TransferGetRxRingBufferLength (uart_handle_t *handle)
| Get the length of received data in RX ring buffer. More...
status_t | UART_TransferSendNonBlocking (UART_Type *base, uart_handle_t *handle, uart_transfer_t *xfer)
| Transmits a buffer of data using the interrupt method. More...
void | UART_TransferAbortSend (UART_Type *base, uart_handle_t *handle)
| Aborts the interrupt-driven data transmit. More...
status_t | UART_TransferGetSendCount (UART_Type *base, uart_handle_t *handle, uint32_t *count)
| Gets the number of bytes written to the UART TX register. More...
status_t | UART_TransferReceiveNonBlocking (UART_Type *base, uart_handle_t *handle, uart_transfer_t *xfer, size_t *receivedBytes)
| Receives a buffer of data using an interrupt method. More...
void | UART_TransferAbortReceive (UART_Type *base, uart_handle_t *handle)
| Aborts the interrupt-driven data receiving. More...
status_t | UART_TransferGetReceiveCount (UART_Type *base, uart_handle_t *handle, uint32_t *count)
| Gets the number of bytes that have been received. More...
void | UART_TransferHandleIRQ (UART_Type *base, void *irqHandle)
| UART IRQ handle function. More...

## DMA control functions.
static void | UART_EnableTxDMA (UART_Type *base, bool enable)
| Enables or disables the UART transmitter DMA request. More...
static void | UART_EnableRxDMA (UART_Type *base, bool enable)
| Enables or disables the UART receiver DMA request. More...

## FIFO control functions.
static void | UART_SetTxFifoWatermark (UART_Type *base, uint8_t watermark)
| This function is used to set the watermark of UART Tx FIFO. More...
static void | UART_SetRxRTSWatermark (UART_Type *base, uint8_t watermark)
| This function is used to set the watermark of UART RTS deassertion. More...
static void | UART_SetRxFifoWatermark (UART_Type *base, uint8_t watermark)
| This function is used to set the watermark of UART Rx FIFO. More...

## Auto baud rate detection.
static void | UART_EnableAutoBaudRate (UART_Type *base, bool enable)
| This function is used to set the enable condition of Automatic Baud Rate Detection feature. More...
static bool | UART_IsAutoBaudRateComplete (UART_Type *base)
| This function is used to read if the automatic baud rate detection has finished. More...

## Data Structure Documentation

struct uart_config_t

### Data Fields
uint32_t | baudRate_Bps
| UART baud rate. More...
uart_parity_mode_t | parityMode
| Parity error check mode of this module. More...
uart_data_bits_t | dataBitsCount
| Data bits count, eight (default), seven.
uart_stop_bit_count_t | stopBitCount
| Number of stop bits in one frame. More...
uint8_t | txFifoWatermark
| TX FIFO watermark.
uint8_t | rxFifoWatermark
| RX FIFO watermark.
uint8_t | rxRTSWatermark
| RX RTS watermark, RX FIFO data count being larger than this triggers RTS deassertion.
bool | enableAutoBaudRate
| Enable automatic baud rate detection.
bool | enableTx
| Enable TX.
bool | enableRx
| Enable RX.
bool | enableRxRTS
| RX RTS enable.
bool | enableTxCTS
| TX CTS enable.

#### Field Documentation

uint32_t uart_config_t::baudRate_Bps

uart_parity_mode_t uart_config_t::parityMode

uart_stop_bit_count_t uart_config_t::stopBitCount

struct uart_transfer_t

### Data Fields
size_t | dataSize
| The byte count to be transfer. More...
uint8_t * | data
| The buffer of data to be transfer. More...
uint8_t * | rxData
| The buffer to receive data. More...
const uint8_t * | txData
| The buffer of data to be sent. More...

#### Field Documentation

uint8_t* uart_transfer_t::data

uint8_t* uart_transfer_t::rxData

const uint8_t* uart_transfer_t::txData

size_t uart_transfer_t::dataSize

struct _uart_handle

Forward declaration of the handle typedef.

### Data Fields
const uint8_t *volatile | txData
| Address of remaining data to send. More...
volatile size_t | txDataSize
| Size of the remaining data to send. More...
size_t | txDataSizeAll
| Size of the data to send out. More...
uint8_t *volatile | rxData
| Address of remaining data to receive. More...
volatile size_t | rxDataSize
| Size of the remaining data to receive. More...
size_t | rxDataSizeAll
| Size of the data to receive. More...
uint8_t * | rxRingBuffer
| Start address of the receiver ring buffer. More...
size_t | rxRingBufferSize
| Size of the ring buffer. More...
volatile uint16_t | rxRingBufferHead
| Index for the driver to store received data into ring buffer. More...
volatile uint16_t | rxRingBufferTail
| Index for the user to get data from the ring buffer. More...
uart_transfer_callback_t | callback
| Callback function. More...
void * | userData
| UART callback function parameter. More...
volatile uint8_t | txState
| TX transfer state. More...
volatile uint8_t | rxState
| RX transfer state.

#### Field Documentation

const uint8_t* volatile uart_handle_t::txData

volatile size_t uart_handle_t::txDataSize

size_t uart_handle_t::txDataSizeAll

uint8_t* volatile uart_handle_t::rxData

volatile size_t uart_handle_t::rxDataSize

size_t uart_handle_t::rxDataSizeAll

uint8_t* uart_handle_t::rxRingBuffer

size_t uart_handle_t::rxRingBufferSize

volatile uint16_t uart_handle_t::rxRingBufferHead

volatile uint16_t uart_handle_t::rxRingBufferTail

uart_transfer_callback_t uart_handle_t::callback

void* uart_handle_t::userData

volatile uint8_t uart_handle_t::txState

## Macro Definition Documentation

#define FSL_UART_DRIVER_VERSION (MAKE_VERSION(2, 3, 1))

#define UART_RETRY_TIMES 0U /* Defining to zero means to keep waiting for the flag until it is assert/deassert. */

## Typedef Documentation

typedef void(* uart_transfer_callback_t)(UART_Type *base, uart_handle_t *handle, status_t status, void *userData)

## Enumeration Type Documentation

anonymous enum

Enumerator
kStatus_UART_TxBusy | Transmitter is busy.
kStatus_UART_RxBusy | Receiver is busy.
kStatus_UART_TxIdle | UART transmitter is idle.
kStatus_UART_RxIdle | UART receiver is idle.
kStatus_UART_TxWatermarkTooLarge | TX FIFO watermark too large.
kStatus_UART_RxWatermarkTooLarge | RX FIFO watermark too large.
kStatus_UART_FlagCannotClearManually | UART flag can't be manually cleared.
kStatus_UART_Error | Error happens on UART.
kStatus_UART_RxRingBufferOverrun | UART RX software ring buffer overrun.
kStatus_UART_RxHardwareOverrun | UART RX receiver overrun.
kStatus_UART_NoiseError | UART noise error.
kStatus_UART_FramingError | UART framing error.
kStatus_UART_ParityError | UART parity error.
kStatus_UART_BaudrateNotSupport | Baudrate is not support in current clock source.
kStatus_UART_BreakDetect | Receiver detect BREAK signal.
kStatus_UART_Timeout | UART times out.

enum uart_data_bits_t

Enumerator
kUART_SevenDataBits | Seven data bit.
kUART_EightDataBits | Eight data bit.

enum uart_parity_mode_t

Enumerator
kUART_ParityDisabled | Parity disabled.
kUART_ParityEven | Even error check is selected.
kUART_ParityOdd | Odd error check is selected.

enum uart_stop_bit_count_t

Enumerator
kUART_OneStopBit | One stop bit.
kUART_TwoStopBit | Two stop bits.

enum uart_idle_condition_t

Enumerator
kUART_IdleFor4Frames | Idle for more than 4 frames.
kUART_IdleFor8Frames | Idle for more than 8 frames.
kUART_IdleFor16Frames | Idle for more than 16 frames.
kUART_IdleFor32Frames | Idle for more than 32 frames.

enum _uart_interrupt_enable

anonymous enum

This provides constants for the UART status flags for use in the UART functions.

Enumerator
kUART_RxCharReadyFlag | Rx Character Ready Flag.
kUART_RxErrorFlag | Rx Error Detect Flag.
kUART_RxOverrunErrorFlag | Rx Overrun Flag.
kUART_RxFrameErrorFlag | Rx Frame Error Flag.
kUART_RxBreakDetectFlag | Rx Break Detect Flag.
kUART_RxParityErrorFlag | Rx Parity Error Flag.
kUART_ParityErrorFlag | Parity Error Interrupt Flag.
kUART_RtsStatusFlag | RTS_B Pin Status Flag.
kUART_TxReadyFlag | Transmitter Ready Interrupt/DMA Flag.
kUART_RtsDeltaFlag | RTS Delta Flag.
kUART_EscapeFlag | Escape Sequence Interrupt Flag.
kUART_FrameErrorFlag | Frame Error Interrupt Flag.
kUART_RxReadyFlag | Receiver Ready Interrupt/DMA Flag.
kUART_AgingTimerFlag | Aging Timer Interrupt Flag.
kUART_DtrDeltaFlag | DTR Delta Flag.
kUART_RxDsFlag | Receiver IDLE Interrupt Flag.
kUART_tAirWakeFlag | Asynchronous IR WAKE Interrupt Flag.
kUART_AwakeFlag | Asynchronous WAKE Interrupt Flag.
kUART_Rs485SlaveAddrMatchFlag | RS-485 Slave Address Detected Interrupt Flag.
kUART_AutoBaudFlag | Automatic Baud Rate Detect Complete Flag.
kUART_TxEmptyFlag | Transmit Buffer FIFO Empty.
kUART_DtrFlag | DTR edge triggered interrupt flag.
kUART_IdleFlag | Idle Condition Flag.
kUART_AutoBaudCntStopFlag | Auto-baud Counter Stopped Flag.
kUART_RiDeltaFlag | Ring Indicator Delta Flag.
kUART_RiFlag | Ring Indicator Input Flag.
kUART_IrFlag | Serial Infrared Interrupt Flag.
kUART_WakeFlag | Wake Flag.
kUART_DcdDeltaFlag | Data Carrier Detect Delta Flag.
kUART_DcdFlag | Data Carrier Detect Input Flag.
kUART_RtsFlag | RTS Edge Triggered Interrupt Flag.
kUART_TxCompleteFlag | Transmitter Complete Flag.
kUART_BreakDetectFlag | BREAK Condition Detected Flag.
kUART_RxOverrunFlag | Overrun Error Flag.
kUART_RxDataReadyFlag | Receive Data Ready Flag.

## Function Documentation

uint32_t UART_GetInstance | ( | UART_Type * | base | ) |

Parameters

  base | UART peripheral base address.

Returns
  UART instance.

static void UART_SoftwareReset | ( | UART_Type * | base | ) |
| inlinestatic

This function resets the transmit and receive state machines, all FIFOs and register USR1, USR2, UBIR, UBMR, UBRC , URXD, UTXD and UTS[6-3]

Parameters

  base | UART peripheral base address.

status_t UART_Init | ( | UART_Type * | base,
|  | const uart_config_t * | config,
|  | uint32_t | srcClock_Hz
| ) |  |

This function configures the UART module with user-defined settings. Call the UART_GetDefaultConfig() function to configure the configuration structure and get the default configuration. The example below shows how to use this API to configure the UART.

* uart_config_t uartConfig;
* uartConfig.baudRate_Bps = 115200U;
* uartConfig.parityMode = kUART_ParityDisabled;
* uartConfig.dataBitsCount = kUART_EightDataBits;
* uartConfig.stopBitCount = kUART_OneStopBit;
* uartConfig.txFifoWatermark = 2;
* uartConfig.rxFifoWatermark = 1;
* uartConfig.enableAutoBaudrate = false;
* uartConfig.enableTx = true;
* uartConfig.enableRx = true;
* UART_Init(UART1, &uartConfig, 24000000U);
*

Parameters

  base | UART peripheral base address.
  config | Pointer to a user-defined configuration structure.
  srcClock_Hz | UART clock source frequency in HZ.

Return values

  kStatus_Success | UART initialize succeed

void UART_Deinit | ( | UART_Type * | base | ) |

This function waits for transmit to complete, disables TX and RX, and disables the UART clock.

Parameters

  base | UART peripheral base address.

void UART_GetDefaultConfig | ( | uart_config_t * | config | ) |

Gets the default configuration structure.

This function initializes the UART configuration structure to a default value. The default values are: uartConfig->baudRate_Bps = 115200U; uartConfig->parityMode = kUART_ParityDisabled; uartConfig->dataBitsCount = kUART_EightDataBits; uartConfig->stopBitCount = kUART_OneStopBit; uartConfig->txFifoWatermark = 2; uartConfig->rxFifoWatermark = 1; uartConfig->enableAutoBaudrate = flase; uartConfig->enableTx = false; uartConfig->enableRx = false;

Parameters

  config | Pointer to a configuration structure.

status_t UART_SetBaudRate | ( | UART_Type * | base,
|  | uint32_t | baudRate_Bps,
|  | uint32_t | srcClock_Hz
| ) |  |

This function configures the UART module baud rate. This function is used to update the UART module baud rate after the UART module is initialized by the UART_Init.

* UART_SetBaudRate(UART1, 115200U, 20000000U);
*

Parameters

  base | UART peripheral base address.
  baudRate_Bps | UART baudrate to be set.
  srcClock_Hz | UART clock source frequency in Hz.

Return values

  kStatus_UART_BaudrateNotSupport | Baudrate is not support in the current clock source.
  kStatus_Success | Set baudrate succeeded.

static void UART_Enable | ( | UART_Type * | base | ) |
| inlinestatic

Parameters

  base | UART base pointer.

static void UART_SetIdleCondition | ( | UART_Type * | base,
|  | uart_idle_condition_t | condition
| ) |  |
| inlinestatic

Parameters

  base | UART base pointer.
  condition | IDLE line detect condition of the enumerators in uart_idle_condition_t.

static void UART_Disable | ( | UART_Type * | base | ) |
| inlinestatic

Parameters

  base | UART base pointer.

bool UART_GetStatusFlag | ( | UART_Type * | base,
|  | uint32_t | flag
| ) |  |

The available status flag can be select from uart_status_flag_t enumeration.

Parameters

  base | UART base pointer.
  flag | Status flag to check.

Return values

  current | state of corresponding status flag.

void UART_ClearStatusFlag | ( | UART_Type * | base,
|  | uint32_t | flag
| ) |  |

The available status flag can be select from uart_status_flag_t enumeration.

Parameters

  base | UART base pointer.
  flag | Status flag to clear.

void UART_EnableInterrupts | ( | UART_Type * | base,
|  | uint32_t | mask
| ) |  |

This function enables the UART interrupts according to the provided mask. The mask is a logical OR of enumeration members. See _uart_interrupt_enable. For example, to enable TX empty interrupt and RX data ready interrupt, do the following.

* UART_EnableInterrupts(UART1,kUART_TxEmptyEnable | kUART_RxDataReadyEnable);
*

Parameters

  base | UART peripheral base address.
  mask | The interrupts to enable. Logical OR of _uart_interrupt_enable.

void UART_DisableInterrupts | ( | UART_Type * | base,
|  | uint32_t | mask
| ) |  |

This function disables the UART interrupts according to the provided mask. The mask is a logical OR of enumeration members. See _uart_interrupt_enable. For example, to disable TX empty interrupt and RX data ready interrupt do the following.

* UART_EnableInterrupts(UART1,kUART_TxEmptyEnable | kUART_RxDataReadyEnable);
*

Parameters

  base | UART peripheral base address.
  mask | The interrupts to disable. Logical OR of _uart_interrupt_enable.

uint32_t UART_GetEnabledInterrupts | ( | UART_Type * | base | ) |

This function gets the enabled UART interrupts. The enabled interrupts are returned as the logical OR value of the enumerators _uart_interrupt_enable. To check a specific interrupt enable status, compare the return value with enumerators in _uart_interrupt_enable. For example, to check whether the TX empty interrupt is enabled:

* uint32_t enabledInterrupts = UART_GetEnabledInterrupts(UART1);
*
* if (kUART_TxEmptyEnable & enabledInterrupts)
* {
* ...
* }
*

Parameters

  base | UART peripheral base address.

Returns
  UART interrupt flags which are logical OR of the enumerators in _uart_interrupt_enable.

static void UART_EnableTx | ( | UART_Type * | base,
|  | bool | enable
| ) |  |
| inlinestatic

This function enables or disables the UART transmitter.

Parameters

  base | UART peripheral base address.
  enable | True to enable, false to disable.

static void UART_EnableRx | ( | UART_Type * | base,
|  | bool | enable
| ) |  |
| inlinestatic

This function enables or disables the UART receiver.

Parameters

  base | UART peripheral base address.
  enable | True to enable, false to disable.

static void UART_WriteByte | ( | UART_Type * | base,
|  | uint8_t | data
| ) |  |
| inlinestatic

This function is used to write data to transmitter register. The upper layer must ensure that the TX register is empty or that the TX FIFO has room before calling this function.

Parameters

  base | UART peripheral base address.
  data | Data write to the TX register.

static uint8_t UART_ReadByte | ( | UART_Type * | base | ) |
| inlinestatic

This function is used to read data from receiver register. The upper layer must ensure that the receiver register is full or that the RX FIFO has data before calling this function.

Parameters

  base | UART peripheral base address.

Returns
  Data read from data register.

status_t UART_WriteBlocking | ( | UART_Type * | base,
|  | const uint8_t * | data,
|  | size_t | length
| ) |  |

This function polls the TX register, waits for the TX register to be empty or for the TX FIFO to have room and writes data to the TX buffer.

Parameters

  base | UART peripheral base address.
  data | Start address of the data to write.
  length | Size of the data to write.

Return values

  kStatus_UART_Timeout | Transmission timed out and was aborted.
  kStatus_Success | Successfully wrote all data.

status_t UART_ReadBlocking | ( | UART_Type * | base,
|  | uint8_t * | data,
|  | size_t | length
| ) |  |

This function polls the RX register, waits for the RX register to be full or for RX FIFO to have data, and reads data from the TX register.

Parameters

  base | UART peripheral base address.
  data | Start address of the buffer to store the received data.
  length | Size of the buffer.

Return values

  kStatus_UART_RxHardwareOverrun | Receiver overrun occurred while receiving data.
  kStatus_UART_NoiseError | A noise error occurred while receiving data.
  kStatus_UART_FramingError | A framing error occurred while receiving data.
  kStatus_UART_ParityError | A parity error occurred while receiving data.
  kStatus_UART_Timeout | Transmission timed out and was aborted.
  kStatus_Success | Successfully received all data.

void UART_TransferCreateHandle | ( | UART_Type * | base,
|  | uart_handle_t * | handle,
|  | uart_transfer_callback_t | callback,
|  | void * | userData
| ) |  |

This function initializes the UART handle which can be used for other UART transactional APIs. Usually, for a specified UART instance, call this API once to get the initialized handle.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.
  callback | The callback function.
  userData | The parameter of the callback function.

void UART_TransferStartRingBuffer | ( | UART_Type * | base,
|  | uart_handle_t * | handle,
|  | uint8_t * | ringBuffer,
|  | size_t | ringBufferSize
| ) |  |

This function sets up the RX ring buffer to a specific UART handle.

When the RX ring buffer is used, data received are stored into the ring buffer even when the user doesn't call the UART_TransferReceiveNonBlocking() API. If data is already received in the ring buffer, the user can get the received data from the ring buffer directly.

Note
  When using the RX ring buffer, one byte is reserved for internal use. In other words, if `ringBufferSize` is 32, only 31 bytes are used for saving data.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.
  ringBuffer | Start address of the ring buffer for background receiving. Pass NULL to disable the ring buffer.
  ringBufferSize | Size of the ring buffer.

void UART_TransferStopRingBuffer | ( | UART_Type * | base,
|  | uart_handle_t * | handle
| ) |  |

This function aborts the background transfer and uninstalls the ring buffer.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.

size_t UART_TransferGetRxRingBufferLength | ( | uart_handle_t * | handle | ) |

Parameters

  handle | UART handle pointer.

Returns
  Length of received data in RX ring buffer.

status_t UART_TransferSendNonBlocking | ( | UART_Type * | base,
|  | uart_handle_t * | handle,
|  | uart_transfer_t * | xfer
| ) |  |

This function sends data using an interrupt method. This is a non-blocking function, which returns directly without waiting for all data to be written to the TX register. When all data is written to the TX register in the ISR, the UART driver calls the callback function and passes the kStatus_UART_TxIdle as status parameter.

Note
  The kStatus_UART_TxIdle is passed to the upper layer when all data is written to the TX register. However, it does not ensure that all data is sent out. Before disabling the TX, check the kUART_TransmissionCompleteFlag to ensure that the TX is finished.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.
  xfer | UART transfer structure. See uart_transfer_t.

Return values

  kStatus_Success | Successfully start the data transmission.
  kStatus_UART_TxBusy | Previous transmission still not finished; data not all written to TX register yet.
  kStatus_InvalidArgument | Invalid argument.

void UART_TransferAbortSend | ( | UART_Type * | base,
|  | uart_handle_t * | handle
| ) |  |

This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out how many bytes are not sent out.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.

status_t UART_TransferGetSendCount | ( | UART_Type * | base,
|  | uart_handle_t * | handle,
|  | uint32_t * | count
| ) |  |

This function gets the number of bytes written to the UART TX register by using the interrupt method.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.
  count | Send bytes count.

Return values

  kStatus_NoTransferInProgress | No send in progress.
  kStatus_InvalidArgument | The parameter is invalid.
  kStatus_Success | Get successfully through the parameter `count`;

status_t UART_TransferReceiveNonBlocking | ( | UART_Type * | base,
|  | uart_handle_t * | handle,
|  | uart_transfer_t * | xfer,
|  | size_t * | receivedBytes
| ) |  |

This function receives data using an interrupt method. This is a non-blocking function, which returns without waiting for all data to be received. If the RX ring buffer is used and not empty, the data in the ring buffer is copied and the parameter `receivedBytes` shows how many bytes are copied from the ring buffer. After copying, if the data in the ring buffer is not enough to read, the receive request is saved by the UART driver. When the new data arrives, the receive request is serviced first. When all data is received, the UART driver notifies the upper layer through a callback function and passes the status parameter kStatus_UART_RxIdle. For example, the upper layer needs 10 bytes but there are only 5 bytes in the ring buffer. The 5 bytes are copied to the xfer->data and this function returns with the parameter `receivedBytes` set to 5. For the left 5 bytes, newly arrived data is saved from the xfer->data[5]. When 5 bytes are received, the UART driver notifies the upper layer. If the RX ring buffer is not enabled, this function enables the RX and RX interrupt to receive data to the xfer->data. When all data is received, the upper layer is notified.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.
  xfer | UART transfer structure, see uart_transfer_t.
  receivedBytes | Bytes received from the ring buffer directly.

Return values

  kStatus_Success | Successfully queue the transfer into transmit queue.
  kStatus_UART_RxBusy | Previous receive request is not finished.
  kStatus_InvalidArgument | Invalid argument.

void UART_TransferAbortReceive | ( | UART_Type * | base,
|  | uart_handle_t * | handle
| ) |  |

This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know how many bytes are not received yet.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.

status_t UART_TransferGetReceiveCount | ( | UART_Type * | base,
|  | uart_handle_t * | handle,
|  | uint32_t * | count
| ) |  |

This function gets the number of bytes that have been received.

Parameters

  base | UART peripheral base address.
  handle | UART handle pointer.
  count | Receive bytes count.

Return values

  kStatus_NoTransferInProgress | No receive in progress.
  kStatus_InvalidArgument | Parameter is invalid.
  kStatus_Success | Get successfully through the parameter `count`;

void UART_TransferHandleIRQ | ( | UART_Type * | base,
|  | void * | irqHandle
| ) |  |

This function handles the UART transmit and receive IRQ request.

Parameters

  base | UART peripheral base address.
  irqHandle | UART handle pointer.

static void UART_EnableTxDMA | ( | UART_Type * | base,
|  | bool | enable
| ) |  |
| inlinestatic

This function enables or disables the transmit request when the transmitter has one or more slots available in the TxFIFO. The fill level in the TxFIFO that generates the DMA request is controlled by the TXTL bits.

Parameters

  base | UART peripheral base address.
  enable | True to enable, false to disable.

static void UART_EnableRxDMA | ( | UART_Type * | base,
|  | bool | enable
| ) |  |
| inlinestatic

This function enables or disables the receive request when the receiver has data in the RxFIFO. The fill level in the RxFIFO at which a DMA request is generated is controlled by the RXTL bits .

Parameters

  base | UART peripheral base address.
  enable | True to enable, false to disable.

static void UART_SetTxFifoWatermark | ( | UART_Type * | base,
|  | uint8_t | watermark
| ) |  |
| inlinestatic

       A maskable interrupt is generated whenever the data level in
       the TxFIFO falls below the Tx FIFO watermark.

Parameters

  base | UART base pointer.
  watermark | The Tx FIFO watermark.

static void UART_SetRxRTSWatermark | ( | UART_Type * | base,
|  | uint8_t | watermark
| ) |  |
| inlinestatic

The RTS signal deasserts whenever the data count in RxFIFO reaches the Rx RTS watermark.

Parameters

  base | UART base pointer.
  watermark | The Rx RTS watermark.

static void UART_SetRxFifoWatermark | ( | UART_Type * | base,
|  | uint8_t | watermark
| ) |  |
| inlinestatic

       A maskable interrupt is generated whenever the data level in
       the RxFIFO reaches the Rx FIFO watermark.

Parameters

  base | UART base pointer.
  watermark | The Rx FIFO watermark.

static void UART_EnableAutoBaudRate | ( | UART_Type * | base,
|  | bool | enable
| ) |  |
| inlinestatic

Parameters

  base | UART base pointer.
  enable | Enable/Disable Automatic Baud Rate Detection feature. true: Enable Automatic Baud Rate Detection feature. false: Disable Automatic Baud Rate Detection feature.

static bool UART_IsAutoBaudRateComplete | ( | UART_Type * | base | ) |
| inlinestatic

Parameters

  base | UART base pointer.

Returns
  - true: Automatic baud rate detection has finished.
  - false: Automatic baud rate detection has not finished.

## Variable Documentation

void* s_uartHandle[]