Migration Guide for SimpleLink MSP432P4 SDK

Table of Contents

1. Introduction to SimpleLink™ MSP432™ SDK

The SimpleLink™ MCU portfolio offers a single development environment that delivers flexible hardware, software and tool options for customers developing wired and wireless applications. With 100% code reuse across host MCUs, Wi-Fi™, Bluetooth® low energy, Sub-1GHz devices and more, you can choose the MCU or connectivity standard that fits your design. A one-time investment with the SimpleLink software development kit (SDK) allows you to reuse often, opening the door to create unlimited applications. For more information, visit www.ti.com/simplelink

The SimpleLink MSP432 Software Development Kit (SDK) is a set of software development tools that enable engineers to develop applications specifically on the MSP432 micro-controller family. This powerful software toolkit provides a cohesive and consistent software experience for MSP432 users by packaging essential software components such as TI RTOS, peripheral drivers and easy-to-use examples in one easy-to-use software package. Developing code with the MSP432 SDK ensures future-proofed portability and scalability.

The SimpleLink MSP432 SDK is the successor to MSP432Ware, and brings with it many advantages that are highlighted in Section 3.

2. Benefits of the SimpleLink MSP432 SDK

This SDK brings users into a software development framework that allows for a consistent look and feel among multiple TI embedded products spanning both connectivity and host MCUs. The following are key advantages of the SDK:

• The SDK is a standalone product that can be built without any external dependencies.

• Device Header files required for the software components are now included within the SDK. This keeps all dependencies for TI-provided embedded software in a single place. The components of the SDK do not rely on the IDE-provided copy of device header files.

• The SDK delivers, via TI RTOS, easy-to-use peripheral drivers named “TI Drivers” that allow quick setup of functional use cases for most peripherals. TI Drivers supports multiple 32-bit products, thereby ensuring that developers can abstract hardware-level decisions that are required to implement peripheral functionality and can instead focus on application development.

• Components that are used by multiple software tools are centralized. For example all TI-provided libraries such as Graphics library, DSPLib etc. use the same version of Driver Library, making it easier for customers to maintain and port software. All SDK software is well-tested together to ensure a better developer experience when using multiple TI-provided embedded software components in a single project.

3. Migration Overview

This document is intended for current MSP432 users that are using MSP432Ware v3.50.00.02 as a development platform for the MSP432P4x family of devices. It details migration considerations for users accustomed to software components delivered via MSP432Ware and is a helpful guide to locate these components in the context of the MSP432 SDK.

If the MSP432 SimpleLink SDK is your starting point, refer to the document SimpleLink MCU SDK User’s Guide and Quick Start Guide

This document does not apply to MSP430 users developing with the MSP430Ware ecosystem.

The SimpleLink SDK is made up of multiple components that offers differing layers of abstraction. This enables full control for the developer, allowing them the flexibility to turn the dial up and down between code portability and code optimization. While the SDK has changed the method of how TI components such as device header files are delivered, it does not change the actual contents of these components.

If you are an MSP432Ware user and your existing project:

• Only uses direct register access code, then no code changes are necessary. It is sufficient to simply point to the SDK version of the device header files. Detailed instructions are available in Section 5 of this document.
• Uses a combination of TI provided libraries and direct register access code, you will need to migrate to the SDK-provided libraries. Driver Library APIs are fully compatible to that used in MSP432Ware and no code changes are necessary. However project level changes are required as explained in Section 5 of this document.
• Uses TI RTOS, refer to Section 6 of this document, for detailed instructions on how to migrate

4. SimpleLink MSP432 SDK Overview

4.1 Minimum Requirements for using the SDK

IDE Requirements

When using the SimpleLink MSP432 SDK package, it is recommended to use Code Composer Studio. The SDK is also supported by IAR and KEIL. Version information is given below.

• Code Composer Studio, CCS 7.1 or later
• IAR for ARM 7.80.3 or later
• Keil uVision 5.22, TexasInstruments::MSP432P4xx_DFP pack, CMSIS-CORE in ARM::CMSIS Pack or later

Hardware Requirements

It is important to note that the MSP432P401x Revision C or newer is required to use the SDK. Older device revisions are not compatible with the SDK.

If you are using MSP432P401x Revision A/B or the MSP-EXP432P401R Black LaunchPad, please order new samples from https://www.ti.com/product/msp432p401R or the MSP-EXP432P401R Red LaunchPad from https://www.ti.com/tool/msp-exp432p401R prior to using the SDK.

You can also use XMS432P401R Revision C or MSP432P401R Revision C devices with the MSP-TS432PZ100 Target Socket Board or any custom board of your choice.

4.2 SDK Overview

This section serves as a quick introduction to the SDK file structure and key components. To understand the detail about the core components delivered by TI RTOS refer to the document SimpleLink MCU SDK User’s Guide

The SimpleLink MSP432 SDK is a single installer that delivers the following key components:

1. Examples: A wide range of examples are provided. Their purpose is to make it easy to start writing applications in the context of the SDK. The examples take advantage of the other components in the SDK to implement meaningful and representative functionality. Each example comes with its own documentation and project files for a selection of the supported IDEs and code generation tools.

2. TI Drivers API: This API layer exposes functionality of the hardware-specific drivers in the same way across all TI SimpleLink devices. For example, though the hardware implementation of the UART may be different on different devices, the TI Drivers API used to access its common functionality is the same. Note that TI Drivers are intended to be “full functional” drivers and include calls to the hardware abstraction layer (driver library), TI RTOS etc. An example of a TI Driver API to read the ADC: ADC_convert(adc, &adcValue0);

3. MSP432 Driver Library: For the MSP432 product family, Driver Library is available in the device ROM. These are hardware-specific drivers that are primarily intended to serve as a hardware abstraction layer and configure bits at the register-level for the user. MSP432 driver library APIs handle interrupts, timing, memory management etc. MSP432 Driver Library is the abstraction layer below TI Drivers APIs. An example of an MSP432 Driver Library API to read the ADC: uint_fast16_t ADC14_getResult(uint32_t memorySelect);

4. TI RTOS: The RTOS kernel offers services such as timing and scheduling of tasks. All TI SimpleLink SDKs come with the TI-RTOS kernel (SYS/BIOS). Some SDKs also offer examples that use alternative RTOS kernels (such as FreeRTOS) or examples that do not use an RTOS. Note that FreeRTOS requires a separate install from https://www.freertos.org/

5. Device Header Files: These are the .h files that map device-specific registers and bit fields to addresses in the CPU address map.

Understanding the SDK directory structure helps to easily locate the above components. The SDK directory structure is organized as follows:

1. Docs: This folder contains all the software documentation relevant to understanding and using the MSP432 SimpleLink SDK. This includes both Users and API Guides as well as release notes.

2. Source: This folder contains the source files, Device-specific header files,TI Drivers API, MSP432 Driver Library and other peripheral libraries such as grlib, iqmathlib etc.

3. OS: This folder contains the source for TI RTOS and components required to support FreeRTOS

4. Examples: The example folder is split in “OS” and “non-OS” sections. The “non-OS” section provides register-level (bare metal) code examples that are implemented without the framework of TI RTOS.

4.3 SDK FAQ

1. Is this update optional or mandatory?

   For new or early MSP432 Users, it is strongly recommended to start your software development using the SDK and TI Drivers. This prevents the need for future software migration and ensures you can always receive the latest device header files, updated libraries etc. Leveraging TI Drivers when creating application code ensures portability across all MCUs in the SimpleLink family as well as lowers the complexity of software design.

   For existing MSP432Ware users, the SDK update is currently not mandatory. TI will continue to make available as a stand-alone installer, MSP432Ware 3_50_00_02. However all future maintenance efforts will be directed towards the SDK and MSP432Ware will no longer be updated for bug fixes, patches or new device support.

• I am not using MSP432/430Ware or any TI-provided software but instead developed my project with custom components. Am I impacted?

  Even if you are not currently using MSP432Ware and/or TI-provided libraries, note that, device header files will not be deployed via the IDE in the future. Hence installing and using the SDK is crucial to keep your software projects updated and using the correct version of the device header files. As mentioned above you can continue to use your bare-metal or driver library code as long as it builds and functions in the SDK environment.

• How do I install the SDK?

  Remember to review the minimum requirements provided in Section 4.1 to ensure your system is setup. Installation instructions are available in the SimpleLink MSP432 Quick Start Guide

• What is the impact to my code base when TI updates the SDK?

  The primary advantage with the using the SDK if that as a developer you can chose to stay with a specific packaged instance of the SDK since it encompasses support for all the library source files you use and the device header files. Your code base will not be impacted by TI updates to the SDK. You can update to the SDK version of your choice as needed.

• Do I need to update CCS to use an updated version of the SDK?

  Yes. Every version of SDK is tested with a specific version of CCS. For example MSP432 SDK v1.20.00.45 has been tested to work only on CCS V7.1 or later. However you can always “freeze” an SDK release and use it across all updated CCS versions.This information will be available in the release notes of the SDK package.

• What type of support is provided for FreeRTOS or other third party RTOS users?

  Simplelink MSP432 SDK does not include FreeRTOS installation. The user must download and install FreeRTOS from www.freertos.org to build the examples.

  The SDK provides TI Drivers examples that run on FreeRTOS. All FreeRTOS examples are based on POSIX layer. No Native FreeRTOS examples are provided. 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.

  The release notes of TI Drivers specifies the version of FreeRTOS it was tested with.

• I use MSP430 (16-bit) devices, can I take advantage of the SimpleLink MSP432 SDK?

  MSP430 (16-bit) devices use a similar software framework known as MSP430Ware to deploy source libraries, examples and board-specific projects. Refer to the MSP430Ware Folder for more details.

5. Migration Considerations

This section only covers the non-OS aspects of migration. For TI RTOS users, refer to Section 6 of this document to understand how to migrate to the latest version of TI RTOS.

Also, as stated before the SDK supports MSP432P401x Revision C or later. If you are currently using XMS432P401x Revision A/B devices refer to this application report to understand the device-specific considerations when migrating to Revision C.

If you are an existing MSP432 user, before you begin migrating your project to the SDK framework, review the components in your code base.

Project Components Review

First, it is important to understand which TI-provided components are being used in your project. The sections below address how to migrate each of these components from the MSP432Ware to the SDK framework.

1. Device Header Files

Check and note down source files that use include paths in your project for files such as msp432.h or msp432p401r.h

If your project was built from the ground up using custom libraries or direct register access code, then your only dependency is the IDE-provided header file. In this case, the migration to the SDK is very simple. Follow the steps below to migrate your project to the SDK-based header file:

1. Download and install SDK
2. Ensure you are using the correct CCS version
3. Open your project in CCS via Project –> Import CCS Projects
4. Change the header file include path to point to the SDK-based header file. Directions on how to do this are provided in the step-by-step examples below.
5. Build your project

2. MSP432P Driver Library

Your project may include driver library either as a source or link directly to the ROM-based driverlib.lib

In such cases, the recommendation is to delete the driver library source and link to the latest SDK-provided version. This ensures any changes or bug fixes to driver library are automatically utilized by your SDK-based project.

For detailed instructions on how to do this, refer to step 5 and step 6 in section 5.1.2.

3. Additional TI libraries

Check if your project includes either source or library components from any of the following TI-provided libraries:

• Graphics library (grlib)
• IQ Math Library (iqmathlib)
• board support files

Each of these libraries may require unique migration steps. Refer to the corresponding release notes for library-specific information.

5.1 Step-by-Step Migration Examples using CCS

As mentioned previously, this section only covers non-OS based projects. Many of the specific migration tasks such as using the SDK-based header files remain the same for OS-based projects. However the user needs to ensure that the RTOS-based components are migrated first (see section 6) before working on the MSP432-specific header files and libraries.

There are two ways to migrate your existing MSP432 project:

Option 1: Use a standard SDK template and copy source code and header files from any existing project into the SDK template project.

OR

Option 2: Keep your existing project as-is and only migrate the TI-provided header files and libraries to use the SDK-based versions instead of the MSP432Ware version.

We highly recommend Option 1 i.e. using the standard SDK template and copying over source files since the SDK-based components are pre-setup and it is the fastest and most efficient migration path especially if multiple TI libraries are being used.

Also, this document assumes the SDK package was installed in the default directory location of C:/TI. All file names and paths are referenced to C:/TI.

5.1.1 Migrating to a new project by using the standard SDK template

The easiest way to get started with migration is by using the standard SDK template project as a starting point and then copying over custom source and header files.

The SDK template project is available in your SDK install directory (default: C:/TI) under the Examples -> nortos folder.

To migrate your project using the standard SDK template:

• Step 1: Open the empty project in your workspace

• Step 2: Copy/add any of your existing project source and header files to this new empty project

• Step 3: Do Not copy over any TI provided MSP432 software library sources previously obtained through MSP432Ware. All TI provided MSP432 software libraries are already accessible through the default compiler include flag in the template project’s setting.

• Step 4: If the existing source files (.c or .h) that were copied to the template project had include paths for TI provided MSP432 software header files these need to be changed to reference the SDK based relative paths.

Change header file include paths as shown below:

`#include "driverlib.h"` =====> `#include <ti/devices/msp432p4xx/driverlib/driverlib.h>`
`#include "grlib.h"` =====>  `#include <ti/grlib/grlib.h>`

• Step 5: Note that the start up file no longer sets up interrupts as “default ISR” instead each ISR is assigned a unique name. Depending on how your project was setup you may need to port the ISR name into the start up file.

Now, you have successfully migrated your existing project to use the SimpleLink SDK.

Important Note: the IDE’s ‘Create New Project’ options does NOT support the SDK template by default. So do not use this option to setup an SDK project.

5.1.2 Retaining existing project and migrating TI components only

This option is only useful if you prefer not to change the file or folder structure of your existing project code. In such cases, you can follow the steps below to modify an existing project and port it to use SDK resources such as libraries and headers.

Also, you can only use this approach if your existing project did not use an RTOS. For migrating TI RTOS based projects refer to Section 6.

The steps provided below are intended to teach you the process of migration by using an MSP432Ware example project as a starting point. Alternatively you can use any custom MSP432 project (direct register access or driver library based) as your starting point.

Step 1: Open an existing (non-SDK) MSP432 project

Open a non-SDK MSP432Ware project in the preferred CCS workspace. If you have MSP432Ware installed, you can find example projects under C:\ti\msp\MSP432Ware_3_50_00_02\driverlib\examples\MSP432P4xx

Note that this exercise uses an MSP432Ware project as a starting point. Alternatively you can use your custom project code base or other example projects from MSP432Ware.

Step 2: Setting up the environment variable

To setup the environment variable to point to the SDK Install path, right click on the Project name.

• Select Properties -> General -> Products (tab)
• Uncheck the “MSP432Ware” option and select the SimpleLink MSP432 SDK option as shown in the screen capture below.

If this step is executed correctly, you should be able to see the SDK install path in the environment variables tab as per below screen capture.

If no variables are seen, check the “show system variables” box in the screen capture below.

Step 3: Using SDK provided device header files

To migrate to the SDK-provided device header files,

• In Project-> Properties -> Build -> MSP432 Compiler -> Include options: Remove ${CCS_BASE_ROOT}/arm/include/ Add ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source

• In all project files, find all occurrences of #include "msp.h" Replace with #include <ti/devices/msp432p4xx/inc/msp.h>

Step 4: Using SDK provided CMSIS files

To migrate to the SDK-provided CMSIS files,

• In Project-> Properties -> Build -> MSP432 Compiler -> Include options:

Remove ${CCS_BASE_ROOT}/arm/include/CMSIS

Add ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/third_party/CMSIS/Include

The final setup from steps #3 and #4 should look like image below.

Step 5: Using SDK provided Startup and System files

To migrate to the SDK-provided startup/system files,

• Copy startup_msp432p401r_ccs.c and system_msp432p401r.c from the SDK installation and replace the corresponding files in your existing project folder.

These files can be found in the following directories: ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/devices/msp432p4xx/startup_system_files/ccs/startup_msp432p401r_ccs.c ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/devices/msp432p4xx/startup_system_files/system_msp432p401r.c

Note that the start up file no longer sets up interrupts as “default ISR” instead each ISR is assigned a unique name. Depending on how your project was setup you may need to port the ISR name into the start up file.

Step 6: Using the SDK provided TI Libraries

The preferred method to use TI libraries is to link the pre-built library instead of copying the source into the project. Although copying library source into your project will produce working results, using a linked library makes it easier to port/maintain a project when updating to a newer SDK.

MSP432 Driver Library

To migrate to the SDK-provided Driver Library,

• Delete any Driver Library source or linked .a files in an existing project.

• Remove existing Driver Library include paths

• In Project-> Properties -> Build -> MSP432 Compiler -> Include options:

Under “Add dir to #include search path (–include_path, -I)”: If this path is included, then remove it "${PROJECT_ROOT}/driverlib/MSP432P4xx"

• Next, go to Project -> Properties -> Build -> MSP432 Linker -> File Search Path: Under “Include library file or command file as input (–library, -l)”, add the line below: "${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/devices/msp432p4xx/driverlib/ccs/msp432p4xx_driverlib.lib"

Refer to the image below for how to link Driver Library:

After Driver Library is linked in your project, you will also need to change the Driver Library include path to point to the SDK-provided files.

• In all project files, find all occurrences of #include "driverlib.h" Replace with #include <ti/devices/msp432p4xx/driverlib/driverlib.h>

Graphics Library

Migrating Graphics Library from MSP432Ware to MSP432 SDK requires additional changes to LCD Drivers, Refer to Graphics Library Migration Guide for further instructions

IQMath Library

To migrate to the SDK-provided IQMath Library,

• Delete any IQMath Library source or linked .a files in an existing project.

• Remove existing IQMath Library include paths In Project-> Options… -> C/C++ Compiler -> Preprocessor -> Additional include directories: Remove "${PROJECT_ROOT}\...\iqmathlib\include"

• Next, go to Project -> Options… -> Linker Under “Additional Libraries”, add the line below: ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/iqmathlib/iar/IQmathLib.lib ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/iqmathlib/iar/QmathLib.lib

Refer to the image below for how to link IQMath Library:

Now all project components have been migrated to the SDK and you can build your project successfully!

5.2 Step-by-Step Migration Examples using IAR

As mentioned previously, this section only covers non-OS based projects. Many of the specific migration tasks such as using the SDK-based header files remain the same for OS-based projects. However the user needs to ensure that the RTOS-based components are migrated first (see section 6) before working on the MSP432-specific header files and libraries.

Configuring Custom Argument Variables

Before starting to work with any of the projects in the SDK, you need to load a set of variables that will be set for your current workspace. This is done using the following steps:

• Choose Tools -> Configure Custom Argument Variables

• Click Global->Import

• Import the custom argvars from the SDK. The argvars are stored in a .custom_argvars file, which is located in the tools/iar/ directory of the SDK: <SDK_INSTALL_PATH>/tools/iar/

• Restart IAR.

5.2.1 Migrating to a new project using the standard SDK template

Creating a New Project

The easiest way to get started with migration is by using the standard SDK template project as a starting point and then copying over custom source and header files. The following steps illustrate how to migrate a current project to use the SDK by starting with the standard SDK project template.

Open a copy of the SDK empty project template

• Step 1: In the IAR-IDE go to the Help tab and click on Information Center

• Step 2: In the new IAR Information Center for ARM window, click on Integrated Solutions

• Step 3: Then, click on Example projects under Texas Instruments

• Step 4: Then, click on example applications link

• Step 5: This Examples page contains information on how to create a new project, and links to import example projects

• Step 6: Scroll through the page and click on the empty project.

• Step 7: When prompted, click Yes to save a copy of the project workspace

• Step 8: Browse to the location where you want to save this workspace. Click Choose

• Step 9: Copy/add any of your existing project source and header files to this new empty project

• Step 10: Do Not copy over any TI provided MSP432 software library sources previously obtained through MSP432Ware. All TI provided MSP432 software libraries are already accessible through the default compiler include flag in the template project’s project setting.

• Step 11: If you had include paths for TI provided MSP432 software header files in your original project sources/headers, you need to change these references to the SDK based relative paths. Change header file include paths relative to ${SDK_INSTALL_DIR}/source
  • #include "driverlib.h" => #include <ti/devices/msp432p4xx/driverlib/driverlib.h>
  • #include "grlib.h" => #include <ti/grlib/grlib.h>

• Step 12: Note that the start up file no longer sets up interrupts as “default ISR” instead each ISR is assigned a unique name. Depending on how your project was setup you may need to port the ISR name into the start up file.

Now, you have successfully migrated your existing project to use the SimpleLink SDK.

Important Note: the IDE’s ‘Create New Project’ options does NOT support the SDK template by default. So do not use this option to setup an SDK project.

5.2.2 Retaining existing project and migrating TI components only

Follow the steps below to modify an existing project over to using SDK provided files/libraries.

Step 1: Open an existing non-SDK MSP432 project

Open a non-SDK MSP432Ware project in the preferred IAR workspace. If you have MSP432Ware installed, you can find example projects under C:\ti\msp\MSP432Ware_3_50_00_02\driverlib\examples\MSP432P4xx

Step 2: Using SDK provided device header files

To migrate to the SDK-provided device header files,

• In Project-> Options… -> C/C++ Compiler -> Preprocessor -> Additional include directories: Remove $TOOLKIT_DIR$/inc/TexasInstruments Add $SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source

• In all project files, find all occurrences of #inlcude msp.h Replace with #include <ti/devices/msp432p4xx/inc/msp.h>

Step 3: Using SDK provided CMSIS files

To migrate to the SDK-provided CMSIS files,

• In Project-> Options… -> C/C++ Compiler -> Preprocessor -> Additional include directories: Remove $TOOLKIT_DIR$\inc\TexasInstruments\CMSIS Remove $TOOLKIT_DIR$\CMSIS\Include Add $SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/third_party/CMSIS/Include

The final setup from steps #2 and #3 should look like image below.

Step 4: Using SDK provided Startup and System files

To migrate to the SDK-provided startup/system files,

• Copy startup_msp432p401r_ewarm.c and system_msp432p401r.c from the SDK installation and replace the corresponding files in your existing project folder.

These files can be found in the following directories: $SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/ti/devices/msp432p4xx/startup_system_files/iar/startup_msp432p401r_ewarm.c $SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/ti/devices/msp432p4xx/startup_system_files/system_msp432p401r.c

Step 5: Using the SDK provided TI Libraries

The preferred method to use TI libraries is to link the pre-built library instead of copying the source into the project. Although copying library source into your project will produce working results, using linked library makes it easier to port/maintain a project when updating to a newer SDK.

MSP432 Driver Library

To migrate to the SDK-provided Driver Library,

• Delete any Driver Library source or linked .a files in an existing project.

• Remove existing Driver Library include paths In Project-> Options… -> C/C++ Compiler -> Preprocessor -> Additional include directories: Remove $PROJ_DIR$\...\driverlib\MSP432P4xx

• Next, go to Project -> Options… -> Linker Under “Additional Libraries”, add the line below: $SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/ti/devices/msp432p4xx/driverlib/iar/msp432p4xx_driverlib.a

Refer to the image below for how to link Driver Library:

After Driver Library is linked in your project, you will also need to change the Driver Library include path to point to the SDK-provided files.

• In all project files, find all occurrences of #include driverlib.h Replace with #include <ti/devices/msp432p4xx/driverlib/driverlib.h>

Graphics Library

Migrating Graphics Library from MSP432Ware to MSP432 SDK requires additional changes to LCD Drivers, Refer to Graphics Library Migration Guide for further instructions

IQMath Library

To migrate to the SDK-provided IQMath Library,

• Delete any IQMath Library source or linked .a files in an existing project.

• Remove existing IQMath Library include paths In Project-> Options… -> C/C++ Compiler -> Preprocessor -> Additional include directories: Remove $PROJ_DIR$\...\iqmathlib\include

• Next, go to Project -> Options… -> Linker Under “Additional Libraries”, add the line below: $SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/ti/iqmathlib/iar/IQmathLib_IAR_MSP432.lib $SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/ti/iqmathlib/iar/QmathLib_IAR_MSP432.lib

Refer to the image below for how to link IQMath Library:

5.3 Step-by-Step Migration Examples using Keil

As mentioned previously, this section only covers non-OS based projects. Many of the specific migration tasks such as using the SDK-based header files remain the same for OS-based projects. However the user needs to ensure that the RTOS-based components are migrated first (see section 6) before working on the MSP432-specific header files and libraries.

5.3.1 Migrating to a new project with the standard SDK template

Do not use the New Project Creation Wizard

• Start with one of the example projects or empty project template shipped inside the SDK. Each software component in the SDK comes with its own set of examples. If your project depends on multiple TI provided software libraries, start from the empty template then add the necessary components into your projects.

• Import one of the empty project template shown below to your IDE and start your application from there. All the necessary include paths and SDK specific defines if any are already part of the Empty Project Template

• Copy/add any of your existing project source and header files to this new empty project

• If any specific file or library needs to be added from the SDK, add through the absolute or relative path from the current project

• Do Not copy over any TI provided MSP432 software library sources previously obtained through MSP432Ware. All TI provided MSP432 software libraries are already accessible through the default compiler include flag in the template project’s project setting.

• If you had include paths for TI provided MSP432 software header files in your project sources/headers, you need to change these references to the SDK based relative paths. Change header file include paths relative to ${SDK_INSTALL_DIR}/source
  • #include "driverlib.h" => #include <ti/devices/msp432p4xx/driverlib/driverlib.h>
  • #include "grlib.h" => #include <ti/grlib/grlib.h>

• Build and Download

5.3.2 Retaining existing project and migrating TI components only

Step 1: Open an existing non-SDK MSP432 Example project

Open a non-SDK MSP432Ware project in Keil. If you have MSP432Ware installed, you can find example projects under C:\ti\msp\MSP432Ware_3_50_00_02\driverlib\examples\MSP432P4xx

Step 2: Using SDK provided device header files

To migrate to the SDK-provided header files.

• In Project -> Options for Target -> C/C++: Check No Auto Includes

• In Project -> Options for Target -> C/C++ -> Include Paths: Add <insert_SDK_install_path>\source

• In all project files, find all occurrences of #inlcude msp.h Replace with #include <ti/devices/msp432p4xx/inc/msp.h>

Step 3: Using SDK provided CMSIS files

To migrate to the SDK-provided CMSIS files,

• Remove existing system startup files Go to Project -> Manage -> Run-Time Environment… Under CMSIS, Deselect Core

• In Project-> Options for Target -> C/C++ -> Include Paths: Remove $TOOLKIT_DIR$\inc\TexasInstruments\CMSIS Remove $TOOLKIT_DIR$\CMSIS\Include Add <insert_SDK_install_path>\source\third_party\CMSIS\Include

The final setup from steps #2 and #3 should look like image below.

Step 4: Using SDK provided Startup and System files

To migrate to the SDK-provided startup/system files,

• Remove existing system startup files Go to Project -> Manage -> Run-Time Environment… Under Device, Deselect Startup

• Copy startup_msp432p401r_ewarm.c and system_msp432p401r.c from the SDK installation and place them add them to your existing project folder.

These files can be found in the following directories: <insert_SDK_install_path>/source/ti/devices/msp432p4xx/startup_system_files/iar/startup_msp432p401r_ewarm.c <insert_SDK_install_path>/source/ti/devices/msp432p4xx/startup_system_files/system_msp432p401r.c

Step 5: Using the SDK provided TI Libraries

The preferred method to use TI libraries is to link the pre-built library instead of copying the source into the project. Although copying library source into your project will produce working results, using linked library makes it easier to port/maintain a project when updating to a newer SDK.

MSP432 Driver Library

To migrate to the SDK-provided Driver Library,

• Delete any Driver Library source or linked .lib files in an existing project.

• Remove existing Driver Library include paths In Project-> Options… -> C/C++ -> Include Paths: Remove ../../../../../driverlib/MSP432P4xx/

• Create a group called Library
• Right-click on the newly created Library group and select Add Existing Files to Group 'Library'...
• Browse to <SDK_install_path>/source/ti/devices/msp432p4xx/driverlib/keil/
• Make sure to change File of Type to Library file (*.lib)

• Add msp432p4xx_driverlib.lib

Refer to the image below for how to link Driver Library:

After Driver Library is linked in your project, you will also need to change the Driver Library include path to point to the SDK-provided files.

• In all project files, find all occurrences of #include driverlib.h Replace with #include <ti/devices/msp432p4xx/driverlib/driverlib.h>

Graphics Library

Migrating Graphics Library from MSP432Ware to MSP432 SDK requires additional changes to LCD Drivers, Refer to Graphics Library Migration Guide for further instructions

IQMath Library

IQMath Library is currently not supported in Keil. Please check back in future versions of SimpleLink MSP432 SDK for updates.

6. TI RTOS Migration

This section will cover the migration of applications that are using TI-RTOS for MSP43x v2.20.00.06. It’s also assuming the necessary software components (e.g. IDE, compiler tools, host OS, etc.) are present as noted in the SimpleLink SDK release notes.

The new SimpleLink SDKs have “shared” debug and release TI-RTOS configuration projects in the product. They are located in SDK_INSTALL_DIR/kernel/tirtos/builds/boards directory. There are projects for the supported compilers (e.g. CCS, GCC and IAR) for both the debug and release configurations. Please refer to the SimpleLink MSP432 SDK User’s Guide for more details on using and managing these configurations. For this migration document, these projects will not be used. Instead, the TI-RTOS configuration file (.cfg) that was in the original project will remain in the migrated project.

This section is separated into (a) required target code changes for all applications and (b) IDE-specific information i.e. the three supported development environments for TI-RTOS applications: CCS, IAR and command-line makefile projects.

Please note: your version of the SimpleLink MSP432 SDK will be different than the one shown in this section.

Target Code Changes

The following are the target content changes that have to be done for each project.

TI-RTOS Configuration Changes

It’s highly recommended you open the .cfg file as a text-file and make these changes.

• Remove all references to the ti.driver.Config module. In this release of the SDK, only the non-instrumented TI driver library is available. This feature will be added in a future release.

  var driversConfig = xdc.useModule('ti.drivers.Config');

• Add the Power_idleFunc function as an Idle function. This was previously done in xdc.useModule('ti.drivers.Config') which you just removed.

  Idle = xdc.useModule('ti.sysbios.knl.Idle');
  Idle.addFunc('&Power_idleFunc');

• Remove all references to the ti.mw.Config and ti.mw.fatfs.FatFS modules. The middleware module libraries are now added via linker options (detailed later).

  var mwConfig = xdc.useModule('ti.mw.Config');
  var FatFS = xdc.useModule('ti.mw.fatfs.FatFS');

• In the SimpleLink SDK, the system stack (ISR stack) is now specified in the linker file (detailed in a later step) for the TI-RTOS examples. Set the Program.stack variable to zero.

  Program.stack = 0;

Code Changes

• All calls to Board_initDriver have been changed to simply Driver_init. These changes are not required since there are compatibility macros present, but for completeness, this change is recommended. For example, change the following

  /* Call board init functions */
  Board_initGeneral();
  Board_initGPIO();
  Board_initUART();

  to

  /* Call board init functions */
  Board_initGeneral();
  GPIO_init();
  UART_init();

• The FatFS has been removed from the TI-RTOS Configuration file (as noted above). This configuration setting created some background code. The application is now responsible for making these calls (e.g. add_device()). Use a driver fatfs examples in the SimpleLink SDK as a guideline to see the changes needed.

• The ti/drivers/WiFi module was removed. Please use the SimpleLink MSP432 WiFi Plugin instead.

Board Files Changes

The Board files (i.e. MSP_EXP432P401R.c, MSP_EXP432P401R.h, MSP_EXP432P401R.cmd, and Board.h) have significantly changed from the 2.20 release. It is highly recommended you use the new files from an SDK example (e.g. drivers/empty). Then make the necessary changes to the new files as needed. For example, if you added a new UART in your TI-RTOS for MSP432x v2.20.00.06 application, add the UART again in the board files. Make sure to compare your linker file with the new ones also. Starting in the SimpleLink SDK, the system stack (ISR stack) is now configured in the linker file instead of the TI-RTOS configuration (.cfg) file. This allows changes to the system stack size without changing the TI-RTOS configuration.

For a summary of the board file changes, please refer to the SimpleLink Core SDK Release Notes.

Application Changes due to MISRA Updates

There might be some compiler warnings in your application because of type mismatches with some of the driver APIs. These are caused by MISRA compliance updates that were detailed in the SimpleLink Core SDK Release Notes. This should be trivial to fix once you build in the application via the below Development Environment Changes listed below.

Development Environment Changes

Please pick the relevant development environment and follow the steps.

CCS Projects

These steps assume that CCSv7 has discovered both the TI-RTOS for MSP432 v2.20.00.06 and SimpleLink MSP432 SDK products.

• Import the project into CCS v7 (Project->Import CCS Project... and navigate as required) if not already present.

• Target Content Changes Please make sure the above target content changes are done.

• Use SimpleLink SDK instead of TI-RTOS Select Project Properties->General->RTSC and check/uncheck in the following order. If you switch the order, you’ll lose the platform name (ti.platforms.msp432:MSP432P401R). If that happens, you can manually type it in.

1. Select the SimpleLink MSP432 SDK box
2. Uncheck the unknown 2.20.00.06 box. Note: a warning at the top of the window may appear (show below). This can be ignored.

Note: if TI-RTOS for MSP43x v2.20.00.06 has not been discovered by CCSv7, it will look like this. Please check/uncheck in the following order

1. Select the SimpleLink MSP432 SDK box
2. Uncheck the unknown 2.20.00.06 box
3. Uncheck the unresolved box

• Change Compiler Include Paths Options The following Project Properties->Build->MSP432 Compiler->Include Options include paths need to change from

  "${COM_TI_RTSC_TIRTOSMSP430_INSTALL_DIR}/products/msp432_driverlib_3_21_00_05/inc/CMSIS"
  "${COM_TI_RTSC_TIRTOSMSP430_INSTALL_DIR}/products/msp432_driverlib_3_21_00_05/inc"
  "${COM_TI_RTSC_TIRTOSMSP430_INSTALL_DIR}/products/msp432_driverlib_3_21_00_05/driverlib/MSP432P4xx"

  to

  "${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/kernel/tirtos/packages/ti/sysbios/posix"
  "${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/third_party/CMSIS/Include"

Here’s what it should look like:

• Change Compiler Predefined Symbols Options In the Project Properties->Build->MSP432 Compiler->Predefined Symbols window, remove TARGET_IS_MSP432P4XX and MSP432WARE symbols.

• Change Linker Libraries The following Project Properties->Build->MSP432 Linker->File Search Path libraries need to change from

  ${COM_TI_RTSC_TIRTOSMSP430_INSTALL_DIR}/products/msp432_driverlib_3_21_00_05/driverlib/MSP432P4xx/ccs/msp432p4xx_driverlib.lib

  to

  "${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/display/lib/display.aem4f"
  "${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/drivers/lib/drivers_msp432p4xx.aem4f"
  "${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/kernel/tirtos/packages/ti/dpl/lib/dpl_msp432p4xx.aem4f"
  "${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/third_party/fatfs/lib/fatfs.aem4f"
  "${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/devices/msp432p4xx/driverlib/ccs/msp432p4xx_driverlib.lib"

Here’s what it should look like:

• Rebuild the CCS project!

IAR Projects

An IAR project that used TI-RTOS for MSP432 v2.20.00.06 in IAR can be migrated with the following steps to work with the new SimpleLink SDK.

• Target Content Changes Please make sure the above target content changes are done.
• Configure Custom Argument Variables… Import the SDK Install Dir\tools\iar\SIMPLELINK_MSP432_SDK.custom_argvars file via Tools->Configure Custom Argument Variables...

• Change Compiler Options Change the default Projects Options->Runtime Checking->C/C++ Compiler->Extra Options specified for a TI-RTOS example

  -f
  $PROJ_DIR$/configPkg/compiler.opt.defs
  --diag_suppress=Pa050
  -I$MSP432DRIVERLIB$/inc/CMSIS
  -I$MSP432DRIVERLIB$/inc
  -I$MSP432DRIVERLIB$/driverlib/MSP432P4xx
  -D__MSP432P401R__
  -Dewarm
  -DMSP432WARE
  --debug
  --silent

  to

  -f
  $PROJ_DIR$/configPkg/compiler.opt.defs
  -I$SIMPLELINK_MSP432_SDK_INSTALL_DIR$/kernel/tirtos/packages/ti/sysbios/posix
  -I$SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source
  -I$SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/third_party/CMSIS/Include
  -D__MSP432P401R__
  --debug
  --silent
  -e
  --aeabi
  --thumb
  --diag_suppress=Pa050
  -I$PROJ_DIR$

  Here’s what it should look like:

• Change Linker Libraries Change the default Projects Options->Runtime Checking->Linker->Extra Options specified for a TI-RTOS example

-f
$PROJ_DIR$/configPkg/linker.cmd
$MSP432DRIVERLIB$/driverlib/MSP432P4xx/ewarm/msp432p4xx_driverlib.a
--silent
--cpu=Cortex-M4F
--entry=__iar_program_start
--redirect
_Printf=_PrintfSmall
--redirect
_Scanf=_ScanfSmall

to

-f
$PROJ_DIR$/configPkg/linker.cmd
$SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/ti/display/lib/display.arm4f
$SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/ti/drivers/lib/drivers_msp432p4xx.arm4f
$SIMPLELINK_MSP432_SDK_INSTALL_DIR$/kernel/tirtos/packages/ti/dpl/lib/dpl_msp432p4xx.arm4f
$SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/third_party/fatfs/lib/fatfs.arm4f
$SIMPLELINK_MSP432_SDK_INSTALL_DIR$/source/ti/devices/msp432p4xx/driverlib/iar/msp432p4xx_driverlib.a
--silent
--cpu=Cortex-M4F
--redirect
_Printf=_PrintfSmall
--redirect
_Scanf=_ScanfSmall

Here’s what it should look like:

• Change Linker Libraries Make sure to update the Linker->Config->Linker configuration file with the new name if the linker file has a new name or location.

• Rebuild the IAR project!

Command Line Makefile Projects

For this discussion, assume the example to be migrated is in the TI-RTOS for MSP43x v2.20.00.06 product. All the changes (besides the target content changes listed above) are going to be isolated to the imports.mak and makedefs for all compiler tools (TI, GCC and IAR). The basic idea is replace parts of the makedefs file from a TI-RTOS for MSP43x v2.20.00.06 example with parts of an example’s makefile from the SimpleLink SDK. The SimpleLink SDK product has fewer directories (e.g. no TIRTOS_INSTALL_DIR/products directory). This allows for a simplier makefile.

This section will focus on the TI compiler (CCS), but the GCC and IAR changes are similar.

• Target Content Changes Please make sure the above target content changes are done.
• imports.mak at the root directory of the SimpleLink SDK Update the directories at the top of the imports.mak as needed in the SimpleLink SDK you are using. Note: if you did not want FreeRTOS, leave the assignment blank. Same for the different compiler tools. For example, if you are only using TI-RTOS and the TI compiler in CCS, you could have the following

XDC_INSTALL_DIR        ?= c:/ti/xdctools_3_32_01_22_core

FREERTOS_INSTALL_DIR   ?=

CCS_ARMCOMPILER        ?= c:/ti/ccsv7/tools/compiler/ti-cgt-arm_16.9.0.LTS
GCC_ARMCOMPILER        ?=
IAR_ARMCOMPILER        ?=

• makedefs in the examples The top of this file can be replaced with basically the contents of a sysbios example’s makefile (e.g. SDK_INSTALL_DIR/examples/rtos/MSP_EXP432P401R/sysbios/swi/tirtos/ccs/makefile). The SIMPLELINK_MSP432_SDK_INSTALL_DIR needs to adjusted accordingly and the CODEGEN_INSTALL_DIR must retained and adjusted accordingly.

For example, the tirtos_msp43x_2_20_00_06/examples/MSP432/TI/MSP_EXP432P401R/makedefs can be changed from this

CODEGEN_INSTALL_DIR = c:/ti/ccsv6/tools/compiler/ti-cgt-arm_15.12.1.LTS

CC = "$(CODEGEN_INSTALL_DIR)/bin/armcl"
LNK = "$(CODEGEN_INSTALL_DIR)/bin/armcl"

XDC_INSTALL_DIR := c:/ti/xdctools_3_32_00_06_core
TIRTOS_INSTALL_DIR := c:/ti/tirtos_msp43x_2_20_00_06
TIDRIVERS_INSTALL_DIR := $(TIRTOS_INSTALL_DIR)/products/tidrivers_msp43x_2_20_00_08
BIOS_INSTALL_DIR := $(TIRTOS_INSTALL_DIR)/products/bios_6_46_00_23
UIA_INSTALL_DIR := $(TIRTOS_INSTALL_DIR)/products/uia_2_00_06_52
MSP432DRIVERLIB_INSTALL_DIR ?= $(TIRTOS_INSTALL_DIR)/products/msp432_driverlib_3_21_00_05

TIRTOS_PACKAGES_DIR = $(TIRTOS_INSTALL_DIR)/packages
TIDRIVERS_PACKAGES_DIR = $(TIDRIVERS_INSTALL_DIR)/packages
BIOS_PACKAGES_DIR = $(BIOS_INSTALL_DIR)/packages
UIA_PACKAGES_DIR = $(UIA_INSTALL_DIR)/packages

XDCPATH = $(TIRTOS_PACKAGES_DIR);$(TIDRIVERS_PACKAGES_DIR);$(BIOS_PACKAGES_DIR);$(UIA_PACKAGES_DIR);

CFLAGS = -I$(MSP432DRIVERLIB_INSTALL_DIR)/inc/CMSIS -I$(MSP432DRIVERLIB_INSTALL_DIR)/inc -I$(MSP432DRIVERLIB_INSTALL_DIR)/driverlib/MSP432P4xx -D__MSP432P401R__ -Dccs -DMSP432WARE -mv7M4 --code_state=16 --abi=eabi -me -g --display_error_number --diag_warning=255 --diag_wrap=off --gen_func_subsections=on --float_support=FPv4SPD16

LFLAGS = -l$(MSP432DRIVERLIB_INSTALL_DIR)/driverlib/MSP432P4xx/ccs/msp432p4xx_driverlib.lib MSP_EXP432P401R.cmd -m$(NAME).map --warn_sections --display_error_number --diag_wrap=off --rom_model -i$(CODEGEN_INSTALL_DIR)/lib -llibc.a

to

SIMPLELINK_MSP432_SDK_INSTALL_DIR ?= c:/ti/simplelink_msp432_sdk_1_20_00_16
include $(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/imports.mak

CODEGEN_INSTALL_DIR = $(CCS_ARMCOMPILER)

XDCPATH = $(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/source;$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/kernel/tirtos/packages;

CC = $(CCS_ARMCOMPILER)/bin/armcl
LNK = $(CCS_ARMCOMPILER)/bin/armcl

CFLAGS =  -I../..   -I$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/source -I$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/source/third_party/CMSIS/Include -D__MSP432P401R__ --advice:power_severity=suppress -I$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/kernel/tirtos/packages/ti/sysbios/posix -mv7M4 --code_state=16 -me -g --display_error_number --diag_warning=255 --diag_wrap=off --gen_func_subsections=on --float_support=FPv4SPD16

LFLAGS =  -l$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/source/ti/display/lib/display.aem4f -l$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/source/ti/drivers/lib/drivers_msp432p4xx.aem4f -l$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/kernel/tirtos/packages/ti/dpl/lib/dpl_msp432p4xx.aem4f -l$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/source/third_party/fatfs/lib/fatfs.aem4f -l$(SIMPLELINK_MSP432_SDK_INSTALL_DIR)/source/ti/devices/msp432p4xx/driverlib/ccs/msp432p4xx_driverlib.lib ./MSP_EXP432P401R_TIRTOS.cmd -m$(NAME).map --warn_sections --display_error_number --diag_wrap=off --rom_model -i$(CCS_ARMCOMPILER)/lib -llibc.a

• Rebuild the Makefile project!

7. Summary

In summary, while the SDK has changed the method of how TI components such as device header files are delivered, it does not change the actual contents of these components.

For all non-OS applications, there are no large scale changes required to your existing code base and it is sufficient to point to the SDK version of TI components.

For OS-based applications, the changes required are provided in detail.

The Migration Guide and the available API and User Guides in the SDK ‘docs’ folder can help ease the migration effort from your existing software product to the simpleLink SDK platform.