Texas Instruments MSP432 Driver Library

What DriverLib is


The Texas Instruments MSP432 Driver Library (DriverLib) is a set of fully functional APIs used to configure, control, and manipulate the hardware peripherals of the MSP432 platform. In addition to being able to control the MSP432 peripherals, DriverLib also gives the user the ability to use common ARM peripherals such as the Interrupt (NVIC) and Memory Protection Unit (MPU) as well as MSP430 peripherals such as the eUSCI Serial peripherals and Watchdog Timer (WDT).

DriverLib for MSP432 Series has been tested and compiled under a variety of different toolchains. Subsequently, for each toolchain a specific debugger was used for testing validation. Below is a list that contains the supported toolchain and corresponding hardware debugger used.

Toolchain Debugger
Texas Instruments Code Composer Studio 7.3   XDS110 (LaunchPad)
IAR Embedded Workbench for ARM 8.11.2 Segger J-LINK
GNU C Compiler gcc-arm-none-eabi-6-2017-q1-update Segger J-LINK
Keil Embedded Development Tools for ARM 5.23  KEIL U-Link Pro

The DriverLib is meant to provide a "software" layer to the programmer in order to facilitate higher level of programming compared to direct register accesses. Nearly every aspect of a MSP432 device can be configured and driven using the DriverLib APIs. By using the high level software APIs provided by DriverLib, users can create powerful and intuitive code which is highly portable between not only devices within the MSP432 platform, but between different families in the MSP430/MSP432 platforms.

Writing code in DriverLib will make user code more legible and easier to share among a group. For example, examine the following pair of code snippets. Both sets of code set MCLK to be sourced from VLO with a divider of four:

Traditional Register Access

CSKEY = 0x695A;
CSCTL1 |= SELM_1 | DIVM_2;
CSKEY = 0;

DriverLib Equivalent

As can be seen, the DriverLib API is readable, sensible, and easy to program for the software engineer. Additionally, DriverLib APIs for other platforms such as MSP430 will use very similar (if not identical) APIs giving code written with DriverLib APIs a boost in portability.


What DriverLib is not


The Driver Library is not meant to provide a layer of intelligence on the level of a user application. It is meant to be an aid to the programmer to be part of the larger solution- not the solution itself.

Interrupt handlers are also not included with the DriverLib APIs. APIs to manage/enable/disable interrupts are included, however the actual authoring of the interrupt service routine is left up to the programmer. For reference, A typical interrupt handler that takes advantage of DriverLib APIs can be seen in the following code snippet:

void port6_isr(void)
{
if (status & GPIO_PIN7)
{
if (powerStates[curPowerState] == PCM_LPM3)
{
curPowerState = 0;
}
stateChange = true;
}
}

Cross Module Considerations


Each DriverLib module will, for the most part, only interact and configure the module that it is designed for. Any cross-module interaction is left up to the user. For example, when changing power modes to a low frequency mode with the PCM module, the user will have to ensure that the proper frequency requirements are configured with the CS module (low frequency requires that the system frequency be no greater that 128Khz).

Calling the following API alone while MCLK is greater that 128Khz will result in a system error:

This is because the DriverLib module will not account for the overall system frequency of the system. Instead, similar APIs to the following must be called in conjunction:

Cross-module considerations such as these must be taken when programming with DriverLib APIs as DriverLib was not designed to account for high level system requirements.


DriverLib in ROM


With all MSP432 devices, a copy of DriverLib is included within the device's ROM space. This allows programmers to take advantage of using high level APIs without having to worry about additional memory overhead of a flash library. In addition to a more optimized execution, the user can drastically cut down the memory footprint requirement of their application when using the software Driver Libraries available in ROM.

Accessing Driver Library APIs in ROM is as easy as including the rom.h header file, and then replacing normal API calls with a ROM_ prefix. For example, take the following API from the pcm.c module that changes the power state to PCM_AM_DCDC_VCORE1:

After including the rom.h file, all that would have to be done to switch to the ROM equivalent of the API would be add the ROM_ prefix to the API:

ROM_PCM_setPowerState(PCM_AM_DCDC_VCORE1);

While the majority of DriverLib APIs are available in ROM, due to architectural limitations some APIs are omitted from being included in ROM. In addition, if any bug fixes were added to the API after the device ROM was programmed, it is desirable to use the flash version of the API. An "intelligence" has been created to account for this problem. If the user includes the rom_map.h header file and uses the MAP_ prefix in front of the API, the header file will automatically use preprocessor macros to decide whether to use a ROM or flash version of the API.


MSP430 Legacy APIs


Since the MSP432 platform is built with many modules from Texas Instruments' MSP430 platform, many shared modules exist between MSP430 and MSP432. For this reason, a "compatibility" layer is provided to provide between the MSP430 Driver Library and the MSP430 Driver Library. The following modules are shared between MSP432 and MSP430:

To use these legacy APIs, no additional work is needed. All that is needed is to include the header file of the module you want to use and both the old and the new APIs will be available. For example, for WDT_A:

#include <wdt_a.h>

By including this header file, the user is granted access to all of the legacy DriverLib APIs from MSP430 Driver Library verbatim. For additional documentation on the MSP430 implementation of DriverLib, please refer to the MSP430Ware Website.

Many of the APIs were simplified and refactored for the MSP432 version of Driver Library. For example, to halt the watchdog module for a 5xx MSP430 device, the following API is used:

WDT_A_hold(WDT_A_BASE);
For MSP432 Driver Library, this same API has been simplified to the following API:

Note that while many Driver Library APIs are shared between MSP430 and MSP432, there are a few underlying differences between the two architectures. Interrupts, for example, are a bit difference on MSP432 compared to MSP430 due to integration with ARM's interrupt controller (the NVIC). While each module will still have individual status (IFG), enable/disable, and clear bits, interrupt service routines now have to be associated with the ARM NVIC before usage.


Quick Start


Getting started using DriverLib for MSP432 Series is very simple regardless of the chosen development environment.

An empty "skeleton" project is provided in the examples directory of the SDK release. This project includes links to the DriverLib library as well as everything that is needed for the programmer to immediately start writing a DriverLib application. A user can import this project in CCS using the TI Resource Explorer, or open the workspace with IAR Embedded Workbench for ARM or KEIL uVision 5. All of the include paths and compiler options are set up to allow the user to seamlessly start development on their MSP432 DriverLib application.

The GNU compiler tools for ARM are fully supported by the MSP432 Series DriverLib. While no IDE in specific is supported, Makefiles are provided for both the library and all of the code examples. Vector table definitions that are compatible with the GCC compiler are also provided for code examples in the startup_gcc.c file for each individual code example. For the GNU tools, separate header files are included in the inc directory of the root installation of DriverLib. These header files are the latest that are available at the time of DriverLib release, however newer header files may be downloaded as a part of the CCS installation.


Copyright 2018, Texas Instruments Incorporated