SimpleLink MCU SDK Driver API Reference

Table of Contents


TI-Drivers Overview

TI-Drivers is a collective of peripheral drivers for TI's SimpleLink portfolio. The drivers are centered around a portable application programming interface (API) which enables seamless migration across the SimpleLink SDK portfolio. Unless specifically stated otherwise, TI-Drivers are designed to be thread safe and work seamlessly inside of a real time operating system (RTOS) application. All TI-Driver implementations utilize the Power driver APIs to ensure low power consumption at all times. The drivers support TI-RTOS (SYS/BIOS) and NoRTOS with examples provided for each variant. Lastly, the drivers are supported by SysConfig to enable easy re-configuration of the drivers.

Features:
  • Portable APIs
  • Native support for TI-RTOS and NoRTOS usage
  • Thread safe APIs
  • SysConfig support
  • Example usage
  • Power driver support
Driver Initialization

TI-Driver APIs follow a common initialization model. This model typically consists of:

  1. Init
  2. Open
  3. Use
  4. Close

Each driver documents how to initialize, open, use, and close the driver. Unless otherwise stated, the initialization function, Driver_init, may be called multiple times by the application. It is only required that the initialization is done once. For drivers which have an open function, Driver_open, it must be called per instance of the driver to be used. Each instance of the driver corresponds to a unique index in the Driver Configuration, Driver_config. Multiple software entities may use the same driver concurrently. For example, a Bluetooth or WiFi stack may utilize a driver instance. The application may concurrently use the same driver assuming it has opened a unique instance of the driver. Let's examine the ADC driver for example.

#include <ti/drivers/ADC.h>
// Define name for ADC index
// This is an index into the ADC_config[] array
#define ADC_INSTANCE 0
// One-time init of ADC driver
// Initialize optional ADC parameters
ADC_Params_init(&params);
// Open ADC instance for usage
// Sample the analog pin
ADC_convert(adcHandle, &result);
// Convert the sample to microvolts
resultUv = ADC_convertToMicroVolts(adcHandle, result);
ADC_close(adcHandle);

A couple observations from this code example:

  1. We need to include the ADC driver header file.
  2. We define a name for our ADC instance. This definition typically comes from ti_drivers_config.h (previously Board.h) and corresponds to an index in the ADC_config array. Our definition corresponds to the zero index of this array. (See: Driver Configuration)
  3. We have to call the initialization function, ADC_init().
  4. We have to create a handle for our ADC driver instance. This is done by calling ADC_open() with our desired config index. Once a handle has been created the driver instance is ready for use. Each index can only be opened once!
  1. In this simple example, we use the ADC_convert() API.
  2. A driver instance can be closed and re-open.

For our simple example, that's all we need. However, for full details on the ADC--and other drivers, reference the Drivers and Documentation section below.


Drivers and Documentation

Shown below is a matrix of available drivers and documentation.

Note
Please view the Device Specific driver implementations as they may contain or exclude certain features that are defined in the top level interfaces.
TI-Drivers Implementations
Driver Interfaces CC32XX
Implementations
Module
Interfaces
Supported Device
Wildcards
ADC.h ADCCC32XX.h ADC CC32*
Capture.h CaptureCC32XX.h General-Purpose Timers CC32*
Crypto CryptoCC32XX.h N/A CC32*
DMA.h UDMACC32XX.h DMA CC32*
GPIO.h GPIOCC32XX.h GPIO CC32*
I2C.h I2CCC32XX.h I2C CC32*
I2S.h I2SCC32XX.h I2S CC32*
ITM.h Not Applicable Instrumentation Trace Macrocell CC32*
NVS.h NVSRAM.h N/A CC32*
NVSSPI25X.h SPI.h
Power.h PowerCC32XX.h Power, Reset, and Clock Management CC32*
PWM.h PWMTimerCC32XX.h General-Purpose Timers CC32*
SD.h SPI.h SDSPI.h CC32*
SDHostCC32XX.h SD Host Controller Interface
SPI.h SPICC32XXDMA.h SPI CC32*
Timer.h TimerCC32XX.h General-Purpose Timers CC32*
UART.h UARTCC32XX.h UART CC32*
UARTCC32XXDMA.h
UART2.h UART2CC32XX.h UART CC32*
Watchdog.h WatchdogCC32XX.h Watchdog Timer CC32*

Display Driver

The Display driver is designed to abstract operations & considerations specific to a given output method.

Display Driver Interface Implementations
Display.h DisplayHost.h
DisplayUart.h


Driver Apps

These helper apps utilize TI drivers and are available to user applications.

Modules Interfaces Descriptions
Button.h GPIO.h Provides an API for button-like hardware attached to device pins.
LED.h GPIO.h Provides an API for LEDs attached to device pins.
PWM.h


Driver Utilities

These utilities are helper modules available to drivers.

Module Description
List.h Double linked list
Random.h Fast and light-weight pseudo random number generator
RingBuf.h Array-based ring buffer for bytes
SDFatFS.h Wrapper to enable the use of file systems for the SD driver.
SPIFFSNVS.h Enables NVS as the physical layer to read/write memory for the SPIFFS file system


Driver Configuration

The generic driver interface defines a configuration structure using the typedef keyword. The name of this declared type follows the naming pattern <driver>_Config. A driver is configured by declaring an array of this configuration data structure. Each config array index contains pointers to other data objects necessary for the driver to function at runtime. These data objects may include a hardware attributes, a function table, and object memory. Multiple indexes of the config array should not share these data objects--with the exception of the function table. Each index of the config array supports an independent instance of the driver.

Warning
The declared array, <driver>_Config, must have a specific C identifier. This identifies follows the case-sensitive pattern <driver>_config.
The configuration must also contain a count of indexes in the <driver>_config. This must also have a specific C identifier following the case-sensitive pattern <driver>_count. The data type must be a uint_least8_t.

The driver interface is joined together during the link process at build time. The <driver>_config and <driver>_count symbols are resolved.


Driver Configuration Files

The driver configuration files contain all driver configurations needed by TI-Drivers at runtime. The SysConfig tool is used to automatically generate the TI-Driver's configuration files. Two files are presently generated for TI-Drivers:


Driver Objects

The driver objects are device specific structures that hold data for an instance of a driver. The driver objects are used exclusively by the driver and should never be accessed by the application. Device specific drivers define an object structure as a new type using the typedef keyword. Each index in a driver's configuration will contain a pointer to a driver object.


Driver Hardware Attributes

The hardware attributes, also commonly referred to as HWAttrs, are device specific settings that typically do not change during runtime operation of a driver. The hardware attributes also aid in abstracting the generic driver interface from the device specific hardware. Device specific drivers define a hardware attribute structure as a new type using the typedef keyword. Each index in a driver's configuration will contain a pointer to a hardware attribute structure.


Driver Function Table

The function pointer table is a structure simply containing pointers to functions. Each index in a driver's configuration will contain a pointer to a function pointer table. The TI-Driver's interface uses function pointers to abstract a generic driver from a device specific driver. Each device specific driver declares a default function pointer table which may be referenced by default in the driver's configuration.


NoRTOS Framework Module

The NoRTOS framework module is provided to enable use of drivers without an underlying operating system. The module provides interfaces used by drivers to perform delays, block execution, register interrupts and more.

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