SimpleLink MCU SDK User's Guide

Table of Contents

Introduction to SimpleLink™ MCU SDK

The SimpleLink™ MCU Software Development Kits (SDK) contain software development tools that enable engineers to develop applications on a range of microcontroller families from Texas Instruments. The SDK is provided as separate installations optimized for each SimpleLink microcontroller family. These versions of the SDK share most components and are engineered to support the creation of portable applications. These powerful software toolkits provide a cohesive and consistent software experience by packaging essential software components and easy-to-use examples in one easy-to-use software package.

If you have not already installed the SDK and performed the initial setup steps, see the Quick Start Guide.

Documentation and Support

Links to documentation for the SDK and its components are provided in the Documentation Overview.

The SimpleLink Academy provides step-by-step workshops and video tutorials that introduce many of the components of the SimpleLink SDK.

This SDK is supported on the TI E2E™ Community.

SDK Components

The SDK components are used together to build applications. The SDK components relate to each other as shown in the following diagram.

Starting from the bottom of this architecture diagram, the components are as follows:

Directory Structure

The SDK is installed in /ti or c:\ti by default. This is also the installation location for any plug-ins that are installed alongside the SDK. This is the top-level directory structure of the SDK installation:

Since the same directory structure is used across the different SDKs in the TI SimpleLink family, it is possible to move application code between the different devices without making significant changes to the file structure or include paths.

The following figure shows a high-level view of the “source” directories that are common to all device types. The SDK provides additional features for specific device families.

The following figure similarly provides an overview of the “examples” directory contents that are common to all device types.

Tools and Utilities Not Included

The SDK does not contain an IDE or code generation tools such as a compiler and linker. You should have one of the supported code generation tool suites available. The supported suites are Code Composer Studio with TI’s Code Generation Tools, IAR Workbench with its compilers, and the GNU Compiler Collection (gcc).

The SDK does not install FreeRTOS. You can download the FreeRTOS source files via the FreeRTOS website. Refer to the SimpleLink Core SDK Release Notes for information about supported versions of FreeRTOS. The SDK does install the Driver Porting Layer (DPL) and POSIX abstractions to allow FreeRTOS to be used with the other SDK components.

The SDK does install XDCtools, which includes configuration tools for the TI-RTOS Kernel. The XDCtools component contains the underlying tools and modules used by TI-RTOS and its kernel. When you install the SDK, XDCtools is installed in a parallel directory at the same level as the SDK’s installation directory.

Some versions of the SDK also offer functionality-specific tools, such as the BTool for interfacing with the TI Bluetooth Low Energy (BLE) stack from a PC.



Understanding a SimpleLink MCU SDK Application

There are three different project layouts with the SimpleLink MCU SDK’s examples:

The SimpleLink MCU SDK provides an example called demos\portable that serves as an introduction to creating your own applications using the SDK. This example is comprised of an application project and a kernel project. The example uses the UART and I2C drivers and low-power states. It illustrates multi-tasking, I/O drivers, and low-power states. The code uses POSIX so that it is easy to run the example using either the TI-RTOS Kernel or the FreeRTOS kernel.

The application has the following functionality.

The “portable” example is located in the <SDK_INSTALL_DIR>\examples\syscfg_preview\rtos\<board>\demos\portable directory. It is available for all supported boards, RTOS kernels, toolchains, and IDEs.

Importing, Building, and Running the Example

Import the example as described in the Quick Start Guide. Separate instructions are provided there for the Code Composer Studio (CCS) IDE, IAR Embedded Workbench, makefiles using the GCC compiler, and other supported development environments. Follow the instructions in the “Execute your First Application” section of the Quick Start Guide for your development environment, but choose the “portable” example for your board, RTOS (TI-RTOS or FreeRTOS), and compiler.

Build the “portable” example as described in the same section of the Quick Start Guide.

A README.html file is included with the example files you imported. View this file and follow the instructions in the “Example Usage” section to run the example.

For boards other than CC32XX, you’ll need the Sensors BoosterPack Module, which contains a TMP116 temperature sensor.

For CC32XX boards using CCS, let the device “Free Run” instead of “Run.”

Understanding the Example

This section examines the “portable” example’s code to understand how it was created.

To see how the example supports multiple IDEs and RTOS kernels, it is best to look at the example files in the SDK installation. The process of importing an example removes files used to support other IDEs and RTOS kernels than the one you are using.

Go to your <SDK_INSTALL_DIR>\examples\syscfg_preview\rtos\<board>\demos\portable directory.

The example contains the following source files:

(The remaining files provide documentation for the example and a default Runtime Object View layout.)

The following sections examine these parts of the application in more detail. Open the code files as you read these sections to better understand how an application uses the SDK.

main_tirtos.c and main_freertos.c

The two versions of the main() function are mostly identical. Because POSIX Pthreads are used instead of direct calls to kernel APIs, only minor differences are needed to run the TI-RTOS Kernel or the FreeRTOS kernel.

Header Files

Both versions of the file #include the following files:

The FreeRTOS version of the file also includes FreeRTOS.h and task.h.

The TI-RTOS version of the file also includes ti/sysbios/BIOS.h, which in this case locates the file within <SDK_INSTALL_DIR>/kernel/tirtos/packages/ti/sysbios.

The main() Function

  1. The main() function begins by calling Board_initGeneral(), which the board.h file defines to point to a board-specific function in the board.c file.
  2. The function then sets various thread attributes in the attrs structure:
    • It calls pthread_attr_setdetachstate() with the PTHREAD_CREATE_DETACHED state to cause the threads created to be in the detached state, since the threads used by this application will never need to join with another thread.
    • It calls pthread_attr_setschedparam() to set the default scheduling priority for the threads to 1 (the minimum priority).
    • It calls pthread_attr_setstacksize() to set the size of the thread’s stack to the value defined for the THREADSTACKSIZE constant, which is defined as a size in bytes earlier in the same file.
  3. The main() function then calls pthread_create() twice.
    • The first time it creates a thread that will run the consoleThread() function. This thread runs at the default priority (1, which is the minimum). (See the console.c file for actions performed by this thread.)
    • The second time it creates a thread that will run the temperatureThread() function. This thread is set to a higher priority (2) than consoleThread. As a result, if both threads are ready to run, the temperatureThread runs first. The console thread runs when the temperature thread is blocked or waiting for data from the I2C transfer. (See the temperature.c file for actions performed by this thread.) For example:
    priParam.sched_priority = 2;
pthread_attr_setschedparam(&attrs, &priParam);

retc = pthread_create(&thread, &attrs, temperatureThread, NULL);
if (retc != 0) {
    /* pthread_create() failed */
    while (1);
}
    See the TI-POSIX User’s Guide for details about which POSIX APIs are supported by the SDK.
  4. The main() function then creates a mutex that will be used to protect the temperature variables from unsafe updates by the consoleThread() and temperatureThread().
  5. Next the main() function called GPIO_init() to initialize the GPIO driver. This initialization is performed in main() because both threads will use the GPIO driver.
  6. At this point, the two versions of the main() function diverge.
    • The TI-RTOS Kernel version simply calls BIOS_start() to start the scheduler. BIOS_start() does not return.
    • The FreeRTOS version calls vTaskStartScheduler() to start the FreeRTOS scheduler. vTaskStartScheduler() does not return.

Note: A “portableNative” variant of the “portable” example is provided for both TI-RTOS and FreeRTOS. These examples call the TI-RTOS Kernel or FreeRTOS APIs directly, instead of calling the POSIX APIs. Using the RTOS APIs directly saves both code and data memory. The only code differences for these native RTOS examples are located in the application source files: main_tirtos.c, main_freertos.c, console.c, and temperature.c.

For example, the TI-RTOS Kernel version of the portableNative example calls the Task_create() API instead of the pthread_create() API code shown in Step 3 as follows:

    Task_Params_init(&taskParams);
    taskParams.priority = 2;
    taskParams.stackSize = 768;

    temperatureTaskHandle = Task_create(temperatureThread, &taskParams, &eb);

See the TI-RTOS Kernel User’s Guide for more about the TI-RTOS Kernel APIs.

console.c

This file is identical for all boards, RTOS kernels, and development environments. Remember to see the README.html file for information about how to open a serial session to run the example’s console.

The consoleThread() function runs when the RTOS scheduler starts. First it performs some setup tasks. Later it drops into a while loop that runs until the application is halted.

Within the setup portion of the function, the consoleThread() function performs these actions:

  1. Enables the Power Manager for CC32XX boards, because power management is disabled by default on the CC32XX for easier debugging.
  2. Configures Board_GPIO_BUTTON1 to run the gpioButtonFxn() to wake the board in response to a button press.
  3. Calls the POSIX function sem_init() to initialize an unnamed semaphore. The button press posts the semaphore and the while loop later in the consoleThread() function waits on the semaphore.
  4. Initializes the parameters for the UART communication.

Within the while loop, the consoleThread() function performs these actions:

  1. If uartEnabled is false (which happens when the console is closed), waits on the semaphore until the button is pressed.
  2. Opens a UART for the console in blocking read and write mode by setting parameters and then calling UART_open().

  3. Runs the simpleConsole() function, which uses UART_write() and UART_read() to manage the console’s user interface, which accepts the following commands:

    Valid Commands
--------------
h: help
q: quit and shutdown UART
c: clear the screen
t: display current temperature
  4. If the “t” command is used, the values of both the temperatureC and temperatureF external variables provided by the temperatureThread are stored locally. A mutex is used to protect these operations. Without the mutex, the temperature thread, which has a higher priority, could interrupt the reading of the variables by the console thread. The result could be that the console thread printed a Celsius value that did not match the Fahrenheit value.
  5. The static itoa() function is used to convert the integer temperature values to strings, and UART_write() is used to output the values to the console.

  6. If the “q” command is used, the simpleConsole() function returns and the UART_close() is called. The Power Manager automatically goes to a lower-power state when the UART is closed. See the TI-RTOS Power Management User’s Guide for more about power states.

temperature.c

This file is identical for all boards, RTOS kernels, and development environments.

The temperatureThread() function runs when the RTOS scheduler starts. First it performs some setup tasks. Later it drops into a while loop that runs until the application is halted. The thread blocks on a semTimer semaphore at the end of the while loop. A timer running at one second posts the semTimer semaphore to unblock the task. A sleep() function could have been used, but a very small amount of drift would have occurred.

Within the setup portion of the function, the temperatureThread() function performs these actions:

  1. Initializes the I2C driver and opens the driver for use.
  2. Initializes the I2C_transaction structure that will be used in the I2C_transfer().
  3. Initializes the timer and semTimer semaphore.

Within the while loop, the temperatureThread() function performs these actions:

  1. If an I2C transfer succeeds, a mutex is locked to make the operations that follow thread safe.
  2. The temperature is extracted from the received data. (For CC32XX boards, the default is to read the temperature from the onboard TMP006 or TMP116 sensor. For all other boards, the example reads the temperature from the TMP116 sensor on the Sensors BoosterPack.)
  3. The temperature is scaled to be accurate in Celsius degrees and is also converted to Fahrenheit. Both values are stored for output.
  4. The mutex lock is released.
  5. If the temperature is higher than 30 C, an alert message is written using GPIO_write(). Otherwise, any previous alert message is cleared.
  6. The while loop blocks on the semTimer semaphore, which will be posted every second by the timer created by the thread. If the UART is closed, this provides enough time for the device to transition to a lower-power state under the control of the Power Manager.

Note: For details about achieving better power savings on the MSP432P4 by using the Watchdog timer, see the TI-RTOS MSP432 Timer wiki topic.

portable.syscfg

This file specifies how SysConfig should be used to set up board-specific items. For example, the GPIO section configures the GPIO input pins, output pins, and LEDs. It creates an array of callback functions for the input pins and sets them to NULL. For each driver, it declares a configuration structure and sets the defaults for the attribute fields in the structure.

When the example is built, this file will be used to generate Board.c and Board.h files, which configure the structures used by the TI Drivers. These structures are similar for most TI Drivers. For example, a configuration data structure called <Driver>_Config is defined. Each driver’s configuration includes a pointer to a function table, a pointer to an object, and a pointer to a set of hardware attribute settings. For more about the driver configuration structures, see the detailed reference information for the TI Driver APIs.

Note: Use of SysConfig is currently optional and requires additional installation steps. If you wish, you may continue to configure TI Drivers and device pins using the board files. Examples are provided for both methods of configuration.

Files for CCS, GCC, and IA

For each supported RTOS, the example contains files that are used to set up a project for the example when you import the example into a development environment. Projects for Code Composer Studio (CCS), IAR Embedded Workbench, and the GNU Compiler Collection (GCC) can be created.

Making Choices for Your Application

When using the SDK to create your own application, you should begin by making the following choices:

Choosing a Development Environment

Choose your preferred development environment. The SimpleLink MCU SDK supports all of the following development environments equally well:

The SDK examples can be imported into any of these environments as described in the Quick Start Guide.

Choosing an RTOS

You may use either the TI-RTOS Kernel or FreeRTOS with SDK applications that use the TI Drivers. Or, you can use the NoRTOS option, which allows you to use the TI Drivers without an underlying operating system (OS).

The TI-RTOS Kernel is a scalable real-time kernel. It is designed to be used by applications that require real-time scheduling and synchronization or real-time instrumentation. It provides preemptive multi-threading, hardware abstraction, real-time analysis, and configuration tools. The Kernel is designed to minimize memory and CPU requirements on the target. The TI-RTOS Kernel was previously called SYS/BIOS. It is described in the TI-RTOS Kernel User’s Guide. The Texas Instruments Wiki also links to training videos and more.

FreeRTOS is an open-source, real-time operating system kernel for embedded devices. It implements a minimalist set of functions, basic task handling and memory management. If you want to use the native FreeRTOS routines without the abstractions provided by the SDK, see the FreeRTOS website. Note: FreeRTOS is not supported for the CC13xx or CC26xx device families, since these devices use TI-RTOS in ROM.

NoRTOS enables the use of the TI Drivers without an underlying operating system (OS). Since there is no OS in this scenario, there can only be one main thread. Interrupts can preempt this main thread, but typical “multithreading” is not available.

Choosing Whether to Use POSIX

To enable re-use of code across the TI-RTOS and FreeRTOS kernels, the SDK provides a POSIX layer.

All of the kernel-based driver examples in the SDK are POSIX-based (except the portableNative examples). This allows the same code to be shared by the applications using the TI-RTOS and FreeRTOS kernels. If you want your applications to have this type of portability across kernels, we recommend that you use POSIX.

However, not all kernel features are available in the POSIX interface. If you need any OS-specific feature that is not available in the POSIX implementation, you can use a direct OS call during part of the application or the entire application.

See the TI-POSIX User’s Guide for details about which POSIX APIs are supported.

Choosing a Driver Access Method

You can choose a driver access method to fit the needs of that application. Factors that can be used to determine which method to use include:

You can use a combination of access methods. For example, you can use TI Drivers and Driverlib together. However, be aware that power management and resource allocation differ between access methods. For this reason, resource conflicts can arise. As long as you remain aware of the issues when using multiple access methods, it is possible to use the best features of each one.

TI Drivers

The TI Drivers provide an API interface that is compatible across the supported MCUs. Your applications can use this API with either the TI-RTOS or FreeRTOS kernel (or no RTOS).

In order to provide a cross-MCU compatible set of APIs, some device-specific features are not available in the TI Drivers. Instead, the focus is on ease of migration. The TI Drivers abstract the common features rather than providing feature-completeness.

Driverlib

Driverlib provides device-specific APIs that abstract register and peripheral details. The goal is to provide most (if not all) of the features of the device or peripheral at an abstracted API level. Since APIs and features are closely tied to the hardware, it may not be easy to migrate the application code from one MCU to another.

This API interface provides an abstracted way to configure hardware registers. This access method acts as a translation layer for setting/resetting a register bit or set of register bits.

Register Access

This access method configures hardware registers directly by setting/resetting specific bit combinations. This method provides 100% feature coverage with no abstraction at all.

When using this method, refer to the Device Family Technical Reference Manual and the Device Datasheet. Set and reset specific bits in the registers using the definitions in the device header files included with the SDK.


TI Drivers

The SDK includes drivers for a number of peripherals. These drivers are provided in the <SDK_INSTALL_DIR>/source/ti/drivers directory. The driver examples show how to use these drivers.

Some of the drivers are available only for certain target families. Some examples of drivers supported on several target families include GPIO, I2C, Power, SPI, UART, and Watchdog. There are many more. See the detailed reference information for the complete list of TI Drivers for your target family along with full information about the APIs and configuration structures.

Driver Framework

TI drivers have a common framework for configuration and a set of APIs that all drivers implement. Applications interface with a TI driver using a top-level driver interface. This interface is configured via a set of data structures that specify one or more specific lower-level driver implementations. TI Drivers can be configured manually or using the SysConfig tool.

TI drivers all implement the following APIs (with a few exceptions).

Drivers Porting Layer (DPL)

The Drivers Porting Layer allows the TI drivers to work with either the TI-RTOS or FreeRTOS kernel.

The TI Drivers use DPL APIs provided by the TI-RTOS and FreeRTOS Kernels for clock, interrupt, mutex, semaphore, and other services. However, the DPL abstracts the RTOS kernel functionality used by the drivers so that the application is not dependent on the TI-RTOS Kernel and can instead make use of the FreeRTOS kernel.

Board Files

Unless you are using SysConfig, TI Driver examples contain a board-specific C file (and its companion header file). The filenames are board.c and board.h, where board is the name of the board. All the TI Driver examples for a specific board use the same board files. These files are considered part of the example application, and you can modify them as needed.

The board files perform board-specific configuration of the drivers provided by the SDK. For example, they typically configure the GPIO ports and pins and configure use of the board LEDs.

SysConfig

The SysConfig tool makes it easy to configure components like TI Drivers and device-specific components (such as the networking stack, EasyLink, and WiFi). SysConfig is available if you are using CCS 8.2 and a SimpleLink MCU SDK v2.30 or later.

For this release, SysConfig is optional and is available as a preview. Future releases will expand the use of SysConfig. See the “System Configuration Basics” lab in SimpleLink Academy for installation steps that are currently required and step-by-step instructions for using SysConfig. (The SysConfig interface is still subject to change, so some of the images below may be out of date.)

You can choose to use SysConfig no matter what your choice is for the following:

SysConfig versions of the examples are provided in the examples/sysconfig_preview directory tree. These examples are basically the same as the examples in examples/rtos and examples/nortos, except they use SysConfig to generate configuration code instead of having the application provide it.

This section focuses on configuring TI Drivers, since all devices support TI Drivers using a common configuration framework. For TI Drivers, the SysConfig tool generates source files-–Board.c and Board.h-–to be compiled and linked with the application during builds. Additional components, such as networking stacks, may be configurable using SysConfig for certain targets, and will cause additional source files to be generated. See the device-specific documentation for information about any additional components that SysConfig can be used to configure.

SysConfig provides easy access to reference documentation for the drivers and other modules you can configure.

Besides the ease-of-use provided by SysConfig, the tool resolves conflicts on the fly. This ensures that you create a valid pin and TI Driver configuration. In addition, you can view diagrams of the pin configuration as you make changes.

SysConfig settings are stored in a file called <project>.syscfg. Its output files are stored in a syscfg folder within the build folder. For example, a “uartecho” application in CCS that uses TI-RTOS would contain the following files when built.

You open the <project>.syscfg file in SysConfig and modify it as needed. You can view the Board.c and Board.h file contents within SysConfig and see how configuration changes affect the generated code.

When you save the uartecho.syscfg file and build the project, the following actions occur:

  1. The Board.c and Board.h files are generated from the <project>.syscfg file.
  2. The Board.c and Board.h files are compiled to create a Board.obj file.
  3. The Board.obj file is linked with the rest of the libraries to create the application.

Note that the XGCONF tool is separately used to configure TI-RTOS Kernel modules. The TI-RTOS configuration is stored in a *.cfg file, which may be in a separate “kernel project” or in the same “application project” that contains the *.syscfg file. Likewise, the FreeRTOS configuration file (FreeRTOSConfig.h) is separately used to configure FreeRTOS.

If you are using the IAR toolchain, you can use SysConfig as a standalone desktop tool to generate the configuration files to be compiled and linked with your application.

Some users may choose to use SysConfig initially to generate the Board.c and Board.h files and then exclude the *.syscfg file from the build so that manual changes made to the Board.c and Board.h files are not overwritten. In this case, you should manually move the generated Board.c and Board.h files from the build folder to the folder that contains your application source files, so that the board files will not be deleted when a clean build is performed.

Debugging Output

The Display middle-ware driver is the recommended strategy for providing “printf” style debugging. It is RTOS independent. The Display module supports sending debug output by different methods (for example, UART, IDE Console, and LCD). Application writers can also provide their own custom Display implementation.

Many of the TI Driver examples use the Display module to send debugging information out a UART or LCD. The main API is the Display_printf() functions. This function is very similar to the standard printf() function. The configuration for the Display module is in the board.c file. For details about the Display module functionality, refer to the reference documentation .

The Runtime Object View (ROV) tool is available for examining the runtime state of TI-RTOS Kernel objects and various important statistics, such as stack usage and CPU load. The ROV tool can be run standalone or within CCS 7.1 or later. For details on using the ROV tool, see the “Runtime Object View (ROV)” wiki topic.

Note: The default printf() API is not recommended for use with SDK applications due to the impact on real-time performance and code footprint size.

Note: The System module in the TI-RTOS Kernel is available for applications that use the TI-RTOS native APIs (instead of the POSIX APIs). The System module functionality is unchanged from previous versions and will continue to be supported. The TI-RTOS “release” configuration uses SysCallback as the System support proxy to minimize footprint and performance impacts. The TI-RTOS “debug” configuration uses SysMin as the System support proxy, which slightly impacts footprint and performance but allows viewing of the System_printf debug output in the RTOS Object Viewer (ROV). Refer to the Configuration with TI-RTOS section for more details about the release and debug versions.



TI-RTOS Kernel

The SDK includes the TI-RTOS Kernel.

TI-RTOS provides a rich set of system-level embedded software, including multi-tasking, power management, device drivers, and instrumentation. TI-RTOS includes support for the TI-RTOS Kernel and FreeRTOS. Through the use of industry-standard POSIX pthread APIs, TI-RTOS enables other kernels (schedulers) to be integrated. TI-RTOS is delivered in the SDK in a consistent manner across the various SimpleLink SDKs.

The TI-RTOS Kernel is a scalable real-time kernel. The kernel is designed to be used by applications that require real-time scheduling and synchronization or real-time instrumentation. It provides preemptive multi-threading, hardware abstraction, real-time analysis, and configuration tools. The Kernel is designed to minimize memory and CPU requirements on the target. This kernel was previously called SYS/BIOS.

The TI-RTOS Kernel is described in the TI-RTOS Kernel User’s Guide. Additionally, detailed reference information is provided for all the TI-RTOS Kernel APIs. The Texas Instruments Wiki links to training videos and more for the TI-RTOS Kernel.

Organization of TI-RTOS Kernel Modules

The TI-RTOS Kernel and the XDCtools underlying tooling it uses are organized into sets of “packages,” each of which delivers a subset of the product’s functionality. The package names reflect the physical layout of the package within the SDK installation. For example, the ti.sysbios.knl package files can be found in the <SDK_INSTALL_DIR>/kernel/tirtos/packages/ti/sysbios/knl directory.

Each package provides one or more modules. Each module, in turn, provides APIs for working with that module. APIs have function names of the form Module_actionDescription(). For example, Task_setPri() sets the priority of a Task thread.

Using TI-RTOS Kernel Modules

In order to use a module, your application must include the standard TI-RTOS Kernel header files and the header file for that particular module. For example, include these header files to enable use of the Task module APIs:

#include <xdc/std.h> /* initializes XDCtools */
#include <ti/sysbios/BIOS.h> /* initializes TI-RTOS Kernel */
#include <ti/sysbios/knl/Task.h> /* initializes Task module */

Configuration with TI-RTOS

All TI-RTOS applications need a TI-RTOS configuration file (.cfg file). This file specifies how the kernel will be built. There are two methods for including the configuration in the application.

  1. Part of the same project: The .cfg file can be part of the application project. When the application is built, the .cfg file is also “built” and the generated files (source and linker file) are included in the application automatically. This method allows for fine tuning of the kernel for a specific application. Examples that use this method are in the examples\rtos\<board>\sysbios directory.
  2. Part of a separate shared project: The application can point to a “shared” configuration project. The SDK provides the following two configurations in the kernel\tirtos\builds\<board> directory:
    • release: A non-instrumented version of the TI-RTOS kernel. The main features are present in this version of the kernel–for example, Tasking, Mailboxes, Semaphores, and Clock. This version has a small footprint and better performance than the debug version. This version is not the absolute minimum footprint because your application may not use all the RTOS kernel features.
    • debug: An instrumented version of the kernel. This version enables asserts, logging, enhanced exception handling, and more. This version has the same RTOS feature set as the release version. This version is intended to be used during development. The separate configuration project method allows a configuration to be used by multiple applications. The build time for the application is faster, since it does not need to rebuild the kernel. The examples in the examples\rtos\<board> directory tree use this method.

Note: We recommend that you do not change the release.cfg and debug.cfg files. Instead refer to the following section if you want to create a new configuration.

For CCS users, when you import an example that uses Method 2, the separate configuration project specified by the example is also automatically imported.

Changing the TI-RTOS Configuration

The steps are different depending on whether the .cfg file is stored within your application project or in a separate project referenced by your application project.

Application Project Contains the .cfg File

You can simply edit the configuration file (via a text editor or the xGCONF tool in CCS). When the application is built, the kernel will be rebuilt also. This method applies for CCS, IAR and command line builds.

Application Project Does Not Contain the .cfg File

The steps are different depending on whether you are using CCS or IAR.

CCS Project

CCS projects can point to a separate configuration project in the Project Properties dialog in the Build->Dependencies tab.

Note: Don’t confuse the “RTOS configuration” with the “CCS Build Configuration”. The RTOS configuration does not need to correspond to the CCS Build Configuration (often also called Debug or Release).

By default, all TI driver examples use the “release” TI-RTOS configuration for both CCS Build Configurations.

To select a different configuration, import the desired configuration into CCS. To do this, follow these steps:

  1. Choose Project->Import CCS Project from the CCS menus.
  2. Next to Select search-directory, click Browse.
  3. Navigate to <SDK_INSTALL_DIR>\kernel\tirtos\builds\<board> directory and then either debug or release. Then click OK.

  4. Check the box for the development environment you will use to build your application (CCS or GCC), and click Finish.

  5. Choose Project->Properties and select the Build category and the Dependencies tab.
  6. Select the old RTOS configuration and click Remove.

  7. Click Add and select the project you imported. Then click OK.

When the application is rebuilt, the new kernel will be build and included.

IAR and Makefile

The IAR and command line example projects point to a specific shared configuration using a line similar to the following in the makefile:

KERNEL_BUILD :=  $(SIMPLELINK_CC32XX_SDK_INSTALL_DIR)/kernel/tirtos/builds/<board>/release

To use the debug version of the kernel, simply change “release” to “debug” and rebuild. If you created your own custom configuration (see below), adjust the path accordingly.

Creating Your Own TI-RTOS Configuration

Some users may want to create a custom TI-RTOS configuration. Common reasons for creating a custom configuration are to:

Once a new configuration is created and built, it can be used as described in the Changing TI-RTOS configuration section.

Creating a Custom TI-RTOS Configuration with CCS

A custom shared TI-RTOS configuration file can be created by following these steps:

  1. Import either a debug or release configuration file project into CCS (for example, <SDK_INSTALL_DIR>\kernel\tirtos\builds\<board>\debug\ccs). Pick the one (debug vs. release) that is closer to the custom configuration you want. You can simply do a text diff of the files to see the differences. Note: When importing the TI-RTOS configuration project, all files are copied into the project. Any changes you make have no impact on the project files stored as part of the SDK product.
  2. Rename the project to something meaningful for you (for example, tirtos_builds_CC3220S_LAUNCHXL_widget_ccs).
  3. We recommend that you also rename the .cfg file. This makes it easier to recognize when the file is open in the editor. (for example, widget.cfg)
  4. Edit the .cfg as desired:
    • For text editing, right-click on the .cfg file and choose Open With->XDCscript editor (or Text editor) or use your favorite text editor.
    • For graphical editing, right-click on the .cfg file and choose Open With->XGCONF. See Chapter 2 of the TI-RTOS Kernel User’s Guide for information about using the XGCONF editor.
  5. Rebuild the project using CCS.

Creating a Custom TI-RTOS Configuration with IAR and the Command Line

A custom shared TI-RTOS configuration file can be created by following these steps:

  1. Copy either the debug or release directory (whichever one is closer to the custom configuration you want) to a desired location. For example, copy <SDK_INSTALL_DIR>\kernel\tirtos\builds\<board>\debug to c:\widgetconfig. Do not use spaces in the destination path.
  2. We recommend that you also rename the .cfg file. This makes it easier to recognize when the file is open in the editor. (for example, widget.cfg)
  3. In the makefile of the desired toolchain (for example, c:\widgetconfig\ccs\makefile) make the following changes:
    • Define SIMPLELINK_<target>_SDK_INSTALL_DIR to point to your <SDK_INSTALL_DIR> location. For example: SIMPLELINK_MSP432P4_SDK_INSTALL_DIR ?= c:\ti\simplelink_msp432p4_sdk_2_30_00_76 (Your location will differ.)
    • Change the name of the configuration file. The file must end with .cfg and not contain spaces. For example in <SDK_INSTALL_DIR>\kernel\tirtos\builds\<board>\debug\ccs\makefile, change “debug.cfg” or “release.cfg” to “widget.cfg”.
    CFG_FILE   ?= ../widget.cfg
  4. Edit the .cfg as desired in your favorite text editor.
  5. Build the project using a command similar to the following:
C:\widgetconfig\ccs>c:\ti\xdctools_3_50_01_22_core\gmake



FreeRTOS Kernel

FreeRTOS is an open-source, real-time operating system kernel for embedded devices. It implements a minimalist set of functions, basic task handling and memory management.

The FreeRTOS kernel has the following characteristics:

The SDK provides support for FreeRTOS but does not install FreeRTOS. You can download the FreeRTOS source files via the FreeRTOS website. Refer to the SimpleLink Core SDK Release Notes for information about supported versions of FreeRTOS. The SDK does install the Driver Porting Layer (DPL) and POSIX abstractions to allow FreeRTOS to be used with the other SDK components.

FreeRTOS does not provide drivers for external hardware or access to a file system. In addition, the network communication stack provided by FreeRTOS is not used by the SimpleLink SDK. These capabilities are all managed by the TI Driver layer.

In the SDK, all FreeRTOS application routines are abstracted using the following:

You can find example FreeRTOS projects that use the SDK in the examples/rtos/ folder for all supported IDEs.

No native FreeRTOS examples are provided in this SDK. If you want to use the native FreeRTOS routines without the abstractions provided by the SDK, documentation is provided on the www.freertos.org website.

Note: FreeRTOS is supported only on certain device families. FreeRTOS is not supported on CC13xx or CC26xx devices, since they use TI-RTOS in ROM.

Using FreeRTOS with CCS

In order to use FreeRTOS within CCS, you must specify the location of the FreeRTOS installation. To do this, follow these steps:

  1. In CCS, choose Window->Preferences from the menus.
  2. Select the General->Workspace->Linked Resource category.
  3. Click New and add a link with the following settings:
    • Name: FREERTOS_INSTALL_DIR
    • Value: the location of you FreeRTOS installation

These steps only need to be performed once per CCS workspace that you use.

Configuration with FreeRTOS

The FreeRTOS configuration file (FreeRTOSConfig.h) is in the <SDK_INSTALL_DIR>\kernel\freertos\builds\<board>\release directory. The library can be built with the supported compiler tools.

Note: We recommend that you do not change the FreeRTOSConfig.h file. Instead refer to the below section on how to create a new configuration.

Creating a Custom FreeRTOS Configuration

For FreeRTOS, only a “release” RTOS configuration project is provided. Some users may want to create a custom FreeRTOS configuration. Common reasons for creating a custom configuration are to:

Once a new configuration is created and built, it can be used as described in the Changing FreeRTOS configuration section.

Creating a Custom FreeRTOS Configuration with CCS

A custom shared FreeRTOS configuration file can be created by following these steps:

  1. Import the release configuration file project into CCS (for example, <SDK_INSTALL_DIR>\kernel\freertos\builds\<board>\release\ccs). Note: When importing the FreeRTOS configuration project, all files are copied into the project. Any changes you make have no impact on the project files stored as part of the SDK product.
  2. Rename the project to something meaningful for you (for example, freertos_builds_CC3220S_LAUNCHXL_widget_ccs).
  3. Edit the FreeRTOSConfig.h file as desired.
  4. Rebuild the project using CCS.

Creating a Custom FreeRTOS Configuration with IAR and the Command Line

A custom shared FreeRTOS configuration file can be created by following these steps:

  1. Copy the release directory to a desired location. For example copy <SDK_INSTALL_DIR>\kernel\freertos\builds\<board>\release to c:\widgetconfig. Do not use spaces in the path.
  2. In the makefile of the desired toolchain (for example, c:\widgetconfig\ccs\makefile) change the definition of SIMPLELINK_<target>_SDK_INSTALL_DIR to point to your <SDK_INSTALL_DIR>. For example, SIMPLELINK_MSP432P4_SDK_INSTALL_DIR ?= c:\ti\ simplelink_msp432p4_sdk_2_30_00_76 (Your location will differ.)
  3. Edit the FreeRTOSConfig.h file as desired.
  4. Rebuild the project using a command similar to the following:
C:\widgetconfig\ccs>c:\ti\xdctools_3_50_01_22_core\gmake

Changing the FreeRTOS Configuration

After you create a custom configuration, you can cause your application to use that configuration. The steps are different depending on whether you are using CCS or IAR.

CCS Project

CCS projects can point to a separate configuration project in the Project Properties dialog in the Build->Dependencies tab.

Note: Don’t confuse the “RTOS configuration” with the “CCS Build Configuration”. The RTOS configuration does not need to correspond to the CCS Build Configuration (often called Debug or Release).

To select a different configuration, import the desired configuration into CCS. To do this, follow these steps:

  1. Choose Project->Import CCS Project from the CCS menus.
  2. Next to Select search-directory, click Browse.
  3. Navigate to the directory where you created your custom configuration. Then click OK.

  4. Check the box for the development environment you will use to build your application (CCS or GCC), and click Finish.

  5. Choose Project->Properties and select the Build category and the Dependencies tab.
  6. Select the old configuration and click Remove.

  7. Click Add and select the project you imported. Then click OK.

When the application is rebuilt, the new kernel will be build and included.

IAR and Makefile

The IAR and command line example projects point to a specific shared configuration using a line similar to the following in the makefile:

KERNEL_BUILD :=  $(SIMPLELINK_CC32XX_SDK_INSTALL_DIR)/kernel/freertos/builds/<board>/release

To use a different version of the kernel, simply change “release” to your custom configuration path and name. Then rebuild. 

NoRTOS

SimpleLink contains support for using the TI Drivers without an underlying operating system (OS). This support is called “nortos”. Examples are provided under the “nortos” subdirectory in the product tree.

Since there is no OS in this usage scenario, there can only be one main thread. As with most any system, interrupts will preempt this main thread, but typical “multithreading” is not available.

Throughout this chapter the term RTOS (Real Time Operating System) will be used to refer to either TI-RTOS, FreeRTOS, and counterintuitively, even “nortos”.

DPL

While SimpleLink applications use the TI Drivers, these drivers use a set of APIs that collectively are named DPL (Driver Porting Layer).

In addition to “nortos”, there are DPL implementations for the supported RTOSes of TI-RTOS and FreeRTOS (For those familiar with TI-RTOS, the TI-RTOS DPL implementation is a thin layer on top of TI-RTOS Kernel APIs).

Applications should not explicitly make use of DPL APIs, as they are intended to be used only by the TI drivers. The DPL APIs are available for TI Driver usage as a set of libraries that are shipped with the SimpleLink SDK product. The makefiles and IDE projects (CCS & IAR) for the RTOS model in use point to the necessary RTOS-specific DPL library.

NoRTOS Threading

The application will consist of just a main thread, which is instantiated by way of the standard C main() function. There is no capability for the main thread to create other threads, including Hwi-like & Swi-like threads, since DPL is not intended for application use, but the application can plug an ISR into the vector table. The TI Drivers will themselves create Hwi-like and Swi-like threads via the DPL APIs.

When the main thread calls into certain TI Driver APIs, some “blocking” will be achieved via the SemaphoreP_pend API in the DPL library. In the “nortos” environment, this “blocking” is implemented by way of a spin loop that can enter low-power modes available to the particular device. This spin loop is similar to an RTOS’s idle loop.

Interrupt handling

In cases where no suitable high-level driver is available in the tidrivers package, it is necessary to implement a custom solution based on the low-level device support APIs. This usually involves hardware interrupt handling and requires to use the low-level device APIs. An example for a custom interrupt handler on a CC1310 is shown in the following code snippet. Other SimpleLink MCUs provide similar APIs.

#include <ti/devices/cc13x0/driverlib/timer.h>

void mainThread()
{
    /* ... */

    /* Register a custom interrupt handler using the
     * low-level device APIs */
    IntRegister(INT_GPT0A, &timerInterruptHandler);

    /* ... */
}

void timerInterruptHandler()
{
    /* Handle the interrupt */
}

NoRTOS Power Management

Power management is handled by the platform-specific power driver in the tidrivers package. The power driver provides a function Power_idleFunc() which tells the MCU to enter the lowest possible power mode and to wait for an hardware interrupt event. The lowest possible power mode depends on the peripherals that are currently active and the MCU architecture. More information about the power driver can be found in the tidrivers API documentation.

Whenever a NoRTOS application performs a blocking call into a peripheral driver, Power_idleFunc() is executed which puts the application into a low-power mode until the desired interrupt event occurs. The following code snippet shows an example for a blocking call into the UART driver:

/* == Example for UART read in blocking mode == */

#include <ti/drivers/Power.h>
#include <ti/drivers/UART.h>

/* System is in RUNNING state */

/* Read 32 bytes from the UART in blocking mode.
 * The MCU will enter a low-power mode while waiting
 * for data. */
int rxBytes = UART_read(handle, rxBuf, 32);

/* System is back in RUNNING state */

When using the peripheral drivers in callback mode, no automatic blocking is performed. This is often desired when implementing an event-driven application. In that case, the application needs to block explicitly by calling Power_idleFunc(). The following code snippets shows an example:

/* == Example for UART read in callback mode == */

#include <ti/drivers/Power.h>
#include <ti/drivers/UART.h>

volatile bool dataReceived = false;

void mainThread()
{
    /* System is in RUNNING state */

    /* 
     * Read 32 bytes from the UART in callback mode.
     * The function returns immediately.
     */
    UART_read(handle, rxBuf, 32);

    /* 
     * In parallel to waiting for data, more work
     * can be done here...
     */

     /*
      * Go to sleep mode if necessary and wait until the
      * data transfer is finished. Accessing 'dataReceived'
      * and calling 'Power_idleFunc()' needs to be atomic.
      */
     enterCriticalSection();
     while (dataReceived == false)
     {
        Power_idleFunc();
        leaveCriticalSection();
        /* Let 'readCallback()' execute... */
        enterCriticalSection();
     }
     dataReceived = false;
     leaveCriticalSection();
}

void readCallback(UART_Handle handle, void *rxBuf, size_t size)
{
    /* Notify the main thread that data has been received */
    dataReceived = true;
}

void enterCriticalSection()
{
    /* Disable hardware interrupts. Platform-specific. */
}

void leaveCriticalSection()
{
    /* Re-enable hardware interrupts. Platform-specific. */
}

The function Power_idleFunc() returns whenever a hardware interrupt has occurred. Depending on the driver implementation, this might happen several times during the waiting period. Thus, a flag dataReceived signals the main thread, that the blocking condition is fulfilled and allows the program to resume.

If an application simply wants to wait for certain time, then it can use the functions sleep() and usleep() offered by the POSIX API:

#include <posix/unistd.h>

/* Block and enter a sleep mode for 47 seconds */
sleep(47);

/* Block and enter a sleep mode for 1701 microseconds */
usleep(1701);

Entering main()

Regardless of the underlying RTOS, main() needs to perform some initial setup and initialization for the application and drivers. In order to use a common initialization scheme for the TI Drivers, main() needs to be running in a similar model for all the RTOSes. TI-RTOS and FreeRTOS ensure that main() is entered with interrupts disabled, which is important for the subsequent Board_initGeneral() function to run properly. TI-RTOS applications must finish up main() by calling BIOS_start(), during which interrupts will be enabled. Similarly, FreeRTOS applications must call vTaskStartScheduler().

In the “nortos” model, the application would typically inherit a boot file from the compiler’s RTS library or the devices driverlib installation, and this boot file would eventually call main() with interrupts enabled. Since SimpleLink needs to do some initialization with interrupts disabled (that is by calling the function Board_initGeneral() as stated above), the “nortos” DPL library contains a set of functions that achieve this model when called from the appropriate places in main(). These functions are prefixed with the module name “NoRTOS”. One of these functions is the “nortos” counterpart to BIOS_start() and vTaskStartScheduler(), named NoRTOS_start(), and should be called after all application setup and initialization in main() but just prior to launching the main application functionality (but, unlike BIOS_start() and vTaskStartScheduler(), NoRTOS_start() does indeed return back to the caller).

The other functions in the NoRTOS module should be called as one of the first statements in main(), and before any call to Board_initGeneral(). See the example listing of main() later in this chapter for a suggested reference implementation for calling these NoRTOS module functions.

Software Interrupts (SwiP module)

Note: Not available for FreeRTOS-based TI Drivers.

A “Software Interrupt” (Swi) is a commonly-used paradigm that is available in many general OSes and RTOSes. It is a “threading level” that sits between HW interrupts and the main thread (or threads for multithread-capable OSes).

A HW ISR can post Swis and the Swi threads will run to completion only after all HW ISRs have been processed and before the program control returns to the main thread. A Swi runs with interrupts enabled, so they can be preempted by HW interrupts.

The DPL APIs contain a module that implements Software Interrupts (SwiP). Note that this SwiP module is not available for the FreeRTOS environment. Since the “nortos” model doesn’t have a HW interrupt dispatcher, a different mechanism must be used to service Swis. The SwiP module in DPL uses an interrupt that is configured at the lowest available priority to trigger the SwiP dispatcher. This interrupt is triggered by the SwiP module when the SwiP scheduler needs to run. Since the interrupt is configured at the lowest available priority, and since no other interrupt can share this priority in order to maintain the appropriate Hwi/Swi threading levels, the HwiP module will prevent any creation of another interrupt with the lowest available priority. As a result, the lowest available priority for use by TI Drivers when they create interrupts is one priority level higher than the lowest available priority in HW.

All supported devices contain an interrupt vector named PENDSV. The HwiP module contains a variable which is initialized to the PENDSV interrupt. This interrupt is not used by any HW so it is available for SW use. SwiP will use this interrupt when creating the HwiP instance to service its dispatcher. If your application needs to use the PENDSV interrupt for a different purpose, it can override the default setting by assigning a different value to NoRTOS_config.swiIntNum (see below). This should be done early in main(), before calling any TI Driver functionality (such as Board_initGeneral()).

DPL Configuration

Even though the DPL library is for use by TI Drivers and not by the application, there are some exposed elements of DPL in the “nortos” model that the application writer can modify. While these elements are assigned default values that should suffice for most all applications, there will be times when it’s easier to reconfigure these elements instead of accommodating their default values and changing the application to suit.

The NoRTOS module contains two functions to achieve the DPL configuration settings.

Between these calls, the application can set any of the NoRTOS_Config structure members to the value that it wants, and the NoRTOS_setConfig() call will configure DPL with these settings. The configuration elements of this structure are detailed here.

NoRTOS_Config.clockTickPeriod

The ClockP DPL module contains a global variable named ClockP_tickPeriod. It contains the “period” of the ClockP tick in microseconds. Its value is device-dependent. The NoRTOS_Config.clockTickPeriod element is used as a “proxy” for the ClockP_tickPeriod variable. The application can change this, but it should be changed before any calls to into the TI Drivers. (Doing this early in main() is recommended.)

NoRTOS_Config.swiIntNum

The HwiP module contains a variable for an interrupt that is used by the SwiP module that is initialized to the PENDSV interrupt value (as mentioned above). SwiP will post this interrupt when its dispatcher needs to run. The NoRTOS_Config.swiIntNum element can be set to a different value to change the HwiP variable. If so desired, the application should make this change before any calls into the TI Drivers. (Doing this early in main() is recommended.)

NoRTOS_Config.idleCallback

NULL by default, NoRTOS_Config.idleCallback is intended to be set by the application to enable low-power modes. If non-NULL, it is used as a function pointer that is called whenever a SemaphoreP_pend() is called for a semaphore that is not available (hence the system is “going idle”). It will be repeatedly called as long as the semaphore is not available and the timeout has not expired. The intended purpose is for the function Power_idleFunc() to be assigned so that the device can enter low-power mode while waiting for the semaphore to be posted.

The application should set this to Power_idleFunc() if low-power modes are desired, and should set it early in main() before any call into the TI Drivers.

Clocks

CC13XX/CC26XX

The ClockP module in the “nortos” DPL for CC13XX/CC26XX uses the RTC timer, which can remain active (running) during low-power modes. Similarly to the TI-RTOS Kernel Clock module on these devices, the ClockP module uses “dynamic tick” mode, which does not generate an interrupt for every Clock “tick” but instead dynamically reprograms the compare register of the timer to generate an interrupt for only the next scheduled ClockP tick event. Unlike TI-RTOS’s Clock module, a periodic mode is not available.

CC32XX

The ClockP module in the “nortos” DPL for CC32XX uses the SysTick timer. This CC32XX ClockP module supports “periodic tick” mode, where an interrupt occurs for every periodic tick regardless of any active ClockP object instance expiring during that tick.

The SysTick timer does not remain active (running) during low-power modes. In order to allow low-power modes while still maintaining a valid time base, the CC32XX ClockP module utilizes a “wakeup” timer that remains active while in the low-power mode, and is scheduled to wake up the device based on the next scheduled ClockP instance expiration time. Once woken up, the ClockP module updates its tick count with the number of “missed” ticks, and resumes operation of the SysTick timer.

MSP432P4

The ClockP module in the “nortos” DPL for MSP432P4 uses the Timer_A timer. This timer does not remain active during low-power modes.

As with the CC13XX/CC26XX ClockP, this timer is operated in “dynamic mode” to reduce the number of interrupts to the minimum amount needed to service the ClockP deadlines in active use.

MSP432E4

The ClockP module in the “nortos” DPL for MSP432E4 uses the SysTick timer. This MSP432E4 ClockP module supports “periodic tick” mode, where an interrupt occurs for every periodic tick regardless of any active ClockP object instance expiring during that tick.

Startup Files

A “nortos” application should use the startup files and linker command files that come packaged with the “nortos” TI Driver examples. These files have been tailored for the devices and OS in use. The startup files contain the initialized vector table, which can be modified to suit the application needs. There is a different startup file and linker command file for each supported compiler (CCS, GCC, IAR).

The SimpleLink examples come packaged with the necessary startup and linker command files from the particular driverlib that is contained in the SDK.

Shutdown

Since there is no RTOS involvement, the application can terminate using the usual “C” mechanisms - either calling exit() directly or returning from the main() function.

Example main() for NoRTOS

    /*
     *  ======== main_nortos.c ========
     */
    #include <stdint.h>
    
    #include <NoRTOS.h>
    #include <ti/drivers/Power.h>
    
    /* Example/Board Header files */
    #include "Board.h"
    
    extern void *mainThread(void *arg0);
    
    /*
     *  ======== main ========
     */
    int main(void)
    {
        NoRTOS_Config config;
    
        /* Set config parameters for NoRTOS */
        NoRTOS_getConfig(&config);
        config.idleCallback = Power_idleFunc;
        NoRTOS_setConfig(&config);
    
        /* Call driver init functions */
        Board_initGeneral();
    
        /* Start NoRTOS */
        NoRTOS_start();
    
        /* Call mainThread function */
        mainThread(NULL);
    
        while (1);
    }

Third-Party Components

The following third-party components can be used with the SDK.

CMSIS

The Cortex Microcontroller Software Interface Standard (CMSIS) is a common hardware abstraction layer for the Cortex-M processor series. It defines generic tool interfaces.

The CMSIS provides consistent device support and simple software interfaces to the processor and the peripherals. This simplifies software re-use, reducing the learning curve for microcontroller developers, and reducing the time to market for new devices. The CMSIS was created to enable software components from multiple middleware vendors to be combined.

There are several components in the CMSIS specifications, many of which are supported by the SDK and its tools infrastructure. Detailed information on these CMSIS components can be found at https://www.keil.com/pack/doc/CMSIS/General/html/index.html

The ARMCLANG and CMSIS-SVD components are not part of the SDK. They are shipped by Keil.

The benefits of the CMSIS-Core and CMSIS include:

CMSIS Header Files

The SDK includes specific releases of CMSIS core files that have been tested and validated with the components the SDK. The CMSIS files include the following:



FatFs

FatFs is an open-source FAT file system module intended for use in embedded systems. The API used by your applications is generic to all FatFs implementations, and is described and documented at http://elm-chan.org/fsw/ff/00index_e.html. Details about the FatFs API are not discussed here. Instead, this section gives a high-level explanation about how it is integrated with the TI Drivers.

In order to use FatFs in SDK applications, use the files in the <SDK Install>\source\third_party\fatfs directory.

The FatFs drivers provided by the SDK enable you to store data on removable storage media, such as Secure Digital (SD) cards. Such storage may be a convenient way to transfer data between embedded devices and conventional PC workstations.

FatFs and TI Drivers

The SDK provides a FatFs module and extends this module by supplying “FatFs” drivers that link into the FatFs implementation. The FatFs drivers are aware of the multi-threaded environment and protect themselves with OS primitives.

From the start of this data flow to the end, the components involved behave as follows:

Using FatFs

The subsections that follow show how to configure FatFs, how to prepare the FatFs drivers for use in your application, and how to open files. For details about performing other file-based actions once you have opened a file, see the FatFs APIs described on http://elm-chan.org/fsw/ff/00index_e.html in the “Application Interface” section or the standard C I/O functions.

The FatSD and FatSDraw examples use FatFs with the SDFatFS driver.

Defining Drive Numbers

Calls to the open() functions of individual FatFs drivers—for example, SDFatFS_open()—require a drive number argument. Calls to the C I/O fopen() function and the FatFs APIs also use the drive number in the string that specifies the file path. The following C code defines driver numbers to be used in such functions:

/* Drive number used for FatFs */
#define SD_DRIVE_NUM 0

Here are some statements from the FatSD example that use these drive number definitions. Note that STR(SD_DRIVE_NUM) uses a MACRO that expands SD_DRIVE_NUM to 0.

SDFatFS_Handle sdfatfsHandle;
FILE *src;
const char inputfile[] = "fat:"STR(SD_DRIVE_NUM)":input.txt";

/* Mount and register the SD Card */
sdfatfsHandle = SDFatFS_open(Board_SDFatFS0, SD_DRIVE_NUM);

/* Open the source file */
src = fopen(inputfile, "r");

Preparing FatFs Drivers

In order to use a FatFs driver in an application, you must do the following:

See the SDFatFS Driver for details about the FatFs driver APIs.

Opening Files Using FatFs APIs

Details on the FatFs APIs can be found at http://elm-chan.org/fsw/ff/00index_e.html in the “Application Interface” section.

The drive number needs to be included as a prefix in the filename string when you call f_open() to open a file. The drive number used in this string needs to match the drive number used to open the FatFs driver. For example:

res = f_open(&fsrc, “SD_DRIVE_NUM:source.dat”, FA_OPEN_EXISTING | FA_READ);

A number of other FatFs APIs require a path string that should include the drive number. For example, f_opendir(), f_mkdir(), f_unlink(), and f_chmod().

Although FatFs supports up to 10 (0-9) drive numbers, the diskIO function table supports only up to 4 (0-3) drives. You can modify this default by changing the definition of FF_VOLUMES in the ffconf.h file in the FatFs module. You will then need to rebuild the TI Drivers and FatFs modules.

It is important to use either the FatFs APIs or the C I/O APIs for file operations. Mixing the APIs in the same application can have unforeseen consequences.

Opening Files Using C I/O APIs

The C input/output runtime implementation for FatFs works similarly to the FatFs API. However, you must add the file name prefix configured for the FatFs module (“fat” by default) and the logical drive number as prefixes to the filename. The file name prefix is extracted from the filename before it gets passed to the FatFs API.

In this example, the default file name prefix is used and the drive number is 0:

fopen(“fat:0:input.txt”, "r");

It is important to use either the FatFs APIs or the C I/O APIs for file operations. Mixing the APIs in the same application can have unforeseen consequences.

Cautionary Notes

Number of Volumes Mounted: The FatFs implementation allows up to four unique volumes (or drives) to be registered and mounted.

FatFs actions and Low-priority Tasks: FatFs drivers perform data block transfers to and from physical media. Depending on the FatFs driver, writing to and reading from the disk could prevent lower-priority tasks from running during that time. If the FatFs driver blocks for the entire transfer time, only higher-priority TI-RTOS Kernel Tasks, Swis or Hwis can interrupt the Task making FatFs calls. In such cases, the application developer should consider how often and how much data needs to be read from or written to the media.

Buffering: RAM Usage vs. Disk Operations: By default the FatFs module keeps a complete sector buffered for each opened file. While this requires additional RAM, it helps mitigate frequent disk operations when operating on more than one file simultaneously.

Use of long file names or XFAT: The FatFs libraries are configured for use without Long File Name (VFAT) or XFAT support. If you chose to reconfigure and build FatFs to include these features, you may be required to license the appropriate patents from Microsoft. For more information, refer to: http://elm-chan.org/fsw/ff/en/appnote.html 

SPI Flash File System (SPIFFS)

SPIFFS is an open source file system authored by Peter Andersson for use on SPI NOR flash devices in embedded systems. It was designed for low RAM usage on embedded targets with little RAM (or possibly no heap).

SPIFFS provides a set of POSIX-like APIs, for which this SDK provides API reference documentation. Further details about the SPIFFS API, the design specification, and file system customization can be found in the open source github project.

This document provides a high-level explanation about how SPIFFS is integrated with TI Drivers, in particular the driver for non-volatile storage (NVS).

SPIFFS is provided as both source and pre-built libraries in <SDK_INSTALL_DIR>\source\third_party\spiffs.

SPIFFS and TI Drivers

The SDK features a SPIFFSNVS module (for certain targets), which provides the interface functions required by SPIFFS to read, write, and erase flash memory. These functions are implemented using the TI NVS driver. By leveraging the NVS driver, application code using SPIFFS is not tied to a physical memory type (like SPI flash). Instead the NVS driver abstracts the physical memory interface so SPIFFS application code can run on either SPI flash or on a device’s internal flash memory by changing the NVS driver instance used.

SPIFFS operates within the memory region that has been allocated for the NVS driver instance. The SPIFFSNVS module and NVS drivers are aware of the multi-threaded environment and protect themselves with OS primitives.

As shown in the figure above, the components involved in the data flow are as follows:

Using SPIFFS

The subsections that follow show how to add SPIFFS to your application and how to open files. For details about performing other file-based actions after you have opened a file, see the SPIFFS API documentation.

The spiffsinternal and spiffsexternal examples use SPIFFS on internal flash and external flash memory (respectively) via NVS drivers.

SPIFFS Runtime Configuration

To mount the file system, the following configuration parameters and RAM must be provided at runtime:

(All sizes are in bytes.)

Because NVS drivers serve as the interface to the physical memory, we can rely on them to provide the physical block size and the amount of memory allocated. These values are set in the driver configuration portion of the application board files.

The logical block size is customizable by the application. It must be an integer multiple of the physical block size as shown in the following equation:

logical_block_size = n * physical_block_size

The logical page size is also customizable by the application. The logical block size must also be an integer multiple of the logical page size:

logical_block_size = i * logical_page_size

We recommend that you set both the logical block size and the logical page size equal to the physical page size when you are starting development with SPIFFS. These multiples can be changed later to optimize the file system for your application.

A statically allocated RAM work buffer must be provided. This buffer must be 2 * logical_page_size in length.

A statically allocated RAM file descriptor cache must also be provided. Typically, file descriptors are 44 bytes in size. The cache must be large enough to store as many file descriptors as desired for the application. We suggest that you begin with enough space for 4 file descriptors and later optimize this value for your application.

Finally, SPIFFS needs a read/write cache. Start with a (2 * logical_page_size) cache; this can be increased or reduced later.

For example, suppose you are using SPIFFS with an NVS driver instance that has 128 KB of memory and the physical block size is 4096 bytes.

You could set the logical block size to 8192 bytes, which results in 16 logical blocks in memory. SPIFFS reserves 2 free logical blocks to use for compaction. So, in this case you would have only 14 logical blocks worth of space available for storage (16 KB would be kept unused).

The logical blocks are further divided into logical pages. For example, you could set the logical page size to 256 bytes, which would result in 32 logical pages per logical block.

Preparing for SPIFFS

In order to use SPIFFS in an application, follow these steps:

  1. Include the SPIFFS and SPIFFSNVS header files. For example:

    #include <third_party/spiffs/spiffs.h>
#include <third_party/spiffs/SPIFFSNVS.h>

  2. Define SPIFFS runtime parameters. The logical block size, logical page size, file descriptor size, file descriptor cache, and work buffer must be defined in the application. For example:

    /* SPIFFS configuration parameters */
#define SPIFFS_LOGICAL_BLOCK_SIZE    (8192)
#define SPIFFS_LOGICAL_PAGE_SIZE     (256)
#define SPIFFS_FILE_DESCRIPTOR_SIZE  (44)

static uint8_t spiffsWorkBuffer[SPIFFS_LOGICAL_PAGE_SIZE * 2];
static uint8_t spiffsFileDescriptorCache[SPIFFS_FILE_DESCRIPTOR_SIZE * 4];
static uint8_t spiffsReadWriteCache[SPIFFS_LOGICAL_PAGE_SIZE * 2];
  3. Create SPIFFS data objects. Three types of objects are required:
    • spiffs object. Holds the file system status during runtime.
    • spiffs_config object. The means to provide SPIFFS with the runtime parameters defined above.
    • SPIFFSNVS_Data object. Binds the file system to a particular NVS driver instance. For example:
    /* File system object */
spiffs fs;

/* SPIFFS runtime configuration object */
spiffs_config fsConfig;

/* Binding to NVS driver */
SPIFFSNVS_Data spiffsnvsData;

Initializing SPIFFS

Use SPIFFSNVS_config() to initialize the spiffs, spiffs_config, and SPIFFSNVS_Data objects. This API does the following:

The following C code shows how to use SPIFFSNVS_config() with the definitions and declarations above:

/* Initialize spiffs, spiffs_config & spiffsnvsdata structures */
status = SPIFFSNVS_config( &spiffsnvsData,
                           Board_NVSINTERNAL,
                           &fs,
                           &fsConfig,
                           SPIFFS_LOGICAL_BLOCK_SIZE,
                           SPIFFS_LOGICAL_PAGE_SIZE );

if (status != SPIFFSNVS_STATUS_SUCCESS) {
    Display_printf(displayHandle, 0, 0, Error with SPIFFS configuration.\n");

    while (1);
}

Mounting the File System

After the SPIFFS objects have been initialized, you can mount the file system.

The following C code mounts the file system. Notice that the “work” buffer and the file descriptor cache are specified when calling SPIFFS_mount().

status = SPIFFS_mount( &fs,
                       &fsConfig,
                       spiffsWorkBuffer,
                       spiffsFileDescriptorCache,
                       sizeof(spiffsFileDescriptorCache),
                       spiffsReadWriteCache,
                       sizeof(spiffsReadWriteCache),
                       NULL);

Opening a File in SPIFFS

After the file system has been successfully mounted, you can open a file in your file system as follows:

/* Open a file */
fd = SPIFFS_open( &fs,
                  "spiffsFile",
                  SPIFFS_RDWR,
                  0 );