PRELIMINARY UART driver interface
WARNING These APIs are PRELIMINARY, and subject to change in the next few months.
To use the UART2 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 UART2 APIs to specific driver implementations which are specified using a pointer to a UART2_FxnTable.
A UART is used to translate data between the chip and a serial port. The UART2 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 modes.
The UART2 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.
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.
The following code example opens a UART instance, reads a byte from the UART, and then writes the byte back to the UART.
Details for the example code above are described in the following subsections.
Opening a UART requires four steps:
Only one UART index can be used at a time; calling UART2_open() a second time with the same index previosly passed to UART2_open() will result in an error. You can, though, re-use the index if the instance is closed via UART2_close(). In the previous example code, CONFIG_UART0 is passed to UART2_open(). This macro is defined in the example's ti_drivers_config.h file.
The UART driver can operate in blocking, callback, or polling mode, by setting the writeMode and readMode parameters passed to UART2_open(). If these parameters are not set, as in the example code, the UART2 driver defaults to blocking mode. Options for the writeMode and readMode parameters are UART2_Mode_BLOCKING, UART2_Mode_CALLBACK, and UART2_Mode_POLLING:
The example code reads one byte frome the UART instance, and then writes one byte back to the same instance:
The UART2 driver allows full duplex data transfers. Therefore, it is possible to call UART2_read() and UART2_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 UART2_read(uart0, buffer0...), any other thread attempting UART2_read(uart0, buffer1...) will result in an error of UART2_STATUS_EINUSE, until all the data from the first UART2_read() has been transferred to buffer0. This applies to blocking, callback, and polling modes. So applications must either synchronize UART2_read() (or UART2_write()) calls that use the same UART handle, or check for the UART2_STATUS_EINUSE return code indicating that a transfer is still ongoing.
Refer to the Driver's Configuration section for driver configuration information.
#include <stddef.h>
#include <stdint.h>
Go to the source code of this file.
Data Structures | |
struct | UART2_Params |
UART2 Parameters. More... | |
struct | UART2_FxnTable |
The definition of a UART2 function table that contains the required set of functions to control a specific UART2 driver implementation. More... | |
struct | UART2_Config |
UART2 Global configuration. More... | |
Macros | |
#define | UART2_STATUS_SUCCESS (0) |
Successful status code returned by UART2 APIs. More... | |
#define | UART2_STATUS_SREADTIMEOUT (1) |
A read timeout occurred (not an error). More... | |
#define | UART2_STATUS_EFRAMING (-1) |
A framing error occurred. More... | |
#define | UART2_STATUS_EPARITY (-2) |
A parity error occurred. More... | |
#define | UART2_STATUS_EBREAK (-4) |
A break error occurred. More... | |
#define | UART2_STATUS_EOVERRUN (-8) |
A FIFO overrun occurred. More... | |
#define | UART2_STATUS_EINUSE (-9) |
The UART is currently in use. More... | |
#define | UART2_STATUS_EINVALID (-10) |
An invalid argument or UART2_Params field was passed to UART2 API. More... | |
#define | UART2_STATUS_EFAIL (-11) |
General failure status returned by UART2 API. More... | |
#define | UART2_STATUS_EMEMORY (-12) |
A memory allocation failure occurred. More... | |
#define | UART2_STATUS_ETIMEOUT (-13) |
A timeout occurred for a blocking UART2_read or UART2_write call. More... | |
#define | UART2_STATUS_ECANCELLED (-14) |
A UART2_write() or UART2_read() operation was cancelled. More... | |
#define | UART2_STATUS_ENOTOPEN (-15) |
A UART2_write() or UART2_read() called on a device not opened. More... | |
#define | UART2_WAIT_FOREVER (~(0U)) |
Wait forever define. More... | |
Typedefs | |
typedef struct UART2_Config * | UART2_Handle |
A handle that is returned from a UART2_open() call. More... | |
typedef void(* | UART2_Callback) (UART2_Handle handle, void *buf, size_t count, void *userArg, int_fast16_t status) |
The definition of a callback function used by the UART2 driver when used in UART2_Mode_CALLBACK The callback can occur in task or HWI context. More... | |
typedef void(* | UART2_CloseFxn) (UART2_Handle handle) |
A function pointer to a driver specific implementation of UART2_CloseFxn(). More... | |
typedef void(* | UART2_FlushRxFxn) (UART2_Handle handle) |
A function to flush the RX data currently in the FIFO. More... | |
typedef UART2_Handle(* | UART2_OpenFxn) (uint_least8_t index, UART2_Params *params) |
A function pointer to a driver specific implementation of UART2_OpenFxn(). More... | |
typedef int_fast16_t(* | UART2_ReadFxn) (UART2_Handle handle, void *buffer, size_t size, size_t *bytesRead) |
A function pointer to a driver specific implementation of UART2_ReadFxn(). More... | |
typedef void(* | UART2_ReadCancelFxn) (UART2_Handle handle) |
A function pointer to a driver specific implementation of UART2_ReadCancelFxn(). More... | |
typedef int_fast16_t(* | UART2_WriteFxn) (UART2_Handle handle, const void *buffer, size_t size, size_t *bytesWritten) |
A function pointer to a driver specific implementation of UART2_WriteFxn(). More... | |
typedef void(* | UART2_WriteCancelFxn) (UART2_Handle handle) |
A function pointer to a driver specific implementation of UART2_WriteCancelFxn(). More... | |
typedef struct UART2_Config | UART2_Config |
UART2 Global configuration. More... | |
Enumerations | |
enum | UART2_Mode { UART2_Mode_BLOCKING, UART2_Mode_CALLBACK, UART2_Mode_POLLING } |
UART2 mode settings. More... | |
enum | UART2_ReadReturnMode { UART2_ReadReturnMode_FULL, UART2_ReadReturnMode_PARTIAL } |
UART2 return mode settings. More... | |
enum | UART2_DataLen { UART2_DataLen_5 = 0, UART2_DataLen_6 = 1, UART2_DataLen_7 = 2, UART2_DataLen_8 = 3 } |
UART2 data length settings. More... | |
enum | UART2_StopBits { UART2_StopBits_1 = 0, UART2_StopBits_2 = 1 } |
UART2 stop bit settings. More... | |
enum | UART2_Parity { UART2_Parity_NONE = 0, UART2_Parity_EVEN = 1, UART2_Parity_ODD = 2, UART2_Parity_ZERO = 3, UART2_Parity_ONE = 4 } |
UART2 parity type settings. More... | |
Functions | |
void | UART2_close (UART2_Handle handle) |
Function to close a UART peripheral specified by the UART2 handle. More... | |
void | UART2_flushRx (UART2_Handle handle) |
Function to flush data in the UART RX FIFO. More... | |
UART2_Handle | UART2_open (uint_least8_t index, UART2_Params *params) |
Function to initialize a given UART peripheral. More... | |
void | UART2_Params_init (UART2_Params *params) |
Function to initialize the UART2_Params struct to its defaults. More... | |
int_fast16_t | UART2_read (UART2_Handle handle, void *buffer, size_t size, size_t *bytesRead) |
Function that reads data from a UART. More... | |
void | UART2_readCancel (UART2_Handle handle) |
Function that cancels a UART2_read() function call. More... | |
int_fast16_t | UART2_write (UART2_Handle handle, const void *buffer, size_t size, size_t *bytesWritten) |
Function that writes data to a UART. More... | |
void | UART2_writeCancel (UART2_Handle handle) |
Function that cancels a UART2_write() function call. More... | |
#define UART2_WAIT_FOREVER (~(0U)) |
Wait forever define.
typedef struct UART2_Config* UART2_Handle |
A handle that is returned from a UART2_open() call.
typedef void(* UART2_Callback) (UART2_Handle handle, void *buf, size_t count, void *userArg, int_fast16_t status) |
The definition of a callback function used by the UART2 driver when used in UART2_Mode_CALLBACK The callback can occur in task or HWI context.
UART2_Handle | UART2_Handle |
buf | Pointer to read/write buffer |
count | Number of elements read/written |
userArg | A user supplied argument specified in UART2_Params. |
status | A UART2_STATUS code indicating success or failure of the transfer. |
typedef void(* UART2_CloseFxn) (UART2_Handle handle) |
A function pointer to a driver specific implementation of UART2_CloseFxn().
typedef void(* UART2_FlushRxFxn) (UART2_Handle handle) |
A function to flush the RX data currently in the FIFO.
typedef UART2_Handle(* UART2_OpenFxn) (uint_least8_t index, UART2_Params *params) |
A function pointer to a driver specific implementation of UART2_OpenFxn().
typedef int_fast16_t(* UART2_ReadFxn) (UART2_Handle handle, void *buffer, size_t size, size_t *bytesRead) |
A function pointer to a driver specific implementation of UART2_ReadFxn().
typedef void(* UART2_ReadCancelFxn) (UART2_Handle handle) |
A function pointer to a driver specific implementation of UART2_ReadCancelFxn().
typedef int_fast16_t(* UART2_WriteFxn) (UART2_Handle handle, const void *buffer, size_t size, size_t *bytesWritten) |
A function pointer to a driver specific implementation of UART2_WriteFxn().
typedef void(* UART2_WriteCancelFxn) (UART2_Handle handle) |
A function pointer to a driver specific implementation of UART2_WriteCancelFxn().
typedef struct UART2_Config UART2_Config |
UART2 Global configuration.
The UART2_Config structure contains a set of pointers used to characterize the UART2 driver implementation.
enum UART2_Mode |
UART2 mode settings.
This enum defines the read and write modes for the configured UART.
Enumerator | |
---|---|
UART2_Mode_BLOCKING | Uses a semaphore to block while data is being sent. Context of the call must be a Task. |
UART2_Mode_CALLBACK | Non-blocking and will return immediately. When UART2_write() or UART2_read() has finished, the callback function is called from either the caller's context or from an interrupt context. |
UART2_Mode_POLLING | UART is polled until all available data is received, or all data that can be sent without blocking is sent. Context of the call can be main(), Task, Swi, or Hwi. |
enum UART2_ReadReturnMode |
UART2 return mode settings.
This enumeration defines the return modes for UART2_read().
UART2_ReadReturnMode_FULL unblocks or performs a callback when the read buffer has been filled with the number of bytes passed to UART2_read(). UART2_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 UART2_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 | |
---|---|
UART2_ReadReturnMode_FULL | Unblock/callback when buffer is full. |
UART2_ReadReturnMode_PARTIAL | Unblock/callback when no new data comes in. |
enum UART2_DataLen |
enum UART2_StopBits |
enum UART2_Parity |
void UART2_close | ( | UART2_Handle | handle | ) |
Function to close a UART peripheral specified by the UART2 handle.
handle | A UART2_Handle returned from UART2_open() |
void UART2_flushRx | ( | UART2_Handle | handle | ) |
Function to flush data in the UART RX FIFO.
This function can be called to remove all data from the RX FIFO, for example, after a UART read error has occurred.
handle | A UART2_Handle returned from UART2_open() |
UART2_Handle UART2_open | ( | uint_least8_t | index, |
UART2_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 UART2_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 UART2_Params_init | ( | UART2_Params * | params | ) |
Function to initialize the UART2_Params struct to its defaults.
params | A pointer to UART2_Params structure for initialization |
Defaults values are: readMode = UART2_Mode_BLOCKING; writeMode = UART2_Mode_BLOCKING; readTimeout = UART2_WAIT_FOREVER; writeTimeout = UART2_WAIT_FOREVER; readCallback = NULL; writeCallback = NULL; readReturnMode = UART2_ReadReturnMode_FULL; baudRate = 115200; dataLength = UART2_DataLen_8; stopBits = UART2_StopBits_1; parityType = UART2_Parity_NONE;
int_fast16_t UART2_read | ( | UART2_Handle | handle, |
void * | buffer, | ||
size_t | size, | ||
size_t * | bytesRead | ||
) |
Function that reads data from a UART.
UART2_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 UART2_Mode_BLOCKING, UART2_read() blocks task execution until all the data in buffer has been read, if the read return mode is UART2_ReadReturnMode_FULL. If the read return mode is UART2_ReadReturnMode_PARTIAL, UART2_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).
In UART2_Mode_CALLBACK, UART2_read() does not block task execution. Instead, a callback function specified by UART2_Params::readCallback is called when the transfer is finished (UART2_ReadReturnMode_FULL), or reception has become inactive (UART2_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 canceled using UART2_readCancel() before calling UART2_close().
In UART2_Mode_POLLING, UART2_read() will return the minimum of size and the number of data in the RX FIFO. In this mode, UART2_read() is non-blocking, but the application should check the number of bytes read in the bytesRead parameter. A status of success will be returned even if not all bytes requested were read, unless an error occured.
handle | A UART2_Handle returned by UART2_open() |
buffer | A pointer to an empty buffer to which received data should be read |
size | The number of bytes to be read into buffer |
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. Similarly, in blocking mode with infinite timeout, NULL can be passed. However, status should be checked in case the number of bytes requested was not received due to errors. In polling mode, it is not recommended to pass NULL for this parameter, as it would be impossible to determine the number of bytes actually read. |
UART2_STATUS_SUCCESS | The call was successful. |
UART2_STATUS_EINUSE | Another read from the UART is currently ongoing. |
UART2_STATUS_ETIMEOUT | The read operation timed out. |
UART2_STATUS_EOVERRUN | A fifo overrun occurred. |
UART2_STATUS_EFRAMING | A framinig error occurred. |
UART2_STATUS_EBREAK | A break error occurred. |
UART2_STATUS_EPARITY | A parity error occurred. |
void UART2_readCancel | ( | UART2_Handle | handle | ) |
Function that cancels a UART2_read() function call.
This function cancels an asynchronous UART2_read() operation in in UART2_Mode_CALLBACK, or unblocks a UART2_read() call in UART2_Mode_BLOCKING. In UART2_Mode_CALLBACK, UART2_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 case only a subset of the bytes were received. The callback function will be passed a status of UART2_STATUS_ECANCELLED.
In UART2_Mode_BLOCKING, UART2_read() will return UART2_STATUS_ECANCELLED, and the bytesRead parameter will be set to the number of bytes received so far.
This API has no affect in UART2_Mode_POLLING.
handle | A UART2_Handle returned by UART2_open() |
int_fast16_t UART2_write | ( | UART2_Handle | handle, |
const void * | buffer, | ||
size_t | size, | ||
size_t * | bytesWritten | ||
) |
Function that writes data to a UART.
UART2_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 UART2_Mode_BLOCKING, UART2_write() blocks task execution until all the data in buffer has been written.
In UART2_Mode_CALLBACK, UART2_write() does not block task execution. Instead, a callback function specified by UART2_Params::writeCallback is called when the transfer is finished. The buffer passed to UART2_write() in UART2_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 UART2_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 UART2_writeCancel() before calling UART2_close().
In UART2_Mode_POLLING, UART2_write() will send out as many of the bytes in the buffer as possible, until the TX FIFO is full. In polling mode, UART2_write() is non-blocking and can be called from any context. The bytesWritten parameter should not be NULL so the application can determine the number of bytes actually written.
handle | A UART2_Handle returned by UART2_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 |
bytesWritten | If non-NULL, the location to store the number of bytes actually written to the UART in UART2_Mode_BLOCKING and UART2_Mode_POLLING. In UART2_Mode_CALLBACK, bytesWritten will be set to 0. If bytesWritten is NULL, this parameter will be ignored. In polling mode, it is not recommended to pass NULL for bytesWritten, as the application would have no way to determine the number of bytes actually written. In polling mode, a status of success will be returned even if not all the requested bytes could be written. |
UART2_STATUS_SUCCESS | The call was successful. |
UART2_STATUS_EINUSE | Another write to the UART is currently ongoing. |
UART2_STATUS_ETIMEOUT | The write operation timed out. |
void UART2_writeCancel | ( | UART2_Handle | handle | ) |
Function that cancels a UART2_write() function call.
This function cancels an asynchronous UART2_write() operation when write mode is UART2_Mode_CALLBACK, or an ongoing UART2_write() in UART2_Mode_POLLING. In callback mode, UART2_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 UART2_STATUS_ECANCELLED. In blocking mode, UART2_write() will return UART2_STATUS_ECANCELLED.
This API has no affect in polling mode.
handle | A UART2_Handle returned by UART2_open() |