The MCUXpresso SDK provides a peripheral driver for the Universal Asynchronous Receiver/Transmitter (UART) function using the Flexible I/O.
FlexIO UART driver includes functional APIs and transactional APIs. Functional APIs target low-level APIs. Functional APIs can be used for the FlexIO UART initialization/configuration/operation for optimization/customization purpose. Using the functional APIs requires the knowledge of the FlexIO UART peripheral and how to organize functional APIs to meet the application requirements. All functional API use the FLEXIO_UART_Type * as the first parameter. FlexIO UART functional operation groups provide the functional APIs set.
Transactional APIs target high-level APIs. Transactional APIs can be used to enable the peripheral and also in the application if the code size and performance of transactional APIs satisfy requirements. If the code size and performance are critical requirements, see the transactional API implementation and write custom code. All transactional APIs use the flexio_uart_handle_t as the second parameter. Initialize the handle by calling the FLEXIO_UART_TransferCreateHandle() API.
Transactional APIs support asynchronous transfer. This means that the functions FLEXIO_UART_SendNonBlocking() and FLEXIO_UART_ReceiveNonBlocking() set up an interrupt for data transfer. When the transfer is complete, the upper layer is notified through a callback function with the kStatus_FLEXIO_UART_TxIdle and kStatus_FLEXIO_UART_RxIdle status.
Transactional receive APIs support the ring buffer. Prepare the memory for the ring buffer and pass in the start address and size through calling the FLEXIO_UART_InstallRingBuffer(). When the ring buffer is enabled, the received data is saved to the ring buffer in the background. The function FLEXIO_UART_ReceiveNonBlocking() first gets data the from the ring buffer. If ring buffer does not have enough data, the function returns the data to the ring buffer and saves the received data to user memory. When all data is received, the upper layer is informed through a callback with the statuskStatus_FLEXIO_UART_RxIdle status.
If the receive ring buffer is full, the upper layer is informed through a callback with status kStatus_FLEXIO_UART_RxRingBufferOverrun. In the callback function, the upper layer reads data from the ring buffer. If not, the oldest data is overwritten by the new data.
The ring buffer size is specified when calling the FLEXIO_UART_InstallRingBuffer. Note that one byte is reserved for the ring buffer maintenance. Create a handle as follows.
FLEXIO_UART_InstallRingBuffer(&uartDev, &handle, &ringBuffer, 32);
In this example, the buffer size is 32. However, only 31 bytes are used for saving data.
Typical use case
FlexIO UART send/receive using a polling method
uint8_t ch;
flexio_uart_user_config user_config;
user_config.baudRate_Bps = 115200U;
user_config.enableUart = true;
if(result != kStatus_Success)
{
return;
}
while(1)
{
}
FlexIO UART send/receive using an interrupt method
flexio_uart_handle_t g_uartHandle;
volatile bool txFinished;
volatile bool rxFinished;
uint8_t sendData[] = ['H', 'e', 'l', 'l', 'o'];
uint8_t receiveData[32];
{
userData = userData;
{
txFinished = true;
}
{
rxFinished = true;
}
}
void main(void)
{
if(result != kStatus_Success)
{
return;
}
sendXfer.
data = sendData;
sendXfer.
dataSize =
sizeof(sendData)/
sizeof(sendData[0]);
txFinished = false;
FLEXIO_UART_SendNonBlocking(&uartDev, &g_uartHandle, &sendXfer);
while (!txFinished)
{
}
receiveXfer.
data = receiveData;
receiveXfer.
dataSize =
sizeof(receiveData)/
sizeof(receiveData[0]);
rxFinished = false;
FLEXIO_UART_ReceiveNonBlocking(&uartDev, &g_uartHandle, &receiveXfer, NULL);
while (!rxFinished)
{
}
}
FlexIO UART receive using the ringbuffer feature
#define RING_BUFFER_SIZE 64
#define RX_DATA_SIZE 32
flexio_uart_handle_t g_uartHandle;
volatile bool txFinished;
volatile bool rxFinished;
uint8_t receiveData[RX_DATA_SIZE];
uint8_t ringBuffer[RING_BUFFER_SIZE];
{
userData = userData;
{
rxFinished = true;
}
}
void main(void)
{
size_t bytesRead;
if(result != kStatus_Success)
{
return;
}
FLEXIO_UART_InstallRingBuffer(&uartDev, &g_uartHandle, ringBuffer, RING_BUFFER_SIZE);
receiveXfer.
data = receiveData;
rxFinished = false;
FLEXIO_UART_ReceiveNonBlocking(&uartDev, &g_uartHandle, &receiveXfer, &bytesRead);
if (bytesRead = RX_DATA_SIZE)
{
;
}
else
{
if (bytesRead)
{
;
}
while (!rxFinished)
{
}
}
}
FlexIO UART send/receive using a DMA method
flexio_uart_handle_t g_uartHandle;
dma_handle_t g_uartTxDmaHandle;
dma_handle_t g_uartRxDmaHandle;
volatile bool txFinished;
volatile bool rxFinished;
uint8_t sendData[] = ['H', 'e', 'l', 'l', 'o'];
uint8_t receiveData[32];
{
userData = userData;
{
txFinished = true;
}
{
rxFinished = true;
}
}
void main(void)
{
if(result != kStatus_Success)
{
return;
}
#if defined(FSL_FEATURE_SOC_DMA_COUNT) && FSL_FEATURE_SOC_DMA_COUNT > 0U
DMA_Init(EXAMPLE_FLEXIO_UART_DMA_BASEADDR);
DMA_CreateHandle(&g_uartTxDmaHandle, EXAMPLE_FLEXIO_UART_DMA_BASEADDR, FLEXIO_UART_TX_DMA_CHANNEL);
DMA_CreateHandle(&g_uartRxDmaHandle, EXAMPLE_FLEXIO_UART_DMA_BASEADDR, FLEXIO_UART_RX_DMA_CHANNEL);
#endif
#if defined(FSL_FEATURE_SOC_EDMA_COUNT) && FSL_FEATURE_SOC_EDMA_COUNT > 0U
EDMA_Init(EXAMPLE_FLEXIO_UART_DMA_BASEADDR, &edmaConfig);
EDMA_CreateHandle(&g_uartTxDmaHandle, EXAMPLE_FLEXIO_UART_DMA_BASEADDR, FLEXIO_UART_TX_DMA_CHANNEL);
EDMA_CreateHandle(&g_uartRxDmaHandle, EXAMPLE_FLEXIO_UART_DMA_BASEADDR, FLEXIO_UART_RX_DMA_CHANNEL);
#endif
dma_request_source_tx = (dma_request_source_t)(FLEXIO_DMA_REQUEST_BASE + uartDev.
shifterIndex[0]);
dma_request_source_rx = (dma_request_source_t)(FLEXIO_DMA_REQUEST_BASE + uartDev.
shifterIndex[1]);
DMAMUX_SetSource(EXAMPLE_FLEXIO_UART_DMAMUX_BASEADDR, FLEXIO_UART_TX_DMA_CHANNEL, (dma_request_source_t)dma_request_source_tx);
DMAMUX_SetSource(EXAMPLE_FLEXIO_UART_DMAMUX_BASEADDR, FLEXIO_UART_RX_DMA_CHANNEL, (dma_request_source_t)dma_request_source_rx);
sendXfer.
dataSize =
sizeof(sendData)/
sizeof(sendData[0]);
txFinished = false;
FLEXIO_UART_SendDMA(&uartDev, &g_uartHandle, &sendXfer);
while (!txFinished)
{
}
receiveXfer.
data = receiveData;
receiveXfer.
dataSize =
sizeof(receiveData)/
sizeof(receiveData[0]);
rxFinished = false;
FLEXIO_UART_ReceiveDMA(&uartDev, &g_uartHandle, &receiveXfer, NULL);
while (!rxFinished)
{
}
}
|
enum | {
kStatus_FLEXIO_UART_TxBusy = MAKE_STATUS(kStatusGroup_FLEXIO_UART, 0),
kStatus_FLEXIO_UART_RxBusy = MAKE_STATUS(kStatusGroup_FLEXIO_UART, 1),
kStatus_FLEXIO_UART_TxIdle = MAKE_STATUS(kStatusGroup_FLEXIO_UART, 2),
kStatus_FLEXIO_UART_RxIdle = MAKE_STATUS(kStatusGroup_FLEXIO_UART, 3),
kStatus_FLEXIO_UART_ERROR = MAKE_STATUS(kStatusGroup_FLEXIO_UART, 4),
kStatus_FLEXIO_UART_RxRingBufferOverrun,
kStatus_FLEXIO_UART_RxHardwareOverrun = MAKE_STATUS(kStatusGroup_FLEXIO_UART, 6)
} |
| Error codes for the UART driver. More...
|
|
enum | flexio_uart_bit_count_per_char_t {
kFLEXIO_UART_7BitsPerChar = 7U,
kFLEXIO_UART_8BitsPerChar = 8U,
kFLEXIO_UART_9BitsPerChar = 9U
} |
| FlexIO UART bit count per char. More...
|
|
enum | _flexio_uart_interrupt_enable {
kFLEXIO_UART_TxDataRegEmptyInterruptEnable = 0x1U,
kFLEXIO_UART_RxDataRegFullInterruptEnable = 0x2U
} |
| Define FlexIO UART interrupt mask. More...
|
|
enum | _flexio_uart_status_flags {
kFLEXIO_UART_TxDataRegEmptyFlag = 0x1U,
kFLEXIO_UART_RxDataRegFullFlag = 0x2U,
kFLEXIO_UART_RxOverRunFlag = 0x4U
} |
| Define FlexIO UART status mask. More...
|
|
|
status_t | FLEXIO_UART_TransferCreateHandle (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle, flexio_uart_transfer_callback_t callback, void *userData) |
| Initializes the UART handle. More...
|
|
void | FLEXIO_UART_TransferStartRingBuffer (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle, uint8_t *ringBuffer, size_t ringBufferSize) |
| Sets up the RX ring buffer. More...
|
|
void | FLEXIO_UART_TransferStopRingBuffer (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle) |
| Aborts the background transfer and uninstalls the ring buffer. More...
|
|
status_t | FLEXIO_UART_TransferSendNonBlocking (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle, flexio_uart_transfer_t *xfer) |
| Transmits a buffer of data using the interrupt method. More...
|
|
void | FLEXIO_UART_TransferAbortSend (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle) |
| Aborts the interrupt-driven data transmit. More...
|
|
status_t | FLEXIO_UART_TransferGetSendCount (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle, size_t *count) |
| Gets the number of bytes sent. More...
|
|
status_t | FLEXIO_UART_TransferReceiveNonBlocking (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle, flexio_uart_transfer_t *xfer, size_t *receivedBytes) |
| Receives a buffer of data using the interrupt method. More...
|
|
void | FLEXIO_UART_TransferAbortReceive (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle) |
| Aborts the receive data which was using IRQ. More...
|
|
status_t | FLEXIO_UART_TransferGetReceiveCount (FLEXIO_UART_Type *base, flexio_uart_handle_t *handle, size_t *count) |
| Gets the number of bytes received. More...
|
|
void | FLEXIO_UART_TransferHandleIRQ (void *uartType, void *uartHandle) |
| FlexIO UART IRQ handler function. More...
|
|
FLEXIO_Type* FLEXIO_UART_Type::flexioBase |
uint8_t FLEXIO_UART_Type::TxPinIndex |
uint8_t FLEXIO_UART_Type::RxPinIndex |
uint8_t FLEXIO_UART_Type::shifterIndex[2] |
uint8_t FLEXIO_UART_Type::timerIndex[2] |
struct flexio_uart_config_t |
bool flexio_uart_config_t::enableUart |
bool flexio_uart_config_t::enableFastAccess |
uint32_t flexio_uart_config_t::baudRate_Bps |
struct flexio_uart_transfer_t |
Data Fields |
uint8_t * | data |
| Transfer buffer.
|
|
size_t | dataSize |
| Transfer size.
|
|
struct _flexio_uart_handle |
uint8_t* volatile flexio_uart_handle_t::txData |
volatile size_t flexio_uart_handle_t::txDataSize |
uint8_t* volatile flexio_uart_handle_t::rxData |
volatile size_t flexio_uart_handle_t::rxDataSize |
size_t flexio_uart_handle_t::txDataSizeAll |
size_t flexio_uart_handle_t::rxDataSizeAll |
uint8_t* flexio_uart_handle_t::rxRingBuffer |
size_t flexio_uart_handle_t::rxRingBufferSize |
volatile uint16_t flexio_uart_handle_t::rxRingBufferHead |
volatile uint16_t flexio_uart_handle_t::rxRingBufferTail |
void* flexio_uart_handle_t::userData |
volatile uint8_t flexio_uart_handle_t::txState |
#define FSL_FLEXIO_UART_DRIVER_VERSION (MAKE_VERSION(2, 1, 6)) |
typedef void(* flexio_uart_transfer_callback_t)(FLEXIO_UART_Type *base, flexio_uart_handle_t *handle, status_t status, void *userData) |
Enumerator |
---|
kStatus_FLEXIO_UART_TxBusy |
Transmitter is busy.
|
kStatus_FLEXIO_UART_RxBusy |
Receiver is busy.
|
kStatus_FLEXIO_UART_TxIdle |
UART transmitter is idle.
|
kStatus_FLEXIO_UART_RxIdle |
UART receiver is idle.
|
kStatus_FLEXIO_UART_ERROR |
ERROR happens on UART.
|
kStatus_FLEXIO_UART_RxRingBufferOverrun |
UART RX software ring buffer overrun.
|
kStatus_FLEXIO_UART_RxHardwareOverrun |
UART RX receiver overrun.
|
Enumerator |
---|
kFLEXIO_UART_7BitsPerChar |
7-bit data characters
|
kFLEXIO_UART_8BitsPerChar |
8-bit data characters
|
kFLEXIO_UART_9BitsPerChar |
9-bit data characters
|
Enumerator |
---|
kFLEXIO_UART_TxDataRegEmptyInterruptEnable |
Transmit buffer empty interrupt enable.
|
kFLEXIO_UART_RxDataRegFullInterruptEnable |
Receive buffer full interrupt enable.
|
Enumerator |
---|
kFLEXIO_UART_TxDataRegEmptyFlag |
Transmit buffer empty flag.
|
kFLEXIO_UART_RxDataRegFullFlag |
Receive buffer full flag.
|
kFLEXIO_UART_RxOverRunFlag |
Receive buffer over run flag.
|
The configuration structure can be filled by the user or be set with default values by FLEXIO_UART_GetDefaultConfig().
Example
.TxPinIndex = 0,
.RxPinIndex = 1,
.shifterIndex = {0,1},
.timerIndex = {0,1}
};
.enableInDebug = true,
.enableFastAccess = false,
.baudRate_Bps = 115200U,
.bitCountPerChar = 8
};
- Parameters
-
- Return values
-
kStatus_Success | Configuration success |
kStatus_InvalidArgument | Buadrate configuration out of range |
- Note
- After calling this API, call the FLEXO_UART_Init to use the FlexIO UART module.
- Parameters
-
The configuration can be used directly for calling the FLEXIO_UART_Init(). Example:
- Parameters
-
- Parameters
-
- Returns
- FlexIO UART status flags.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
mask | Status flag. The parameter can be any combination of the following values:
- kFLEXIO_UART_TxDataRegEmptyFlag
- kFLEXIO_UART_RxEmptyFlag
- kFLEXIO_UART_RxOverRunFlag
|
This function enables the FlexIO UART interrupt.
- Parameters
-
This function disables the FlexIO UART interrupt.
- Parameters
-
This function returns the UART data register address, which is mainly used by DMA/eDMA.
- Parameters
-
- Returns
- FlexIO UART transmit data register address.
This function returns the UART data register address, which is mainly used by DMA/eDMA.
- Parameters
-
- Returns
- FlexIO UART receive data register address.
This function enables/disables the FlexIO UART Tx DMA, which means asserting the kFLEXIO_UART_TxDataRegEmptyFlag does/doesn't trigger the DMA request.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
enable | True to enable, false to disable. |
This function enables/disables the FlexIO UART Rx DMA, which means asserting kFLEXIO_UART_RxDataRegFullFlag does/doesn't trigger the DMA request.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
enable | True to enable, false to disable. |
- Parameters
-
base | Pointer to the FLEXIO_UART_Type. |
enable | True to enable, false does not have any effect. |
static void FLEXIO_UART_WriteByte |
( |
FLEXIO_UART_Type * |
base, |
|
|
const uint8_t * |
buffer |
|
) |
| |
|
inlinestatic |
- Note
- This is a non-blocking API, which returns directly after the data is put into the data register. Ensure that the TxEmptyFlag is asserted before calling this API.
- Parameters
-
- Note
- This is a non-blocking API, which returns directly after the data is read from the data register. Ensure that the RxFullFlag is asserted before calling this API.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
buffer | The buffer to store the received bytes. |
void FLEXIO_UART_WriteBlocking |
( |
FLEXIO_UART_Type * |
base, |
|
|
const uint8_t * |
txData, |
|
|
size_t |
txSize |
|
) |
| |
- Note
- This function blocks using the polling method until all bytes have been sent.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
txData | The data bytes to send. |
txSize | The number of data bytes to send. |
void FLEXIO_UART_ReadBlocking |
( |
FLEXIO_UART_Type * |
base, |
|
|
uint8_t * |
rxData, |
|
|
size_t |
rxSize |
|
) |
| |
- Note
- This function blocks using the polling method until all bytes have been received.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
rxData | The buffer to store the received bytes. |
rxSize | The number of data bytes to be received. |
This function initializes the FlexIO UART handle, which can be used for other FlexIO UART transactional APIs. Call this API once to get the initialized handle.
The UART driver supports the "background" receiving, which means that users can set up a RX ring buffer optionally. Data received is stored into the ring buffer even when the user doesn't call the FLEXIO_UART_TransferReceiveNonBlocking() API. If there is already data received in the ring buffer, users can get the received data from the ring buffer directly. The ring buffer is disabled if passing NULL as ringBuffer
.
- Parameters
-
base | to FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
callback | The callback function. |
userData | The parameter of the callback function. |
- Return values
-
kStatus_Success | Successfully create the handle. |
kStatus_OutOfRange | The FlexIO type/handle/ISR table out of range. |
void FLEXIO_UART_TransferStartRingBuffer |
( |
FLEXIO_UART_Type * |
base, |
|
|
flexio_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 is 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, users 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 | Pointer to the FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
ringBuffer | Start address of ring buffer for background receiving. Pass NULL to disable the ring buffer. |
ringBufferSize | Size of the ring buffer. |
void FLEXIO_UART_TransferStopRingBuffer |
( |
FLEXIO_UART_Type * |
base, |
|
|
flexio_uart_handle_t * |
handle |
|
) |
| |
This function aborts the background transfer and uninstalls the ring buffer.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
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 ISR, the FlexIO UART driver calls the callback function and passes the kStatus_FLEXIO_UART_TxIdle as status parameter.
- Note
- The kStatus_FLEXIO_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.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
xfer | FlexIO UART transfer structure. See flexio_uart_transfer_t. |
- Return values
-
kStatus_Success | Successfully starts the data transmission. |
kStatus_UART_TxBusy | Previous transmission still not finished, data not written to the TX register. |
void FLEXIO_UART_TransferAbortSend |
( |
FLEXIO_UART_Type * |
base, |
|
|
flexio_uart_handle_t * |
handle |
|
) |
| |
This function aborts the interrupt-driven data sending. Get the remainBytes to find out how many bytes are still not sent out.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
This function gets the number of bytes sent driven by interrupt.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
count | Number of bytes sent so far by the non-blocking transaction. |
- Return values
-
kStatus_NoTransferInProgress | transfer has finished or no transfer in progress. |
kStatus_Success | Successfully return the count. |
This function receives data using the 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 ring buffer is copied and the parameter receivedBytes
shows how many bytes are copied from the ring buffer. After copying, if the data in ring buffer is not enough to read, the receive request is saved by the UART driver. When 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, if the upper layer needs 10 bytes but there are only 5 bytes in the ring buffer, the 5 bytes are copied to xfer->data. This function returns with the parameter receivedBytes
set to 5. For the last 5 bytes, newly arrived data is saved from the xfer->data[5]. When 5 bytes are received, the UART driver notifies upper layer. If the RX ring buffer is not enabled, this function enables the RX and RX interrupt to receive data to xfer->data. When all data is received, the upper layer is notified.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
xfer | UART transfer structure. See flexio_uart_transfer_t. |
receivedBytes | Bytes received from the ring buffer directly. |
- Return values
-
kStatus_Success | Successfully queue the transfer into the transmit queue. |
kStatus_FLEXIO_UART_RxBusy | Previous receive request is not finished. |
void FLEXIO_UART_TransferAbortReceive |
( |
FLEXIO_UART_Type * |
base, |
|
|
flexio_uart_handle_t * |
handle |
|
) |
| |
This function aborts the receive data which was using IRQ.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
This function gets the number of bytes received driven by interrupt.
- Parameters
-
base | Pointer to the FLEXIO_UART_Type structure. |
handle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |
count | Number of bytes received so far by the non-blocking transaction. |
- Return values
-
kStatus_NoTransferInProgress | transfer has finished or no transfer in progress. |
kStatus_Success | Successfully return the count. |
void FLEXIO_UART_TransferHandleIRQ |
( |
void * |
uartType, |
|
|
void * |
uartHandle |
|
) |
| |
This function processes the FlexIO UART transmit and receives the IRQ request.
- Parameters
-
uartType | Pointer to the FLEXIO_UART_Type structure. |
uartHandle | Pointer to the flexio_uart_handle_t structure to store the transfer state. |