Processor SDK RTOS UART

From Texas Instruments Wiki
Jump to: navigation, search


RTOS Software Developer Guide UART



Overview

User Interface

Application

Debug


Introduction

Driver enables UART's available on SOC for reading and writing to any peripherals on board. Additionally it supports simple APIs for Console/STDIO operations.

Modes of Operation

Following modes of operations are supported

UART_MODE_BLOCKING: In this mode, read and write APIs, blocks on semaphore until required operation is complete. By default, UART driver operates in blocking mode. In this mode, code execution of a task blocks until UART transaction is complete. While transaction is in progress additional tasks pending requests will remain in blocked state waiting for semaphore.

UART_MODE_CALLBACK: In this mode, read and write operation returns immediately. On trigger of hardware Interrupt (hwi) callback function gets triggered.

Driver Configuration

Board Specific Configuration

All board specific configurations eg:enabling clock and pin-mux for UART pins are required before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs. In addition it initializes UART instance for Console/STDIO.Refer Processor SDK RTOS Board Support for additional details.Once board specific configuration is complete  UART_init() API can be called to initialize driver.

UART Configuration Structure

The UART_soc.c file binds driver with hardware attributes on the board through UART_config structure. This structure must be provided to UART driver. It must be initialized before the UART_init() function is called and cannot be changed afterwards. For details about individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\uart\docs\doxygen\html\index.html.

APIs

API reference for application:

#include <ti/drv/uart/UART.h>

STDIO API reference for application:

#include <ti/drv/uart/UART_stdio.h>
Open UART

There are three ways to open a UART instance:

1. UART_open()

...
Board_init(boardCfg);
...
UART_socGetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_socSetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_Params_init(&params);
...
handle = UART_open(UART_INSTANCE, &params);

At this point UART driver is ready for data transfer on specific instance identified by handle. Application can call UART_read/write API for read/write operation

2. UART_stdioInit() using the default UART parameters

...
Board_init(boardCfg);
...
UART_socGetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_socSetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_stdioInit(UART_INSTANCE);

At this point UART driver is ready for data transfer on specific instance. Application can call UART_printf/scanFmt API for read/write operation

3. UART_stdioInit2() using Application specified UART parameters

...
Board_init(boardCfg);
...
UART_socGetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_socSetInitCfg(UART_INSTANCE, &uart_cfg);
...
UART_Params_init(&params);
...
UART_stdioInit2(UART_INSTANCE, &params);

At this point UART driver is ready for data transfer on specific instance. Application can call UART_printf/scanFmt API for read/write operation

Read/Write APIs

Interrupt:

UART_read(handle,scanPrompt, sizeof(scanPrompt));/* Read API */ 
... 
UART_write(handle, bufferPrompt, sizeof(bufferPrompt));/* Write API */ 

Or

UART_transactionInit(&transaction);
transaction.buf = (void *)scanPrompt;
transaction.count = sizeof(scanPrompt);
UART_read2(uart, &transaction);
...
UART_transactionInit(&transaction);
transaction.buf = (void *)bufferPrompt;
transaction.count = sizeof(bufferPrompt);
UART_write2(uart, &transaction);

Polling:

UART_readPolling(handle,scanPrompt, sizeof(scanPrompt));/* Read Polling mode API */
... 
UART_writePolling(handle, bufferPrompt, sizeof(bufferPrompt));/* Write Polling API */ 
EDMA Usage :

UART driver supports EDMA operations to transfer data between

  • Memory and RX FIFO for read transfer
  • Memory and TX FIFO for write transfer.

Driver uses separate source files for these operations.Refer source UART_soc_dma.c for DMA UART SOC configuration. Application need to create EDMA handle and update the configuration before UART_init() API.

uartInitCfg[UART_INSTANCE].edmaHandle = UartApp_edmaInit();/* Refer Example/Test */
UART_init();

Refer “UART_BasicExample_[SOC]_[cpu]DMATestproject” for additional reference. Refer SDK Release Note for supported EVMs.

Example

Name
Description
Expected Results
UART_Example application

Example demonstrating simple UART use case. Reference example for developers

Application prompts user to enter input data in console.

User can enter up to 16 characters or terminate with enter key.Application echoes back characters.

UART_TestApplication

Unit Test application to test all APIs

User can enter up to 16 characters using serial console.Application echoes back

UART_DMATestApplication

Unit Test application with DMA mode.

User can enter up to 16 characters using serial console.Application echoes back

Additional References

Document Location
API Reference Manual $(TI_PDK_INSTALL_DIR)\packages\ti\drv\uart\docs\doxygen\html\index.html
Release Notes $(TI_PDK_INSTALL_DIR)\packages\ti\drv\uart\docs\ReleaseNotes_UART_LLD.pdf