![]() |
![]() |
TI-RTOS Drivers
tidrivers_full_2_20_01_10
|
UART driver interface.
============================================================================
The UART header file should be included in an application as follows:
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 board's UART pins must be configured before initializing the UART driver. The application initializes the UART driver by calling UART_init() and is then ready to open a UART by calling UART_open(), passing in a UART parameters data structure.
The APIs in this driver serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible to create all the SYS/BIOS specific primitives to allow for thread-safe operation.
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 UART_MODE_CALLBACK and UART_MODE_BLOCKING 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_ERROR, until all the data from the first UART_read() has been transferred to buffer0. This applies to both UART_MODE_CALLBACK and UART_MODE_BLOCKING modes. So applications must either synchronize UART_read() (or UART_write()) calls that use the same UART handle, or check for the UART_ERROR return code indicating that a transfer is still ongoing.
This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a UART_FxnTable.
The UART driver interface module is joined (at link time) to a NULL-terminated array of UART_Config data structures named UART_config. UART_config is implemented in the application with each entry being an instance of a UART peripheral. Each entry in UART_config contains a:
It is STRONGLY discouraged to perform UART_read() or UART_write calls within the driver's own callback function when in UART_MODE_CALLBACK. Doing so will incur additional task or system stack size requirements. See the peripheral implementations' documentation for stack size estimations. It is expected that the user perform his/her own stack and usage analysis when choosing to nest these calls.
The UART driver interface produces log statements if instrumentation is enabled.
Diagnostics Mask | Log details |
---|---|
Diags_USER1 | basic operations performed |
Diags_USER2 | detailed operations performed |
#include <stdint.h>
#include <stddef.h>
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 (~0) |
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, 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(* | UART_ControlFxn) (UART_Handle handle, unsigned int 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(* | UART_ReadFxn) (UART_Handle handle, void *buffer, size_t size) |
A function pointer to a driver specific implementation of UART_ReadFxn(). More... | |
typedef int(* | 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(* | 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(* | 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 | UART_control (UART_Handle handle, unsigned int 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 (unsigned int 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 | UART_write (UART_Handle handle, const void *buffer, size_t size) |
Function that writes data to a UART with interrupts enabled. More... | |
int | 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 | UART_read (UART_Handle handle, void *buffer, size_t size) |
Function that reads data from a UART with interrupt enabled. More... | |
int | 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... | |
#define UART_ERROR UART_STATUS_ERROR |
#define UART_WAIT_FOREVER (~0) |
Wait forever define.
typedef struct UART_Config* UART_Handle |
A handle that is returned from a UART_open() call.
typedef void(* UART_Callback) (UART_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.
UART_Handle | UART_Handle |
buf | Pointer to read/write buffer |
count | Number of elements read/written |
UART mode settings.
This enum defines the read and write modes for the configured UART.
typedef enum UART_ReturnMode 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 |
typedef enum UART_DataMode UART_DataMode |
UART data mode settings.
This enumeration defines the data mode for read and write. In UART_DATA_TEXT mode the driver will examine the UART_ReturnMode value.
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.
UART data length settings.
This enumeration defines the UART data lengths.
UART stop bit settings.
This enumeration defines the UART stop bits.
UART parity type settings.
This enumeration defines the UART parity types.
typedef struct UART_Params UART_Params |
UART Parameters.
UART parameters are used to with the UART_open() call. Default values for these parameters are set using UART_Params_init().
typedef void(* UART_CloseFxn) (UART_Handle handle) |
A function pointer to a driver specific implementation of UART_CloseFxn().
typedef int(* UART_ControlFxn) (UART_Handle handle, unsigned int cmd, void *arg) |
A function pointer to a driver specific implementation of UART_ControlFxn().
typedef void(* UART_InitFxn) (UART_Handle handle) |
A function pointer to a driver specific implementation of UART_InitFxn().
typedef UART_Handle(* UART_OpenFxn) (UART_Handle handle, UART_Params *params) |
A function pointer to a driver specific implementation of UART_OpenFxn().
typedef int(* UART_ReadFxn) (UART_Handle handle, void *buffer, size_t size) |
A function pointer to a driver specific implementation of UART_ReadFxn().
typedef int(* UART_ReadPollingFxn) (UART_Handle handle, void *buffer, size_t size) |
A function pointer to a driver specific implementation of UART_ReadPollingFxn().
typedef void(* UART_ReadCancelFxn) (UART_Handle handle) |
A function pointer to a driver specific implementation of UART_ReadCancelFxn().
typedef int(* UART_WriteFxn) (UART_Handle handle, const void *buffer, size_t size) |
A function pointer to a driver specific implementation of UART_WriteFxn().
typedef int(* UART_WritePollingFxn) (UART_Handle handle, const void *buffer, size_t size) |
A function pointer to a driver specific implementation of UART_WritePollingFxn().
typedef void(* UART_WriteCancelFxn) (UART_Handle handle) |
A function pointer to a driver specific implementation of UART_WriteCancelFxn().
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.
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.
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. |
enum 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 |
Enumerator | |
---|---|
UART_RETURN_FULL |
Unblock/callback when buffer is full. |
UART_RETURN_NEWLINE |
Unblock/callback when newline character is received. |
enum UART_DataMode |
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.
Enumerator | |
---|---|
UART_ECHO_OFF |
Data is not echoed |
UART_ECHO_ON |
Data is echoed |
enum UART_LEN |
enum UART_STOP |
enum UART_PAR |
void UART_close | ( | UART_Handle | handle | ) |
Function to close a UART peripheral specified by the UART handle.
handle | A UART_Handle returned from UART_open() |
int UART_control | ( | UART_Handle | handle, |
unsigned int | 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, UARTTiva.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.
handle | A UART handle returned from UART_open() |
cmd | UART.h or UART*.h commands. |
arg | An optional R/W (read/write) command argument accompanied with cmd |
void UART_init | ( | void | ) |
Function to initialize the UART module.
UART_Handle UART_open | ( | unsigned int | index, |
UART_Params * | params | ||
) |
Function to initialize a given UART peripheral.
Function to initialize a given UART peripheral specified by the particular index value.
index | Logical peripheral number for the UART indexed into the UART_config table |
params | Pointer to a parameter block. If NULL, default parameter values will be used. All the fields in this structure are RO (read-only). |
void UART_Params_init | ( | UART_Params * | params | ) |
Function to initialize the UART_Params struct to its defaults.
params | An 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;
int 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 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 cancelled 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.
handle | A UART_Handle returned by UART_open() |
buffer | A read-only pointer to buffer containing data to be written to the UART |
size | The number of bytes in the buffer that should be written to the UART |
int 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).
handle | A UART_Handle returned by UART_open() |
buffer | A read-only pointer to the buffer containing the data to be written to the UART |
size | The number of bytes in the buffer that should be written to the UART |
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.
handle | A UART_Handle returned by UART_open() |
int 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 cancelled 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.
handle | A UART_Handle returned by UART_open() |
buffer | A pointer to an empty buffer to which received data should be written |
size | The number of bytes to be written into buffer |
int 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.
handle | A UART_Handle returned by UART_open() |
buffer | A pointer to an empty buffer in which received data should be written to |
size | The number of bytes to be written into buffer |
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.
handle | A UART_Handle returned by UART_open() |