MCUXpresso SDK API Reference Manual
Rev. 0
NXP Semiconductors
|
Data Structures | |
struct | usart_config_t |
USART configuration structure. More... | |
struct | usart_transfer_t |
USART transfer structure. More... | |
struct | usart_handle_t |
USART handle structure. More... | |
Typedefs | |
typedef void(* | usart_transfer_callback_t )(USART_Type *base, usart_handle_t *handle, status_t status, void *userData) |
USART transfer callback function. More... | |
Enumerations | |
enum | _usart_status { kStatus_USART_TxBusy = MAKE_STATUS(kStatusGroup_LPC_USART, 0), kStatus_USART_RxBusy = MAKE_STATUS(kStatusGroup_LPC_USART, 1), kStatus_USART_TxIdle = MAKE_STATUS(kStatusGroup_LPC_USART, 2), kStatus_USART_RxIdle = MAKE_STATUS(kStatusGroup_LPC_USART, 3), kStatus_USART_TxError = MAKE_STATUS(kStatusGroup_LPC_USART, 7), kStatus_USART_RxError = MAKE_STATUS(kStatusGroup_LPC_USART, 9), kStatus_USART_RxRingBufferOverrun = MAKE_STATUS(kStatusGroup_LPC_USART, 8), kStatus_USART_NoiseError = MAKE_STATUS(kStatusGroup_LPC_USART, 10), kStatus_USART_FramingError = MAKE_STATUS(kStatusGroup_LPC_USART, 11), kStatus_USART_ParityError = MAKE_STATUS(kStatusGroup_LPC_USART, 12), kStatus_USART_BaudrateNotSupport } |
Error codes for the USART driver. More... | |
enum | usart_parity_mode_t { kUSART_ParityDisabled = 0x0U, kUSART_ParityEven = 0x2U, kUSART_ParityOdd = 0x3U } |
USART parity mode. More... | |
enum | usart_stop_bit_count_t { kUSART_OneStopBit = 0U, kUSART_TwoStopBit = 1U } |
USART stop bit count. More... | |
enum | usart_data_len_t { kUSART_7BitsPerChar = 0U, kUSART_8BitsPerChar = 1U } |
USART data size. More... | |
enum | usart_txfifo_watermark_t { kUSART_TxFifo0 = 0, kUSART_TxFifo1 = 1, kUSART_TxFifo2 = 2, kUSART_TxFifo3 = 3, kUSART_TxFifo4 = 4, kUSART_TxFifo5 = 5, kUSART_TxFifo6 = 6, kUSART_TxFifo7 = 7 } |
txFIFO watermark values More... | |
enum | usart_rxfifo_watermark_t { kUSART_RxFifo1 = 0, kUSART_RxFifo2 = 1, kUSART_RxFifo3 = 2, kUSART_RxFifo4 = 3, kUSART_RxFifo5 = 4, kUSART_RxFifo6 = 5, kUSART_RxFifo7 = 6, kUSART_RxFifo8 = 7 } |
rxFIFO watermark values More... | |
enum | _usart_interrupt_enable |
USART interrupt configuration structure, default settings all disabled. | |
enum | _usart_flags { kUSART_TxError = (USART_FIFOSTAT_TXERR_MASK), kUSART_RxError = (USART_FIFOSTAT_RXERR_MASK), kUSART_TxFifoEmptyFlag = (USART_FIFOSTAT_TXEMPTY_MASK), kUSART_TxFifoNotFullFlag = (USART_FIFOSTAT_TXNOTFULL_MASK), kUSART_RxFifoNotEmptyFlag = (USART_FIFOSTAT_RXNOTEMPTY_MASK), kUSART_RxFifoFullFlag = (USART_FIFOSTAT_RXFULL_MASK) } |
USART status flags. More... | |
Functions | |
uint32_t | USART_GetInstance (USART_Type *base) |
Returns instance number for USART peripheral base address. More... | |
Driver version | |
#define | FSL_USART_DRIVER_VERSION (MAKE_VERSION(2, 0, 0)) |
USART driver version 2.0.0. More... | |
Initialization and deinitialization | |
status_t | USART_Init (USART_Type *base, const usart_config_t *config, uint32_t srcClock_Hz) |
Initializes a USART instance with user configuration structure and peripheral clock. More... | |
void | USART_Deinit (USART_Type *base) |
Deinitializes a USART instance. More... | |
void | USART_GetDefaultConfig (usart_config_t *config) |
Gets the default configuration structure. More... | |
status_t | USART_SetBaudRate (USART_Type *base, uint32_t baudrate_Bps, uint32_t srcClock_Hz) |
Sets the USART instance baud rate. More... | |
Status | |
static uint32_t | USART_GetStatusFlags (USART_Type *base) |
Get USART status flags. More... | |
static void | USART_ClearStatusFlags (USART_Type *base, uint32_t mask) |
Clear USART status flags. More... | |
Interrupts | |
static void | USART_EnableInterrupts (USART_Type *base, uint32_t mask) |
Enables USART interrupts according to the provided mask. More... | |
static void | USART_DisableInterrupts (USART_Type *base, uint32_t mask) |
Disables USART interrupts according to a provided mask. More... | |
static uint32_t | USART_GetEnabledInterrupts (USART_Type *base) |
Returns enabled USART interrupts. More... | |
static void | USART_EnableTxDMA (USART_Type *base, bool enable) |
Enable DMA for Tx. | |
static void | USART_EnableRxDMA (USART_Type *base, bool enable) |
Enable DMA for Rx. | |
Bus Operations | |
static void | USART_WriteByte (USART_Type *base, uint8_t data) |
Writes to the FIFOWR register. More... | |
static uint8_t | USART_ReadByte (USART_Type *base) |
Reads the FIFORD register directly. More... | |
void | USART_WriteBlocking (USART_Type *base, const uint8_t *data, size_t length) |
Writes to the TX register using a blocking method. More... | |
status_t | USART_ReadBlocking (USART_Type *base, uint8_t *data, size_t length) |
Read RX data register using a blocking method. More... | |
Transactional | |
status_t | USART_TransferCreateHandle (USART_Type *base, usart_handle_t *handle, usart_transfer_callback_t callback, void *userData) |
Initializes the USART handle. More... | |
status_t | USART_TransferSendNonBlocking (USART_Type *base, usart_handle_t *handle, usart_transfer_t *xfer) |
Transmits a buffer of data using the interrupt method. More... | |
void | USART_TransferStartRingBuffer (USART_Type *base, usart_handle_t *handle, uint8_t *ringBuffer, size_t ringBufferSize) |
Sets up the RX ring buffer. More... | |
void | USART_TransferStopRingBuffer (USART_Type *base, usart_handle_t *handle) |
Aborts the background transfer and uninstalls the ring buffer. More... | |
size_t | USART_TransferGetRxRingBufferLength (usart_handle_t *handle) |
Get the length of received data in RX ring buffer. More... | |
void | USART_TransferAbortSend (USART_Type *base, usart_handle_t *handle) |
Aborts the interrupt-driven data transmit. More... | |
status_t | USART_TransferGetSendCount (USART_Type *base, usart_handle_t *handle, uint32_t *count) |
Get the number of bytes that have been written to USART TX register. More... | |
status_t | USART_TransferReceiveNonBlocking (USART_Type *base, usart_handle_t *handle, usart_transfer_t *xfer, size_t *receivedBytes) |
Receives a buffer of data using an interrupt method. More... | |
void | USART_TransferAbortReceive (USART_Type *base, usart_handle_t *handle) |
Aborts the interrupt-driven data receiving. More... | |
status_t | USART_TransferGetReceiveCount (USART_Type *base, usart_handle_t *handle, uint32_t *count) |
Get the number of bytes that have been received. More... | |
void | USART_TransferHandleIRQ (USART_Type *base, usart_handle_t *handle) |
USART IRQ handle function. More... | |
struct usart_config_t |
Data Fields | |
uint32_t | baudRate_Bps |
USART baud rate. | |
usart_parity_mode_t | parityMode |
Parity mode, disabled (default), even, odd. | |
usart_stop_bit_count_t | stopBitCount |
Number of stop bits, 1 stop bit (default) or 2 stop bits. | |
usart_data_len_t | bitCountPerChar |
Data length - 7 bit, 8 bit. | |
bool | loopback |
Enable peripheral loopback. | |
bool | enableRx |
Enable RX. | |
bool | enableTx |
Enable TX. | |
usart_txfifo_watermark_t | txWatermark |
txFIFO watermark | |
usart_rxfifo_watermark_t | rxWatermark |
rxFIFO watermark | |
struct usart_transfer_t |
struct _usart_handle |
Data Fields | |
uint8_t *volatile | txData |
Address of remaining data to send. More... | |
volatile size_t | txDataSize |
Size of the remaining data to send. More... | |
size_t | txDataSizeAll |
Size of the data to send out. More... | |
uint8_t *volatile | rxData |
Address of remaining data to receive. More... | |
volatile size_t | rxDataSize |
Size of the remaining data to receive. More... | |
size_t | rxDataSizeAll |
Size of the data to receive. More... | |
uint8_t * | rxRingBuffer |
Start address of the receiver ring buffer. More... | |
size_t | rxRingBufferSize |
Size of the ring buffer. More... | |
volatile uint16_t | rxRingBufferHead |
Index for the driver to store received data into ring buffer. More... | |
volatile uint16_t | rxRingBufferTail |
Index for the user to get data from the ring buffer. More... | |
usart_transfer_callback_t | callback |
Callback function. More... | |
void * | userData |
USART callback function parameter. More... | |
volatile uint8_t | txState |
TX transfer state. More... | |
volatile uint8_t | rxState |
RX transfer state. | |
usart_txfifo_watermark_t | txWatermark |
txFIFO watermark | |
usart_rxfifo_watermark_t | rxWatermark |
rxFIFO watermark | |
uint8_t* volatile usart_handle_t::txData |
volatile size_t usart_handle_t::txDataSize |
size_t usart_handle_t::txDataSizeAll |
uint8_t* volatile usart_handle_t::rxData |
volatile size_t usart_handle_t::rxDataSize |
size_t usart_handle_t::rxDataSizeAll |
uint8_t* usart_handle_t::rxRingBuffer |
size_t usart_handle_t::rxRingBufferSize |
volatile uint16_t usart_handle_t::rxRingBufferHead |
volatile uint16_t usart_handle_t::rxRingBufferTail |
usart_transfer_callback_t usart_handle_t::callback |
void* usart_handle_t::userData |
volatile uint8_t usart_handle_t::txState |
#define FSL_USART_DRIVER_VERSION (MAKE_VERSION(2, 0, 0)) |
typedef void(* usart_transfer_callback_t)(USART_Type *base, usart_handle_t *handle, status_t status, void *userData) |
enum _usart_status |
enum usart_parity_mode_t |
enum usart_data_len_t |
enum _usart_flags |
This provides constants for the USART status flags for use in the USART functions.
uint32_t USART_GetInstance | ( | USART_Type * | base | ) |
status_t USART_Init | ( | USART_Type * | base, |
const usart_config_t * | config, | ||
uint32_t | srcClock_Hz | ||
) |
This function configures the USART module with the user-defined settings. The user can configure the configuration structure and also get the default configuration by using the USART_GetDefaultConfig() function. Example below shows how to use this API to configure USART.
base | USART peripheral base address. |
config | Pointer to user-defined configuration structure. |
srcClock_Hz | USART clock source frequency in HZ. |
kStatus_USART_BaudrateNotSupport | Baudrate is not support in current clock source. |
kStatus_InvalidArgument | USART base address is not valid |
kStatus_Success | Status USART initialize succeed |
void USART_Deinit | ( | USART_Type * | base | ) |
This function waits for TX complete, disables TX and RX, and disables the USART clock.
base | USART peripheral base address. |
void USART_GetDefaultConfig | ( | usart_config_t * | config | ) |
This function initializes the USART configuration structure to a default value. The default values are: usartConfig->baudRate_Bps = 115200U; usartConfig->parityMode = kUSART_ParityDisabled; usartConfig->stopBitCount = kUSART_OneStopBit; usartConfig->bitCountPerChar = kUSART_8BitsPerChar; usartConfig->loopback = false; usartConfig->enableTx = false; usartConfig->enableRx = false;
config | Pointer to configuration structure. |
status_t USART_SetBaudRate | ( | USART_Type * | base, |
uint32_t | baudrate_Bps, | ||
uint32_t | srcClock_Hz | ||
) |
This function configures the USART module baud rate. This function is used to update the USART module baud rate after the USART module is initialized by the USART_Init.
base | USART peripheral base address. |
baudrate_Bps | USART baudrate to be set. |
srcClock_Hz | USART clock source freqency in HZ. |
kStatus_USART_BaudrateNotSupport | Baudrate is not support in current clock source. |
kStatus_Success | Set baudrate succeed. |
kStatus_InvalidArgument | One or more arguments are invalid. |
|
inlinestatic |
This function get all USART status flags, the flags are returned as the logical OR value of the enumerators _usart_flags. To check a specific status, compare the return value with enumerators in _usart_flags. For example, to check whether the TX is empty:
base | USART peripheral base address. |
|
inlinestatic |
This function clear supported USART status flags Flags that can be cleared or set are: kUSART_TxError kUSART_RxError For example:
base | USART peripheral base address. |
mask | status flags to be cleared. |
|
inlinestatic |
This function enables the USART interrupts according to the provided mask. The mask is a logical OR of enumeration members. See _usart_interrupt_enable. For example, to enable TX empty interrupt and RX full interrupt:
base | USART peripheral base address. |
mask | The interrupts to enable. Logical OR of _usart_interrupt_enable. |
|
inlinestatic |
This function disables the USART interrupts according to a provided mask. The mask is a logical OR of enumeration members. See _usart_interrupt_enable. This example shows how to disable the TX empty interrupt and RX full interrupt:
base | USART peripheral base address. |
mask | The interrupts to disable. Logical OR of _usart_interrupt_enable. |
|
inlinestatic |
This function returns the enabled USART interrupts.
base | USART peripheral base address. |
|
inlinestatic |
This function writes data to the txFIFO directly. The upper layer must ensure that txFIFO has space for data to write before calling this function.
base | USART peripheral base address. |
data | The byte to write. |
|
inlinestatic |
This function reads data from the rxFIFO directly. The upper layer must ensure that the rxFIFO is not empty before calling this function.
base | USART peripheral base address. |
void USART_WriteBlocking | ( | USART_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.
base | USART peripheral base address. |
data | Start address of the data to write. |
length | Size of the data to write. |
status_t USART_ReadBlocking | ( | USART_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 read data from the TX register.
base | USART peripheral base address. |
data | Start address of the buffer to store the received data. |
length | Size of the buffer. |
kStatus_USART_FramingError | Receiver overrun happened while receiving data. |
kStatus_USART_ParityError | Noise error happened while receiving data. |
kStatus_USART_NoiseError | Framing error happened while receiving data. |
kStatus_USART_RxError | Overflow or underflow rxFIFO happened. |
kStatus_Success | Successfully received all data. |
status_t USART_TransferCreateHandle | ( | USART_Type * | base, |
usart_handle_t * | handle, | ||
usart_transfer_callback_t | callback, | ||
void * | userData | ||
) |
This function initializes the USART handle which can be used for other USART transactional APIs. Usually, for a specified USART instance, call this API once to get the initialized handle.
base | USART peripheral base address. |
handle | USART handle pointer. |
callback | The callback function. |
userData | The parameter of the callback function. |
status_t USART_TransferSendNonBlocking | ( | USART_Type * | base, |
usart_handle_t * | handle, | ||
usart_transfer_t * | xfer | ||
) |
This function sends data using an interrupt method. This is a non-blocking function, which returns directly without waiting for all data to be written to the TX register. When all data is written to the TX register in the IRQ handler, the USART driver calls the callback function and passes the kStatus_USART_TxIdle as status parameter.
base | USART peripheral base address. |
handle | USART handle pointer. |
xfer | USART transfer structure. See usart_transfer_t. |
kStatus_Success | Successfully start the data transmission. |
kStatus_USART_TxBusy | Previous transmission still not finished, data not all written to TX register yet. |
kStatus_InvalidArgument | Invalid argument. |
void USART_TransferStartRingBuffer | ( | USART_Type * | base, |
usart_handle_t * | handle, | ||
uint8_t * | ringBuffer, | ||
size_t | ringBufferSize | ||
) |
This function sets up the RX ring buffer to a specific USART handle.
When the RX ring buffer is used, data received are stored into the ring buffer even when the user doesn't call the USART_TransferReceiveNonBlocking() API. If there is already data received in the ring buffer, the user can get the received data from the ring buffer directly.
ringBufferSize
is 32, then only 31 bytes are used for saving data.base | USART peripheral base address. |
handle | USART 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 USART_TransferStopRingBuffer | ( | USART_Type * | base, |
usart_handle_t * | handle | ||
) |
This function aborts the background transfer and uninstalls the ring buffer.
base | USART peripheral base address. |
handle | USART handle pointer. |
size_t USART_TransferGetRxRingBufferLength | ( | usart_handle_t * | handle | ) |
handle | USART handle pointer. |
void USART_TransferAbortSend | ( | USART_Type * | base, |
usart_handle_t * | handle | ||
) |
This function aborts the interrupt driven data sending. The user can get the remainBtyes to find out how many bytes are still not sent out.
base | USART peripheral base address. |
handle | USART handle pointer. |
status_t USART_TransferGetSendCount | ( | USART_Type * | base, |
usart_handle_t * | handle, | ||
uint32_t * | count | ||
) |
This function gets the number of bytes that have been written to USART TX register by interrupt method.
base | USART peripheral base address. |
handle | USART handle pointer. |
count | Send bytes count. |
kStatus_NoTransferInProgress | No send in progress. |
kStatus_InvalidArgument | Parameter is invalid. |
kStatus_Success | Get successfully through the parameter count ; |
status_t USART_TransferReceiveNonBlocking | ( | USART_Type * | base, |
usart_handle_t * | handle, | ||
usart_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 USART driver. When the new data arrives, the receive request is serviced first. When all data is received, the USART driver notifies the upper layer through a callback function and passes the status parameter kStatus_USART_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 USART 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.
base | USART peripheral base address. |
handle | USART handle pointer. |
xfer | USART transfer structure, see usart_transfer_t. |
receivedBytes | Bytes received from the ring buffer directly. |
kStatus_Success | Successfully queue the transfer into transmit queue. |
kStatus_USART_RxBusy | Previous receive request is not finished. |
kStatus_InvalidArgument | Invalid argument. |
void USART_TransferAbortReceive | ( | USART_Type * | base, |
usart_handle_t * | handle | ||
) |
This function aborts the interrupt-driven data receiving. The user can get the remainBytes to find out how many bytes not received yet.
base | USART peripheral base address. |
handle | USART handle pointer. |
status_t USART_TransferGetReceiveCount | ( | USART_Type * | base, |
usart_handle_t * | handle, | ||
uint32_t * | count | ||
) |
This function gets the number of bytes that have been received.
base | USART peripheral base address. |
handle | USART handle pointer. |
count | Receive bytes count. |
kStatus_NoTransferInProgress | No receive in progress. |
kStatus_InvalidArgument | Parameter is invalid. |
kStatus_Success | Get successfully through the parameter count ; |
void USART_TransferHandleIRQ | ( | USART_Type * | base, |
usart_handle_t * | handle | ||
) |
This function handles the USART transmit and receive IRQ request.
base | USART peripheral base address. |
handle | USART handle pointer. |