APIs for UART

Introduction

This module contains APIs to program and use the UART.

Files
file	uart_sci.h
	This file contains the prototype of UART driver APIs.

Data Structures
struct	UART_Transaction
	Data structure used with UART_read() and UART_write() More...
struct	UART_Params
	UART Parameters. More...
struct	UART_Attrs
	UART instance attributes - used during init time. More...
struct	UART_EdmaParams
	UART EDMA Parameters. More...
struct	UART_Object
	UART driver object. More...
struct	UART_Config
	UART global configuration array. More...

Functions
void	UART_init (void)
	This function initializes the UART module. More...
void	UART_deinit (void)
	This function de-initializes the UART module. More...
UART_Handle	UART_open (uint32_t index, const UART_Params *prms)
	This function opens a given UART peripheral. More...
void	UART_close (UART_Handle handle)
	Function to close a UART peripheral specified by the UART handle. More...
int32_t	UART_write (UART_Handle handle, UART_Transaction *trans)
	Function to perform UART write operation. More...
int32_t	UART_read (UART_Handle handle, UART_Transaction *trans)
	Function to perform UART read operation. More...
int32_t	UART_writeCancel (UART_Handle handle, UART_Transaction *trans)
	Function to perform UART canceling of current write transaction. More...
int32_t	UART_readCancel (UART_Handle handle, UART_Transaction *trans)
	Function to perform UART canceling of current read transaction. More...
UART_Handle	UART_getHandle (uint32_t index)
	Function to return a open'ed UART handle given a UART instance index. More...
void	UART_flushTxFifo (UART_Handle handle)
	Function to flush a TX FIFO of peripheral specified by the UART handle. More...
static void	UART_Params_init (UART_Params *prms)
	Function to initialize the UART_Params struct to its defaults. More...
static void	UART_Transaction_init (UART_Transaction *trans)
	Function to initialize the UART_Transaction struct to its defaults. More...

Typedefs
typedef void *	UART_Handle
	A handle that is returned from a UART_open() call. More...
typedef void(*	UART_CallbackFxn) (UART_Handle handle, UART_Transaction *transaction)
	The definition of a callback function used by the UART driver when used in UART_TRANSFER_MODE_CALLBACK. More...

Transfer Status Code
Status codes that are set by the UART driver
#define	UART_TRANSFER_STATUS_SUCCESS   (0U)
	Transaction success. More...
#define	UART_TRANSFER_STATUS_TIMEOUT   (1U)
	Time out error. More...
#define	UART_TRANSFER_STATUS_ERROR_BI   (2U)
	Break condition error. More...
#define	UART_TRANSFER_STATUS_ERROR_FE   (3U)
	Framing error. More...
#define	UART_TRANSFER_STATUS_ERROR_PE   (4U)
	Parity error. More...
#define	UART_TRANSFER_STATUS_ERROR_OE   (5U)
	Overrun error. More...
#define	UART_TRANSFER_STATUS_CANCELLED   (6U)
	Cancelled. More...
#define	UART_TRANSFER_STATUS_STARTED   (7U)
	Transaction started. More...
#define	UART_TRANSFER_STATUS_READ_TIMEOUT   (8U)
	Read timeout error. More...
#define	UART_TRANSFER_STATUS_ERROR_INUSE   (9U)
	UART is currently in use. More...
#define	UART_TRANSFER_STATUS_ERROR_OTH   (10U)
	Other errors. More...

Transfer Mode
This determines whether the driver operates synchronously or asynchronously In UART_TRANSFER_MODE_BLOCKING mode UART_read() and UART_write() blocks code execution until the transaction has completed In UART_TRANSFER_MODE_CALLBACK UART_read() and UART_write() does not block code execution and instead calls a UART_CallbackFxn callback function when the transaction has completed
#define	UART_TRANSFER_MODE_BLOCKING   (0U)
	UART read/write APIs blocks execution. This mode can only be used when called within a Task context. More...
#define	UART_TRANSFER_MODE_CALLBACK   (1U)
	UART read/write APIs does not block code execution and will call a UART_CallbackFxn. This mode can be used in a Task, Swi, or Hwi context. More...

UART data length
Note: The values should not be changed since it represents the actual register configuration values used to configure the UART
#define	UART_LEN_1   (0U)
#define	UART_LEN_2   (1U)
#define	UART_LEN_3   (2U)
#define	UART_LEN_4   (3U)
#define	UART_LEN_5   (4U)
#define	UART_LEN_6   (5U)
#define	UART_LEN_7   (6U)
#define	UART_LEN_8   (7U)

UART stop bits
Note: The values should not be changed since it represents the actual register configuration values used to configure the UART
#define	UART_STOPBITS_1   (0U)
#define	UART_STOPBITS_2   (1U)

UART Parity
Note: The values should not be changed since it represents the actual register configuration values used to configure the UART
#define	UART_PARITY_NONE   (0x00U)
#define	UART_PARITY_ODD   (0x01U)
#define	UART_PARITY_EVEN   (0x03U)

UART Configration Mode
This determines whether the driver configuration mode like Polled, Interrupt, Dma used for the transfer function
#define	UART_CONFIG_MODE_POLLED   (0x00U)
#define	UART_CONFIG_MODE_INTERRUPT   (0x01U)
#define	UART_CONFIG_MODE_USER_INTR   (0x02U)
#define	UART_CONFIG_MODE_DMA   (0x03U)

Macro Definition Documentation

UART_TRANSFER_STATUS_SUCCESS

#define UART_TRANSFER_STATUS_SUCCESS   (0U)

Transaction success.

UART_TRANSFER_STATUS_TIMEOUT

#define UART_TRANSFER_STATUS_TIMEOUT   (1U)

Time out error.

UART_TRANSFER_STATUS_ERROR_BI

#define UART_TRANSFER_STATUS_ERROR_BI   (2U)

Break condition error.

UART_TRANSFER_STATUS_ERROR_FE

#define UART_TRANSFER_STATUS_ERROR_FE   (3U)

Framing error.

UART_TRANSFER_STATUS_ERROR_PE

#define UART_TRANSFER_STATUS_ERROR_PE   (4U)

Parity error.

UART_TRANSFER_STATUS_ERROR_OE

#define UART_TRANSFER_STATUS_ERROR_OE   (5U)

Overrun error.

UART_TRANSFER_STATUS_CANCELLED

#define UART_TRANSFER_STATUS_CANCELLED   (6U)

Cancelled.

UART_TRANSFER_STATUS_STARTED

#define UART_TRANSFER_STATUS_STARTED   (7U)

Transaction started.

UART_TRANSFER_STATUS_READ_TIMEOUT

#define UART_TRANSFER_STATUS_READ_TIMEOUT   (8U)

Read timeout error.

UART_TRANSFER_STATUS_ERROR_INUSE

#define UART_TRANSFER_STATUS_ERROR_INUSE   (9U)

UART is currently in use.

UART_TRANSFER_STATUS_ERROR_OTH

#define UART_TRANSFER_STATUS_ERROR_OTH   (10U)

Other errors.

UART_TRANSFER_MODE_BLOCKING

#define UART_TRANSFER_MODE_BLOCKING   (0U)

UART read/write APIs blocks execution. This mode can only be used when called within a Task context.

UART_TRANSFER_MODE_CALLBACK

#define UART_TRANSFER_MODE_CALLBACK   (1U)

UART read/write APIs does not block code execution and will call a UART_CallbackFxn. This mode can be used in a Task, Swi, or Hwi context.

UART_LEN_1

#define UART_LEN_1   (0U)

UART_LEN_2

#define UART_LEN_2   (1U)

UART_LEN_3

#define UART_LEN_3   (2U)

UART_LEN_4

#define UART_LEN_4   (3U)

UART_LEN_5

#define UART_LEN_5   (4U)

UART_LEN_6

#define UART_LEN_6   (5U)

UART_LEN_7

#define UART_LEN_7   (6U)

UART_LEN_8

#define UART_LEN_8   (7U)

UART_STOPBITS_1

#define UART_STOPBITS_1   (0U)

UART_STOPBITS_2

#define UART_STOPBITS_2   (1U)

UART_PARITY_NONE

#define UART_PARITY_NONE   (0x00U)

UART_PARITY_ODD

#define UART_PARITY_ODD   (0x01U)

UART_PARITY_EVEN

#define UART_PARITY_EVEN   (0x03U)

UART_CONFIG_MODE_POLLED

#define UART_CONFIG_MODE_POLLED   (0x00U)

UART_CONFIG_MODE_INTERRUPT

#define UART_CONFIG_MODE_INTERRUPT   (0x01U)

UART_CONFIG_MODE_USER_INTR

#define UART_CONFIG_MODE_USER_INTR   (0x02U)

UART_CONFIG_MODE_DMA

#define UART_CONFIG_MODE_DMA   (0x03U)

Typedef Documentation

UART_Handle

typedef void* UART_Handle

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

UART_CallbackFxn

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

The definition of a callback function used by the UART driver when used in UART_TRANSFER_MODE_CALLBACK.

Parameters

UART_Handle	UART_Handle
UART_Transaction*	Pointer to a UART_Transaction

Function Documentation

UART_init()

void UART_init

(

void

)

This function initializes the UART module.

UART_deinit()

void UART_deinit

(

void

)

This function de-initializes the UART module.

UART_open()

UART_Handle UART_open	(	uint32_t	index,
		const UART_Params *	prms
	)

This function opens a given UART peripheral.

Precondition

UART controller has been initialized using UART_init()

Parameters

index	Index of config to use in the UART_Config array
prms	Pointer to open parameters. If NULL is passed, then default values will be used

Returns

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

See also

UART_init()

UART_close()

UART_Params_init

UART_close()

void UART_close

(

UART_Handle

handle

)

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

Precondition

UART_open() has to be called first

Parameters

handle

UART_Handle returned from UART_open()

See also

UART_open()

UART_write()

int32_t UART_write	(	UART_Handle	handle,
		UART_Transaction *	trans
	)

Function to perform UART write operation.

In UART_TRANSFER_MODE_BLOCKING, UART_write() will block task execution until the transaction has completed or a timeout has occurred.

In UART_TRANSFER_MODE_CALLBACK, UART_write() does not block task execution, but calls a UART_CallbackFxn once the transfer has finished. This makes UART_write() safe to be used within a Task, software or hardware interrupt context.

In interrupt mode, UART_write() does not wait until tx fifo is empty. Application needs to call UART_flushTxFifo() to ensure write is completed. i.e. data is out from the FIFO and shift registers.

From calling UART_write() until transfer completion, the UART_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the UART_Transaction.buf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption.

Parameters

handle

UART_Handle returned from UART_open()

trans

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 has occurred, UART_Transaction.count will contain the number of bytes that were transferred. Neither is it allowed to modify the transaction object nor the content of UART_Transaction.buf until the transfer has completed

Returns

SystemP_SUCCESS if started successfully; else error on failure

See also

UART_open

UART_read()

int32_t UART_read	(	UART_Handle	handle,
		UART_Transaction *	trans
	)

Function to perform UART read operation.

In UART_TRANSFER_MODE_BLOCKING, UART_read() will block task execution until the transaction has completed or a timeout has occurred.

In UART_TRANSFER_MODE_CALLBACK, UART_read() does not block task execution, but calls a UART_CallbackFxn once the transfer has finished. This makes UART_read() safe to be used within a Task, software or hardware interrupt context.

From calling UART_read() until transfer completion, the UART_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the UART_Transaction.buf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption.

Parameters

handle

UART_Handle returned from UART_open()

trans

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 has occurred, UART_Transaction.count will contain the number of bytes that were transferred. Neither is it allowed to modify the transaction object nor the content of UART_Transaction.buf until the transfer has completed

Returns

SystemP_SUCCESS if started successfully; else error on failure

See also

UART_open

UART_writeCancel()

int32_t UART_writeCancel	(	UART_Handle	handle,
		UART_Transaction *	trans
	)

Function to perform UART canceling of current write transaction.

In UART_TRANSFER_MODE_CALLBACK, UART_writeCancel() does not block task execution, but calls a UART_CallbackFxn once the cancel has finished. This makes UART_writeCancel() safe to be used within a Task, software or hardware interrupt context.

From calling UART_writeCancel() until cancel completion, the UART_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the UART_Transaction.buf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption.

Parameters

handle

UART_Handle returned from UART_open()

trans

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 has occurred, UART_Transaction.count will contain the number of bytes that were transferred. Neither is it allowed to modify the transaction object nor the content of UART_Transaction.buf until the transfer has completed

Returns

SystemP_SUCCESS if started successfully; else error on failure

See also

UART_open

UART_readCancel()

int32_t UART_readCancel	(	UART_Handle	handle,
		UART_Transaction *	trans
	)

Function to perform UART canceling of current read transaction.

In UART_TRANSFER_MODE_CALLBACK, UART_readCancel() does not block task execution, but calls a UART_CallbackFxn once the cancel has finished. This makes UART_writeCancel() safe to be used within a Task, software or hardware interrupt context.

From calling UART_readCancel() until cancel completion, the UART_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the UART_Transaction.buf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption.

Parameters

handle

UART_Handle returned from UART_open()

trans

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 has occurred, UART_Transaction.count will contain the number of bytes that were transferred. Neither is it allowed to modify the transaction object nor the content of UART_Transaction.buf until the transfer has completed

Returns

SystemP_SUCCESS if started successfully; else error on failure

See also

UART_open

UART_getHandle()

UART_Handle UART_getHandle

(

uint32_t

index

)

Function to return a open'ed UART handle given a UART instance index.

Parameters

index

Index of config to use in the UART_Config array

Returns

A UART_Handle on success or a NULL on an error or if the instance index has NOT been opened yet

UART_flushTxFifo()

void UART_flushTxFifo

(

UART_Handle

handle

)

Function to flush a TX FIFO of peripheral specified by the UART handle.

Precondition

UART_open() has to be called first

Parameters

handle

UART_Handle returned from UART_open()

See also

UART_open()

UART_Params_init()

static void UART_Params_init ( UART_Params *  prms )

inlinestatic

Function to initialize the UART_Params struct to its defaults.

Parameters

prms	Pointer to UART_Params structure for initialization

UART_Transaction_init()

static void UART_Transaction_init ( UART_Transaction *  trans )

inlinestatic

Function to initialize the UART_Transaction struct to its defaults.

Parameters

trans

Pointer to UART_Transaction structure for initialization

Variable Documentation

gUartConfig

UART_Config gUartConfig[]

extern

Externally defined driver configuration array.

gUartConfigNum

uint32_t gUartConfigNum

extern

Externally defined driver configuration array size.