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 6.0   XDS100v3
IAR Embedded Workbench for ARM 7.20 Segger J-LINK
GNU C Compiler 4.8 (gcc) Segger J-LINK
Keil Embedded Development Tools for ARM 5.11  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 MSP432 platform.

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

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 also, 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 power run mode with the pcm.c module, the user will have to ensure that the proper frequency requirements are configured with the cs.c module (low power run 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 means that programmers can take advantage of using high level APIs without having to worry about additional 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 the 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 MSP432L Driver Library, this same API has been simplified to the following API:

Note that while many Driver Library APIs are shared between MSP430 and MSP432L, 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.


Future Devices with Multiple Instances


For MSP432 there exist many modules which currently only have one instance of the device on the chip, but theoretically could have multiple instances on future devices. For example, the current MSP432 product portfolio does not have any device that has multiple ADC14 modules, however it is theoretically possible for a device in the future to have multiple ADC14s. In this case, the ADC14 API would have to have an additional parameter to specify which ADC14 instance the user wants to configure. Since the majority of devices will only have one module, the instance parameter has been removed from the API definition. However, if the programmer is concerned about cross compatibility with future devices that might have more than one instance, an additional API with the instance parameter has been provided.

The normal API for the majority of devices that only have one ADC14 would look as follows:

For the minority of devices that might have two ADC14s, the user can use the following API:

Note that the functions can work in tandem. If the first API is called on a device with multiple ADC14s, the first instance of the module will be configured.


Quick Start


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

An empty "skeleton" project is provided in the examples directory of the MSPWare release. The 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. 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.

Keil IDE support is currently pending. A library is provided under the library folder of the release, however currently there has been minimal validation/testing.


Copyright 2014, Texas Instruments Incorporated