UART

Table of Contents

• Features Supported
• SysConfig Features
• Features NOT Supported
• Usage Overview
  • API Sequence
  • Initializing the UART Driver
  • Opening the UART Driver
  • UART Write Mode
  • UART Read Mode
• Important Usage Guidelines
• Example Usage
• API

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
• 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);
    }
}

API

APIs for UART