Data Structures | Macros | Typedefs | Enumerations | Functions
UART.h File Reference

Detailed Description

Universal Asynchronous Receiver-Transmitter (UART) Driver.


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

This module serves as the main interface for applications. Its purpose is to redirect the UART APIs to specific driver implementations which are specified using a pointer to a UART_FxnTable.

Overview

A UART is used to translate data between the chip and a serial port. The UART driver simplifies reading and writing to any of the UART peripherals on the board, with multiple modes of operation and performance. These include blocking, non-blocking, and polling, as well as text/binary mode, echo and return characters.

The UART driver interface provides device independent APIs, data types, and macros. The APIs in this driver serve as an interface to a typical RTOS application. The specific peripheral implementations are responsible for creating all the RTOS specific primitives to allow for thread-safe operation.


Usage

This documentation provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the APIs are provided in subsequent sections.

Synopsis

// Import the UART driver definitions
// One-time initialization of UART driver
// Initialize UART parameters
UART_Params params;
params.baudRate = 9600;
// Open the UART
uart = UART_open(Board_UART0, &params);
// Read from the UART
int32_t readCount;
uint8_t buffer[BUFSIZE];
readCount = UART_read(uart, buffer, BUFSIZE);
// Write to the UART
UART_write(uart, buffer, BUFSIZE);
// Close the UART
UART_close(uart);

Examples

The following code example opens a UART instance, reads a byte from the UART, and then writes the byte back to the UART.

char input;
UART_Params uartParams;
// Initialize the UART driver. UART_init() must be called before
// calling any other UART APIs.
// Create a UART with data processing off.
UART_Params_init(&uartParams);
uartParams.readEcho = UART_ECHO_OFF;
uartParams.baudRate = 115200;
// Open an instance of the UART drivers
uart = UART_open(Board_UART0, &uartParams);
if (uart == NULL) {
// UART_open() failed
while (1);
}
// Loop forever echoing
while (1) {
UART_read(uart, &input, 1);
UART_write(uart, &input, 1);
}

Details for the example code above are described in the following subsections.

Opening the UART Driver

Opening a UART requires four steps:

  1. Create and initialize a UART_Params structure.
  2. Fill in the desired parameters.
  3. Call UART_open(), passing the index of the UART in the UART_config structure, and the address of the UART_Params structure. The UART instance is specified by the index in the UART_config structure.
  4. Check that the UART handle returned by UART_open() is non-NULL, and save it. The handle will be used to read and write to the UART you just opened.

Only one UART index can be used at a time; calling UART_open() a second time with the same index previosly passed to UART_open() will result in an error. You can, though, re-use the index if the instance is closed via UART_close(). In the example code, Board_UART0 is passed to UART_open(). This macro is defined in the example's Board.h file.

Modes of Operation

The UART driver can operate in blocking mode or callback mode, by setting the writeMode and readMode parameters passed to UART_open(). If these parameters are not set, as in the example code, the UART driver defaults to blocking mode. Options for the writeMode and readMode parameters are UART_MODE_BLOCKING and UART_MODE_CALLBACK:

The example sets the writeDataMode and readDataMode parameters to UART_DATA_BINARY. Options for these parameters are UART_DATA_BINARY and UART_DATA_TEXT:

Other parameters set by the example are readReturnMode and readEcho. Options for the readReturnMode parameter are UART_RETURN_FULL and UART_RETURN_NEWLINE:

Options for the readEcho parameter are UART_ECHO_OFF and UART_ECHO_ON. This parameter determines whether the driver echoes data back to the UART. When echo is turned on, each character that is read by the target is written back, independent of any write operations. If data is received in the middle of a write and echo is turned on, the echoed characters will be mixed in with the write data.

Reading and Writing data

The example code reads one byte frome the UART instance, and then writes one byte back to the same instance:

UART_read(uart, &input, 1);
UART_write(uart, &input, 1);

The UART driver allows full duplex data transfers. Therefore, it is possible to call UART_read() and UART_write() at the same time (for either blocking or callback modes). It is not possible, however, to issue multiple concurrent operations in the same direction. For example, if one thread calls UART_read(uart0, buffer0...), any other thread attempting UART_read(uart0, buffer1...) will result in an error of UART_STATUS_ERROR, until all the data from the first UART_read() has been transferred to buffer0. This applies to both blocking and and callback modes. So applications must either synchronize UART_read() (or UART_write()) calls that use the same UART handle, or check for the UART_STATUS_ERROR return code indicating that a transfer is still ongoing.


Configuration

Refer to the Driver's Configuration section for driver configuration information.



#include <stddef.h>
#include <stdint.h>
Include dependency graph for UART.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  UART_Params_
 UART Parameters. More...
 
struct  UART_FxnTable_
 The definition of a UART function table that contains the required set of functions to control a specific UART driver implementation. More...
 
struct  UART_Config_
 UART Global configuration. More...
 

Macros

#define UART_CMD_RESERVED   (32)
 
#define UART_STATUS_RESERVED   (-32)
 
#define UART_STATUS_SUCCESS   (0)
 Successful status code returned by UART_control(). More...
 
#define UART_STATUS_ERROR   (-1)
 Generic error status code returned by UART_control(). More...
 
#define UART_STATUS_UNDEFINEDCMD   (-2)
 An error status code returned by UART_control() for undefined command codes. More...
 
#define UART_CMD_PEEK   (0)
 Command code used by UART_control() to read the next unsigned char. More...
 
#define UART_CMD_ISAVAILABLE   (1)
 Command code used by UART_control() to determine if the read buffer is empty. More...
 
#define UART_CMD_GETRXCOUNT   (2)
 Command code used by UART_control() to determine how many unsigned chars are in the read buffer. More...
 
#define UART_CMD_RXENABLE   (3)
 Command code used by UART_control() to enable data receive by the UART. More...
 
#define UART_CMD_RXDISABLE   (4)
 Command code used by UART_control() to disable data received by the UART. More...
 
#define UART_ERROR   (UART_STATUS_ERROR)
 
#define UART_WAIT_FOREVER   (~(0U))
 Wait forever define. More...
 

Typedefs

typedef struct UART_Config_UART_Handle
 A handle that is returned from a UART_open() call. More...
 
typedef void(* UART_Callback) (UART_Handle handle, void *buf, size_t count)
 The definition of a callback function used by the UART driver when used in UART_MODE_CALLBACK The callback can occur in task or HWI context. More...
 
typedef enum UART_Mode_ UART_Mode
 UART mode settings. More...
 
typedef enum UART_ReturnMode_ UART_ReturnMode
 UART return mode settings. More...
 
typedef enum UART_DataMode_ UART_DataMode
 UART data mode settings. More...
 
typedef enum UART_Echo_ UART_Echo
 UART echo settings. More...
 
typedef enum UART_LEN_ UART_LEN
 UART data length settings. More...
 
typedef enum UART_STOP_ UART_STOP
 UART stop bit settings. More...
 
typedef enum UART_PAR_ UART_PAR
 UART parity type settings. More...
 
typedef struct UART_Params_ UART_Params
 UART Parameters. More...
 
typedef void(* UART_CloseFxn) (UART_Handle handle)
 A function pointer to a driver specific implementation of UART_CloseFxn(). More...
 
typedef int_fast16_t(* UART_ControlFxn) (UART_Handle handle, uint_fast16_t cmd, void *arg)
 A function pointer to a driver specific implementation of UART_ControlFxn(). More...
 
typedef void(* UART_InitFxn) (UART_Handle handle)
 A function pointer to a driver specific implementation of UART_InitFxn(). More...
 
typedef UART_Handle(* UART_OpenFxn) (UART_Handle handle, UART_Params *params)
 A function pointer to a driver specific implementation of UART_OpenFxn(). More...
 
typedef int_fast32_t(* UART_ReadFxn) (UART_Handle handle, void *buffer, size_t size)
 A function pointer to a driver specific implementation of UART_ReadFxn(). More...
 
typedef int_fast32_t(* UART_ReadPollingFxn) (UART_Handle handle, void *buffer, size_t size)
 A function pointer to a driver specific implementation of UART_ReadPollingFxn(). More...
 
typedef void(* UART_ReadCancelFxn) (UART_Handle handle)
 A function pointer to a driver specific implementation of UART_ReadCancelFxn(). More...
 
typedef int_fast32_t(* UART_WriteFxn) (UART_Handle handle, const void *buffer, size_t size)
 A function pointer to a driver specific implementation of UART_WriteFxn(). More...
 
typedef int_fast32_t(* UART_WritePollingFxn) (UART_Handle handle, const void *buffer, size_t size)
 A function pointer to a driver specific implementation of UART_WritePollingFxn(). More...
 
typedef void(* UART_WriteCancelFxn) (UART_Handle handle)
 A function pointer to a driver specific implementation of UART_WriteCancelFxn(). More...
 
typedef struct UART_FxnTable_ UART_FxnTable
 The definition of a UART function table that contains the required set of functions to control a specific UART driver implementation. More...
 
typedef struct UART_Config_ UART_Config
 UART Global configuration. More...
 

Enumerations

enum  UART_Mode_ { UART_MODE_BLOCKING, UART_MODE_CALLBACK }
 UART mode settings. More...
 
enum  UART_ReturnMode_ { UART_RETURN_FULL, UART_RETURN_NEWLINE }
 UART return mode settings. More...
 
enum  UART_DataMode_ { UART_DATA_BINARY = 0, UART_DATA_TEXT = 1 }
 UART data mode settings. More...
 
enum  UART_Echo_ { UART_ECHO_OFF = 0, UART_ECHO_ON = 1 }
 UART echo settings. More...
 
enum  UART_LEN_ { UART_LEN_5 = 0, UART_LEN_6 = 1, UART_LEN_7 = 2, UART_LEN_8 = 3 }
 UART data length settings. More...
 
enum  UART_STOP_ { UART_STOP_ONE = 0, UART_STOP_TWO = 1 }
 UART stop bit settings. More...
 
enum  UART_PAR_ {
  UART_PAR_NONE = 0, UART_PAR_EVEN = 1, UART_PAR_ODD = 2, UART_PAR_ZERO = 3,
  UART_PAR_ONE = 4
}
 UART parity type settings. More...
 

Functions

void UART_close (UART_Handle handle)
 Function to close a UART peripheral specified by the UART handle. More...
 
int_fast16_t UART_control (UART_Handle handle, uint_fast16_t cmd, void *arg)
 Function performs implementation specific features on a given UART_Handle. More...
 
void UART_init (void)
 Function to initialize the UART module. More...
 
UART_Handle UART_open (uint_least8_t index, UART_Params *params)
 Function to initialize a given UART peripheral. More...
 
void UART_Params_init (UART_Params *params)
 Function to initialize the UART_Params struct to its defaults. More...
 
int_fast32_t UART_write (UART_Handle handle, const void *buffer, size_t size)
 Function that writes data to a UART with interrupts enabled. More...
 
int_fast32_t UART_writePolling (UART_Handle handle, const void *buffer, size_t size)
 Function that writes data to a UART, polling the peripheral to wait until new data can be written. Usage of this API is mutually exclusive with usage of UART_write(). More...
 
void UART_writeCancel (UART_Handle handle)
 Function that cancels a UART_write() function call. More...
 
int_fast32_t UART_read (UART_Handle handle, void *buffer, size_t size)
 Function that reads data from a UART with interrupt enabled. More...
 
int_fast32_t UART_readPolling (UART_Handle handle, void *buffer, size_t size)
 Function that reads data from a UART without interrupts. This API must be used mutually exclusive with UART_read(). More...
 
void UART_readCancel (UART_Handle handle)
 Function that cancels a UART_read() function call. More...
 

Macro Definition Documentation

§ UART_ERROR

#define UART_ERROR   (UART_STATUS_ERROR)

§ UART_WAIT_FOREVER

#define UART_WAIT_FOREVER   (~(0U))

Wait forever define.

Typedef Documentation

§ UART_Handle

typedef struct UART_Config_* UART_Handle

A handle that is returned from a UART_open() call.

§ UART_Callback

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

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

Parameters
UART_HandleUART_Handle
bufPointer to read/write buffer
countNumber of elements read/written

§ UART_Mode

typedef enum UART_Mode_ UART_Mode

UART mode settings.

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

§ UART_ReturnMode

UART return mode settings.

This enumeration defines the return modes for UART_read() and UART_readPolling(). This mode only functions when in UART_DATA_TEXT mode.

UART_RETURN_FULL unblocks or performs a callback when the read buffer has been filled. UART_RETURN_NEWLINE unblocks or performs a callback whenever a newline character has been received.

UART operation UART_RETURN_FULL UART_RETURN_NEWLINE
UART_read() Returns when buffer is full Returns when buffer is full or newline was read
UART_write() Sends data as is Sends data with an additional newline at the end
Precondition
UART driver must be used in UART_DATA_TEXT mode.

§ UART_DataMode

UART data mode settings.

This enumeration defines the data mode for reads and writes.

In UART_DATA_BINARY, data is passed as is, with no processing.

In UART_DATA_TEXT mode, the driver will examine the UART_ReturnMode value, to determine whether or not to unblock/callback when a newline is received. Read actions replace a carriage return with a newline, and write actions add a carriage return before a newline. This effectively treats all device line endings as LF, and all host PC line endings as CRLF.

§ UART_Echo

typedef enum UART_Echo_ UART_Echo

UART echo settings.

This enumeration defines if the driver will echo data when uses in UART_DATA_TEXT mode. This only applies to data received by the UART.

UART_ECHO_ON will echo back characters it received while in UART_DATA_TEXT mode. UART_ECHO_OFF will not echo back characters it received in UART_DATA_TEXT mode.

Precondition
UART driver must be used in UART_DATA_TEXT mode.

§ UART_LEN

typedef enum UART_LEN_ UART_LEN

UART data length settings.

This enumeration defines the UART data lengths.

§ UART_STOP

typedef enum UART_STOP_ UART_STOP

UART stop bit settings.

This enumeration defines the UART stop bits.

§ UART_PAR

typedef enum UART_PAR_ UART_PAR

UART parity type settings.

This enumeration defines the UART parity types.

§ UART_Params

typedef struct UART_Params_ UART_Params

UART Parameters.

UART parameters are used with the UART_open() call. Default values for these parameters are set using UART_Params_init().

See also
UART_Params_init()

§ UART_CloseFxn

typedef void(* UART_CloseFxn) (UART_Handle handle)

A function pointer to a driver specific implementation of UART_CloseFxn().

§ UART_ControlFxn

typedef int_fast16_t(* UART_ControlFxn) (UART_Handle handle, uint_fast16_t cmd, void *arg)

A function pointer to a driver specific implementation of UART_ControlFxn().

§ UART_InitFxn

typedef void(* UART_InitFxn) (UART_Handle handle)

A function pointer to a driver specific implementation of UART_InitFxn().

§ UART_OpenFxn

typedef UART_Handle(* UART_OpenFxn) (UART_Handle handle, UART_Params *params)

A function pointer to a driver specific implementation of UART_OpenFxn().

§ UART_ReadFxn

typedef int_fast32_t(* UART_ReadFxn) (UART_Handle handle, void *buffer, size_t size)

A function pointer to a driver specific implementation of UART_ReadFxn().

§ UART_ReadPollingFxn

typedef int_fast32_t(* UART_ReadPollingFxn) (UART_Handle handle, void *buffer, size_t size)

A function pointer to a driver specific implementation of UART_ReadPollingFxn().

§ UART_ReadCancelFxn

typedef void(* UART_ReadCancelFxn) (UART_Handle handle)

A function pointer to a driver specific implementation of UART_ReadCancelFxn().

§ UART_WriteFxn

typedef int_fast32_t(* UART_WriteFxn) (UART_Handle handle, const void *buffer, size_t size)

A function pointer to a driver specific implementation of UART_WriteFxn().

§ UART_WritePollingFxn

typedef int_fast32_t(* UART_WritePollingFxn) (UART_Handle handle, const void *buffer, size_t size)

A function pointer to a driver specific implementation of UART_WritePollingFxn().

§ UART_WriteCancelFxn

typedef void(* UART_WriteCancelFxn) (UART_Handle handle)

A function pointer to a driver specific implementation of UART_WriteCancelFxn().

§ UART_FxnTable

typedef struct UART_FxnTable_ UART_FxnTable

The definition of a UART function table that contains the required set of functions to control a specific UART driver implementation.

§ UART_Config

typedef struct UART_Config_ UART_Config

UART Global configuration.

The UART_Config structure contains a set of pointers used to characterize the UART driver implementation.

This structure needs to be defined before calling UART_init() and it must not be changed thereafter.

See also
UART_init()

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 

Uses a semaphore to block while data is being sent. Context of the call must be a Task.

UART_MODE_CALLBACK 

Non-blocking and will return immediately. When UART_write() or UART_read() has finished, the callback function is called from either the caller's context or from an interrupt context.

§ UART_ReturnMode_

UART return mode settings.

This enumeration defines the return modes for UART_read() and UART_readPolling(). This mode only functions when in UART_DATA_TEXT mode.

UART_RETURN_FULL unblocks or performs a callback when the read buffer has been filled. UART_RETURN_NEWLINE unblocks or performs a callback whenever a newline character has been received.

UART operation UART_RETURN_FULL UART_RETURN_NEWLINE
UART_read() Returns when buffer is full Returns when buffer is full or newline was read
UART_write() Sends data as is Sends data with an additional newline at the end
Precondition
UART driver must be used in UART_DATA_TEXT mode.
Enumerator
UART_RETURN_FULL 

Unblock/callback when buffer is full.

UART_RETURN_NEWLINE 

Unblock/callback when newline character is received.

§ UART_DataMode_

UART data mode settings.

This enumeration defines the data mode for reads and writes.

In UART_DATA_BINARY, data is passed as is, with no processing.

In UART_DATA_TEXT mode, the driver will examine the UART_ReturnMode value, to determine whether or not to unblock/callback when a newline is received. Read actions replace a carriage return with a newline, and write actions add a carriage return before a newline. This effectively treats all device line endings as LF, and all host PC line endings as CRLF.

Enumerator
UART_DATA_BINARY 

Data is not processed

UART_DATA_TEXT 

Data is processed according to above

§ UART_Echo_

enum UART_Echo_

UART echo settings.

This enumeration defines if the driver will echo data when uses in UART_DATA_TEXT mode. This only applies to data received by the UART.

UART_ECHO_ON will echo back characters it received while in UART_DATA_TEXT mode. UART_ECHO_OFF will not echo back characters it received in UART_DATA_TEXT mode.

Precondition
UART driver must be used in UART_DATA_TEXT mode.
Enumerator
UART_ECHO_OFF 

Data is not echoed

UART_ECHO_ON 

Data is echoed

§ UART_LEN_

enum UART_LEN_

UART data length settings.

This enumeration defines the UART data lengths.

Enumerator
UART_LEN_5 

Data length is 5 bits

UART_LEN_6 

Data length is 6 bits

UART_LEN_7 

Data length is 7 bits

UART_LEN_8 

Data length is 8 bits

§ UART_STOP_

enum UART_STOP_

UART stop bit settings.

This enumeration defines the UART stop bits.

Enumerator
UART_STOP_ONE 

One stop bit

UART_STOP_TWO 

Two stop bits

§ UART_PAR_

enum UART_PAR_

UART parity type settings.

This enumeration defines the UART parity types.

Enumerator
UART_PAR_NONE 

No parity

UART_PAR_EVEN 

Parity bit is even

UART_PAR_ODD 

Parity bit is odd

UART_PAR_ZERO 

Parity bit is always zero

UART_PAR_ONE 

Parity bit is always one

Function Documentation

§ 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.
Ongoing asynchronous read or write have been canceled using UART_readCancel() or UART_writeCancel() respectively.
Parameters
handleA UART_Handle returned from UART_open()
See also
UART_open()

§ UART_control()

int_fast16_t UART_control ( UART_Handle  handle,
uint_fast16_t  cmd,
void *  arg 
)

Function performs implementation specific features on a given UART_Handle.

Commands for UART_control() can originate from UART.h or from implementation specific UART*.h (UARTCC26XX.h, UARTMSP432.h, etc.. ) files. While commands from UART.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific UART*.h files add unique driver capabilities but are not API portable across all UART driver implementations.

Commands supported by UART.h follow a UART_CMD_<cmd> naming convention.
Commands supported by UART*.h follow a UART*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See UART_control command codes for command codes.

See UART_control return status codes for status codes.

Precondition
UART_open() has to be called.
Parameters
handleA UART handle returned from UART_open()
cmdUART.h or UART*.h commands.
argAn optional R/W (read/write) command argument accompanied with cmd
Returns
Implementation specific return codes. Negative values indicate unsuccessful operations.
See also
UART_open()

§ UART_init()

void UART_init ( void  )

Function to initialize the UART module.

Precondition
The UART_config structure must exist and be persistent before this function can be called. This function must also be called before any other UART driver APIs.

§ 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.

Precondition
UART_init() has been called
Parameters
indexLogical peripheral number for the UART indexed into the UART_config table
paramsPointer to a parameter block. If NULL, default parameter values will be used. All the fields in this structure are RO (read-only).
Returns
A UART_Handle upon success. NULL if an error occurs, or if the indexed UART peripheral is already opened.
See also
UART_init()
UART_close()

§ UART_Params_init()

void UART_Params_init ( UART_Params params)

Function to initialize the UART_Params struct to its defaults.

Parameters
paramsAn pointer to UART_Params structure for initialization

Defaults values are: readMode = UART_MODE_BLOCKING; writeMode = UART_MODE_BLOCKING; readTimeout = UART_WAIT_FOREVER; writeTimeout = UART_WAIT_FOREVER; readCallback = NULL; writeCallback = NULL; readReturnMode = UART_RETURN_NEWLINE; readDataMode = UART_DATA_TEXT; writeDataMode = UART_DATA_TEXT; readEcho = UART_ECHO_ON; baudRate = 115200; dataLength = UART_LEN_8; stopBits = UART_STOP_ONE; parityType = UART_PAR_NONE;

§ UART_write()

int_fast32_t UART_write ( UART_Handle  handle,
const void *  buffer,
size_t  size 
)

Function that writes data to a UART with interrupts enabled.

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 written.

In UART_MODE_CALLBACK, UART_write() does not block task execution. Instead, a callback function specified by UART_Params::writeCallback is called when the transfer is finished. 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 tx 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 a HWI or SWI context, depending on the device implementation. An unfinished asynchronous write operation must always be canceled using UART_writeCancel() before calling UART_close().

UART_write() is mutually exclusive to UART_writePolling(). For an opened UART peripheral, either UART_write() or UART_writePolling() can be used, but not both.

Warning
Do not call UART_write() from its own callback function when in UART_MODE_CALLBACK.
See also
UART_writePolling()
Parameters
handleA UART_Handle returned by UART_open()
bufferA read-only pointer to buffer containing data to be written to the UART
sizeThe number of bytes in the buffer that should be written to the UART
Returns
Returns the number of bytes that have been written to the UART. If an error occurs, UART_STATUS_ERROR is returned. In UART_MODE_CALLBACK mode, the return value is always 0.

§ UART_writePolling()

int_fast32_t UART_writePolling ( UART_Handle  handle,
const void *  buffer,
size_t  size 
)

Function that writes data to a UART, polling the peripheral to wait until new data can be written. Usage of this API is mutually exclusive with usage of UART_write().

This function initiates an operation to write data to a UART controller.

UART_writePolling() will not return until all the data was written to the UART (or to its FIFO if applicable).

See also
UART_write()
Parameters
handleA UART_Handle returned by UART_open()
bufferA read-only pointer to the buffer containing the data to be written to the UART
sizeThe number of bytes in the buffer that should be written to the UART
Returns
Returns the number of bytes that have been written to the UART. If an error occurs, UART_STATUS_ERROR is returned.

§ UART_writeCancel()

void UART_writeCancel ( UART_Handle  handle)

Function that cancels a UART_write() function call.

This function cancels an asynchronous UART_write() operation and is only applicable in UART_MODE_CALLBACK. UART_writeCancel() calls the registered TX 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.

Parameters
handleA UART_Handle returned by UART_open()

§ UART_read()

int_fast32_t UART_read ( UART_Handle  handle,
void *  buffer,
size_t  size 
)

Function that reads data from a UART with interrupt enabled.

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.

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. The callback function can occur in the caller's context or in HWI or SWI context, depending on the device-specific implementation. An unfinished asynchronous read operation must always be canceled using UART_readCancel() before calling UART_close().

UART_read() is mutually exclusive to UART_readPolling(). For an opened UART peripheral, either UART_read() or UART_readPolling() can be used, but not both.

Warning
Do not call UART_read() from its own callback function when in UART_MODE_CALLBACK.
See also
UART_readPolling()
Parameters
handleA UART_Handle returned by UART_open()
bufferA pointer to an empty buffer to which received data should be written
sizeThe number of bytes to be written into buffer
Returns
Returns the number of bytes that have been read from the UART, UART_STATUS_ERROR on an error.

§ UART_readPolling()

int_fast32_t UART_readPolling ( UART_Handle  handle,
void *  buffer,
size_t  size 
)

Function that reads data from a UART without interrupts. This API must be used mutually exclusive with UART_read().

This function initiates an operation to read data from a UART peripheral.

UART_readPolling() will not return until size data was read to the UART.

See also
UART_read()
Parameters
handleA UART_Handle returned by UART_open()
bufferA pointer to an empty buffer in which received data should be written to
sizeThe number of bytes to be written into buffer
Returns
Returns the number of bytes that have been read from the UART, UART_STATUS_ERROR on an error.

§ UART_readCancel()

void UART_readCancel ( UART_Handle  handle)

Function that cancels a UART_read() function call.

This function cancels an asynchronous UART_read() operation and is only applicable in UART_MODE_CALLBACK. UART_readCancel() calls the registered RX callback function no matter how many bytes were received. 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 received.

Parameters
handleA UART_Handle returned by UART_open()
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale