Introduction

UART driver interface

Sub Modules
	UART Driver Error code

Files
file	UART.h
	UART driver interface.

Data Structures
struct	UART_Transaction
	A UART_Transaction data structure is used with UART_read2(), UART_write2() and UART_Callback2() More...

struct	UART_Params
	Basic 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...

Functions
void	UART_close (UART_Handle uartHnd)
	Function to closes a given UART peripheral specified by the UART handle. More...

int32_t	UART_control (UART_Handle uartHnd, uint32_t cmd, void *arg)
	Function performs implementation specific features on a given UART_Handle. More...

void	UART_init (void)
	Function to initializes the UART module. More...

UART_Handle	UART_open (uint32_t idx, UART_Params *uartParams)
	Function to initialize a given UART peripheral specified by the particular index value. The parameter specifies which mode the UART will operate. More...

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

int32_t	UART_write (UART_Handle uartHnd, const void *buffer, size_t size)
	Function that writes data to a UART. More...

int32_t	UART_writePolling (UART_Handle uartHnd, const void *buffer, size_t size)
	Function that writes data to a UART. More...

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

int32_t	UART_read (UART_Handle handle, void *buffer, size_t size)
	Function that read data from a UART. More...

int32_t	UART_readPolling (UART_Handle handle, void *buffer, size_t size)
	Function that reads data from a UART. More...

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

int32_t	UART_read2 (UART_Handle handle, UART_Transaction *uartTrans)
	Extended function that read data from a UART. More...

int32_t	UART_write2 (UART_Handle handle, UART_Transaction *uartTrans)
	Extended function that writes data to a UART. More...

void	UART_transactionInit (UART_Transaction *uartTrans)
	Function to initialize the UART_Transaction struct to its defaults. More...

Typedefs
typedef struct UART_Config_s *	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. More...

typedef void(*	UART_Callback2) (UART_Handle handle, UART_Transaction *transaction)
	The definition of a callback2 function used by the UART driver when used in UART_MODE_CALLBACK. More...

typedef void(*	UART_CloseFxn) (UART_Handle handle)
	A function pointer to a driver specific implementation of UART_CloseFxn(). More...

typedef int32_t(*	UART_ControlFxn) (UART_Handle handle, uint32_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, const UART_Params *params)
	A function pointer to a driver specific implementation of UART_OpenFxn(). More...

typedef int32_t(*	UART_ReadFxn) (UART_Handle handle, void *buffer, size_t size)
	A function pointer to a driver specific implementation of UART_ReadFxn(). More...

typedef int32_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 int32_t(*	UART_WriteFxn) (UART_Handle handle, const void *buffer, size_t size)
	A function pointer to a driver specific implementation of UART_CloseFxn(). More...

typedef int32_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 int32_t(*	UART_ReadFxn2) (UART_Handle handle, UART_Transaction *transaction)
	A function pointer to a driver specific implementation of UART_ReadFxn2(). More...

typedef int32_t(*	UART_WriteFxn2) (UART_Handle handle, UART_Transaction *transaction)
	A function pointer to a driver specific implementation of UART_WriteFxn2(). More...

typedef UART_Config	UART_config_list[UART_MAX_CONFIG_CNT]

Enumerations
enum	UART_TransferApiVer { UART_TRANSFER_API_VER_1 = 1, UART_TRANSFER_API_VER_2 = 2 }
	Transfer API version. More...

enum	UART_TransferStatus { UART_TRANSFER_STATUS_SUCCESS = 0, UART_TRANSFER_STATUS_TIMEOUT, UART_TRANSFER_STATUS_ERROR_BI, UART_TRANSFER_STATUS_ERROR_FE, UART_TRANSFER_STATUS_ERROR_PE, UART_TRANSFER_STATUS_ERROR_OE, UART_TRANSFER_STATUS_ERROR_OTH }
	Transfer status codes that are set by the UART driver. More...

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, UART_DATA_TEXT }
	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...

enum	UART_FC_TYPE { UART_FC_NONE = 0, UART_FC_HW = 1 }
	UART flow control settings. More...

Macros
#define	UART_SUCCESS ((int32_t)(0))

#define	UART_ERROR (-((int32_t)1))

#define	UART_NO_WAIT ((uint32_t)0U)
	UART transaction timeout define. More...

#define	UART_WAIT_FOREVER (~((uint32_t)0U))

#define	UART_MAX_CONFIG_CNT (14U)

Macro Definition Documentation

◆ UART_SUCCESS

#define UART_SUCCESS ((int32_t)(0))

◆ UART_ERROR

#define UART_ERROR (-((int32_t)1))

◆ UART_NO_WAIT

#define UART_NO_WAIT ((uint32_t)0U)

UART transaction timeout define.

◆ UART_WAIT_FOREVER

#define UART_WAIT_FOREVER (~((uint32_t)0U))

◆ UART_MAX_CONFIG_CNT

#define UART_MAX_CONFIG_CNT (14U)

Typedef Documentation

◆ UART_Handle

typedef struct UART_Config_s* 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.

Parameters

UART_Handle	UART_Handle
buf	Pointer to read/write buffer
count	Number of elements read/written

◆ UART_Callback2

typedef void(* UART_Callback2) (UART_Handle handle, UART_Transaction *transaction)

The definition of a callback2 function used by the UART driver when used in UART_MODE_CALLBACK.

Parameters

UART_Handle	UART_Handle
transaction	A pointer to a UART_Transaction. All of the fields within transaction except UART_Transaction.count and UART_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout or error has occured, UART_Transaction.count will contain the number of bytes that were transferred.

◆ UART_CloseFxn

typedef void(* UART_CloseFxn) (UART_Handle handle)

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

◆ UART_ControlFxn

typedef int32_t(* UART_ControlFxn) (UART_Handle handle, uint32_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, const UART_Params *params)

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

◆ UART_ReadFxn

typedef int32_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 int32_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 int32_t(* UART_WriteFxn) (UART_Handle handle, const void *buffer, size_t size)

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

◆ UART_WritePollingFxn

typedef int32_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_ReadFxn2

typedef int32_t(* UART_ReadFxn2) (UART_Handle handle, UART_Transaction *transaction)

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

◆ UART_WriteFxn2

typedef int32_t(* UART_WriteFxn2) (UART_Handle handle, UART_Transaction *transaction)

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

◆ UART_config_list

typedef UART_Config UART_config_list[UART_MAX_CONFIG_CNT]

Enumeration Type Documentation

◆ UART_TransferApiVer

enum UART_TransferApiVer

Transfer API version.

Enumerator
UART_TRANSFER_API_VER_1
UART_TRANSFER_API_VER_2

◆ UART_TransferStatus

enum UART_TransferStatus

Transfer status codes that are set by the UART driver.

Enumerator
UART_TRANSFER_STATUS_SUCCESS
UART_TRANSFER_STATUS_TIMEOUT
UART_TRANSFER_STATUS_ERROR_BI
UART_TRANSFER_STATUS_ERROR_FE
UART_TRANSFER_STATUS_ERROR_PE
UART_TRANSFER_STATUS_ERROR_OE
UART_TRANSFER_STATUS_ERROR_OTH

◆ 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 the transfer by the Hwi is finished the configured callback function is called.

◆ UART_ReturnMode

enum UART_ReturnMode

UART return mode settings.

This enumeration defines the return modes for UART_read and UART_readPolling. 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.

Enumerator
UART_RETURN_FULL	Unblock/callback when buffer is full.
UART_RETURN_NEWLINE	Unblock/callback when newline character is received.

◆ UART_DataMode

enum UART_DataMode

UART data mode settings.

This enumeration defines the data mode for read and write. If the DataMode is text for write, write will add a return before a newline character. If the DataMode is text for a read, read will replace a return with 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
UART_LEN_6	Data length is 6
UART_LEN_7	Data length is 7
UART_LEN_8	Data length is 8

◆ 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

◆ UART_FC_TYPE

enum UART_FC_TYPE

UART flow control settings.

This enumeration defines the UART parity types.

Enumerator
UART_FC_NONE	No flow control
UART_FC_HW	Hardware flow control

Function Documentation

◆ UART_close()

void UART_close ( UART_Handle uartHnd )

Function to closes a given UART peripheral specified by the UART handle.

Precondition: UART_open() had to be called first.

Parameters

uartHnd A UART_Handle returned from UART_open

See also: UART_open

◆ UART_control()

int32_t UART_control	(	UART_Handle	uartHnd,
		uint32_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given UART_Handle.

Precondition: UART_open() has to be called first.

Parameters

uartHnd	A UART handle returned from UART_open()
cmd	A command value defined by the driver specific implementation
arg	An optional argument that is 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 initializes the UART module.

Precondition: The UART controller needs to be powered up and clocked. 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	(	uint32_t	idx,
		UART_Params *	uartParams
	)

Function to initialize a given UART peripheral specified by the particular index value. The parameter specifies which mode the UART will operate.

Precondition: UART controller has been initialized

Parameters

idx	Logical peripheral number indexed into the HWAttrs table
uartParams	Pointer to an parameter block, if NULL it will use default values

Returns: A UART_Handle on success or a NULL on an error or if it has been already opened

See also: UART_close

◆ UART_Params_init()

void UART_Params_init ( UART_Params * uartParams )

Function to initialize the UART_Params struct to its defaults.

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

Parameters

uartParams Parameter structure to initialize

◆ UART_write()

int32_t UART_write	(	UART_Handle	uartHnd,
		const void *	buffer,
		size_t	size
	)

Function that writes data to a UART.

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

In UART_MODE_BLOCKING, UART_write will block task execution until all the data in buffer has been written.

In UART_MODE_CALLBACK, UART_write does not block task execution an calls a callback function specified by writeCallback.

Parameters

uartHnd	A UART_Handle
buffer	A pointer to buffer containing data to be written
size	The number of bytes in buffer that should be written onto the UART.

Returns: Returns the number of bytes that have been written to the UART, UART_ERROR on an error.

◆ UART_writePolling()

int32_t UART_writePolling	(	UART_Handle	uartHnd,
		const void *	buffer,
		size_t	size
	)

Function that writes data to a UART.

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

UART_write will not return until all the data was written to the UART.

Parameters

uartHnd	A UART_Handle
buffer	A pointer to buffer containing data to be written
size	The number of bytes in buffer that should be written onto the UART.

Returns: Returns the number of bytes that have been written to the UART, UART_ERROR on an error.

◆ UART_writeCancel()

void UART_writeCancel ( UART_Handle handle )

Function that cancels a UART_write function call.

This function cancels an operation to write data to a UART controller when in UART_MODE_CALLBACK.

Parameters

handle A UART_Handle

◆ UART_read()

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

Function that read data from a UART.

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

In UART_MODE_BLOCKING, UART_read will block task execution until all the data in buffer has been read.

In UART_MODE_CALLBACK, UART_read does not block task execution an calls a callback function specified by readCallback.

Parameters

handle	A UART_Handle
buffer	A pointer to an empty buffer in which data should be written to
size	The number of bytes to be written into buffer

Returns: Returns the number of bytes that have been read from the UART, UART_ERROR on an error.

◆ UART_readPolling()

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

Function that reads data from a UART.

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

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

Parameters

handle	A UART_Handle
buffer	A pointer to an empty buffer in which data should be written to
size	The number of bytes to be written into buffer

Returns: Returns the number of bytes that have been read from the UART, UART_ERROR on an error.

◆ UART_readCancel()

void UART_readCancel ( UART_Handle handle )

Function that cancels a UART_read function call.

This function cancels an operation to read data from a UART controller when in UART_MODE_CALLBACK.

Parameters

handle A UART_Handle

◆ UART_read2()

int32_t UART_read2	(	UART_Handle	handle,
		UART_Transaction *	uartTrans
	)

Extended function that read data from a UART.

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

In UART_MODE_BLOCKING, UART_read2 will block task execution until all the data in buffer has been read.

In UART_MODE_CALLBACK, UART_read2 does not block task execution an calls a callback function specified by readCallback.

Parameters

handle A UART_Handle

uartTrans A pointer to a UART_Transaction. All of the fields within transaction except UART_Transaction.count and UART_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout or error has occured, UART_Transaction.count will contain the number of bytes that were transferred. In the callback mode, the application allocates transaction memory and UART driver owns the pointer unitil it is returned to the application via the callback function, thus the memory should not be allocated on the stack, and dynamic free must occur in the callback (not immediately after calling read2/write2)

Returns: Returns UART_SUCCESS or UART_ERROR on an error.

◆ UART_write2()

int32_t UART_write2	(	UART_Handle	handle,
		UART_Transaction *	uartTrans
	)

Extended function that writes data to a UART.

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

In UART_MODE_BLOCKING, UART_write will block task execution until all the data in buffer has been written.

In UART_MODE_CALLBACK, UART_write does not block task execution an calls a callback function specified by writeCallback.

Parameters

handle A UART_Handle

uartTrans A pointer to a UART_Transaction. All of the fields within transaction except UART_Transaction.count and UART_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout or error has occured, UART_Transaction.count will contain the number of bytes that were transferred. In the callback mode, the application allocates transaction memory and UART driver owns the pointer unitil it is returned to the application via the callback function, thus the memory should not be allocated on the stack, and dynamic free must occur in the callback (not immediately after calling read2/write2)

Returns: Returns UART_SUCCESS or UART_ERROR on an error.

◆ UART_transactionInit()

void UART_transactionInit ( UART_Transaction * uartTrans )

Function to initialize the UART_Transaction struct to its defaults.

Parameters

uartTrans A pointer to a UART_Transaction to be initialized.

Returns: uartTrans initialized with default values such as: uartTrans->buf = NULL; uartTrans->timeout = UART_WAIT_FOREVER; uartTrans->count = 0; uartTrans->status = UART_TRANSFER_STATUS_SUCCESS;

Introduction

Sub Modules

Files

Data Structures

Functions

Typedefs

Enumerations

Macros

Macro Definition Documentation

◆ UART_SUCCESS

◆ UART_ERROR

◆ UART_NO_WAIT

◆ UART_WAIT_FOREVER

◆ UART_MAX_CONFIG_CNT

Typedef Documentation

◆ UART_Handle

◆ UART_Callback

◆ UART_Callback2

◆ UART_CloseFxn

◆ UART_ControlFxn

◆ UART_InitFxn

◆ UART_OpenFxn

◆ UART_ReadFxn

◆ UART_ReadPollingFxn

◆ UART_ReadCancelFxn

◆ UART_WriteFxn

◆ UART_WritePollingFxn

◆ UART_WriteCancelFxn

◆ UART_ReadFxn2

◆ UART_WriteFxn2

◆ UART_config_list

Enumeration Type Documentation

◆ UART_TransferApiVer

◆ UART_TransferStatus

◆ UART_Mode

◆ UART_ReturnMode

◆ UART_DataMode

◆ UART_Echo

◆ UART_LEN

◆ UART_STOP

◆ UART_PAR

◆ UART_FC_TYPE

Function Documentation

◆ UART_close()

◆ UART_control()

◆ UART_init()

◆ UART_open()

◆ UART_Params_init()

◆ UART_write()

◆ UART_writePolling()

◆ UART_writeCancel()

◆ UART_read()

◆ UART_readPolling()

◆ UART_readCancel()

◆ UART_read2()

◆ UART_write2()

◆ UART_transactionInit()