| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures
UART Peripheral Driver
Universal Asynchronous Receiver/Transmitter (UART)

The section describes the programming interface of the UART Peripheral driver. More...

## Data Structures
struct | uart_state_t
| Runtime state of the UART driver. More...
struct | uart_user_config_t
| User configuration structure for UART driver. More...

## UART Driver
uart_status_t | uart_init (uint32_t uartInstance, uart_state_t *uartState, const uart_user_config_t *uartUserConfig)
| This function initializes a UART instance for operation. More...
uart_status_t | uart_send_data (uart_state_t *uartState, const uint8_t *sendBuffer, uint32_t txByteCount, uint32_t timeout)
| This function sends (transmits) data out through the UART module using a blocking method. More...
uart_status_t | uart_send_data_async (uart_state_t *uartState, const uint8_t *sendBuffer, uint32_t txByteCount)
| This function sends (transmits) data through the UART module using a non-blocking method. More...
uart_status_t | uart_get_transmit_status (uart_state_t *uartState, uint32_t *bytesTransmitted)
| This function returns whether the previous UART transmit has finished. More...
uart_status_t | uart_get_receive_status (uart_state_t *uartState, uint32_t *bytesReceived)
| This function returns whether the previous UART receive is complete. More...
void | uart_shutdown (uart_state_t *uartState)
| This function shuts down the UART by disabling interrupts and the transmitter/receiver. More...
uart_status_t | uart_receive_data (uart_state_t *uartState, uint8_t *rxBuffer, uint32_t requestedByteCount, uint32_t timeout)
| This function gets (receives) data from the UART module using a blocking method. More...
uart_status_t | uart_receive_data_async (uart_state_t *uartState, uint8_t *rxBuffer, uint32_t requestedByteCount)
| This function gets (receives) data from the UART module using a non-blocking method. More...
uart_status_t | uart_abort_sending_data (uart_state_t *uartState)
| This function terminates an asynchronous UART transmission early. More...
uart_status_t | uart_abort_receiving_data (uart_state_t *uartState)
| This function terminates an asynchronous UART receive early. More...

### UART Peripheral Driver

# Overview

The UART peripheral driver is used to transfer data to and from external devices on the Universal Asynchronous Receiver/Transmitter (UART) serial bus. It provides a way to transmit and receive buffers of data with a single function call.

# Device structs

The driver uses an instantiation of the uart_state_t structure to maintain the current state of a particular UART instance module driver. This struct holds data that are 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 init. The user is only responsible to pass in the memory for this run-time state structure where the UART driver will take care of filling out the members.

# User config structs

The UART driver uses instances of the user configuration structure uart_user_config_t for the UART driver. This allows you to configure 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; the number of bits per data word.

# Initialization

To initialize the UART driver, call uart_init() and pass the instance number of the UART peripheral you want to use, 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 init function. Then, 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 for user
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, 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. uart_user_config_t instantiation can be easily modified to configure the UART peripheral 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 is an example of how to make the uart_init() function call given the user configuration structure previously given, as well as for UART instance 0.
uint32_t uartInstance = 0;
uart_state_t uartState; // user provides memory for the driver state structure
uart_init(uartInstance, &uartConfig, &uartState);

# Transfers

The driver implements transmit and receive functions to transfer buffers of data. The driver also supports two different modes for transferring data: blocking and non-blocking.The blocking transmit and receive functions are uart_send_data() and uart_receive_data().The non-blocking (async) transmit and receive functions are uart_send_data_async() and uart_receive_data_async().In all cases mentioned here, the functions are interrupt driven.The following code examples show how to use the aforementioned functions. First, it is assumed 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_receive_data function
uint32_t byteCount = sizeof(sourceBuff);
uint32_t readByteCount = 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_send_data(&uartState, sourceBuff, byteCount, 1); // function won't return until transmit is complete
uart_receive_data(&uartState, 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 txCurrentByteCount, readByteCount;
// assume pTxBuff and txCurrentByteCount have been initialized
uart_send_data_async(&uartState, pTxBuff, txCurrentByteCount);
// now check on status of transmit and wait until done, the code can do something else and
// check back later, this is just an example
while (uart_get_transmit_status(&uartState, &bytesTransmittedCount) == kStatus_UART_TxBusy);
// for receive, assume rxBuff is set up to receive data and readByteCount is initialized
uart_receive_data_async(&uartState, rxBuff, readByteCount);
// now check on status of receive and wait until done, the code can do something else and
// check back later, this is just an example
while (uart_get_receive_status(&uartState, &bytesReceivedCount) == kStatus_UART_RxBusy);

## Data Structure Documentation

struct uart_state_t

This struct 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 is only responsible to pass in the memory for this run-time state structure where the UART driver will take care of filling out the members.

### Data Fields
uint32_t | instance
| UART module instance number. More...
volatile bool | isTransmitInProgress
| True if there is an active transmit. More...
bool | isTransmitAsync
| Whether the transmit is asynchronous or not. More...
const uint8_t * | sendBuffer
| The buffer of data being sent. More...
volatile size_t | remainingSendByteCount
| The remaining number of bytes to be transmitted. More...
volatile size_t | transmittedByteCount
| Number of bytes transmitted so far. More...
volatile bool | isReceiveInProgress
| True if there is an active receive. More...
bool | isReceiveAsync
| Whether the receive is asynchronous or not. More...
uint8_t * | receiveBuffer
| The buffer of received data. More...
volatile size_t | remainingReceiveByteCount
| The remaining number of bytes to be received. More...
volatile size_t | receivedByteCount
| Number of bytes received so far. More...
sync_object_t | txIrqSync
| Used to wait for ISR to complete its TX business. More...
sync_object_t | rxIrqSync
| Used to wait for ISR to complete its RX business. More...
uint8_t | txFifoEntryCount
| Number of data word entries in TX FIFO. More...

#### Field Documentation

uint32_t uart_state_t::instance

volatile bool uart_state_t::isTransmitInProgress

bool uart_state_t::isTransmitAsync

const uint8_t* uart_state_t::sendBuffer

volatile size_t uart_state_t::remainingSendByteCount

volatile size_t uart_state_t::transmittedByteCount

volatile bool uart_state_t::isReceiveInProgress

bool uart_state_t::isReceiveAsync

uint8_t* uart_state_t::receiveBuffer

volatile size_t uart_state_t::remainingReceiveByteCount

volatile size_t uart_state_t::receivedByteCount

sync_object_t uart_state_t::txIrqSync

sync_object_t uart_state_t::rxIrqSync

uint8_t uart_state_t::txFifoEntryCount

struct uart_user_config_t

Use an instance of this struct with uart_init(). This allows you to configure 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; 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_init | ( | uint32_t | uartInstance,
|  | uart_state_t * | uartState,
|  | const uart_user_config_t * | uartUserConfig
| ) |  |

This function will initialize the run-time state structure to keep track of the on-going transfers, ungate the clock to the UART module, initialize the module to user defined settings and default settings, configure the IRQ state structure and enable the module-level interrupt to the core, and enable the UART module transmitter and receiver. The following is an example of how to set up the uart_state_t and the uart_user_config_t parameters and how to call the uart_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_init(uartInstance, &uartState, &uartConfig);

Parameters

  uartInstance | The UART module instance number.
  uartState | A pointer to the UART driver state structure memory. The user is only responsible to pass in the memory for this run-time state structure where the UART driver will take care of filling out the members. This 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 is responsbile to fill out the members of this structure and to pass the pointer of this struct into this function.

Returns
  An error code or kStatus_UART_Success.

uart_status_t uart_send_data | ( | uart_state_t * | uartState,
|  | const uint8_t * | sendBuffer,
|  | uint32_t | txByteCount,
|  | 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

  uartInstance | The UART module instance number.
  sendBuffer | A pointer to the source buffer containing 8-bit data chars to send.
  txByteCount | The number of bytes to send.
  timeout | A timeout value for RTOS abstraction sync control in milli-seconds (ms).

Returns
  An error code or kStatus_UART_Success.

uart_status_t uart_send_data_async | ( | uart_state_t * | uartState,
|  | const uint8_t * | sendBuffer,
|  | uint32_t | txByteCount
| ) |  |

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 completed or not. The asynchronous method of transmitting and receiving allows the UART to perform a full duplex operation (simultaneously transmit and receive).

Parameters

  uartState | A pointer to the UART driver state structure.
  sendBuffer | A pointer to the source buffer containing 8-bit data chars to send.
  txByteCount | The number of bytes to send.

Returns
  An error code or kStatus_UART_Success.

uart_status_t uart_get_transmit_status | ( | uart_state_t * | uartState,
|  | uint32_t * | bytesTransmitted
| ) |  |

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

Parameters

  uartState | A pointer to the UART driver state structure.
  bytesTransmitted | A pointer to a value that is filled in with the number of bytes that are sent in the active transfer.

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_get_receive_status | ( | uart_state_t * | uartState,
|  | uint32_t * | bytesReceived
| ) |  |

When performing an async receive, the user can call this function to ascertain 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

  uartState | A pointer to the UART driver state structure.
  bytesReceived | A pointer to a value that is filled in with the number of bytes which are received in the active transfer.

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.

void uart_shutdown | ( | uart_state_t * | uartState | ) |

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

Parameters

  uartState | A pointer to the UART driver state structure.

uart_status_t uart_receive_data | ( | uart_state_t * | uartState,
|  | uint8_t * | rxBuffer,
|  | uint32_t | requestedByteCount,
|  | 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 is used to send data through the UART port.

Parameters

  uartState | A pointer to the UART driver state structure.
  rxBuffer | A pointer to the buffer containing 8-bit read data chars received.
  requestedByteCount | The number of bytes to receive.
  timeout | A timeout value for RTOS abstraction sync control in milli-seconds (ms).

Returns
  An error code or kStatus_UART_Success.

uart_status_t uart_receive_data_async | ( | uart_state_t * | uartState,
|  | uint8_t * | rxBuffer,
|  | uint32_t | requestedByteCount
| ) |  |

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

  uartState | A pointer to the UART driver state structure.
  rxBuffer | A pointer to the buffer containing 8-bit read data chars received.
  requestedByteCount | The number of bytes to receive.

Returns
  An error code or kStatus_UART_Success.

uart_status_t uart_abort_sending_data | ( | uart_state_t * | uartState | ) |

During an async UART tranmission, the user has the option to terminate the transmission early if the transmission is still in progress.

Parameters

  uartState | A pointer to the UART driver state structure.

Return values

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

uart_status_t uart_abort_receiving_data | ( | uart_state_t * | uartState | ) |

During an async UART receive, the user has the option to terminate the receive early if the receive is still in progress.

Parameters

  uartState | A pointer to the UART driver state structure.

Return values

  kStatus_UART_Success | The receive was succesful.
  kStatus_UART_NoTransmitInProgress | No receive is currently in progress.