Collaboration diagram for Universal Asynchronous Receiver-Transmitter (UART):

Modules
	UART driver APIs

	UART driver supporting APIs

	UART status codes

Data Structures
struct	UART_Params
	UART Parameters. More...

Typedefs
typedef struct UART_Config_ *	UART_Handle
	A handle that is returned from a UART_open() call.

typedef void(*	UART_Callback) (UART_Handle handle, void buf, size_t count, void userArg, int_fast16_t status)
	The definition of a callback function used by the UART driver when used in UART_Mode_CALLBACK. The callback can occur in task or interrupt context. More...

typedef void(*	UART_EventCallback) (UART_Handle handle, uint32_t event, uint32_t data, void *userArg)
	The definition of a callback function used by the UART driver. The callback can occur in task or interrupt context. More...

Enumerations
enum	UART_Mode { UART_Mode_BLOCKING = 0, UART_Mode_CALLBACK, UART_Mode_NONBLOCKING }
	UART mode settings. More...

enum	UART_ReadReturnMode { UART_ReadReturnMode_FULL = 0, UART_ReadReturnMode_PARTIAL }
	UART return mode settings. More...

enum	UART_DataLen { UART_DataLen_5 = DL_UART_WORD_LENGTH_5_BITS, UART_DataLen_6 = DL_UART_WORD_LENGTH_6_BITS, UART_DataLen_7 = DL_UART_WORD_LENGTH_7_BITS, UART_DataLen_8 = DL_UART_WORD_LENGTH_8_BITS }
	UART data length settings. More...

enum	UART_StopBits { UART_StopBits_1 = DL_UART_STOP_BITS_ONE, UART_StopBits_2 = DL_UART_STOP_BITS_TWO }
	UART stop bit settings. More...

enum	UART_Parity { UART_Parity_NONE = DL_UART_PARITY_NONE, UART_Parity_EVEN = DL_UART_PARITY_EVEN, UART_Parity_ODD = DL_UART_PARITY_ODD, UART_Parity_ZERO = DL_UART_PARITY_STICK_ZERO, UART_Parity_ONE = DL_UART_PARITY_STICK_ONE }
	UART parity type settings. More...

Functions
void	UART_Params_init (UART_Params *params)
	Function to initialize the UART_Params struct to its defaults. More...

UART_Handle	UART_open (uint_least8_t index, UART_Params *params)
	Function to initialize a given UART peripheral. More...

void	UART_close (UART_Handle handle)
	Function to close a UART peripheral specified by the UART handle. More...

int_fast16_t	UART_read (UART_Handle handle, void buf, size_t size, size_t bytesRead)
	Function that reads data from a UART. More...

int_fast16_t	UART_write (UART_Handle handle, const void buf, size_t size, size_t bytesWritten)
	Function that writes data to a UART. More...

int_fast16_t	UART_readTimeout (UART_Handle handle, void buf, size_t size, size_t bytesRead, uint32_t timeout)
	UART read with timeout. Note that the timeout parameter is different from the hardware read timeout. More...

int_fast16_t	UART_writeTimeout (UART_Handle handle, const void buf, size_t size, size_t bytesWritten, uint32_t timeout)
	UART write with timeout. Note that the timeout parameter is different from the hardware read timeout. More...

void	UART_readCancel (UART_Handle handle)
	Function that cancels a UART_read() function call. More...

void	UART_writeCancel (UART_Handle handle)
	Function that cancels a UART_write() function call. More...

void	UART_rxDisable (UART_Handle handle)
	Function that disables collecting of RX data into the circular buffer. More...

void	UART_rxEnable (UART_Handle handle)
	Function that enables collecting of RX data into the circular buffer. More...

void	UART_flushRx (UART_Handle handle)
	Function to flush data in the UART RX FIFO. More...

void	UART_getRxCount (UART_Handle handle)
	Get the number of bytes available in the circular buffer. More...

Detailed Description

The UART header file should be included in an application as follows:

#include <ti/drivers/UART.h>

Overview

UART has both RX and TX ring buffers for receiving/sending data. UART uses DMA to transfer data between the UART FIFOs and the RX and TX ring buffers in blocking mode. In callback mode, DMA will transfer data straight between the hardware FIFO and the source/destination buffer supplied by the application. NOTE: If the source-buffer for a TX operation resides in flash, the driver will constrain the flash to remain on during idle. The UART APIs for reading and writing data have been made more posix-like. UART provides for event notification, allowing the application to receive TX start and completion events, and RX error events.

Note: These events are synchronous to what can be observed on the data lines. A UART_STAT_TXFE_SET event will for example only occur after all data has been shifted from the hardware FIFO out onto the TX-pin. In contrast, read and write-callbacks are invoked when the driver has finished writing data into the hardware FIFO.

To use the UART driver, ensure that the correct driver library for your device is linked in and include this header file as follows:

#include <ti/drivers/UART.h>

Typedef Documentation

§ UART_Callback

typedef void(* UART_Callback) (UART_Handle handle, void *buf, size_t count, void *userArg, int_fast16_t status)

The definition of a callback function used by the UART driver when used in UART_Mode_CALLBACK. The callback can occur in task or interrupt context.

Parameters

[in]	UART_Handle	UART_Handle.
[in]	buf	Pointer to read/write buffer.
[in]	count	Number of elements read/written.
[in]	userArg	A user supplied argument specified in UART_Params.
[in]	status	A UART status codes code indicating success or failure of the transfer.

§ UART_EventCallback

typedef void(* UART_EventCallback) (UART_Handle handle, uint32_t event, uint32_t data, void *userArg)

The definition of a callback function used by the UART driver. The callback can occur in task or interrupt context.

Parameters

[in]	UART_Handle	UART_Handle.
[in]	event	UART_EVENT that has occurred.
[in]	data	One of the following UART_EVENT_OVERRUN: accumulated count UART_EVENT_BREAK: unused UART_EVENT_PARITY: unused UART_EVENT_FRAMING: unused
[in]	userArg	A user supplied argument specified in UART_Params.
[in]	status	A UART_STATUS code indicating success or failure of the transfer.

Enumeration Type Documentation

§ UART_Mode

enum UART_Mode

UART mode settings.

This enum defines the read and write modes for the configured UART.

Enumerator
UART_Mode_BLOCKING	UART_write() will block the calling task until all of the data can be accepted by the device driver. UART_read() will block until some data becomes available.
UART_Mode_CALLBACK	Non-blocking, UART_write() or UART_read() will return immediately. When the transfer has finished, the callback function is called from either the caller's context or from an interrupt context.
UART_Mode_NONBLOCKING	Non-blocking, UART_write() or UART_read() will return immediately. UART_write() will copy as much data into the transmit buffer as space allows. UART_read() will copy as much data from the receive buffer as is immediately available.

§ UART_ReadReturnMode

enum UART_ReadReturnMode

UART return mode settings.

This enumeration defines the return modes for UART_read().

UART_ReadReturnMode_FULL unblocks or performs a callback when the read buffer has been filled with the number of bytes passed to UART_read(). UART_ReadReturnMode_PARTIAL unblocks or performs a callback whenever a read timeout error occurs on the UART peripheral. This timeout error is not the same as the blocking read timeout in the UART_Params; the read timeout occurs if the read FIFO is non-empty and no new data has been received for a device/baudrate dependent number of clock cycles. This mode can be used when the exact number of bytes to be read is not known.

Enumerator
UART_ReadReturnMode_FULL	Unblock/callback when buffer is full.
UART_ReadReturnMode_PARTIAL	Unblock/callback when no new data comes in.

§ UART_DataLen

enum UART_DataLen

UART data length settings.

This enumeration defines the UART data lengths.

Enumerator
UART_DataLen_5	Data length is 5 bits
UART_DataLen_6	Data length is 6 bits
UART_DataLen_7	Data length is 7 bits
UART_DataLen_8	Data length is 8 bits

§ UART_StopBits

enum UART_StopBits

UART stop bit settings.

This enumeration defines the UART stop bits.

Enumerator
UART_StopBits_1	One stop bit
UART_StopBits_2	Two stop bits

§ UART_Parity

enum UART_Parity

UART parity type settings.

This enumeration defines the UART parity types.

Enumerator
UART_Parity_NONE	No parity
UART_Parity_EVEN	Parity bit is even
UART_Parity_ODD	Parity bit is odd
UART_Parity_ZERO	Parity bit is always zero
UART_Parity_ONE	Parity bit is always one

Function Documentation

§ UART_Params_init()

void UART_Params_init ( UART_Params * params )

Function to initialize the UART_Params struct to its defaults.

Parameters

[in] params A pointer to UART_Params structure for initialization.

Defaults values are:

readMode = UART_Mode_BLOCKING;
writeMode = UART_Mode_BLOCKING;
eventCallback = NULL;
eventMask = 0;
readCallback = NULL;
writeCallback = NULL;
readReturnMode = UART_ReadReturnMode_PARTIAL;
baudRate = 9600;
dataLength = UART_DataLen_8;
stopBits = UART_StopBits_1;
parityType = UART_Parity_NONE;
userArg = NULL;

§ UART_open()

UART_Handle UART_open	(	uint_least8_t	index,
		UART_Params *	params
	)

Function to initialize a given UART peripheral.

Function to initialize a given UART peripheral specified by the particular index value.

Parameters

[in]	index	Logical peripheral number for the UART indexed into the UART_config table.
[in]	params	Pointer to a UART_Params structure. If NULL, default parameter values will be used. All the fields in this structure are read-only.

Returns: UART handle

See also: UART_close()

§ UART_close()

void UART_close ( UART_Handle handle )

Function to close a UART peripheral specified by the UART handle.

Precondition: UART_open() has been called.; There are no ongoing read or write calls. Any ongoing read or write calls can be cancelled with UART_readCancel() or UART_writeCancel().

Parameters

[in] handle A UART_Handle returned from UART_open().

See also: UART_open()

§ UART_read()

int_fast16_t UART_read	(	UART_Handle	handle,
		void *	buf,
		size_t	size,
		size_t *	bytesRead
	)

Function that reads data from a UART.

UART_read() reads data from a UART controller. The destination is specified by buffer and the number of bytes to read is given by size.

In UART_Mode_BLOCKING, UART_read() blocks task execution until all the data in buffer has been read, if the read return mode is UART_ReadReturnMode_FULL. If the read return mode is UART_ReadReturnMode_PARTIAL, UART_read() returns before all the data has been read, if some data has been received, but reception has been inactive sufficiently long for a hardware read timeout to occur (e.g., for a 32-bit period). If a receive error occurs (e.g., framing, FIFO overrun), UART_read() will return with the number of bytes read up to the occurrence of the error.

In UART_Mode_CALLBACK, UART_read() does not block task execution. Instead, a callback function specified by UART_Params::readCallback is called when the transfer is finished (UART_ReadReturnMode_FULL), or reception has become inactive (UART_ReadReturnMode_PARTIAL). The callback function can occur in the caller's context or in SWI context, depending on the device-specific implementation. An unfinished asynchronous read operation must always be cancelled using UART_readCancel() before calling UART_close().

Note: It is ok to call UART_read() from its own callback function when in UART_Mode_CALLBACK.

Parameters

[in]	handle	A UART_Handle returned by UART_open().
[in]	buf	A pointer to an empty buffer to which received data should be read.
[in]	size	The number of bytes to be read into buffer.
[out]	bytesRead	If non-NULL, the location to store the number of bytes actually read into the buffer. If NULL, this parameter will be ignored. In callback mode, NULL could be passed in for this parameter, since the callback function will be passed the number of bytes read. In blocking mode, NULL can be passed, however, status should be checked in case the number of bytes requested was not received due to errors.

Returns: Returns a status indicating success or failure of the read.

Return values

UART_STATUS_SUCCESS	The call was successful.
UART_STATUS_EINUSE	Another read from the UART is currently ongoing.
UART_STATUS_ECANCELLED	In UART_Mode_BLOCKING, the read was canceled by a call to UART_readCancel() before any data could be received.

§ UART_write()

int_fast16_t UART_write	(	UART_Handle	handle,
		const void *	buf,
		size_t	size,
		size_t *	bytesWritten
	)

Function that writes data to a UART.

UART_write() writes data from a memory buffer to the UART interface. The source is specified by buffer and the number of bytes to write is given by size.

In UART_Mode_BLOCKING, UART_write() blocks task execution until all the data in buffer has been transmitted onto the TX pin.

In UART_Mode_CALLBACK, UART_write() does not block task execution. Instead, a callback function specified by UART_Params::writeCallback is called when all data has been written to the hardware FIFO. This means that that driver is ready to accept another call to UART_write().

Note: In contrast to UART_Mode_BLOCKING, it is not guaranteed that all data has been transmitted onto the TX pin when callback is invoked.

The buffer passed to UART_write() in UART_Mode_CALLBACK is not copied. The buffer must remain coherent until all the characters have been sent (ie until the write callback has been called with a byte count equal to that passed to UART_write()). The callback function can occur in the caller's task context or in interrupt context, depending on the device implementation. An unfinished asynchronous write operation must always be cancelled using UART_writeCancel() before calling UART_close().

The bytesWritten parameter should not be NULL so the application can determine the number of bytes actually written.

Parameters

[in]	handle	A UART_Handle returned by UART_open().
[in]	buf	A read-only pointer to buffer containing data to be written to the UART.
[in]	size	The number of bytes in the buffer that should be written to the UART.
[out]	bytesWritten	If non-NULL, the location to store the number of bytes actually written to the UART in UART_Mode_BLOCKING. In UART_Mode_CALLBACK, bytesWritten will be set to 0. If bytesWritten is NULL, this parameter will be ignored.

Returns: Returns a status indicating success or failure of the write.

Return values

UART_STATUS_SUCCESS	The call was successful.
UART_STATUS_EINUSE	Another write to the UART is currently ongoing.

§ UART_readTimeout()

int_fast16_t UART_readTimeout	(	UART_Handle	handle,
		void *	buf,
		size_t	size,
		size_t *	bytesRead,
		uint32_t	timeout
	)

UART read with timeout. Note that the timeout parameter is different from the hardware read timeout.

Parameters

[in]	handle	UART_Handle instance from UART_open().
[in]	buf	location where the data to be written.
[in]	size	amount of data to write in bytes.
[out]	bytesRead	If non-NULL, the location to store the number of bytes actually read into the buffer. If NULL, this parameter will be ignored.
[in]	timeout	The number of system clock ticks to wait until all data is received. If not all requested data was received within the timeout period, an error of UART_STATUS_ETIMEOUT will be returned. This parameter is only applicable to UART_Mode_BLOCKING.

Returns: Returns a status indicating success or failure of the read.

Return values

UART_STATUS_SUCCESS	The call was successful.
UART_STATUS_EINUSE	Another read from the UART is currently ongoing.
UART_STATUS_ECANCELLED	In UART_Mode_BLOCKING, the read was canceled by a call to UART_readCancel() before any data could be received.
UART_STATUS_ETIMEOUT	The read operation timed out.

§ UART_writeTimeout()

int_fast16_t UART_writeTimeout	(	UART_Handle	handle,
		const void *	buf,
		size_t	size,
		size_t *	bytesWritten,
		uint32_t	timeout
	)

UART write with timeout. Note that the timeout parameter is different from the hardware read timeout.

Parameters

[in]	handle	UART_Handle instance from UART_open().
[in]	buf	location to write data from.
[in]	size	amount of data to write in bytes.
[out]	bytesWritten	If non-NULL, the location to store the number of bytes actually written into the buffer. If NULL, this parameter will be ignored.
[in]	timeout	The number of system clock ticks to wait for the write to complete (UART_Mode_BLOCKING only). If the timeout expires before all bytes are written, a status of UART_STATUS_ETIMEOUT will be returned.

Returns: Returns a status indicating success or failure of the write.

Return values

UART_STATUS_SUCCESS	The call was successful.
UART_STATUS_EINUSE	Another write to the UART is currently ongoing.
UART_STATUS_ETIMEOUT	The write operation timed out.

§ UART_readCancel()

void UART_readCancel ( UART_Handle handle )

Function that cancels a UART_read() function call.

This function cancels an asynchronous UART_read() operation in in UART_Mode_CALLBACK, or unblocks a UART_read() call in UART_Mode_BLOCKING. In UART_Mode_CALLBACK, UART_readCancel() calls the registered read callback function with the number of bytes received so far. It is the application's responsibility to check the count argument in the callback function and handle the case where only a subset of the bytes were received. The callback function will be passed a status of UART_STATUS_ECANCELLED.

In UART_Mode_BLOCKING, UART_read() will return UART_STATUS_ECANCELLED, and the bytesRead parameter will be set to the number of bytes received so far.

Parameters

[in] handle A UART_Handle returned by UART_open().

§ UART_writeCancel()

void UART_writeCancel ( UART_Handle handle )

Function that cancels a UART_write() function call.

This function cancels an asynchronous UART_write() operation when write mode is UART_Mode_CALLBACK. In callback mode, UART_writeCancel() calls the registered write callback function no matter how many bytes were sent. It is the application's responsibility to check the count argument in the callback function and handle cases where only a subset of the bytes were sent. The callback function will be passed a status of UART_STATUS_ECANCELLED. In blocking mode, UART_write() will return UART_STATUS_ECANCELLED.

Note: The above applies to UART_writeTimeout() as well.

Parameters

[in] handle A UART_Handle returned by UART_open().

§ UART_rxDisable()

void UART_rxDisable ( UART_Handle handle )

Function that disables collecting of RX data into the circular buffer.

The driver implementation uses a circular buffer to collect RX data while a UART_read() is not in progress. This function will disable buffering of RX data into the circular buffer. UART_read() will read directly from the UART driver's RX buffer. Disabling the circular buffer will also allow the device to go into low power modes.

Parameters

[in] handle A UART_Handle returned by UART_open().

See also: UART_rxEnable()

§ UART_rxEnable()

void UART_rxEnable ( UART_Handle handle )

Function that enables collecting of RX data into the circular buffer.

The driver implementation uses a circular buffer to collect RX data while a UART_read() is not in progress. This function will enable buffering of RX data into the circular buffer. UART_read() will read directly from the UART drivers RX buffer. Enabling the circular buffer will also prevent the device from going into low power modes.

Parameters

[in] handle A UART_Handle returned by UART_open().

See also: UART_rxDisable()

§ UART_flushRx()

void UART_flushRx ( UART_Handle handle )

Function to flush data in the UART RX FIFO.

Precondition: UART_open() has been called.

This function can be called to remove all data from the RX FIFO, for example, after a UART read error has occurred. All data in the RX circular buffer will be discarded.

Parameters

[in] handle A UART_Handle returned from UART_open().

§ UART_getRxCount()

void UART_getRxCount ( UART_Handle handle )

Get the number of bytes available in the circular buffer.

Precondition: UART_open() has been called.

Parameters

[in] handle A UART_Handle returned from UART_open().

Returns: Returns the number of bytes available in the RX circular buffer.

See also: UART_rxEnable()

Modules

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Overview

Typedef Documentation

§ UART_Callback

§ UART_EventCallback

Enumeration Type Documentation

§ UART_Mode

§ UART_ReadReturnMode

§ UART_DataLen

§ UART_StopBits

§ UART_Parity

Function Documentation

§ UART_Params_init()

§ UART_open()

§ UART_close()

§ UART_read()

§ UART_write()

§ UART_readTimeout()

§ UART_writeTimeout()

§ UART_readCancel()

§ UART_writeCancel()

§ UART_rxDisable()

§ UART_rxEnable()

§ UART_flushRx()

§ UART_getRxCount()