UART

UART is used to translate the data between the chip and a serial port. The UART driver provides API to perform read and write to any of the UART peripherals on the board, with the multiple modes of operation.

Features Supported

• Write and Read mode of operation

• Interrupt, Polled Mode

• DMA mode of operation

• Blocking and Non-blocking (callback) transfers

• Write and Read Cancel mode of operation

• For low latency direct register read/write API, refer UART Echo Low Latency Interrupt and UART Echo Low Latency Polling example.

SysConfig Features

Note

It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.

SysConfig can be used to configure below parameters apart from common configuration like Clock,MPU,RAT and others.

• UART module configuration parmaters like baudrate, parity type, datalength and others.

• UART instances and pin configurations.

• Interrupt mode option is used to select one of the following.

  • Polling Mode.

  • Interrupt Mode in which driver manages the interrupt service routine.

  • User Managed Interrupt in which user manages the interrupt service routine. This mode can be used in low latency applications.

• Based on above parameters, the SysConfig generated code does below as part of Drivers_open and Drivers_close functions

  • Set UART instance parameter configuration.

  • Driver ISR registration if Interrupt Mode is enabled.

  • Skip driver ISR registration if “User Managed Interrupt” mode is configured.

• In case of DMA mode, please configure UDMA instance to PKTDMA_0.

Features NOT Supported

• #UART_READ_RETURN_MODE_PARTIAL is not supported in DMA mode of operation

• DMA mode is not supported.

• MODEM control functions

• IrDA(Infrared Data Association) and CIR(Consumer Infrared) features

Usage Overview

API Sequence

To use the UART driver to send data or receive, the application calls the following APIs:

• #UART_init() : Initialize the UART driver.

• #UART_Params_init(): Initialize a #UART_Params structure with default values. Then change the parameters from non-default values as needed.

• #UART_open() : Open an instance of the UART driver, passing the initialized parameters, or NULL, and an index to the configuration to open (detailed later).

• #UART_write(): Transmit data. This function takes a #UART_Transaction argument that describes the transfer that is requested.

• #UART_read() : Receive data. This function takes a #UART_Transaction argument that describes the receive that is requested.

• #UART_close(): De-initialize the UART instance.

• #UART_deinit(): De-Initialize the UART driver.

Initializing the UART Driver

#UART_init() must be called before any other UART APIs. This function iterates through the elements of the UART_config[] array, calling the element’s device implementation UART initialization function. Please note that initializing UART driver is taken care by the SysConfig generated code.

Opening the UART Driver

After initializing the UART driver by calling #UART_init(), the application can open a UART instance by calling #UART_open(). Please note that opening UART driver is taken care by the SysConfig generated code. This function takes an index into the UART_config[] array, and the UART parameters data structure. The UART instance is specified by the index of the UART in UART_config[]. Calling #UART_open() second time with the same index previously passed to #UART_open() will result in an error. You can, though, re-use the index if the instance is closed via #UART_close().

If no #UART_Params_init structure is passed to UART_open(), default values are used. If the open call is successful, it returns a non-NULL value.

UART Write Mode

The UART driver supports two transfer modes of operation: interrupt and polling mode. In polling mode a task’s code execution is blocked until a UART transaction has completed or a timeout has occurred.

In interrupt mode, again there are two modes blocking and callback. The transfer mode is determined by the #UART_Params.writeMode parameter. The UART driver defaults to blocking mode, if the application does not set it. Once a UART driver is opened, the only way to change the operation mode is to close and re-open the UART instance with the new write mode.

In blocking mode, a task’s code execution is blocked until a UART transaction has completed or a timeout has occurred. This ensures that only one UART transfer operates at a given time. Other tasks requesting UART transfers while a transfer is currently taking place will receive an error as return value. If a timeout occurs the transfer is cancelled, the task is unblocked & will receive an error as return value. The transaction count field will have the number of bytes transferred successfully before the timeout.

In callback mode, a UART transaction functions asynchronously, which means that it does not block code execution. After a UART transaction has been completed, the UART driver calls a user-provided callback function. Callback mode is supported in the execution context of tasks and hardware interrupt routines.

UART Read Mode

The UART driver supports two read modes of operation: interrupt and polling mode. In polling mode a task’s code execution is blocked until a UART transaction has completed or a timeout has occurred.

In interrupt mode, again there are two modes blocking and callback. The read mode is determined by the #UART_Params.readMode parameter. The UART driver defaults to blocking mode, if the application does not set it. Once a UART driver is opened, the only way to change the operation mode is to close and re-open the UART instance with the new read mode.

In blocking mode, a task’s code execution is blocked until a UART transaction has completed or a timeout has occurred. This ensures that only one UART read completes at a given time. Other tasks requesting UART read while a read is currently taking place will receive an error as return value. If a timeout occurs the read is cancelled, the task is unblocked & will receive an error as return value. The transaction count field will have the number of bytes read successfully before the timeout.

In callback mode, a UART transaction functions asynchronously, which means that it does not block code execution. After a UART transaction has been completed, the UART driver calls a user-provided callback function. Callback mode is supported in the execution context of tasks and hardware interrupt routines.

There is an additional #UART_Params.readReturnMode parameter. #UART_READ_RETURN_MODE_FULL unblocks or performs a callback when the read buffer has been filled with the number of bytes passed to #UART_read(). #UART_READ_RETURN_MODE_PARTIAL unblocks or performs a callback whenever a read timeout error occurs on the UART peripheral. The read timeout occurs if the read FIFO is non-empty and no new data has been received for a specific number of clock cycles w.r.o device/baudrate dependent. This mode can be used when the exact number of bytes to be read is not known.

Important Usage Guidelines

• In case of DMA mode, as R5F core is not Cache Coherent, Cache Writeback is required if R5F writes to the buffers. And before reading the buffers, application needs to invalidate those. Please refer UART Echo DMA.

Example Usage

Include the below file to access the APIs

#include <drivers/uart.h>

Instance Open Example

    UART_Params         params;

    UART_Params_init(&params);      /* Initialize parameters */
    params.baudRate = 115200;
    gUartHandle = UART_open(CONFIG_UART0, &params);
    DebugP_assert(gUartHandle != NULL);

Instance Close Example

    UART_close(gUartHandle);

Write Transfer Example

    int32_t             transferOK;
    UART_Transaction    transaction;
    uint8_t             txBuffer[APP_UART_MSGSIZE];

    UART_Transaction_init(&transaction);
 
 /* Initiate write */
    transaction.count   = APP_UART_MSGSIZE;
    transaction.buf     = (void *)txBuffer;
    transaction.args    = NULL;
    transferOK = UART_write(gUartHandle, &transaction);
    if((SystemP_SUCCESS != transferOK) ||
       (UART_TRANSFER_STATUS_SUCCESS != transaction.status))
    {
        /* UART transfer failed!! */
        DebugP_assert(FALSE);
    }

Read Transfer Example

    int32_t             transferOK;
    UART_Transaction    transaction;
    uint8_t             rxBuffer[APP_UART_MSGSIZE];

    UART_Transaction_init(&transaction);

    /* Initiate read */
    transaction.count   = APP_UART_MSGSIZE;
    transaction.buf     = (void *)rxBuffer;
    transaction.args    = NULL;
    transferOK = UART_read(gUartHandle, &transaction);
    if((SystemP_SUCCESS != transferOK) ||
       (UART_TRANSFER_STATUS_SUCCESS != transaction.status))
    {
        /* UART transfer failed!! */
        DebugP_assert(FALSE);
    }

Write Non-Blocking Transfer Example

void write_callback(UART_Handle handle, UART_Transaction *trans)
{
    DebugP_assertNoLog(UART_TRANSFER_STATUS_SUCCESS == trans->status);
    gNumBytesWritten = trans->count;
    SemaphoreP_post(&gUartWriteDoneSem);

    return;
}

void write_transfer_nonblocking(void)
{
    int32_t             transferOK;
    UART_Transaction    transaction;
    uint8_t             txBuffer[APP_UART_MSGSIZE];

    UART_Transaction_init(&transaction);

    /* Initiate write */
    transaction.count   = APP_UART_MSGSIZE;
    transaction.buf     = (void *)txBuffer;
    transaction.args    = NULL;
    transferOK = UART_write(gUartHandle, &transaction);
    if((SystemP_SUCCESS != transferOK) ||
       (UART_TRANSFER_STATUS_SUCCESS != transaction.status))
    {
        /* UART transfer failed!! */
        DebugP_assert(FALSE);
    }
    else
    {
        /* Wait for callback */
        SemaphoreP_pend(&gUartWriteDoneSem, SystemP_WAIT_FOREVER);
        DebugP_assert(gNumBytesWritten == transaction.count);
    }
}

Read Non-Blocking Transfer Example

void read_callback(UART_Handle handle, UART_Transaction *trans)
{
    DebugP_assertNoLog(UART_TRANSFER_STATUS_SUCCESS == trans->status);
    gNumBytesRead = trans->count;
    SemaphoreP_post(&gUartReadDoneSem);

    return;
}

void read_transfer_nonblocking(void)
{
    int32_t             transferOK;
    UART_Transaction    transaction;
    uint8_t             rxBuffer[APP_UART_MSGSIZE];

    UART_Transaction_init(&transaction);

    /* Initiate read */
    transaction.count   = APP_UART_MSGSIZE;
    transaction.buf     = (void *)rxBuffer;
    transaction.args    = NULL;
    transferOK = UART_read(gUartHandle, &transaction);
    if((SystemP_SUCCESS != transferOK) ||
       (UART_TRANSFER_STATUS_SUCCESS != transaction.status))
    {
        /* UART transfer failed!! */
        DebugP_assert(FALSE);
    }
    else
    {
        /* Wait for callback */
        SemaphoreP_pend(&gUartReadDoneSem, SystemP_WAIT_FOREVER);
        DebugP_assert(gNumBytesRead == transaction.count);
    }
}

Timeout

The UART driver uses SystemP_WAIT_FOREVER (0xFFFFFFFFU) as the default timeout for blocking transfers.

Configurable Timeout

The transfer timeout is configurable per-transaction via the timeout field in UART_Transaction, as shown below:

UART_Transaction txn;
UART_Transaction_init(&txn);   /* default: txn.timeout = SystemP_WAIT_FOREVER */
txn.timeout = 2000;            /* override: 2000 OS ticks */

When to change: Set a finite timeout in applications where the remote UART sender or receiver may become unresponsive. A finite timeout allows the application to detect a communication failure and take corrective action rather than blocking indefinitely.

Non-Configurable Timeouts

The following operations always use SystemP_WAIT_FOREVER and cannot be overridden by the application:

• Internal driver lock - A mutex protecting driver state, acquired at the start of every transfer. This waits forever if another transfer is already in progress on the same instance.

API Reference

This file contains the prototype of UART driver APIs.

Transfer Status Code

Status codes that are set by the UART driver

UART_TRANSFER_STATUS_SUCCESS

Transaction success.

UART_TRANSFER_STATUS_TIMEOUT

Time out error.

UART_TRANSFER_STATUS_ERROR_BI

Break condition error.

UART_TRANSFER_STATUS_ERROR_FE

Framing error.

UART_TRANSFER_STATUS_ERROR_PE

Parity error.

UART_TRANSFER_STATUS_ERROR_OE

Overrun error.

UART_TRANSFER_STATUS_CANCELLED

Cancelled.

UART_TRANSFER_STATUS_STARTED

Transaction started.

UART_TRANSFER_STATUS_READ_TIMEOUT

Read timeout error.

UART_TRANSFER_STATUS_ERROR_INUSE

UART is currently in use.

UART_TRANSFER_STATUS_ERROR_OTH

Other errors.

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

UART_TRANSFER_MODE_BLOCKING

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

UART_TRANSFER_MODE_CALLBACK

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 Read length

This enumeration defines the return modes for UART_read().

UART_READ_RETURN_MODE_FULL unblocks or performs a callback when the read buffer has been filled with the number of bytes passed to UART_read(). UART_READ_RETURN_MODE_PARTIAL unblocks or performs a callback whenever a read timeout error occurs on the UART peripheral. The read timeout occurs if the read FIFO is non-empty and no new data has been received for a specific device/baudrate dependent number of clock cycles. This mode can be used when the exact number of bytes to be read is not known.

UART_READ_RETURN_MODE_FULL

Unblock/callback when buffer is full.

UART_READ_RETURN_MODE_PARTIAL

Unblock/callback when no new data comes in.

UART data length

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_LEN_5

UART_LEN_6

UART_LEN_7

UART_LEN_8

UART stop bits

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_STOPBITS_1

UART_STOPBITS_2

UART Parity

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_PARITY_NONE

UART_PARITY_ODD

UART_PARITY_EVEN

UART_PARITY_FORCED0

UART_PARITY_FORCED1

UART Flow Control Type

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_FCTYPE_NONE

UART_FCTYPE_HW

UART Flow Control Params for RX

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_FCPARAM_RXNONE

UART_FCPARAM_RXXONXOFF_2

UART_FCPARAM_RXXONXOFF_1

UART_FCPARAM_RXXONXOFF_12

UART_FCPARAM_AUTO_RTS

UART Flow Control Params for TX

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_FCPARAM_TXNONE

UART_FCPARAM_TXXONXOFF_2

UART_FCPARAM_TXXONXOFF_1

UART_FCPARAM_TXXONXOFF_12

UART_FCPARAM_AUTO_CTS

UART RX trigger level

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_RXTRIGLVL_1

UART_RXTRIGLVL_8

UART_RXTRIGLVL_16

UART_RXTRIGLVL_56

UART_RXTRIGLVL_60

UART TX trigger level

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_TXTRIGLVL_1

UART_TXTRIGLVL_8

UART_TXTRIGLVL_16

UART_TXTRIGLVL_32

UART_TXTRIGLVL_56

UART Operational Mode

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_OPER_MODE_16X

UART_OPER_MODE_SIR

UART_OPER_MODE_16X_AUTO_BAUD

UART_OPER_MODE_13X

UART_OPER_MODE_MIR

UART_OPER_MODE_FIR

UART_OPER_MODE_CIR

UART_OPER_MODE_DISABLED

Values indicating the filled status of TX FIFO

Note: The values should not be changed since it represents the actual register configuration values used to configure the UART

UART_TX_FIFO_NOT_FULL

UART_TX_FIFO_FULL

Values related to status of Interrupt souces.

UART_INTID_MODEM_STAT

Values pertaining to status of UART Interrupt sources.

UART_INTID_TX_THRES_REACH

UART_INTID_RX_THRES_REACH

UART_INTID_RX_LINE_STAT_ERROR

UART_INTID_CHAR_TIMEOUT

UART_INTID_XOFF_SPEC_CHAR_DETECT

UART_INTID_MODEM_SIG_STATE_CHANGE

UART_INTR_PENDING

Values indicating the UART Interrupt pending status.

UART_N0_INTR_PENDING

Values related to enabling/disabling of Interrupts.

UART_INTR_CTS

Values for enabling/disabling the interrupts of UART.

UART_INTR_RTS

UART_INTR_XOFF

UART_INTR_SLEEPMODE

UART_INTR_MODEM_STAT

UART_INTR_LINE_STAT

UART_INTR_THR

UART_INTR_RHR_CTI

UART_INTR2_RX_EMPTY

UART_INTR2_TX_EMPTY

Values related to Line Status information.

UART_FIFO_PE_FE_BI_DETECTED

Values pertaining to UART Line Status information.

UART_BREAK_DETECTED_ERROR

UART_FRAMING_ERROR

UART_PARITY_ERROR

UART_OVERRUN_ERROR

Values related to Register Mode Configuration.

UART_REG_CONFIG_MODE_A

Values to be used while switching between register configuration modes.

UART_REG_CONFIG_MODE_B

UART_REG_OPERATIONAL_MODE

UART Configration Mode

This determines whether the driver configuration mode like Polled, Interrupt, Dma used for the transfer function

UART_CONFIG_MODE_POLLED

UART_CONFIG_MODE_INTERRUPT

UART_CONFIG_MODE_USER_INTR

UART_CONFIG_MODE_DMA

UART_DMA_MODE_PKTDMA

UART_DMA_MODE_BCDMA

Defines

UART_FIFO_SIZE

Uart FIFO Size.

UART_TRANSMITEMPTY_TRIALCOUNT

Timeout in ms used for TX FIFO empty at the time of delete. Three seconds is more than sufficient to transfer 64 bytes (FIFO size) at the lowest baud rate of 2400.

UART_ERROR_COUNT

Count Value to check error in the recieved byte

Typedefs

typedef void *UART_Handle

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

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.

Param handle:

UART_Handle

Param transaction*:

Pointer to a UART_Transaction

Functions

void UART_init(void)

This function initializes the UART module.

void UART_deinit(void)

This function de-initializes the UART module.

UART_Handle UART_open(uint32_t index, const UART_Params *prms)

This function opens a given UART peripheral.

See also

UART_init()

See also

UART_close()

See also

UART_Params_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

Pre:

UART controller has been initialized using UART_init()

Returns:

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

void UART_close(UART_Handle handle)

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

See also

UART_open()

Parameters:

handle – UART_Handle returned from UART_open()

Pre:

UART_open() has to be called first

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.

See also

UART_open

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

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.

See also

UART_open

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

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.

See also

UART_open

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

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.

See also

UART_open

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

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

void UART_flushTxFifo(UART_Handle handle)

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

See also

UART_open()

Parameters:

handle – UART_Handle returned from UART_open()

Pre:

UART_open() has to be called first

static inline void UART_Params_init(UART_Params *prms)

Function to initialize the UART_Params struct to its defaults.

Parameters:

prms – Pointer to UART_Params structure for initialization

static inline void UART_Transaction_init(UART_Transaction *trans)

Function to initialize the UART_Transaction struct to its defaults.

Parameters:

trans – Pointer to UART_Transaction structure for initialization

uint32_t UART_getBaseAddr(UART_Handle handle)

Function to get base address of UART instance of a particular handle.

See also

UART_open

Parameters:

handle – UART_Handle returned from UART_open()

int32_t UART_enableLoopbackMode(uint32_t baseAddr)

Function to enable loopback mode. This function is for internal use. Not recommended for customers to use.

See also

UART_open

Parameters:

baseAddr – Memory address of the UART instance being used.

Returns:

SystemP_SUCCESS on success, SystemP_FAILURE if baseAddr is 0

int32_t UART_disableLoopbackMode(uint32_t baseAddr)

Function to disable loopback mode. This function is for internal use. Not recommended for customers to use.

See also

UART_open

Parameters:

baseAddr – Memory address of the UART instance being used.

Returns:

SystemP_SUCCESS on success, SystemP_FAILURE if baseAddr is 0

static inline void UART_putChar(uint32_t baseAddr, uint8_t byteTx)

This API writes a byte to the Transmitter FIFO without checking for the emptiness of the Transmitter FIFO or the Transmitter Shift Register(TSR).

See also

UART_open

Note

Unlike the APIs UARTCharPut() or UARTCharPutNonBlocking(), this API does not check for the emptiness of the TX FIFO or TSR. This API is ideal for use in FIFO mode of operation where the 64-byte TX FIFO has to be written with successive bytes. If transmit interrupt is enabled, it provides a mechanism to control the writes to the TX FIFO.

Parameters:

• baseAddr – Memory address of the UART instance being used.

• byteTx – The byte to be transmitted by the UART.

static inline uint32_t UART_getChar(uint32_t baseAddr, uint8_t *pChar)

This API reads a byte from the Receiver Buffer Register (RBR). It checks once if any character is ready to be read.

See also

UART_open

Parameters:

• baseAddr – Memory address of the UART instance being used.

• pChar – Pointer to the byte variable which saves the byte read from RBR if there is any char ready to be read

Returns:

If the RX FIFO(or RHR) was found to have atleast one byte of data, then this API returns TRUE. Else it returns FALSE.

static inline void UART_intrEnable(uint32_t baseAddr, uint32_t intrFlag)

This API enables the specified interrupts in the UART mode of operation.

‘intrFlag’ can take one or a combination of the following macros:

• UART_INTR_CTS - to enable Clear-To-Send interrupt,

• UART_INTR_RTS - to enable Request-To-Send interrupt,

• UART_INTR_XOFF - to enable XOFF interrupt,

• UART_INTR_SLEEPMODE - to enable Sleep Mode,

• UART_INTR_MODEM_STAT - to enable Modem Status interrupt,

• UART_INTR_LINE_STAT - to enable Line Status interrupt,

• UART_INTR_THR - to enable Transmitter Holding Register Empty interrupt,

• UART_INTR_RHR_CTI - to enable Receiver Data available interrupt and Character timeout indication interrupt.

See also

UART_open

Note

This API modifies the contents of UART Interrupt Enable Register (IER). Modifying the bits IER[7:4] requires that EFR[4] be set. This API does the needful before it accesses IER. Moreover, this API should be called when UART is operating in UART 16x Mode, UART 13x Mode or UART 16x Auto-baud mode.

Parameters:

• baseAddr – Memory address of the UART instance being used.

• intrFlag – Bit mask value of the bits corresponding to Interrupt Enable Register(IER). This specifies the UART interrupts to be enabled.

static inline void UART_intrDisable(uint32_t baseAddr, uint32_t intrFlag)

This API disables the specified interrupts in the UART mode of operation.

‘intrFlag’ can take one or a combination of the following macros:

• UART_INTR_CTS - to disable Clear-To-Send interrupt,

• UART_INTR_RTS - to disable Request-To-Send interrupt,

• UART_INTR_XOFF - to disable XOFF interrupt,

• UART_INTR_SLEEPMODE - to disable Sleep Mode,

• UART_INTR_MODEM_STAT - to disable Modem Status interrupt,

• UART_INTR_LINE_STAT - to disable Line Status interrupt,

• UART_INTR_THR - to disable Transmitter Holding Register Empty interrupt,

• UART_INTR_RHR_CTI - to disable Receiver Data available interrupt and Character timeout indication interrupt.

See also

UART_open

Note

The note section of UART_intrEnable() also applies to this API.

Parameters:

• baseAddr – Memory address of the UART instance being used.

• intrFlag – Bit mask value of the bits corresponding to Interrupt Enable Register(IER). This specifies the UART interrupts to be disabled.

static inline void UART_intr2Enable(uint32_t baseAddr, uint32_t intrFlag)

This API enables the specified interrupts in the UART mode of operation for IER2.

‘intrFlag’ can take one or a combination of the following macros:

• UART_INTR2_RX_EMPTY - to enable receive FIFO empty interrupt

• UART_INTR2_TX_EMPTY - to enable TX FIFO empty interrupt

See also

UART_open

Note

This API modifies the contents of UART Interrupt Enable Register 2 (IER2).

Parameters:

• baseAddr – Memory address of the UART instance being used.

• intrFlag – Bit mask value of the bits corresponding to Interrupt Enable Register(IER2). This specifies the UART interrupts to be enabled.

static inline void UART_intr2Disable(uint32_t baseAddr, uint32_t intrFlag)

This API disables the specified interrupts in the UART mode of operation for IER2.

‘intrFlag’ can take one or a combination of the following macros:

• UART_INTR2_RX_EMPTY - to enable receive FIFO empty interrupt

• UART_INTR2_TX_EMPTY - to enable TX FIFO empty interrupt

See also

UART_open

Note

The note section of UART_intr2Enable() also applies to this API.

Parameters:

• baseAddr – Memory address of the UART instance being used.

• intrFlag – Bit mask value of the bits corresponding to Interrupt Enable Register(IER2). This specifies the UART interrupts to be disabled.

static inline uint32_t UART_getIntrIdentityStatus(uint32_t baseAddr)

This API determines the UART Interrupt Status.

See also

UART_open

Parameters:

baseAddr – Memory address of the UART instance being used.

Returns:

This returns one or a combination of the following macros:

• UART_INTID_MODEM_STAT - indicating the occurence of a Modem Status interrupt

• UART_INTID_TX_THRES_REACH - indicating that the TX FIFO Threshold number of bytes can be written to the TX FIFO.

• UART_INTID_RX_THRES_REACH - indicating that the RX FIFO has reached its programmed Trigger Level

• UART_INTID_RX_LINE_STAT_ERROR - indicating the occurence of a receiver Line Status error

• UART_INTID_CHAR_TIMEOUT - indicating the occurence of a Receiver Timeout

• UART_INTID_XOFF_SPEC_CHAR_DETECT - indicating the detection of XOFF or a Special character

• UART_INTID_MODEM_SIG_STATE_CHANGE - indicating that atleast one of the Modem signals among CTSn, RTSn and DSRn have changed states from active(low) to inactive(high)

static inline uint32_t UART_getIntr2Status(uint32_t baseAddr)

This API determines the UART Interrupt Status 2.

See also

UART_open

Parameters:

baseAddr – Memory address of the UART instance being used.

Returns:

This returns one or a combination of the following macros:

• UART_INTR2_RX_EMPTY - to enable receive FIFO empty interrupt

• UART_INTR2_TX_EMPTY - to enable TX FIFO empty interrupt

static inline uint32_t UART_checkCharsAvailInFifo(uint32_t baseAddr)

This API checks if the RX FIFO (or RHR in non-FIFO mode) has atleast one byte of data to be read.

See also

UART_open

Parameters:

baseAddr – Memory address of the UART instance being used.

Returns:

TRUE - if there is atleast one data byte present in the RX FIFO (or RHR in non-FIFO mode)

FALSE - if there are no data bytes present in the RX FIFO(or RHR in non-FIFO mode)

static inline uint32_t UART_readLineStatus(uint32_t baseAddr)

This API reads the line status register value.

See also

UART_open

Parameters:

baseAddr – Memory address of the UART instance being used.

Returns:

This returns the line status register value.

static inline uint8_t UART_getCharFifo(uint32_t baseAddr, uint8_t *readBuf)

This API reads the data present at the top of the RX FIFO, that is, the data in the Receive Holding Register(RHR). However before reading the data from RHR, it checks for RX error.

See also

UART_open

Parameters:

• baseAddr – Memory address of the UART instance being used.

• readBuf – Pointer to the byte buffer to be read from RHR register.

Returns:

The data read from the RHR.

Variables

UART_Config gUartConfig[]

Externally defined driver configuration array.

uint32_t gUartConfigNum

Externally defined driver configuration array size.

struct UART_Transaction

#include <uart.h>

Data structure used with UART_read() and UART_write()

Public Members

void *buf

[IN] void * to a buffer with data to be transferred . This parameter can’t be NULL

uint32_t count

[IN/OUT] Number of bytes for this transaction. This is input incase of read/write call and on API return this represents number of bytes actually read by the API

uint32_t timeout

Timeout for this transaction in units of system ticks

uint32_t status

[OUT] UART_TransferStatus code

void *args

[IN] Argument to be passed to the callback function

struct UART_Params

#include <uart.h>

UART Parameters.

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

If NULL is passed for the parameters, UART_open() uses default parameters.

See also

UART_Params_init()

Public Members

uint32_t baudRate

Baud rate for UART

uint32_t dataLength

Data length for UART. Refer UART_DataLength

uint32_t stopBits

Stop bits for UART. Refer UART_StopBits

uint32_t parityType

Parity bit type for UART. Refer UART_Parity

uint32_t readMode

Read blocking or Callback mode. Refer UART_TransferMode

uint32_t readReturnMode

Receive return mode Refer UART_ReadReturnMode

uint32_t writeMode

Write blocking or Callback mode. Refer UART_TransferMode

UART_CallbackFxn readCallbackFxn

Read callback function pointer

UART_CallbackFxn writeCallbackFxn

Write callback function pointer

uint32_t hwFlowControl

uint32_t hwFlowControlThr

< Enable HW Flow Control Hardware flow Control threshold, greater than or equal to the RX FIFO trigger level UART_RxTrigLvl

uint32_t transferMode

Transfer mode UART_ConfigMode

uint32_t dmaMode

Peripheral BCDMA/PKTDMA mode

uint32_t intrNum

Peripheral interrupt number

uint16_t eventId

interrupt event ID, not used for ARM cores

uint8_t intrPriority

Interrupt priority

uint32_t skipIntrReg

Skips Driver registering interrupt

int32_t uartDmaIndex

Index of DMA instance used by UART Driver. This index will be set by SysCfg according to the DMA driver chosen. The UART driver uses this index to do an UART_dmaOpen inside the UART_open if the DMA mode is enabled

uint32_t operMode

Refer UART_OperMode for valid values

uint32_t rxTrigLvl

Refer UART_RxTrigLvl for valid values

uint32_t txTrigLvl

Refer UART_TxTrigLvl for valid values

uint32_t rxEvtNum

DMA Event number used for UART Rx

uint32_t txEvtNum

DMA Event number used for UART Tx

struct UART_Attrs

#include <uart.h>

UART instance attributes - used during init time.

Public Members

uint32_t baseAddr

Peripheral base address

uint32_t inputClkFreq

Module input clock frequency

struct UART_Object

#include <uart.h>

UART driver object.

Public Members

UART_Handle handle

Instance handle to which this object belongs

UART_Params prms

Open parameter as provided by user

const void *writeBuf

Buffer data pointer

uint32_t writeCount

Number of Chars sent

uint32_t writeSizeRemaining

Chars remaining in buffer

void *readBuf

Buffer data pointer

uint32_t readCount

Number of Chars read

uint32_t readSizeRemaining

Chars remaining in buffer

uint32_t rxTimeoutCnt

Receive timeout error count

uint32_t readErrorCnt

Line status error count

UART_Transaction *readTrans

Pointer to the current read transaction

UART_Transaction *writeTrans

Pointer to the current write transaction

uint32_t isOpen

Flag to indicate whether the instance is opened already

void *lock

Instance lock - to protect across transfers

SemaphoreP_Object lockObj

Driver lock object

void *readTransferSem

Read Transfer Sync Sempahore - to sync between transfer completion ISR and task

SemaphoreP_Object readTransferSemObj

Read Transfer Sync Sempahore object

void *writeTransferSem

Write Transfer Sync Sempahore - to sync between transfer completion ISR and task

SemaphoreP_Object writeTransferSemObj

Write Transfer Sync Sempahore object

void *hwiHandle

Interrupt handle for master ISR

HwiP_Object hwiObj

Interrupt object

void *uartDmaHandle

Pointer to current transaction struct

struct UART_Config

#include <uart.h>

UART global configuration array.

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

Public Members

UART_Attrs *attrs

Pointer to driver specific attributes

UART_Object *object

Pointer to driver specific data object

uint32_t traceInstance

Mark the instance to be used for remote core trace or DM trace

UART DMA header file.

Typedefs

typedef void *UART_DmaHandle

Handle to the UART DMA Config Object returned by UART_dmaOpen.

typedef int32_t (*UART_dmaOpenFxn)(UART_Handle uartHandle, void *uartDmaArgs)

Driver implementation to open a specific DMA driver channel - UDMA, EDMA etc.

Typically this callback is hidden from the end application and is implemented when a new DMA driver needs to be supported.

Param uartHandle:

[in] UART Handle

Param uartDmaArgs:

[in] DMA specific arguments, obtained from the config

Return:

SystemP_SUCCESS on success, else failure

typedef int32_t (*UART_dmaTransferReadFxn)(UART_Object *obj, const UART_Attrs *attrs, UART_Transaction *transaction)

Driver implementation to do a DMA read using a specific DMA driver - UDMA, EDMA etc.

Typically this callback is hidden from the end application and is implemented when a new DMA driver needs to be supported.

Param obj:

[in] Pointer to UART object

Param attrs:

[in] Pointer to UART attributes.

Param transaction:

[in] Pointer to UART_Transaction. This parameter can’t be NULL

Return:

SystemP_SUCCESS on success, else failure

typedef int32_t (*UART_dmaTransferWriteFxn)(UART_Object *obj, const UART_Attrs *attrs, UART_Transaction *transaction)

Driver implementation to do a DMA write using a specific DMA driver - UDMA, EDMA etc.

Typically this callback is hidden from the end application and is implemented when a new DMA driver needs to be supported.

Param obj:

[in] Pointer to UART object.

Param attrs:

[in] Pointer to UART attributes.

Param transaction:

[in] Pointer to UART_Transaction. This parameter can’t be NULL

Return:

SystemP_SUCCESS on success, else failure

typedef int32_t (*UART_dmaCloseFxn)(UART_Handle handle)

Driver implementation to close a specific DMA driver channel - UDMA, EDMA etc.

Typically this callback is hidden from the end application and is implemented when a new DMA driver needs to be supported.

Param handle:

[in] UART handle returned from UART_open

Return:

SystemP_SUCCESS on success, else failure

typedef int32_t (*UART_dmaDisableChannelFxn)(UART_Handle handle, uint32_t isChannelTx)

Driver implementation to diisable a specific DMA driver channel - UDMA, EDMA etc.

Param handle:

[in] UART handle returned from UART_open

Param isChannelTx:

[in] Variable to indicate if it is TX/RX Channel

Return:

SystemP_SUCCESS on success, else failure

Functions

UART_DmaHandle UART_dmaOpen(UART_Handle uartHandle, int32_t index)

API to open an UART DMA channel.

This API will open a DMA Channel using the appropriate DMA driver callbacks and the registered via Sysconfig

Parameters:

• uartHandle – [in] UART Handle

• index – [in] Index of the DMA Config selected for this particular UART driver instance

Returns:

Handle to the UART DMA Config Object

int32_t UART_dmaClose(UART_Handle handle)

API to close an UART DMA channel.

Parameters:

handle – [in] UART handle returned from UART_open

Returns:

SystemP_SUCCESS on success, else failure

int32_t UART_dmaDisableChannel(UART_Handle handle, uint32_t isChannelTx)

API to disable an DMA channel.

Parameters:

• handle – [in] UART handle returned from UART_open

• isChannelTx – [in] Variable to indicate if it is TX/RX Channel

Returns:

SystemP_SUCCESS on success, else failure

int32_t UART_writeInterruptDma(UART_Object *obj, const UART_Attrs *attrs, UART_Transaction *transaction)

API to write data using an UART DMA channel.

Parameters:

• obj – [in] Pointer to UART object

• attrs – [in] Pointer to UART attributes

• transaction – [in] Pointer to UART_Transaction. This parameter can’t be NULL

Returns:

SystemP_SUCCESS on success, else failure

int32_t UART_readInterruptDma(UART_Object *obj, const UART_Attrs *attrs, UART_Transaction *transaction)

API to read data using an UART DMA channel.

Parameters:

• obj – [in] Pointer to UART object

• attrs – [in] Pointer to UART attributes

• transaction – [in] Pointer to UART_Transaction. This parameter can’t be NULL

Returns:

SystemP_SUCCESS on success, else failure

struct UART_DmaFxns

#include <uart_dma.h>

Driver implementation callbacks.

Public Members

UART_dmaOpenFxn dmaOpenFxn

UART_dmaTransferWriteFxn dmaTransferWriteFxn

UART_dmaTransferReadFxn dmaTransferReadFxn

UART_dmaCloseFxn dmaCloseFxn

UART_dmaDisableChannelFxn dmaDisableChannelFxn

struct UART_DmaConfig

#include <uart_dma.h>

UART DMA Configuration, these are filled by SysCfg based on the DMA driver that is selected.

Public Members

UART_DmaFxns *fxns

void *uartDmaArgs

Registered callbacks for a particular DMA driver. This will be set by Sysconfig depending on the DMA driver selected