Overview

This section describes the programming interface of the UART Peripheral driver. The UART peripheral driver transfers data to and from external devices on the Universal Asynchronous Receiver/Transmitter (UART) serial bus with a single function call.

UART Device structures

The driver uses an instantiation of the uart_state_t structure to maintain the current state of a particular UART instance module driver. This structure holds data that is used by the UART Peripheral driver to communicate between the transmit and receive transfer functions and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. Because the driver itself does not statically allocate memory, the caller provides memory for the driver state structure during initialization by providing a structure. The UART driver populates the structure members.

UART User configuration structures

The UART driver uses instances of the user configuration structure uart_user_config_t for the UART driver. This enables configuration of the most common settings of the UART with a single function call. Settings include: UART baud rate, UART parity mode: disabled (default), or even or odd, the number of stop bits, and the number of bits per data word.

UART Initialization

To initialize the UART driver, call the UART_DRV_Init() function and pass the instance number of the UART peripheral, memory for the run-time state structure, and a pointer to the user configuration structure. For example, to use UART0 pass a value of 0 to the initialization function.
Then, pass the memory for the run-time state structure.
Finally, pass a user configuration structure of the type uart_user_config_t as shown here:

// UART configuration structure
typedef struct UartUserConfig {
    uint32_t baudRate;            
    uart_parity_mode_t parityMode;     
    uart_stop_bit_count_t stopBitCount; 
    uart_bit_count_per_char_t bitCountPerChar; 
} uart_user_config_t;

Typically, the uart_user_config_t instantiation is configured as 8-bit-char, no-parity, 1-stop-bit (8-n-1) with a 9600 bps baud rate. The uart_user_config_t instantiation can be easily modified to configure the UART Peripheral driver either to a different baud rate or character transfer features. This is an example code to set up a user UART configuration instantiation:

uart_user_config_t uartConfig;
uartConfig.baudRate = 9600;
uartConfig.bitCountPerChar = kUart8BitsPerChar;
uartConfig.parityMode = kUartParityDisabled;
uartConfig.stopBitCount = kUartOneStopBit;

This example shows how to call the UART_DRV_Init() given the user configuration structure and the UART instance 0.

uint32_t uartInstance = 0;
uart_state_t uartState; // user provides memory for the driver state structure
UART_DRV_Init(uartInstance, &uartConfig, &uartState);

UART Transfers

The driver implements transmit and receive functions to transfer buffers of data in blocking and non-blocking modes.

The non-blocking transmit and receive functions include the UART_DRV_SendData() and UART_DRV_ReceiveData() functions.

The blocking (async) transmit and receive functions include the UART_DRV_SendDataBlocking() and UART_DRV_ReceiveDataBlocking() functions.

When using DMA to transfer data, ensure that date is consistent because of the cache for memory. In other words, when reading/ writing the data from/to memory, the application should ensure that data from or to the memory device is not cached.

In all cases mentioned here, the functions are interrupt-driven.

This code examples show how to use the functions, assuming that the UART module has been initialized as described previously in the Initialization Section.

For blocking transfer functions transmit and receive:

uint8_t sourceBuff[26] ={0}; // sourceBuff can be filled out with desired data
uint8_t readBuffer[10] = {0}; // readBuffer gets filled with UART_DRV_ReceiveData function
uint32_t byteCount = sizeof(sourceBuff);
uint32_t rxRemainingSize = sizeof(readBuffer);
// for each use there, set timeout as "1"
// uartState is the run-time state. Pass in memory for this 
// declared previously in the initialization section
UART_DRV_SendDataBlocking(uartInstance, sourceBuff, byteCount, 1); // Function won't return until transmit is complete
UART_DRV_ReceiveDataBlocking(uartInstance, readBuffer, 1, timeoutValue); // Function won't return until it receives all data

For non-blocking (async) transfer functions transmit and receive:

uint8_t *pTxBuff;
uint8_t rxBuff[10];
uint32_t txBytesRemaining, rxBytesRemaining;
// Assume pTxBuff and txSize have been initialized
UART_DRV_SendData(uartInstance, pTxBuff, txSize);
// Check on status of transmit and wait until done; the code can do something else and 
// check back later
while (UART_DRV_GetTransmitStatus(uartInstance, &txBytesRemaining) == kStatus_UART_TxBusy);
// For receive, assume rxBuff is set up to receive data and rxSize is initialized
UART_DRV_ReceiveData(uartInstance, rxBuff, rxSize);
// Check on status of receive and wait until done; the code can do something else and 
// check back later
while (UART_DRV_GetReceiveStatus(uartInstance, &rxBytesRemaining) == kStatus_UART_RxBusy);

Files
file	fsl_uart_driver.h
	Some devices count the UART instances with LPUART(e.g., KL27) or UART0(e.g., KL25) together.

Data Structures
struct	uart_state_t
	Runtime state of the UART driver. More...

struct	uart_user_config_t
	User configuration structure for the UART driver. More...

Typedefs
typedef void(*	uart_rx_callback_t )(uint32_t instance, void *uartState)
	UART receive callback function type.

typedef void(*	uart_tx_callback_t )(uint32_t instance, void *uartState)
	UART transmit callback function type.

Variables
UART_Type *const	g_uartBase [UART_INSTANCE_COUNT]
	Table of base addresses for UART instances. More...

const IRQn_Type	g_uartRxTxIrqId [UART_INSTANCE_COUNT]
	Table to save UART IRQ enumeration numbers defined in the CMSIS header file.

UART Interrupt Driver
uart_status_t	UART_DRV_Init (uint32_t instance, uart_state_t uartStatePtr, const uart_user_config_t uartUserConfig)
	Initializes an UART instance for operation. More...

uart_status_t	UART_DRV_Deinit (uint32_t instance)
	Shuts down the UART by disabling interrupts and the transmitter/receiver. More...

uart_rx_callback_t	UART_DRV_InstallRxCallback (uint32_t instance, uart_rx_callback_t function, uint8_t rxBuff, void callbackParam, bool alwaysEnableRxIrq)
	Installs the callback function for the UART receive. More...

uart_tx_callback_t	UART_DRV_InstallTxCallback (uint32_t instance, uart_tx_callback_t function, uint8_t txBuff, void callbackParam)
	Installs the callback function for the UART transmit. More...

uart_status_t	UART_DRV_SendDataBlocking (uint32_t instance, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout)
	Sends (transmits) data out through the UART module using a blocking method. More...

uart_status_t	UART_DRV_SendData (uint32_t instance, const uint8_t *txBuff, uint32_t txSize)
	Sends (transmits) data through the UART module using a non-blocking method. More...

uart_status_t	UART_DRV_GetTransmitStatus (uint32_t instance, uint32_t *bytesRemaining)
	Returns whether the previous UART transmit has finished. More...

uart_status_t	UART_DRV_AbortSendingData (uint32_t instance)
	Terminates an asynchronous UART transmission early. More...

uart_status_t	UART_DRV_ReceiveDataBlocking (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout)
	Gets (receives) data from the UART module using a blocking method. More...

uart_status_t	UART_DRV_ReceiveData (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize)
	Gets (receives) data from the UART module using a non-blocking method. More...

uart_status_t	UART_DRV_GetReceiveStatus (uint32_t instance, uint32_t *bytesRemaining)
	Returns whether the previous UART receive is complete. More...

uart_status_t	UART_DRV_AbortReceivingData (uint32_t instance)
	Terminates an asynchronous UART receive early. More...

Data Structure Documentation

struct uart_state_t

This structure holds data that are used by the UART peripheral driver to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user passes in the memory for the run-time state structure and the UART driver fills out the members.

Data Fields
uint8_t	txFifoEntryCount
	Number of data word entries in TX FIFO. More...

const uint8_t *	txBuff
	The buffer of data being sent. More...

uint8_t *	rxBuff
	The buffer of received data. More...

volatile size_t	txSize
	The remaining number of bytes to be transmitted. More...

volatile size_t	rxSize
	The remaining number of bytes to be received. More...

volatile bool	isTxBusy
	True if there is an active transmit. More...

volatile bool	isRxBusy
	True if there is an active receive. More...

volatile bool	isTxBlocking
	True if transmit is blocking transaction. More...

volatile bool	isRxBlocking
	True if receive is blocking transaction. More...

semaphore_t	txIrqSync
	Used to wait for ISR to complete its TX business. More...

semaphore_t	rxIrqSync
	Used to wait for ISR to complete its RX business. More...

uart_rx_callback_t	rxCallback
	Callback to invoke after receiving byte. More...

void *	rxCallbackParam
	Receive callback parameter pointer. More...

uart_tx_callback_t	txCallback
	Callback to invoke after transmitting byte. More...

void *	txCallbackParam
	Transmit callback parameter pointer. More...

Field Documentation

uint8_t uart_state_t::txFifoEntryCount

const uint8_t* uart_state_t::txBuff

uint8_t* uart_state_t::rxBuff

volatile size_t uart_state_t::txSize

volatile size_t uart_state_t::rxSize

volatile bool uart_state_t::isTxBusy

volatile bool uart_state_t::isRxBusy

volatile bool uart_state_t::isTxBlocking

volatile bool uart_state_t::isRxBlocking

semaphore_t uart_state_t::txIrqSync

semaphore_t uart_state_t::rxIrqSync

uart_rx_callback_t uart_state_t::rxCallback

void* uart_state_t::rxCallbackParam

uart_tx_callback_t uart_state_t::txCallback

void* uart_state_t::txCallbackParam

struct uart_user_config_t

Use an instance of this structure with the UART_DRV_Init()function. This enables configuration of the most common settings of the UART peripheral with a single function call. Settings include: UART baud rate, UART parity mode: disabled (default), or even or odd, the number of stop bits, and the number of bits per data word.

Data Fields
uint32_t	baudRate
	UART baud rate.

uart_parity_mode_t	parityMode
	parity mode, disabled (default), even, odd

uart_stop_bit_count_t	stopBitCount
	number of stop bits, 1 stop bit (default) or 2 stop bits

uart_bit_count_per_char_t	bitCountPerChar
	number of bits, 8-bit (default) or 9-bit in a word (up to 10-bits in some UART instances)

Function Documentation

uart_status_t UART_DRV_Init	(	uint32_t	instance,
		uart_state_t *	uartStatePtr,
		const uart_user_config_t *	uartUserConfig
	)

This function initializes the run-time state structure to keep track of the on-going transfers, un-gates the clock to the UART module, initializes the module to user-defined settings and default settings, configures the IRQ state structure, and enables the module-level interrupt to the core, and the UART module transmitter and receiver. This example shows how to set up the uart_state_t and the uart_user_config_t parameters and how to call the UART_DRV_Init function by passing in these parameters:

uart_user_config_t uartConfig;
uartConfig.baudRate = 9600;
uartConfig.bitCountPerChar = kUart8BitsPerChar;
uartConfig.parityMode = kUartParityDisabled;
uartConfig.stopBitCount = kUartOneStopBit;
uart_state_t uartState;
UART_DRV_Init(instance, &uartState, &uartConfig);

Parameters

instance	The UART instance number.
uartStatePtr	A pointer to the UART driver state structure memory. The user passes in the memory for this run-time state structure. The UART driver populates the members. The run-time state structure keeps track of the current transfer in progress.
uartUserConfig	The user configuration structure of type uart_user_config_t. The user populates the members of this structure and passes the pointer of this structure to this function.

Returns: An error code or kStatus_UART_Success.

uart_status_t UART_DRV_Deinit ( uint32_t instance )

This function disables the UART interrupts, the transmitter and receiver, and flushes the FIFOs (for modules that support FIFOs).

Parameters

instance The UART instance number.

Returns: An error code or kStatus_UART_Success.

uart_rx_callback_t UART_DRV_InstallRxCallback	(	uint32_t	instance,
		uart_rx_callback_t	function,
		uint8_t *	rxBuff,
		void *	callbackParam,
		bool	alwaysEnableRxIrq
	)

Note: After a callback is installed, it bypasses part of the UART IRQHandler logic. So, the callback needs to handle the indexes of rxBuff, rxSize.

Parameters

instance	The UART instance number.
function	The UART receive callback function.
rxBuff	The receive buffer used inside IRQHandler. This buffer must be kept as long as the callback is alive.
callbackParam	The UART receive callback parameter pointer.
alwaysEnableRxIrq	Whether always enable receive IRQ or not.

Returns: Former UART receive callback function pointer.

uart_tx_callback_t UART_DRV_InstallTxCallback	(	uint32_t	instance,
		uart_tx_callback_t	function,
		uint8_t *	txBuff,
		void *	callbackParam
	)

Note: After a callback is installed, it bypasses part of the UART IRQHandler logic. Therefore, the callback needs to handle the txBuff and txSize indexes.

Parameters

instance	The UART instance number.
function	The UART transmit callback function.
txBuff	The transmit buffer used inside IRQHandler. This buffer must be kept as long as the callback is alive.
callbackParam	The UART transmit callback parameter pointer.

Returns: Former UART transmit callback function pointer.

uart_status_t UART_DRV_SendDataBlocking	(	uint32_t	instance,
		const uint8_t *	txBuff,
		uint32_t	txSize,
		uint32_t	timeout
	)

A blocking (also known as synchronous) function means that the function does not return until the transmit is complete. This blocking function is used to send data through the UART port.

Parameters

instance	The UART instance number.
txBuff	A pointer to the source buffer containing 8-bit data chars to send.
txSize	The number of bytes to send.
timeout	A timeout value for RTOS abstraction sync control in milliseconds (ms).

Returns: An error code or kStatus_UART_Success.

uart_status_t UART_DRV_SendData	(	uint32_t	instance,
		const uint8_t *	txBuff,
		uint32_t	txSize
	)

A non-blocking (also known as synchronous) function means that the function returns immediately after initiating the transmit function. The application has to get the transmit status to see when the transmit is complete. In other words, after calling non-blocking (asynchronous) send function, the application must get the transmit status to check if transmit is complete. The asynchronous method of transmitting and receiving allows the UART to perform a full duplex operation (simultaneously transmit and receive).

Parameters

instance	The UART module base address.
txBuff	A pointer to the source buffer containing 8-bit data chars to send.
txSize	The number of bytes to send.

Returns: An error code or kStatus_UART_Success.

uart_status_t UART_DRV_GetTransmitStatus	(	uint32_t	instance,
		uint32_t *	bytesRemaining
	)

When performing an a-sync transmit, call this function to ascertain the state of the current transmission: in progress (or busy) or complete (success). If the transmission is still in progress, the user can obtain the number of words that have been transferred.

Parameters

instance	The UART module base address.
bytesRemaining	A pointer to a value that is filled in with the number of bytes that are remaining in the active transfer.

Returns: The transmit status.

Return values

kStatus_UART_Success	The transmit has completed successfully.
kStatus_UART_TxBusy	The transmit is still in progress. bytesTransmitted is filled with the number of bytes which are transmitted up to that point.

uart_status_t UART_DRV_AbortSendingData ( uint32_t instance )

During an a-sync UART transmission, the user can terminate the transmission early if the transmission is still in progress.

Parameters

instance The UART module base address.

Returns: Whether the aborting success or not.

Return values

kStatus_UART_Success	The transmit was successful.
kStatus_UART_NoTransmitInProgress	No transmission is currently in progress.

uart_status_t UART_DRV_ReceiveDataBlocking	(	uint32_t	instance,
		uint8_t *	rxBuff,
		uint32_t	rxSize,
		uint32_t	timeout
	)

A blocking (also known as synchronous) function means that the function does not return until the receive is complete. This blocking function sends data through the UART port.

Parameters

instance	The UART module base address.
rxBuff	A pointer to the buffer containing 8-bit read data chars received.
rxSize	The number of bytes to receive.
timeout	A timeout value for RTOS abstraction sync control in milliseconds (ms).

Returns: An error code or kStatus_UART_Success.

uart_status_t UART_DRV_ReceiveData	(	uint32_t	instance,
		uint8_t *	rxBuff,
		uint32_t	rxSize
	)

A non-blocking (also known as synchronous) function means that the function returns immediately after initiating the receive function. The application has to get the receive status to see when the receive is complete. In other words, after calling non-blocking (asynchronous) get function, the application must get the receive status to check if receive is completed or not. The asynchronous method of transmitting and receiving allows the UART to perform a full duplex operation (simultaneously transmit and receive).

Parameters

instance	The UART module base address.
rxBuff	A pointer to the buffer containing 8-bit read data chars received.
rxSize	The number of bytes to receive.

Returns: An error code or kStatus_UART_Success.

uart_status_t UART_DRV_GetReceiveStatus	(	uint32_t	instance,
		uint32_t *	bytesRemaining
	)

When performing an a-sync receive, call this function to find out the state of the current receive progress: in progress (or busy) or complete (success). In addition, if the receive is still in progress, the user can obtain the number of words that have been currently received.

Parameters

instance	The UART module base address.
bytesRemaining	A pointer to a value that is filled in with the number of bytes which still need to be received in the active transfer.

Returns: The receive status.

Return values

kStatus_UART_Success	The receive has completed successfully.
kStatus_UART_RxBusy	The receive is still in progress. bytesReceived is filled with the number of bytes which are received up to that point.

uart_status_t UART_DRV_AbortReceivingData ( uint32_t instance )

During an a-sync UART receive, the user can terminate the receive early if the receive is still in progress.

Parameters

instance The UART module base address.

Returns: Whether the aborting success or not.

Return values

kStatus_UART_Success	The receive was successful.
kStatus_UART_NoTransmitInProgress	No receive is currently in progress.

Variable Documentation

UART_Type* const g_uartBase[UART_INSTANCE_COUNT]

Overview

UART Device structures

UART User configuration structures

UART Initialization

UART Transfers

Files

Data Structures

Typedefs

Variables

UART Interrupt Driver

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Function Documentation

Variable Documentation