Data Structures | Macros | Typedefs | Enumerations | Variables
UARTCC26XX.h File Reference

Detailed Description

UART driver implementation for a CC26XX UART controller.

============================================================================

Driver include

The UART header file should be included in an application as follows:

Refer to UART.h for a complete description of APIs.

Overview

The general UART API should used in application code, i.e. UART_open() is used instead of UARTCC26XX_open(). The board file will define the device specific config, and casting in the general API will ensure that the correct device specific functions are called. This is also reflected in the example code in Use Cases.

General Behavior

Before using the UART in CC26XX:

The following is true for receive operation:

The following apply for transmit operation:

If UART is no longer needed by application:

If the UART is configured in UART_MODE_CALLBACK mode:

Error handling

Read errors

If an error occurs during read operation:

Write errors

If a timeout occurs during a write, an UART_ERROR will be returned and the UART_Object.status will be set to UART_TIMED_OUT. All bytes that are not transmitted, will be flushed. If flow control is not enabled, the UARTCC26XX_Object.writeTimeout should be kept at default value, BIOS_WAIT_FOREVER. The write call will return after all bytes are transmitted. If flow control is enabled, the timeout should be set by the application in order to recover if the receiver gets stuck.

General timeout

A timeout value can only be specified for reads and writes in UART_MODE_BLOCKING. If a timeout occurs during a read when in UART_MODE_BLOCKING, the number of bytes received will be returned and the UART_Object.status will be set to UART_TIMED_OUT. After a read timeout, RX will remain on, but device is allowed to enter standby. For more details see Power Management chapter below.

In UART_MODE_CALLBACK there is no timeout and the application must call UART_readCancel() or UART_writeCancel() to abort the operation.

Note
A new read or write will reset the UART_Object.status to UART_OK. Caution must be taken when doing parallel reads and writes.

Closing driver during an ongoing read/write

It's safe to call UART_close() during an ongoing UART_read() and/or UART_write(), this will cancel the ongoing RX/TX immediately.

The RX callback is alwyas called when you call UART_close() if there's an ongoing read. Note that if UART_close() is called during an ongoing read, the size provided in the RX callback function is 0 if < 16 bytes were received before calling UART_close(). This is because 16 bytes is the RX watermark that triggers the ISR to copy bytes from the internal UART FIFO to the software RX buffer.

The TX callback is always called when you call UART_close() if there's an ongoing write. The driver does not wait until a byte is transmitted correctly, so if UART_close() is called in the middle of sending a byte, this byte will be corrupted.

Power Management

The TI-RTOS power management framework will try to put the device into the most power efficient mode whenever possible. Please see the technical reference manual for further details on each power mode.

The UARTCC26XX driver is setting a power constraint during operation to keep the device out of standby. When the operation has finished, the power constraint is released. The following statements are valid:

Flow Control

To enable Flow Control, the RTS and CTS pins must be assigned in the UARTCC26XX_HWAttrsV2:

const UARTCC26XX_HWAttrsV2 uartCC26xxHWAttrs[] = {
{
.baseAddr = UART0_BASE,
.powerMngrId = PERIPH_UART0,
.intNum = INT_UART0,
.intPriority = ~0,
.swiPriority = 0,
.txPin = Board_UART_TX,
.rxPin = Board_UART_RX,
.ctsPin = Board_UART_CTS,
.rtsPin = Board_UART_RTS
.ringBufPtr = uartCC26XXRingBuffer[0],
.ringBufSize = sizeof(uartCC26XXRingBuffer[0]),
}
};

If the RTS and CTS pins are set to PIN_UNASSIGNED, the flow control is disabled. An example is shown in the UARTCC26XX_HWAttrsV2 description.

Supported Functions

Generic API function API function Description
UART_init() UARTCC26XX_init() Initialize UART driver
UART_open() UARTCC26XX_open() Initialize UART HW and set system dependencies
UART_close() UARTCC26XX_close() Disable UART HW and release system dependencies
UART_control() UARTCC26XX_control() Configure an already opened UART handle
UART_read() UARTCC26XX_read() Start read from UART
UART_readCancel() UARTCC26XX_readCancel() Cancel ongoing read from UART
UART_write() UARTCC26XX_write() Start write to UART
UART_writeCancel() UARTCC26XX_writeCancel() Cancel ongoing write to UART
Note
All calls should go through the generic API

Not Supported Functionality

The CC26XX UART driver currently does not support:

Use Cases

Basic Receive

Receive 100 bytes over UART in UART_MODE_BLOCKING.

UART_Handle handle;
UART_Params params;
uint8_t rxBuf[100]; // Receive buffer
uint32_t timeoutUs = 5000; // 5ms timeout, default timeout is no timeout (BIOS_WAIT_FOREVER)
// Init UART and specify non-default parameters
params.baudRate = 9600;
params.readTimeout = timeoutUs / ClockP_tickPeriod; // Default tick period is 10us
// Open the UART and do the read
handle = UART_open(Board_UART, &params);
int rxBytes = UART_read(handle, rxBuf, 100);

Receive with Return Partial

This use case will read in UART_MODE_BLOCKING until the wanted amount of bytes is received or until a started reception is inactive for a 32-bit period. This UART_read() call can also be used when unknown amount of bytes shall be read. Note: The partial return is also possible in UART_MODE_CALLBACK mode.

UART_Handle handle;
UART_Params params;
uint8_t rxBuf[100]; // Receive buffer
// Init UART and specify non-default parameters
params.baudRate = 9600;
// Open the UART and initiate the partial read
handle = UART_open(Board_UART, &params);
// Enable RETURN_PARTIAL
// Begin read
int rxBytes = UART_read(handle, rxBuf, 100));

Basic Transmit

This case will configure the UART to send the data in txBuf in BLOCKING_MODE.

UART_Handle handle;
UART_Params params;
uint8_t txBuf[] = "Hello World"; // Transmit buffer
// Init UART and specify non-default parameters
params.baudRate = 9600;
// Open the UART and do the write
handle = UART_open(Board_UART, &params);
UART_write(handle, txBuf, sizeof(txBuf));

Receive Continously in UART_MODE_CALLBACK

This case will configure the UART to receive and transmit continously in UART_MODE_CALLBACK, 16 bytes at the time and transmit them back via UART TX. Note that UART_Params.readTimeout is not in use when using UART_MODE_CALLBACK mode.

#define MAX_NUM_RX_BYTES 1000 // Maximum RX bytes to receive in one go
#define MAX_NUM_TX_BYTES 1000 // Maximum TX bytes to send in one go
uint32_t wantedRxBytes; // Number of bytes received so far
uint8_t rxBuf[MAX_NUM_RX_BYTES]; // Receive buffer
uint8_t txBuf[MAX_NUM_TX_BYTES]; // Transmit buffer
// Read callback function
static void readCallback(UART_Handle handle, void *rxBuf, size_t size)
{
// Make sure we received all expected bytes
if (size == wantedRxBytes) {
// Copy bytes from RX buffer to TX buffer
for(size_t i = 0; i < size; i++)
txBuf[i] = ((uint8_t*)rxBuf)[i];
// Echo the bytes received back to transmitter
UART_write(handle, txBuf, size);
// Start another read, with size the same as it was during first call to
// UART_read()
UART_read(handle, rxBuf, wantedRxBytes);
}
else {
// Handle error or call to UART_readCancel()
}
}
// Write callback function
static void writeCallback(UART_Handle handle, void *rxBuf, size_t size)
{
// Do nothing
}
static void taskFxn(uintptr_t a0, uintptr_t a1)
{
UART_Handle handle;
UART_Params params;
// Init UART
// Specify non-default parameters
UART_Params_init(&params);
params.baudRate = 9600;
params.writeCallback = writeCallback;
params.readCallback = readCallback;
// Open the UART and initiate the first read
handle = UART_open(Board_UART, &params);
wantedRxBytes = 16;
int rxBytes = UART_read(handle, rxBuf, wantedRxBytes);
while(true); // Wait forever
}

Baud Rate

The CC26xx driver supports baud rates up to 3Mbaud. However, when receiving more than 32 bytes back-to-back the baud rate is limited to approximately 2Mbaud. The throughput is also dependent on the user application.

Stack requirements

There are no additional stack requirements for calling UART_read() within its own callback.

Instrumentation

The UART driver interface produces log statements if instrumentation is enabled.

Diagnostics Mask Log details
Diags_USER1 basic UART operations performed
Diags_USER2 detailed UART operations performed

#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/UART.h>
#include <ti/drivers/pin/PINCC26XX.h>
#include <ti/drivers/Power.h>
#include <ti/drivers/utils/RingBuf.h>
#include <ti/devices/DeviceFamily.h>
#include <DeviceFamily_constructPath(driverlib/uart.h)>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SwiP.h>
#include <ti/drivers/dpl/ClockP.h>
#include <ti/drivers/dpl/SemaphoreP.h>
Include dependency graph for UARTCC26XX.h:

Go to the source code of this file.

Data Structures

struct  UARTCC26XX_HWAttrsV2
 UARTCC26XX Hardware attributes. More...
 
struct  UARTCC26XX_Object
 UARTCC26XX Object. More...
 

Macros

#define UARTCC26XX_CMD_RETURN_PARTIAL_ENABLE   (UART_CMD_RESERVED + 0)
 Command used by UART_control to enable partial return. More...
 
#define UARTCC26XX_CMD_RETURN_PARTIAL_DISABLE   (UART_CMD_RESERVED + 1)
 Command used by UART_control to disable partial return. More...
 
#define UARTCC26XX_CMD_RX_FIFO_FLUSH   (UART_CMD_RESERVED + 2)
 Command used by UART_control to flush the RX FIFO. More...
 
#define UARTCC26XX_FIFO_SIZE   32
 
#define UARTCC26XX_RETURN_PARTIAL_ENABLE   UARTCC26XX_CMD_RETURN_PARTIAL_ENABLE
 
#define UARTCC26XX_RETURN_PARTIAL_DISABLE   UARTCC26XX_CMD_RETURN_PARTIAL_DISABLE
 

Typedefs

typedef enum UARTCC26XX_FifoThreshold UARTCC26XX_FifoThreshold
 UART TX/RX interrupt FIFO threshold select. More...
 
typedef void(* UARTCC26XX_ErrorCallback) (UART_Handle handle, uint32_t error)
 The definition of an optional callback function used by the UART driver to notify the application when a receive error (FIFO overrun, parity error, etc) occurs. More...
 
typedef struct UARTCC26XX_HWAttrsV2 UARTCC26XX_HWAttrsV2
 UARTCC26XX Hardware attributes. More...
 
typedef enum UART_Status UART_Status
 UART status. More...
 
typedef struct UARTCC26XX_Object UARTCC26XX_Object
 UARTCC26XX Object. More...
 
typedef struct UARTCC26XX_ObjectUARTCC26XX_Handle
 

Enumerations

enum  UARTCC26XX_FifoThreshold {
  UARTCC26XX_FIFO_THRESHOLD_DEFAULT = 0, UARTCC26XX_FIFO_THRESHOLD_1_8, UARTCC26XX_FIFO_THRESHOLD_2_8, UARTCC26XX_FIFO_THRESHOLD_4_8,
  UARTCC26XX_FIFO_THRESHOLD_6_8, UARTCC26XX_FIFO_THRESHOLD_7_8
}
 UART TX/RX interrupt FIFO threshold select. More...
 
enum  UART_Status {
  UART_TIMED_OUT = 0x10, UART_PARITY_ERROR = UART_RXERROR_PARITY, UART_BRAKE_ERROR = UART_RXERROR_BREAK, UART_OVERRUN_ERROR = UART_RXERROR_OVERRUN,
  UART_FRAMING_ERROR = UART_RXERROR_FRAMING, UART_OK = 0x0
}
 UART status. More...
 

Variables

const UART_FxnTable UARTCC26XX_fxnTable
 

Macro Definition Documentation

§ UARTCC26XX_FIFO_SIZE

#define UARTCC26XX_FIFO_SIZE   32

Size of the TX and RX FIFOs is 32 items

§ UARTCC26XX_RETURN_PARTIAL_ENABLE

#define UARTCC26XX_RETURN_PARTIAL_ENABLE   UARTCC26XX_CMD_RETURN_PARTIAL_ENABLE

§ UARTCC26XX_RETURN_PARTIAL_DISABLE

#define UARTCC26XX_RETURN_PARTIAL_DISABLE   UARTCC26XX_CMD_RETURN_PARTIAL_DISABLE

Typedef Documentation

§ UARTCC26XX_FifoThreshold

UART TX/RX interrupt FIFO threshold select.

Defined FIFO thresholds for generation of both TX interrupt and RX interrupt. The default value (UARTCC26XX_FIFO_THRESHOLD_DEFAULT) is defined for backward compatibility handling.

§ UARTCC26XX_ErrorCallback

typedef void(* UARTCC26XX_ErrorCallback) (UART_Handle handle, uint32_t error)

The definition of an optional callback function used by the UART driver to notify the application when a receive error (FIFO overrun, parity error, etc) occurs.

Parameters
UART_HandleUART_Handle
errorThe current value of the receive status register.

§ UARTCC26XX_HWAttrsV2

UARTCC26XX Hardware attributes.

These fields, with the exception of intPriority, txIntFifoThr and rxIntFifoThr, are used by driverlib APIs and therefore must be populated by driverlib macro definitions. For CC26xxWare these definitions are found in:

  • inc/hw_memmap.h
  • inc/hw_ints.h

intPriority is the UART peripheral's interrupt priority, as defined by the underlying OS. It is passed unmodified to the underlying OS's interrupt handler creation code, so you need to refer to the OS documentation for usage. For example, for SYS/BIOS applications, refer to the ti.sysbios.family.arm.m3.Hwi documentation for SYS/BIOS usage of interrupt priorities. If the driver uses the ti.dpl interface instead of making OS calls directly, then the HwiP port handles the interrupt priority in an OS specific way. In the case of the SYS/BIOS port, intPriority is passed unmodified to Hwi_create().

A sample structure is shown below:

const UARTCC26XX_HWAttrsV2 uartCC26xxHWAttrs[] = {
{
.baseAddr = UART0_BASE,
.powerMngrId = PERIPH_UART0,
.intNum = INT_UART0,
.intPriority = ~0,
.swiPriority = 0,
.txPin = Board_UART_TX,
.rxPin = Board_UART_RX,
.ctsPin = PIN_UNASSIGNED,
.rtsPin = PIN_UNASSIGNED,
.ringBufPtr = uartCC26XXRingBuffer[0],
.ringBufSize = sizeof(uartCC26XXRingBuffer[0]),
}
};

The .ctsPin and .rtsPin must be assigned to enable flow control.

§ UART_Status

typedef enum UART_Status UART_Status

UART status.

The UART Status is used to flag the different Receive Errors.

§ UARTCC26XX_Object

UARTCC26XX Object.

The application must not access any member variables of this structure!

§ UARTCC26XX_Handle

Enumeration Type Documentation

§ UARTCC26XX_FifoThreshold

UART TX/RX interrupt FIFO threshold select.

Defined FIFO thresholds for generation of both TX interrupt and RX interrupt. The default value (UARTCC26XX_FIFO_THRESHOLD_DEFAULT) is defined for backward compatibility handling.

Enumerator
UARTCC26XX_FIFO_THRESHOLD_DEFAULT 

Default value forces FIFO threshold of 1/8 for TX interrupt and 4/8 for RX interrupt

UARTCC26XX_FIFO_THRESHOLD_1_8 

FIFO threshold of 1/8 full

UARTCC26XX_FIFO_THRESHOLD_2_8 

FIFO threshold of 2/8 full

UARTCC26XX_FIFO_THRESHOLD_4_8 

FIFO threshold of 4/8 full

UARTCC26XX_FIFO_THRESHOLD_6_8 

FIFO threshold of 6/8 full

UARTCC26XX_FIFO_THRESHOLD_7_8 

FIFO threshold of 7/8 full

§ UART_Status

UART status.

The UART Status is used to flag the different Receive Errors.

Enumerator
UART_TIMED_OUT 

UART timed out

UART_PARITY_ERROR 

UART Parity error

UART_BRAKE_ERROR 

UART Break error

UART_OVERRUN_ERROR 

UART overrun error

UART_FRAMING_ERROR 

UART Framing error

UART_OK 

UART OK

Variable Documentation

§ UARTCC26XX_fxnTable

const UART_FxnTable UARTCC26XX_fxnTable
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale