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 optimization/customization purpose. 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 Send/Receive using the DMA method
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/uart
|
#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...
|
|
|
enum | {
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),
kStatus_UART_NoiseError = MAKE_STATUS(kStatusGroup_UART, 10),
kStatus_UART_FramingError = MAKE_STATUS(kStatusGroup_UART, 11),
kStatus_UART_ParityError = MAKE_STATUS(kStatusGroup_UART, 12),
kStatus_UART_BaudrateNotSupport,
kStatus_UART_IdleLineDetected = MAKE_STATUS(kStatusGroup_UART, 14),
kStatus_UART_Timeout = MAKE_STATUS(kStatusGroup_UART, 15)
} |
| 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_idle_type_select_t {
kUART_IdleTypeStartBit = 0U,
kUART_IdleTypeStopBit = 1U
} |
| UART idle type select. 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_RXOFE_MASK << 24),
kUART_TxFifoOverflowInterruptEnable = (UART_CFIFO_TXOFE_MASK << 24),
kUART_RxFifoUnderflowInterruptEnable = (UART_CFIFO_RXUFE_MASK << 24)
} |
| UART interrupt configuration structure, default settings all disabled. More...
|
|
enum | {
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,
kUART_RxActiveEdgeFlag,
kUART_RxActiveFlag,
kUART_NoiseErrorInRxDataRegFlag = (UART_ED_NOISY_MASK << 16),
kUART_ParityErrorInRxDataRegFlag = (UART_ED_PARITYE_MASK << 16),
kUART_TxFifoEmptyFlag = (int)(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...
|
|
|
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 sent out to bus. 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...
|
|
status_t | UART_EnableTxFIFO (UART_Type *base, bool enable) |
| Enables or disables the UART Tx FIFO. More...
|
|
status_t | UART_EnableRxFIFO (UART_Type *base, bool enable) |
| Enables or disables the UART Rx FIFO. More...
|
|
void | UART_TransferHandleIRQ (UART_Type *base, uart_handle_t *handle) |
| UART IRQ handle function. More...
|
|
void | UART_TransferHandleErrorIRQ (UART_Type *base, uart_handle_t *handle) |
| UART Error IRQ handle function. More...
|
|
uint8_t* uart_transfer_t::data |
size_t uart_transfer_t::dataSize |
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 |
void* uart_handle_t::userData |
volatile uint8_t uart_handle_t::txState |
#define UART_RETRY_TIMES 0U /* Defining to zero means to keep waiting for the flag until it is assert/deassert. */ |
typedef void(* uart_transfer_callback_t)(UART_Type *base, uart_handle_t *handle, status_t status, void *userData) |
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_IdleLineDetected |
UART IDLE line detected.
|
kStatus_UART_Timeout |
UART times out.
|
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.
|
Enumerator |
---|
kUART_OneStopBit |
One stop bit.
|
kUART_TwoStopBit |
Two stop bits.
|
Enumerator |
---|
kUART_IdleTypeStartBit |
Start counting after a valid start bit.
|
kUART_IdleTypeStopBit |
Start counting after a stop bit.
|
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 |
RX FIFO overflow interrupt.
|
kUART_TxFifoOverflowInterruptEnable |
TX FIFO overflow interrupt.
|
kUART_RxFifoUnderflowInterruptEnable |
RX FIFO underflow interrupt.
|
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 |
Parity 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.
|
uint32_t UART_GetInstance |
( |
UART_Type * |
base | ) |
|
- Parameters
-
base | UART peripheral base address. |
- Returns
- UART instance.
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. The example below shows how to use this API to configure UART.
- Parameters
-
base | UART peripheral base address. |
config | Pointer to the user-defined configuration structure. |
srcClock_Hz | UART clock source frequency in HZ. |
- Return values
-
kStatus_UART_BaudrateNotSupport | Baudrate is not support in current clock source. |
kStatus_Success | Status UART initialize succeed |
void UART_Deinit |
( |
UART_Type * |
base | ) |
|
This function waits for TX complete, disables TX and RX, and disables the UART clock.
- Parameters
-
base | UART peripheral base address. |
This function initializes the UART configuration structure to a default value. The default values are as follows. uartConfig->baudRate_Bps = 115200U; uartConfig->bitCountPerChar = kUART_8BitsPerChar; uartConfig->parityMode = kUART_ParityDisabled; uartConfig->stopBitCount = kUART_OneStopBit; uartConfig->txFifoWatermark = 0; uartConfig->rxFifoWatermark = 1; uartConfig->idleType = kUART_IdleTypeStartBit; uartConfig->enableTx = false; uartConfig->enableRx = false;
- Parameters
-
config | Pointer to 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.
- 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. |
void UART_Enable9bitMode |
( |
UART_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
This function set the 9-bit mode for UART module. The 9th bit is not used for parity thus can be modified by user.
- Parameters
-
base | UART peripheral base address. |
enable | true to enable, flase to disable. |
static void UART_SetMatchAddress |
( |
UART_Type * |
base, |
|
|
uint8_t |
address1, |
|
|
uint8_t |
address2 |
|
) |
| |
|
inlinestatic |
This function configures the address for UART module that works as slave in 9-bit data mode. One or two address fields can be configured. When the address field's match enable bit is set, the frame it receices with MSB being 1 is considered as an address frame, otherwise it is considered as data frame. Once the address frame matches one of slave's own addresses, this slave is addressed. This address frame and its following data frames are stored in the receive buffer, otherwise the frames will be discarded. To un-address a slave, just send an address frame with unmatched address.
- Note
- Any UART instance joined in the multi-slave system can work as slave. The position of the address mark is the same as the parity bit when parity is enabled for 8 bit and 9 bit data formats.
- Parameters
-
base | UART peripheral base address. |
address1 | UART slave address 1. |
address2 | UART slave address 2. |
static void UART_EnableMatchAddress |
( |
UART_Type * |
base, |
|
|
bool |
match1, |
|
|
bool |
match2 |
|
) |
| |
|
inlinestatic |
- Parameters
-
base | UART peripheral base address. |
match1 | true to enable match address1, false to disable. |
match2 | true to enable match address2, false to disable. |
static void UART_Set9thTransmitBit |
( |
UART_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
base | UART peripheral base address. |
static void UART_Clear9thTransmitBit |
( |
UART_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
base | UART peripheral base address. |
uint32_t UART_GetStatusFlags |
( |
UART_Type * |
base | ) |
|
This function gets all UART status flags. The flags are returned as the logical OR value of the enumerators _uart_flags. To check a specific status, compare the return value with enumerators in _uart_flags. For example, to check whether the TX is empty, do the following.
- Parameters
-
base | UART peripheral base address. |
- Returns
- UART status flags which are ORed by the enumerators in the _uart_flags.
status_t UART_ClearStatusFlags |
( |
UART_Type * |
base, |
|
|
uint32_t |
mask |
|
) |
| |
This function clears UART status flags with a provided mask. An automatically cleared flag can't be cleared by this function. These flags can only be cleared or set by hardware. kUART_TxDataRegEmptyFlag, kUART_TransmissionCompleteFlag, kUART_RxDataRegFullFlag, kUART_RxActiveFlag, kUART_NoiseErrorInRxDataRegFlag, kUART_ParityErrorInRxDataRegFlag, kUART_TxFifoEmptyFlag,kUART_RxFifoEmptyFlag
- Note
- that this API should be called when the Tx/Rx is idle. Otherwise it has no effect.
- 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 is cleared. |
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 full interrupt, do the following.
- Parameters
-
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 full interrupt do the following.
- Parameters
-
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 interrupts enable status, compare the return value with enumerators in _uart_interrupt_enable. For example, to check whether TX empty interrupt is enabled, do the following.
- Parameters
-
base | UART peripheral base address. |
- Returns
- UART interrupt flags which are logical OR of the enumerators in _uart_interrupt_enable.
static uint32_t UART_GetDataRegisterAddress |
( |
UART_Type * |
base | ) |
|
|
inlinestatic |
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 addresses which are used both by the transmitter and the receiver.
static void UART_EnableTxDMA |
( |
UART_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
|
inlinestatic |
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 void UART_EnableRxDMA |
( |
UART_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
|
inlinestatic |
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 |
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 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. |
static uint8_t UART_ReadByte |
( |
UART_Type * |
base | ) |
|
|
inlinestatic |
This function reads data from the RX 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.
void UART_SendAddress |
( |
UART_Type * |
base, |
|
|
uint8_t |
address |
|
) |
| |
- Parameters
-
base | UART peripheral base address. |
address | UART slave address. |
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.
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 sent out to bus 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 ; |
status_t UART_EnableTxFIFO |
( |
UART_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
This function enables or disables the UART Tx FIFO.
param base UART peripheral base address. param enable true to enable, false to disable. retval kStatus_Success Successfully turn on or turn off Tx FIFO. retval kStatus_Fail Fail to turn on or turn off Tx FIFO.
status_t UART_EnableRxFIFO |
( |
UART_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
This function enables or disables the UART Rx FIFO.
param base UART peripheral base address. param enable true to enable, false to disable. retval kStatus_Success Successfully turn on or turn off Rx FIFO. retval kStatus_Fail Fail to turn on or turn off Rx FIFO.
void UART_TransferHandleIRQ |
( |
UART_Type * |
base, |
|
|
uart_handle_t * |
handle |
|
) |
| |
This function handles the UART transmit and receive IRQ request.
- Parameters
-
base | UART peripheral base address. |
handle | UART handle pointer. |
void UART_TransferHandleErrorIRQ |
( |
UART_Type * |
base, |
|
|
uart_handle_t * |
handle |
|
) |
| |
This function handles the UART error IRQ request.
- Parameters
-
base | UART peripheral base address. |
handle | UART handle pointer. |