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...

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

Enumerations
enum	_uart_status { kStatus_UART_TxBusy = MAKE_STATUS(kStatusGroup_UART, 0), kStatus_UART_RxBusy = MAKE_STATUS(kStatusGroup_UART, 1), kStatus_UART_TxIdle = MAKE_STATUS(kStatusGroup_UART, 2), kStatus_UART_RxIdle = MAKE_STATUS(kStatusGroup_UART, 3), kStatus_UART_TxWatermarkTooLarge = MAKE_STATUS(kStatusGroup_UART, 4), kStatus_UART_RxWatermarkTooLarge = MAKE_STATUS(kStatusGroup_UART, 5), kStatus_UART_FlagCannotClearManually, kStatus_UART_Error = MAKE_STATUS(kStatusGroup_UART, 7), kStatus_UART_RxRingBufferOverrun = MAKE_STATUS(kStatusGroup_UART, 8), kStatus_UART_RxHardwareOverrun = MAKE_STATUS(kStatusGroup_UART, 9) }
	Error codes for the UART driver. 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 = 0U, kUART_TwoStopBit = 1U }
	UART stop bit count. More...

enum	_uart_interrupt_enable { kUART_LinBreakInterruptEnable = (UART_BDH_LBKDIE_MASK), kUART_RxActiveEdgeInterruptEnable = (UART_BDH_RXEDGIE_MASK), kUART_TxDataRegEmptyInterruptEnable = (UART_C2_TIE_MASK << 8), kUART_TransmissionCompleteInterruptEnable = (UART_C2_TCIE_MASK << 8), kUART_RxDataRegFullInterruptEnable = (UART_C2_RIE_MASK << 8), kUART_IdleLineInterruptEnable = (UART_C2_ILIE_MASK << 8), kUART_RxOverrunInterruptEnable = (UART_C3_ORIE_MASK << 16), kUART_NoiseErrorInterruptEnable = (UART_C3_NEIE_MASK << 16), kUART_FramingErrorInterruptEnable = (UART_C3_FEIE_MASK << 16), kUART_ParityErrorInterruptEnable = (UART_C3_PEIE_MASK << 16), kUART_RxFifoOverflowInterruptEnable = (UART_CFIFO_TXOFE_MASK << 24), kUART_TxFifoOverflowInterruptEnable = (UART_CFIFO_RXUFE_MASK << 24), kUART_RxFifoUnderflowInterruptEnable = (UART_CFIFO_RXUFE_MASK << 24) }
	UART interrupt configuration structure, default settings all disabled. More...

enum	_uart_flags { kUART_TxDataRegEmptyFlag = (UART_S1_TDRE_MASK), kUART_TransmissionCompleteFlag = (UART_S1_TC_MASK), kUART_RxDataRegFullFlag = (UART_S1_RDRF_MASK), kUART_IdleLineFlag = (UART_S1_IDLE_MASK), kUART_RxOverrunFlag = (UART_S1_OR_MASK), kUART_NoiseErrorFlag = (UART_S1_NF_MASK), kUART_FramingErrorFlag = (UART_S1_FE_MASK), kUART_ParityErrorFlag = (UART_S1_PF_MASK), kUART_LinBreakFlag = (UART_S2_LBKDIF_MASK << 8), kUART_RxActiveEdgeFlag = (UART_S2_RXEDGIF_MASK << 8), kUART_RxActiveFlag = (UART_S2_RAF_MASK << 8), kUART_NoiseErrorInRxDataRegFlag = (UART_ED_NOISY_MASK << 16), kUART_ParityErrorInRxDataRegFlag = (UART_ED_PARITYE_MASK << 16), kUART_TxFifoEmptyFlag = (UART_SFIFO_TXEMPT_MASK << 24), kUART_RxFifoEmptyFlag = (UART_SFIFO_RXEMPT_MASK << 24), kUART_TxFifoOverflowFlag = (UART_SFIFO_TXOF_MASK << 24), kUART_RxFifoOverflowFlag = (UART_SFIFO_RXOF_MASK << 24), kUART_RxFifoUnderflowFlag = (UART_SFIFO_RXUF_MASK << 24) }
	UART status flags. More...

Initialization and deinitialization
void	UART_Init (UART_Type base, const uart_config_t config, uint32_t srcClock_Hz)
	Initializes a UART instance with user configuration structure and peripheral clock. More...

void	UART_Deinit (UART_Type *base)
	Deinitializes a UART instance. More...

void	UART_GetDefaultConfig (uart_config_t *config)
	Gets the default configuration structure. More...

void	UART_SetBaudRate (UART_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz)
	Sets the UART instance baud rate. More...

Status
uint32_t	UART_GetStatusFlags (UART_Type *base)
	Get UART status flags. More...

status_t	UART_ClearStatusFlags (UART_Type *base, uint32_t mask)
	Clears status flags with the provided mask. 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 the enabled UART interrupts. More...

DMA Control
static uint32_t	UART_GetDataRegisterAddress (UART_Type *base)
	Gets the UART data register address. More...

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. 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...

void	UART_WriteBlocking (UART_Type base, const uint8_t data, size_t length)
	Writes to the TX register using a blocking method. More...

static void	UART_WriteByte (UART_Type *base, uint8_t data)
	Writes to the TX register. More...

void	UART_ReadBlocking (UART_Type base, uint8_t data, size_t length)
	Read RX data register using a blocking method. More...

static uint8_t	UART_ReadByte (UART_Type *base)
	Reads the RX register directly. More...

Transactional
void	UART_CreateHandle (UART_Type base, uart_handle_t handle, uart_transfer_callback_t callback, void *userData)
	Initializes the UART handle. More...

void	UART_StartRingBuffer (UART_Type base, uart_handle_t handle, uint8_t *ringBuffer, size_t ringBufferSize)
	Sets up the RX ring buffer. More...

void	UART_StopRingBuffer (UART_Type base, uart_handle_t handle)
	Aborts the background transfer and uninstalls the ring buffer. More...

status_t	UART_SendNonBlocking (UART_Type base, uart_handle_t handle, uart_transfer_t *xfer)
	Transmits a buffer of data using the interrupt method. More...

void	UART_AbortSend (UART_Type base, uart_handle_t handle)
	Aborts the interrupt driven data transmit. More...

status_t	UART_GetSendCount (UART_Type base, uart_handle_t handle, uint32_t *count)
	Get the number of bytes that have been written to UART TX register. More...

status_t	UART_ReceiveNonBlocking (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_AbortReceive (UART_Type base, uart_handle_t handle)
	Aborts the interrupt-driven data receiving. More...

status_t	UART_GetReceiveCount (UART_Type base, uart_handle_t handle, uint32_t *count)
	Get the number of bytes that have been received. More...

void	UART_HandleIRQ (UART_Type base, uart_handle_t handle)
	UART IRQ handle function. More...

void	UART_HandleErrorIRQ (UART_Type base, uart_handle_t handle)
	UART Error IRQ handle function. More...

Usage Information

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

UART driver includes 2 parts: functional APIs and transactional APIs.

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

Transactional APIs are transaction target high level APIs. 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 first parameter. Initialize the handle by calling the UART_CreateHandle() API.

Transactional APIs support asynchronous transfer, which means that the functions UART_SendNonBlocking() and UART_ReceiveNonBlocking() 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_CreateHandle(). 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_ReceiveNonBlocking() 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, the oldest 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:

UART_CreateHandle(&handle, UART0, &ringBuffer, 32);

In this example, the buffer size is 32, but only 31 bytes are used for saving data.

Function groups

Initialization and deinitialization

The UART_Init() function initializes UART with specified configurations. The UART_GetDefaultConfig() function gets the default configurations.

Status

Provides functions to get and clear the UART status.

Interrupt

Provides functions to enable/disable UART interrupts and get the current enabled interrupts.

DMA Control

Provide functions to enable/disable UART to generate the DMA request.

Bus Operations

Provide functions to enable/disable transmit/receive and functions to write/read data.

Transactional

Provide functions to send/receive data through interrupt or DMA.

Typical use case

UART Send/receive using a polling method

uint8_t ch;
UART_GetDefaultConfig(&user_config);
user_config.baudRate_Bps = 115200U;
user_config.enableTx = true;
user_config.enableRx = true;
UART_Init(UART1,&user_config,120000000U);
while(1)
{
    UART_ReadBlocking(UART1, &ch, 1);
    UART_WriteBlocking(UART1, &ch, 1);
}

UART Send/receive using an interrupt method

uart_handle_t g_uartHandle;
uart_config_t user_config;
uart_transfer_t sendXfer;
uart_transfer_t receiveXfer;
volatile bool txFinished;
volatile bool rxFinished;
uint8_t sendData[] = ['H', 'e', 'l', 'l', 'o'];
uint8_t receiveData[32];
void UART_UserCallback(uart_handle_t *handle, status_t status, void *userData)
{
    userData = userData;
    if (kStatus_UART_TxIdle == status)
    {
        txFinished = true;
    }
    if (kStatus_UART_RxIdle == status)
    {
        rxFinished = true;
    }
}
void main(void)
{
    //...
    UART_GetDefaultConfig(&user_config);
    user_config.baudRate_Bps = 115200U;
    user_config.enableTx = true;
    user_config.enableRx = true;
    UART_Init(UART1, &user_config, 120000000U);
    UART_CreateHandle(&g_uartHandle, UART1, NULL, 0);
    UART_SetTransferCallback(&g_uartHandle, UART_UserCallback, NULL);
    // Prepare to send.
    sendXfer.data = sendData
    sendXfer.dataSize = sizeof(sendData)/sizeof(sendData[0]);
    txFinished = false;
    // Send out.
    UART_SendNonBlocking(&g_uartHandle, &sendXfer);
    // Wait send finished.
    while (!txFinished)
    {
    }
    // Prepare to receive.
    receiveXfer.data = receiveData;
    receiveXfer.dataSize = sizeof(receiveData)/sizeof(receiveData[0]);
    rxFinished = false;
    // Receive.
    UART_ReceiveNonBlocking(&g_uartHandle, &receiveXfer, NULL);
    // Wait receive finished.
    while (!rxFinished)
    {
    }
    // ...
}

UART Receive using the ringbuffer feature

#define RING_BUFFER_SIZE 64
#define RX_DATA_SIZE     32
uart_handle_t g_uartHandle;
uart_config_t user_config;
uart_transfer_t sendXfer;
uart_transfer_t receiveXfer;
volatile bool txFinished;
volatile bool rxFinished;
uint8_t receiveData[RX_DATA_SIZE];
uint8_t ringBuffer[RING_BUFFER_SIZE];
void UART_UserCallback(uart_handle_t *handle, status_t status, void *userData)
{
    userData = userData;
    if (kStatus_UART_RxIdle == status)
    {
        rxFinished = true;
    }
}
void main(void)
{
    size_t bytesRead;
    //...
    UART_GetDefaultConfig(&user_config);
    user_config.baudRate_Bps = 115200U;
    user_config.enableTx = true;
    user_config.enableRx = true;
    UART_Init(UART1, &user_config, 120000000U);
    UART_CreateHandle(&g_uartHandle, UART1, &ringBuffer, RING_BUFFER_SIZE);
    UART_SetTransferCallback(&g_uartHandle, UART_UserCallback, NULL);
    // Now the RX is working in background, receive in to ring buffer.
    // Prepare to receive.
    receiveXfer.data = receiveData;
    receiveXfer.dataSize = RX_DATA_SIZE;
    rxFinished = false;
    // Receive.
    UART_ReceiveNonBlocking(&g_uartHandle, &receiveXfer, &bytesRead);
    if (bytesRead = RX_DATA_SIZE) /* Have read enough data. */
    {
        ;
    }
    else
    {
        if (bytesRead) /* Received some data, process first. */
        {
            ;
        }
        // Wait receive finished.
        while (!rxFinished)
        {
        }
    }
    // ...
}

UART Send/Receive using the DMA method

uart_handle_t g_uartHandle;
dma_handle_t g_uartTxDmaHandle;
dma_handle_t g_uartRxDmaHandle;
uart_config_t user_config;
uart_transfer_t sendXfer;
uart_transfer_t receiveXfer;
volatile bool txFinished;
volatile bool rxFinished;
uint8_t sendData[] = ['H', 'e', 'l', 'l', 'o'];
uint8_t receiveData[32];
void UART_UserCallback(uart_handle_t *handle, status_t status, void *userData)
{
    userData = userData;
    if (kStatus_UART_TxIdle == status)
    {
        txFinished = true;
    }
    if (kStatus_UART_RxIdle == status)
    {
        rxFinished = true;
    }
}
void main(void)
{
    //...
    UART_GetDefaultConfig(&user_config);
    user_config.baudRate_Bps = 115200U;
    user_config.enableTx = true;
    user_config.enableRx = true;
    UART_Init(UART1, &user_config, 120000000U);
    // Set up the DMA
    DMAMUX_Init(DMAMUX0);
    DMAMUX_SetSource(DMAMUX0, UART_TX_DMA_CHANNEL, UART_TX_DMA_REQUEST);
    DMAMUX_EnableChannel(DMAMUX0, UART_TX_DMA_CHANNEL);
    DMAMUX_SetSource(DMAMUX0, UART_RX_DMA_CHANNEL, UART_RX_DMA_REQUEST);
    DMAMUX_EnableChannel(DMAMUX0, UART_RX_DMA_CHANNEL);
    DMA_Init(DMA0);
    /* Create DMA handle. */
    DMA_CreateHandle(&g_uartTxDmaHandle, DMA0, UART_TX_DMA_CHANNEL);
    DMA_CreateHandle(&g_uartRxDmaHandle, DMA0, UART_RX_DMA_CHANNEL);
    UART_CreateHandleDMA(&g_uartHandle, UART1, &g_uartTxDmaHandle, &g_uartRxDmaHandle);
    UART_SetTransferCallbackDMA(&g_uartDmaHandle, UART_UserCallback, NULL);
    // Prepare to send.
    sendXfer.data = sendData
    sendXfer.dataSize = sizeof(sendData)/sizeof(sendData[0]);
    txFinished = false;
    // Send out.
    UART_SendDMA(&g_uartHandle, &sendXfer);
    // Wait send finished.
    while (!txFinished)
    {
    }
    // Prepare to receive.
    receiveXfer.data = receiveData;
    receiveXfer.dataSize = sizeof(receiveData)/sizeof(receiveData[0]);
    rxFinished = false;
    // Receive.
    UART_ReceiveDMA(&g_uartHandle, &receiveXfer, NULL);
    // Wait receive finished.
    while (!rxFinished)
    {
    }
    // ...
}

Data Structure Documentation

struct uart_config_t

UART configuration structure.

Data Fields
uint32_t	baudRate_Bps	UART baud rate
bool	enableRx	Enable RX
bool	enableTx	Enable TX
uart_parity_mode_t	parityMode	Parity mode, disabled (default), even, odd
uint8_t	rxFifoWatermark	RX FIFO watermark
uart_stop_bit_count_t	stopBitCount	Number of stop bits, 1 stop bit (default) or 2 stop bits
uint8_t	txFifoWatermark	TX FIFO watermark

struct uart_transfer_t

UART transfer structure.

Data Fields
uint8_t *	data	The buffer of data to be transfer.
size_t	dataSize	The byte count to be transfer.

struct _uart_handle

UART handle structure.

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

Enumeration Type Documentation

enum _uart_flags

UART status flags.

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

Enumerator
kUART_TxDataRegEmptyFlag	TX data register empty flag.
kUART_TransmissionCompleteFlag	Transmission complete flag.
kUART_RxDataRegFullFlag	RX data register full flag.
kUART_IdleLineFlag	Idle line detect flag.
kUART_RxOverrunFlag	RX overrun flag.
kUART_NoiseErrorFlag	RX takes 3 samples of each received bit. If any of these samples differ, noise flag sets
kUART_FramingErrorFlag	Frame error flag, sets if logic 0 was detected where stop bit expected
kUART_ParityErrorFlag	If parity enabled, sets upon parity error detection
kUART_LinBreakFlag	LIN break detect interrupt flag, sets when LIN break char detected and LIN circuit enabled
kUART_RxActiveEdgeFlag	RX pin active edge interrupt flag, sets when active edge detected
kUART_RxActiveFlag	Receiver Active Flag (RAF), sets at beginning of valid start bit
kUART_NoiseErrorInRxDataRegFlag	Noisy bit, sets if noise detected.
kUART_ParityErrorInRxDataRegFlag	Paritye bit, sets if parity error detected.
kUART_TxFifoEmptyFlag	TXEMPT bit, sets if TX buffer is empty
kUART_RxFifoEmptyFlag	RXEMPT bit, sets if RX buffer is empty
kUART_TxFifoOverflowFlag	TXOF bit, sets if TX buffer overflow occurred
kUART_RxFifoOverflowFlag	RXOF bit, sets if receive buffer overflow
kUART_RxFifoUnderflowFlag	RXUF bit, sets if receive buffer underflow

enum _uart_interrupt_enable

UART interrupt configuration structure, default settings all disabled.

This structure contains the settings for all of the UART interrupt configurations.

Enumerator
kUART_LinBreakInterruptEnable	LIN break detect interrupt.
kUART_RxActiveEdgeInterruptEnable	RX active edge interrupt.
kUART_TxDataRegEmptyInterruptEnable	Transmit data register empty interrupt.
kUART_TransmissionCompleteInterruptEnable	Transmission complete interrupt.
kUART_RxDataRegFullInterruptEnable	Receiver data register full interrupt.
kUART_IdleLineInterruptEnable	Idle line interrupt.
kUART_RxOverrunInterruptEnable	Receiver overrun interrupt.
kUART_NoiseErrorInterruptEnable	Noise error flag interrupt.
kUART_FramingErrorInterruptEnable	Framing error flag interrupt.
kUART_ParityErrorInterruptEnable	Parity error flag interrupt.
kUART_RxFifoOverflowInterruptEnable	TX FIFO overflow interrupt.
kUART_TxFifoOverflowInterruptEnable	RX FIFO underflow interrupt.
kUART_RxFifoUnderflowInterruptEnable	RX FIFO underflow interrupt.

enum _uart_status

Error codes for the UART driver.

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.

enum uart_parity_mode_t

UART parity mode.

Enumerator
kUART_ParityDisabled	Parity disabled
kUART_ParityEven	Parity enabled, type even, bit setting: PE\|PT = 10
kUART_ParityOdd	Parity enabled, type odd, bit setting: PE\|PT = 11

enum uart_stop_bit_count_t

UART stop bit count.

Enumerator
kUART_OneStopBit	One stop bit
kUART_TwoStopBit	Two stop bits

Function Documentation

void UART_AbortReceive	(	UART_Type *	base,
		uart_handle_t *	handle
	)

Aborts the interrupt-driven data receiving.

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

Parameters

base	UART peripheral base address.
handle	UART handle pointer.

void UART_AbortSend	(	UART_Type *	base,
		uart_handle_t *	handle
	)

Aborts the interrupt driven data transmit.

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

Parameters

base	UART peripheral base address.
handle	UART handle pointer.

status_t UART_ClearStatusFlags	(	UART_Type *	base,
		uint32_t	mask
	)

Clears status flags with the provided mask.

This function clears UART status flags with a provided mask. Automatically cleared flag can't be cleared by this function. Some flags can only be cleared or set by hardware itself. These flags are: kUART_TxDataRegEmptyFlag, kUART_TransmissionCompleteFlag, kUART_RxDataRegFullFlag, kUART_RxActiveFlag, kUART_NoiseErrorInRxDataRegFlag, kUART_ParityErrorInRxDataRegFlag, kUART_TxFifoEmptyFlag,kUART_RxFifoEmptyFlag

Parameters

base	UART peripheral base address.
mask	The status flags to be cleared, it is logical OR value of _uart_flags.

Return values

kStatus_UART_FlagCannotClearManually	The flag can't be cleared by this function but it is cleared automatically by hardware.
kStatus_Success	Status in the mask are cleared.

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

Initializes the UART handle.

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_Deinit ( UART_Type * base )

Deinitializes a UART instance.

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

Parameters

base	UART peripheral base address.

void UART_DisableInterrupts	(	UART_Type *	base,
		uint32_t	mask
	)

Disables the UART interrupts according to the provided 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 full interrupt:

1 UART_DisableInterrupts(UART1,kUART_TxDataRegEmptyInterruptEnable | kUART_RxDataRegFullInterruptEnable);

Parameters

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

void UART_EnableInterrupts	(	UART_Type *	base,
		uint32_t	mask
	)

Enables UART interrupts according to the provided 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 full interrupt:

1 UART_EnableInterrupts(UART1,kUART_TxDataRegEmptyInterruptEnable | kUART_RxDataRegFullInterruptEnable);

Parameters

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

static void UART_EnableRx	(	UART_Type *	base,
		bool	enable
	)

inlinestatic

Enables or disables the UART receiver.

This function enables or disables the UART receiver.

Parameters

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

static void UART_EnableRxDMA	(	UART_Type *	base,
		bool	enable
	)

inlinestatic

Enables or disables the UART receiver DMA.

This function enables or disables the receiver data register full flag, S1[RDRF], to generate DMA requests.

Parameters

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

static void UART_EnableTx	(	UART_Type *	base,
		bool	enable
	)

inlinestatic

Enables or disables the UART transmitter.

This function enables or disables the UART transmitter.

Parameters

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

static void UART_EnableTxDMA	(	UART_Type *	base,
		bool	enable
	)

inlinestatic

Enables or disables the UART transmitter DMA request.

This function enables or disables the transmit data register empty flag, S1[TDRE], to generate the DMA requests.

Parameters

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

static uint32_t UART_GetDataRegisterAddress ( UART_Type * base )

inlinestatic

Gets the UART data register address.

This function returns the UART data register address, which is mainly used by DMA/eDMA.

Parameters

base	UART peripheral base address.

Returns: UART data register address which are used both by transmitter and receiver.

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->bitCountPerChar = kUART_8BitsPerChar; uartConfig->parityMode = kUART_ParityDisabled; uartConfig->stopBitCount = kUART_OneStopBit; uartConfig->txFifoWatermark = 0; uartConfig->rxFifoWatermark = 1; uartConfig->enableTx = false; uartConfig->enableRx = false;

Parameters

config Pointer to configuration structure.

uint32_t UART_GetEnabledInterrupts ( UART_Type * base )

Gets the enabled UART interrupts.

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 specific interrupts enable status, compare the return value with enumerators in _uart_interrupt_enable. For example, to check whether TX empty interrupt is enabled:

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

Parameters

base	UART peripheral base address.

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

status_t UART_GetReceiveCount	(	UART_Type *	base,
		uart_handle_t *	handle,
		uint32_t *	count
	)

Get the number of bytes that have been received.

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`;

status_t UART_GetSendCount	(	UART_Type *	base,
		uart_handle_t *	handle,
		uint32_t *	count
	)

Get the number of bytes that have been written to UART TX register.

This function gets the number of bytes that have been written to UART TX register by 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	Parameter is invalid.
kStatus_Success	Get successfully through the parameter `count`;

uint32_t UART_GetStatusFlags ( UART_Type * base )

Get UART status flags.

This function get all UART status flags, the flags are returned as the logical OR value of the enumerators _uart_flags. To check specific status, compare the return value with enumerators in _uart_flags. For example, to check whether the TX is empty:

 if (kUART_TxDataRegEmptyFlag & UART_GetStatusFlags(UART1))
 {
     ...
 }

Parameters

base	UART peripheral base address.

Returns: UART status flags which are ORed by the enumerators in the _uart_flags.

void UART_HandleErrorIRQ	(	UART_Type *	base,
		uart_handle_t *	handle
	)

UART Error IRQ handle function.

This function handle the UART error IRQ request.

Parameters

base	UART peripheral base address.
handle	UART handle pointer.

void UART_HandleIRQ	(	UART_Type *	base,
		uart_handle_t *	handle
	)

UART IRQ handle function.

This function handles the UART transmit and receive IRQ request.

Parameters

base	UART peripheral base address.
handle	UART handle pointer.

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

Initializes a UART instance with user configuration structure and peripheral clock.

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

 uart_config_t uartConfig;
 uartConfig.baudRate_Bps = 115200U;
 uartConfig.parityMode = kUART_ParityDisabled;
 uartConfig.stopBitCount = kUART_OneStopBit;
 uartConfig.txFifoWatermark = 0;
 uartConfig.rxFifoWatermark = 1;
 UART_Init(UART1, &uartConfig, 20000000U);

Parameters

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

void UART_ReadBlocking	(	UART_Type *	base,
		uint8_t *	data,
		size_t	length
	)

Read RX data register using a blocking method.

This function polls the RX register, waits for the RX register to be full or for RX FIFO to have data and read 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.

static uint8_t UART_ReadByte ( UART_Type * base )

inlinestatic

Reads the RX register directly.

This function reads data from the TX register directly. The upper layer must ensure that the RX register is full or that the TX FIFO has data before calling this function.

Parameters

base	UART peripheral base address.

Returns: The byte read from UART data register.

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

Receives a buffer of data using an interrupt method.

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, refer to 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.

status_t UART_SendNonBlocking	(	UART_Type *	base,
		uart_handle_t *	handle,
		uart_transfer_t *	xfer
	)

Transmits a buffer of data using the interrupt method.

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 are 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.

void UART_SetBaudRate	(	UART_Type *	base,
		uint32_t	baudRate_Bps,
		uint32_t	srcClock_Hz
	)

Sets the UART instance baud rate.

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.

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

Parameters

base	UART peripheral base address.
baudRate_Bps	UART baudrate to be set.
srcClock_Hz	UART clock source freqency in HZ.

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

Sets up the RX ring buffer.

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_ReceiveNonBlocking() API. If there is already data 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, then 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_StopRingBuffer	(	UART_Type *	base,
		uart_handle_t *	handle
	)

Aborts the background transfer and uninstalls the ring buffer.

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

Parameters

base	UART peripheral base address.
handle	UART handle pointer.

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

Writes to the TX register using a blocking method.

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.

Note: This function does not check whether all the data has been sent out to the bus. Before disabling the TX, check kUART_TransmissionCompleteFlag to ensure that the TX is finished.

Parameters

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

static void UART_WriteByte	(	UART_Type *	base,
		uint8_t	data
	)

inlinestatic

Writes to the TX register.

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

Parameters

base	UART peripheral base address.
data	The byte to write.

Data Structures

Typedefs

Enumerations

Initialization and deinitialization

Status

Interrupts

DMA Control

Bus Operations

Transactional

Usage Information

Function groups

Initialization and deinitialization

Status

Interrupt

DMA Control

Bus Operations

Transactional

Typical use case

UART Send/receive using a polling method

UART Send/receive using an interrupt method

UART Receive using the ringbuffer feature

UART Send/Receive using the DMA method

Data Structure Documentation

Enumeration Type Documentation

Function Documentation