The SimpleLink™ MCU Software Development Kit (SDK) is a set of software development tools that enables engineers to develop applications on a range of micro-controller families from Texas Instruments. This powerful software toolkit provides 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 Quickstart Guide.
Links to documentation for the SDK and its components are provided in the Documentation Overview.
This SDK is supported on the TI E2E Community.
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:
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 the contents of the "source" directory. Notice the key in the lower-left, which shows the colors used to indicate target-specific packages within the SDK.
The following figure similarly shows more detail about the contents of the "examples" directory using the same color code.
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. 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.
The SimpleLink MCU SDK provides an example called demos\portable
that serves as an introduction to creating your own applications using the SDK. 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.
consoleThread
thread provides a simple console. When the UART is closed, the device can go into a lower-power state.temperatureThread
thread reads the temperature from a peripheral device via the I2C driver.The "portable" example is located in the <SDK_INSTALL_DIR>\examples\rtos\<board>\demos\portable
directory. It is available for all supported boards, RTOS kernels, toolchains, and IDEs.
Import the example as described in the Quickstart 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 Quickstart 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 Quickstart 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 CC3220, you'll need the Sensors BoosterPack, which contains a TMP007 temperature sensor.
For CC3220 boards using CCS, let the device “Free Run” instead of "Run."
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\rtos\<board>\demos\portable
directory.
The example contains the following source files:
consoleThread
and the temperatureThread
threads.consoleThread
thread along with the callback function for the GPIO interrupt run when the board BUTTON1 is pressed.temperatureThread
thread.<board>.c
and <board>.h
(where <board>
is the name of your board): These file set up board-specific items, such as attribute structures for the various TI Drivers. For example, for the UART driver, properties such as the clock source and pins used are configured.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.
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:
stdint.h
pthread.h
ti/drivers/GPIO.h
(this is a TI-RTOS package path, which locates the file within <SDK_INSTALL_DIR>/source
)Board.h
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
<board>.c
file. priParam.sched_priority = 2;
pthread_attr_setschedparam(&pAttrs, &priParam);
retc = pthread_create(&thread, &pAttrs, temperatureThread, NULL);
if (retc != 0) {
/* pthread_create() failed */
while (1);
}
See the "SYS/BIOS POSIX Thread (pthread) Support" wiki topic for details about which POSIX APIs are supported by the SDK.
If you chose to have your application use the TI-RTOS Kernel directly instead of using POSIX, it would call the Task_create() API instead of the pthread_create() API 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.
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:
Within the while loop, the consoleThread() function performs these actions:
Valid Commands
--------------
h: help
q: quit and shutdown UART
c: clear the screen
t: display current temperature
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.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.
Within the setup portion of the function, the temperatureThread() function performs these actions:
Within the while loop, the temperatureThread() function performs these actions:
Note: For details about achieving better power savings on the MSP432 by using the Watchdog timer, see the TI-RTOS MSP432 Timer wiki topic.
(Where <board>
is the name of your board.) These files are responsible for setting up the board specific items for the board. 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.
The <board>.c file also configures 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 in <board>.c. 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.
This file maps board-specific constants and functions to board-independent constants and functions. The board-independent names should be used by the application so that the application code is portable.
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.
When using the SDK to create your own application, you should begin by making the following choices:
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 Quickstart Guide.
You may use either the TI-RTOS Kernel or FreeRTOS with SDK applications that use the TI Drivers.
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.
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. 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 "SYS/BIOS POSIX Thread (pthread) Support" wiki topic for details about which POSIX APIs are supported.
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.
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.
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 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.
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.
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.
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 all implement the following APIs (with a few exceptions).
Void Driver_init(Void)
— Initializes the driver. This function must be called only once and before any calls to the other driver APIs. Generally, this is done before the TI-RTOS Kernel is started.Void Driver_Params_init(Driver_Params *params)
— Initializes the driver’s parameter structure to default values. All drivers, with the exception of GPIO, implement the Params structure. The Params structure is empty for some drivers.Driver_Handle Driver_open(UInt index, Driver_Params *params)
— Opens the driver instance specified by the index with the params provided. If the params field is NULL, the driver uses default values. This function returns a handle that will be used by other driver APIs and should be saved. If there is an error opening the driver or the driver has already been opened, Driver_open() returns NULL.Void Driver_close(Driver_Handle handle)
— Closes the driver instance that was opened, specified by the driver handle returned during open. This function closes the driver immediately, without checking to see if the driver is currently in use. It is up to the application to determine when to call Driver_close() and to ensure it doesn’t disrupt on-going driver activity.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.
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.
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 .
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.
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.
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.
In order to use a module, your application must include the standard SYS/BIOS 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 SYS/BIOS */
#include <ti/sysbios/knl/Task.h> /* initializes Task module */
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.
examples\rtos\<board>\sysbios
directory.kernel\tirtos\builds\<board>
directory:
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.
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.
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.
The steps are different depending on whether you are using CCS or IAR.
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:
<SDK_INSTALL_DIR>\kernel\tirtos\builds\<board>
directory and then either debug
or release
. Then click OK.When the application is rebuilt, the new kernel will be build and included.
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.
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.
A custom shared TI-RTOS configuration file can be created by following these steps:
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.A custom shared TI-RTOS configuration file can be created by following these steps:
<SDK_INSTALL_DIR>\kernel\tirtos\builds\<board>\debug
to c:\widgetconfig
. Do not use spaces in the destination path.c:\widgetconfig\ccs\makefile
) make the following changes:
SIMPLELINK_<target>_SDK_INSTALL_DIR
to point to your <SDK_INSTALL_DIR>
location. For example: SIMPLELINK_MSP432_SDK_INSTALL_DIR ?= c:\ti\simplelink_msp432_sdk_1_10_00_76
(Your location will differ.)<SDK_INSTALL_DIR>\kernel\tirtos\builds\<board>\debug\ccs\makefile
, change “debug.cfg” or “release.cfg” to "widget.cfg".CFG_FILE ?= ../widget.cfg
C:\widgetconfig\ccs>c:\ti\xdctools_3_32_01_22_core\gmake
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. 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 a network communication stack, drivers for external hardware, or access to a file system. Those capabilities are covered by the TI Driver layer.
In the SDK, all FreeRTOS application routines are abstracted using the following:
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.
You can find example projects in the examples/rtos/
folder for all supported IDEs. No native FreeRTOS examples are provided in this SDK.
In order to use FreeRTOS within CCS, you must specify the location of the FreeRTOS installation. To do this, follow these steps:
These steps only need to be performed once per CCS workspace that you use.
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.
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.
A custom shared FreeRTOS configuration file can be created by following these steps:
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.A custom shared FreeRTOS configuration file can be created by following these steps:
<SDK_INSTALL_DIR>\kernel\freertos\builds\<board>\release
to c:\widgetconfig
. Do not use spaces in the path.c:\widgetconfig\ccs\makefile
) change the definition of SIMPLELINK_<target>_SDK_INSTALL_DIR
to point to your <SDK_INSTALL_DIR>
. For example, SIMPLELINK_MSP432_SDK_INSTALL_DIR ?= c:\ti\ simplelink_msp432_sdk_1_10_00_76
(Your location will differ.)C:\widgetconfig\ccs>c:\ti\xdctools_3_32_01_22_core\gmake
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 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:
When the application is rebuilt, the new kernel will be build and included.
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.
The following third-party components can be used with the SDK.
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 http://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:
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 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.
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:
Application. The top application layer calls the basic open, close, read, and write functions. Users who are familiar with FatFs can easily use the FatFs API, which is documented at the module’s download site. Alternatively, the application can also connect the C input/output (C I/O) runtime support library in TI’s Code Generation Tools to FatFs. You can call familiar functions such as fopen(), fclose(), fread(), and fwrite(). Functionally, the C I/O interface and the FatFs APIs perform the same operations (with a few exceptions described in the following section).
FatFS module. The next layer, the source/third_party/FatFS
module, is provided as part of the SDK. This module handles the details needed to manage and use the FAT file system, including the media’s boot sector, FAT tables, root directories, and data regions. It also protects its functions in a multi-threaded environment. Internally, the FatFS module makes low-level data transfer requests to the Disk IO functions described on the FatFs product web page. Implementations of this set of functions are called "FatFs drivers" in this document.
diskIO Function table. To allow products to provide multiple FatFs drivers, the FatFS module contains a simple driver table. You can use this to register multiple FatFs drivers at runtime. Based on the drive number passed by FatFs, the driver table routes FatFs calls to a particular FatFs driver.
FatFs drivers. The last layer in the figure above is the FatFs drivers. The SDK comes with pre-built FatFs drivers that plug into the FatFS module. A FatFs driver has no knowledge of the internal workings of FatFs. Its only task is to perform disk-specific operations such as initialization, reading, and writing. The FatFs driver performs read and write operations in data block units called sectors (commonly 512 bytes). Details about writing data to the device are left to the particular FatFs driver, which typically accesses a peripheral’s hardware registers or uses a driver library.
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 SDSPI driver.
Calls to the open() functions of individual FatFs drivers—for example, SDSPI_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
#define USB_DRIVE_NUM 1
Here are some statements from the FatSD USB Copy example that use these drive number definitions. Note that STR(SD_DRIVE_NUM) uses a MACRO that expands SD_DRIVE_NUM to 0.
SDSPI_Handle sdspiHandle;
SDSPI_Params sdspiParams;
FILE *src;
const Char inputfilesd[] = "fat:"STR(SD_DRIVE_NUM)":input.txt";
/* Mount and register the SD Card */
SDSPI_Params_init(&sdspiParams);
sdspiHandle = SDSPI_open(Board_SDSPI0, SD_DRIVE_NUM, &sdspiParams);
/* Open the source file */
src = fopen(inputfilesd, "r");
In order to use a FatFs driver in an application, you must do the following:
#include <ti/drivers/SDSPI.h>
SDSPI_init();
sdspiHandle = SDSPI_open(Board_SDSPI0, SD_DRIVE_NUM, NULL);
See the SDSPI Driver for details about the FatFs driver 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);
res = f_open(&fdst, “USB_DRIVE_NUM:destination.dat”, FA_CREATE_ALWAYS | FA_WRITE);
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 _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.
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.
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 SYS/BIOS 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