CC254x to CC23xx Porting Guide

This section will describe, in general terms, how to port a project developed for the CC254x device on the SimpleLink CC254x SDK to a CC23xx device running the SimpleLink Low Power F3 SDK.

Introduction

There are some notable software differences between the CC23xx and the CC254x device. It is important to know and understand what these differences are when porting your project from the CC254x to the CC23xx. The differences between the SimpleLink CC254x SDK and the SimpleLink Low Power F3 SDK are covered in-depth in this document. Among these changes are moving to FreeRTOS from OSAL, implementing multi-threading, incorporating BLE5 through use of the BLE5-stack, and much more.

The following sections discuss the major changes between the CC254x and the CC23xx devices.

• OSAL

  • OSAL

  • Application and Stack With ICall

  • Event Processing

  • Word alignment boundary support in CCS for split image build configurations

  • FreeRTOS

  • LaunchPad support

  • Bluetooth 5.2 Enabled

• Migration Guides

  • Migrate to BLE5 stack

  • Migrate to FreeRTOS

  • Migrate the TI drivers

• Compatibility Notes

---

OSAL

A major change in moving to FreeRTOS is the complete removal of the application from the OSAL environment. While the stack code uses OSAL within its own thread, the application thread can only use the APIs of OSAL that are defined in ICallBleAPI.c. Many functions such as osal_memcpy, osal_memcmp, and osal_mem_alloc() are unavailable. These functions have been replaced by FreeRTOS, C runtime, and ICall APIs.

Application and Stack With ICall

In the CC23xx Bluetooth Low Energy protocol stack, the application and the stack now communicate with one another through the use of messages. Messages between the application and stack pass through a framework developed called ICall (Indirect Call Framework). This functionality lets the application call the same APIs used in OSAL but is parsed by the ICall and sent to the stack for processing. Many of these stack functions are defined in icall_ble_api.h for the application to use transparently while ICall handles the sending and receiving from the stack transparently.

ICall has been optimized for reduced flash usage and increased stack operational efficiency.

No ICall/Stack API changes are required to realize these benefits.

For details regarding improved ICall and it’s benefits, see ICall Translation and Include.

For additional information on ICall see ICall.

Threads, Semaphores, and Queues

Unlike single-threaded operating systems such as OSAL, FreeRTOS is multi-threaded with custom priorities for each thread. The FreeRTOS handles thread synchronization and APIs are provided for the application threads to use to maintain synchronization between different threads. Semaphores are the prime source of synchronization for applications. The semaphores are used to pass event messages to the event processor of the application.

Profile callbacks that run in the context of the Bluetooth low energy protocol stack thread are made re-entrant by storing event data and posting a semaphore of the application to process in the context of the application. Similarly, key press events and clock events that run in ISR context also post semaphores to pass events to the application. Unique to FreeRTOS, queues are how applications process events in the order the events were called and make callback functions from profiles and the stack re-entrant. The queues also provide a FIFO ordering for event processing. An example project may use a queue to manage internal events from an application profile or a GAP profile role (for example, Peripheral or Central). ICall uses a queue and it is accessed through the ICall API.

For more information on FreeRTOS and its features, see FreeRTOS (RTOS Kernel) Overview

Event Processing

Similar to OSAL, each FreeRTOS task has two functions that implement the fundamental tasks for an application: Peripheral_start() and BLEAppUtil_Task().

The BLEAppUtil framework framework has a dedicated folder for ICall containing ICall registration routines. The Peripheral_start() function has all the initialization functions for the application profiles and the GAP and GATT roles. The initialization includes setting up callbacks that the application should receive from the profile and stack layers. For more details on callbacks, and other messaging systems see Intertask Messages.

BLEAppUtil_Task() contains an infinite loop in which events are processed. After entry of the loop and having just finished initialization, the application task calls mq_receive() to block on its semaphore until an event occurs.

Similar to osal_set_event() in a CC254x application, the application task can post the semaphore of the application with a call to mq_send() after setting an event. An alternative way is to enqueue a message using BLEAppUtil_enqueueMsg() which preserves the order in which the events are processed.

Events can come from within the same task, the profiles, or the stack. Events from the stack are handled first with a call to ICall_fetchMsg() similar to osal_msg_receive() in a CC254x application. Internal events and messages from profiles or the GAP roles, that are received in callback functions, must be treated as re-entrant and should be handled in the BLEAppUtil_Task() function too. In other words, processing should be done within the application context. In many cases such as in GAP role profile callbacks, you must place events in a queue to preserve the order in which messages arrive. For general overview of application architecture see Introduction.

Word alignment boundary support in CCS for split image build configurations

In previous versions of Code Composer Studio, the flash-loader driver was limited to writing/reading/erasing a page at a time.

Utilizing the upgraded word aligned CCS flash-loader driver in CCS 7.0.0 and newer, along with enhancements in the Frontier tool, limits the worst case to the size of a word (32 bits). Word alignment allows for additional available Flash to be used by the application or the stack.

FreeRTOS

The CC23xx devices exclusively support FreeRTOS. If a project needs to be migrated from the SimpleLink CC254x SDK, then it will need to be converted to FreeRTOS during the migration process.

LaunchPad support

Find support and all the collaterals for the LaunchPad CC2340R5 in the CC23xx LaunchPad Development Kit Product Page: CC2340R5 LaunchPad

Bluetooth 5.2 Enabled

If your project wasn’t already on a BLE5 platform, the CC23xx will provide the ability to support the new features of Bluetooth 5.2. This includes features such as higher throughput, longer range, advertising extensions, and improved coexistence with other wireless technology.

Migration Guides

Migrate to BLE5 stack

If migrating from a SimpleLink CC254x SDK based project to a SimpleLink Low Power F3 SDK based project, then it is necessary to migrate the SimpleLink CC254x SDK project to the BLE5 stack if it’s not already in the BLE5 stack. This initial migration will greatly ease the porting process further down the line.

If the project has not already been migrated to the BLE5 stack, then the Porting BLE-Stack to BLE5-Stack guide should be leveraged to aid in this section of the migration.

Migrate to FreeRTOS

An important step that must be taken in order to port an example from the SimpleLink CC254x SDK to the SimpleLink Low Power F3 SDK is to ensure that the project is implemented in FreeRTOS. The SimpleLink Low Power F3 SDK only supports FreeRTOS, so any projects running on OSAL will not work unless they are converted to FreeRTOS. This part of the process should be done after the application code has been transferred to a sample project running on the SimpleLink Low Power F3 SDK.

Migrate the TI drivers

Aside from the change in RTOS and BLE stack, peripheral drivers represent a significant change from the CC254x architecture. Any drivers used by the CC254x project must be ported to the respective SimpleLink Low Power F3 SDK drivers.

It is recommended to reference relevant TI drivers examples in the SimpleLink Low Power F3 SDK when porting driver code from the SimpleLink CC254x SDK to the SimpleLink Low Power F3 SDK. The API Guides available for the SimpleLink Low Power F3 SDK contain function descriptions, example code, return codes, and parameter descriptions that can be verbosity helpful during the migration process.

For example, if SPI was used in the original SimpleLink CC254x SDK project then the spicontroller and spiperipheral SimpleLink Low Power F3 SDK example projects should be referenced. These projects will showcase how the SPI driver is used and works in the SimpleLink Low Power F3 SDK.

The changes in the TI Drivers from the SimpleLink CC254x SDK to the SimpleLink Low Power F3 SDK varies in complexity and amount depending on the specific driver. To learn about how the TI Drivers work and should be used, the documents referenced earlier in this section should be leveraged.

It is important to ensure that projects that are being ported to CC23xx are not using deprecated libraries. A few migration guides for libraries that should be updated are shown below:

• UART to UART2 Porting Guide

• GPIO++ Driver Porting Guide

Compatibility Notes

Due to a number of improvements and feature additions, the recommended migration path for customers is to start with a CC23xx based project and migrate any custom application code and project configuration to the new project.