The CC2640R2F SDK Platform¶

ARM Cortex M0 (Radio Core)¶

The Cortex M0 (CM0) core within the CC2640R2F is responsible for both interfacing to the radio hardware, and translating complex instructions from the Cortex M3 (CM3) core into bits that are sent over the air using the radio. For the Bluetooth low energy protocol, the CM0 implements the PHY layer of the protocol stack. Often, the CM0 is able to operate autonomously, which frees up the CM3 for higher-level protocol and application-layer processing.

The CM3 communicates with the CM0 through a hardware interface called the RF doorbell, which is documented in section 23.2 of the CC26xx Technical Reference Manual. The radio core firmware is not intended to be used or modified by the application developer.

ARM Cortex M3 (System Core)¶

The system core (CM3) is designed to run the Bluetooth low energy protocol stack from the link layer up to the user application. The link layer interfaces to the radio core through a software module called the RF driver, which sits above the RF doorbell. The RF driver runs on the CM3 and acts as an interface to the radio on the CC2640R2F, and also manages the power domains of the radio hardware and core. Documentation for the RF driver can be found at the TI-RTOS Drivers Reference. Above the RF driver is the TI Bluetooth low energy protocol stack, which is implemented in library code.

The application developer interfaces with the protocol stack through a set of APIs (ICall) to implement a Bluetooth low energy application. The rest of this document intends to document application development on the CC2640R2F using the Bluetooth low energy stack.

Stack Library Configuration (_stack_library)¶

In BLE-Stack 3.00.01, stack can be built as a library that can be statically linked to the application. Projects with build with this new configuration can be identified by project build configurations with _stack_library in its configuration name. Using this build configuration will yield additional flash footprint optimizations by the linker since the application and stack can share contiguous flash pages. The gained footprint savings will however prevent split-image application- or on-chip OAD downloads. See Available CCS project build configurations and Available IAR project build configurations for the available project build configurations. Stack library projects have the following properties

• Stack project generates a static library (.lib)
• Application project will now link the stack in as a library
• There is no explicit app/stack boundary. The application’s link step decides the memory locations of the code within the stack_library. There are some exceptions to this such as SNV.
• This architecture saves flash by allowing the linker work more efficiently.
• These projects used the improved ICall architecture

Split Image Configuration¶

As with previous BLE-Stack 2.x SDK releases, application and stack images are built as two separate projects that generate two separate images. These images occupy separate, non-overlapping flash memory pages. The split image configuration is useful in purposes such as on-chip OAD where it could be advantageous to perform independent application or stack downloads. Split image projects have the following properties:

• Fixed stack entry point
• Stack project generates a separate executable (.hex, .out, .bin)
• Explicit Flash/RAM boundaries between app and stack
• Independent update of stack/app (API compatibility must be ensured by the user)

Project Build Configurations¶

Sample applications within the BLE-Stack 3.00.01 portion of the SimpleLink CC2640R2 SDK support multiple build configurations to enable using the protocol stack build types discussed above. Other build configurations may have been created to support features such as RCOSC or OAD out of the box. The table below gives a summary of the build configurations found within BLE-Stack 3.00.01 and their compatibility with one another.

Converting Library Build to Split Image¶

All BLE-Stack 3.00.01 projects will support improved ICall and the Library build configuration. However, not all projects will have ICall in non-Library Build configuration. In other words, not all projects will have a split application/stack build configuration.

A split Application and Stack configuration is required for on-chip OAD applications where only the stack or the application image is planned to be upgraded. Library configuration only supports full application + stack image off-chip OAD.

This section outlines how to convert an ICall Library Project to a split application and stack project.

Standard Project Task Hierarchy¶

Considering the simple_peripheral project as an example, these tasks are listed by priority. A higher task number corresponds to a higher priority task:

• Priority 5: Bluetooth low energy protocol stack task (must be highest priority)
• Priority 3: GapRole task (peripheral role)
• Priority 1: Application task (simple_peripheral)

TI-RTOS Overview introduces TI-RTOS tasks. Overview describes interfacing with the Bluetooth low energy protocol stack. GAPRole Task describes the GapRole task. Pre-main initialization describes the application task.

Examples Folder¶

The examples\ folder contains example source files for the BLE-Stack, TI-RTOS kernel, and TI-RTOS drivers. All the source code supporting the SimpleLink CC2640R2 SDK examples can be found at *examples\rtos\CC2640R2_LAUNCHXL\. Examples for each product can be found within their respective folders and are accessible via various means as shown in Examples available for the CC2640R2F platform.

For TI-RTOS Kernel and TI-RTOS driver examples, see the linked documentation. To help select a specific BLE example, see BLE examples available for the CC2640R2F platform. As with previous BLE-Stack releases, each example contains a toolchain subdirectory for CCS and IAR.

IAR examples are available as .eww projects whereas CCS project are imported.

See Table 1. for a list of examples supported by the SDK.

Source Folder¶

The source\ti\ folder contains libraries and source files for the BLE-Stack, TI-RTOS drivers, and various shared modules. They can be found within their respective folders as shown in CC2640R2F SDK’s source\ti\ directory.

Hardware Interrupts (Hwi)¶

Hwi threads (also called Interrupt Service Routines or ISRs) are the threads with the highest priority in a TI-RTOS application. Hwi threads are used to perform time critical tasks that are subject to hard deadlines. They are triggered in response to external asynchronous events (interrupts) that occur in the real-time environment. Hwi threads always run to completion but can be preempted temporarily by Hwi threads triggered by other interrupts, if enabled. Specific information on the nesting, vectoring, and functionality of interrupts can be found in the CC26xx Technical Reference Manual.

Generally, interrupt service routines are kept short as not to affect the hard real-time system requirements. Also, as Hwis must run to completion, no blocking APIs may be called from within this context.

TI-RTOS drivers that require interrupts will initialize the required interrupts for the assigned peripheral. See Drivers for more information.

The Hwi module for the CC2640R2F also supports Zero-latency interrupts. These interrupts do not go through the TI-RTOS Hwi dispatcher and therefore are more responsive than standard interrupts, however this feature prohibits its interrupt service routine from invoking any TI-RTOS kernel APIs directly. It is up to the ISR to preserve its own context to prevent it from interfering with the kernel’s scheduler.

For the Bluetooth low energy protocol stack to meet RF time-critical requirements, all application-defined Hwis execute at the lowest priority. TI does not recommend modifying the default Hwi priority when adding new Hwis to the system. No application-defined critical sections should exist to prevent breaking TI-RTOS or time-critical sections of the Bluetooth low energy protocol stack. Code executing in a critical section prevents processing of real-time interrupt-related events.

Software Interrupts (Swi)¶

Patterned after hardware interrupts (Hwi), software interrupt threads provide additional priority levels between Hwi threads and Task threads. Unlike Hwis, which are triggered by hardware interrupts, Swis are triggered programmatically by calling certain Swi module APIs. Swis handle threads subject to time constraints that preclude them from being run as tasks, but whose deadlines are not as severe as those of hardware ISRs. Like Hwis, Swi threads always run to completion. Swis allow Hwis to defer less critical processing to a lower-priority thread, minimizing the time the CPU spends inside an interrupt service routine, where other Hwis can be disabled. Swis require only enough space to save the context for each Swi interrupt priority level, while Tasks use a separate stack for each thread.

Similar with Hwis, Swis should be kept to short and may not include any blocking API calls. This allows high priority tasks such as the wireless protocol stack to execute as needed. It is suggested to _post() some TI-RTOS synchronization primitive to allow for further post processing from within a Task context. See Figure 20. to illustrate such a use-case.

Figure 20. Preemption Scenario

The commonly used Clock module operates from within a Swi context. It is important that functions called by a Clock object do not invoke blocking APIs and are rather short in execution.

Task¶

Task threads have higher priority than the background (Idle) thread and lower priority than software interrupts. Tasks differ from software interrupts in that they can wait (block) during execution until necessary resources are available. Tasks require a separate stack for each thread. TI-RTOS provides a number of mechanisms that can be used for inter-task communication and synchronization. These include Semaphores, Event, Message queues, and Mailboxes.

See Tasks for more details.

Idle Task¶

Idle threads execute at the lowest priority in a TI-RTOS application and are executed one after another in a continuous loop (the Idle Loop). After main returns, a TI-RTOS application calls the startup routine for each TI-RTOS module and then falls into the Idle Loop. Each thread must wait for all others to finish executing before it is called again. The Idle Loop runs continuously except when it is preempted by higher-priority threads. Only functions that do not have hard deadlines should be executed in the Idle Loop.

For CC2640R2F devices, the idle task allows the Power Policy Manager to enter the lowest allowable power savings.

Semaphores¶

Semaphores are commonly used for task synchronization and mutual exclusions throughout TI-RTOS applications. Figure 21. shows the semaphore functionality. Semaphores can be counting semaphores or binary semaphores. Counting semaphores keep track of the number of times the semaphore is posted with Semaphore_post(). When a group of resources are shared between tasks, this function is useful. Such tasks might call Semaphore_pend() to see if a resource is available before using one. Binary semaphores can have only two states: available (count = 1) and unavailable (count = 0). Binary semaphores can be used to share a single resource between tasks or for a basic-signaling mechanism where the semaphore can be posted multiple times. Binary semaphores do not keep track of the count; they track only whether the semaphore has been posted.

Figure 21. Semaphore Functionality

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

bool isSuccessful;
uint32_t timeout = 1000 * (1000/Clock_tickPeriod);

/* Pend (approximately) up to 1 second */
isSuccessful = Semaphore_pend(sem, timeoutInTicks);

if (isSuccessful)
{
    System_printf("Semaphore was posted");
}
else
{
    System_printf("Semaphore timed out");
}

1

Semaphore_post(sem);

Event¶

Semaphores themselves provide rudimentary synchronization between threads. There are cases just the Semaphore itself is enough to understand on what process needs to be triggered. Often however, a specific causes for the synchronization need to be passed across threads as well. To help accomplish this, one can utilize the TI-RTOS Event module. Events are similar to Semaphores in a sense that each instance of an event object actually contains a Semaphore. The added advantage of using Events lie in the fact that tasks can be notified of specific events in a thread-safe manner.

1
2
3
4
5
6
7
8
9

Event_Handle event;
Event_Params eventParams;
Event_Struct structEvent; /* Memory allocated at build time */

Event_Params_init(&eventParams);
Event_construct(&structEvent, 0, &eventParams);

/* It's optional to store the handle */
event = Event_handle(&structEvent);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

#define START_ADVERTISING_EVT         Event_Id_00
#define START_CONN_UPDATE_EVT         Event_Id_01
#define CONN_PARAM_TIMEOUT_EVT        Event_Id_02

void TaskFxn(..)
{
    /* Local copy of events that have been posted */
    uint32_t events;

    while(1)
    {
        /* Wait for an event to be posted */
        events = Event_pend(event,
                            Event_Id_NONE,
                            START_ADVERTISING_EVT |
                            START_CONN_UPDATE_EVT |
                            CONN_PARAM_TIMEOUT_EVT,
                            BIOS_WAIT_FOREVER);

        if (events & START_ADVERTISING_EVT)
        {
            /* Process this event */
        }

        if (events & START_CONN_UPDATE_EVT)
        {
            /* Process this event */
        }

        if (events & CONN_PARAM_TIMEOUT_EVT)
        {
            /* Process this event */
        }
    }
}

1
2
3
4
5
6
7
8

#define START_ADVERTISING_EVT         Event_Id_00
#define START_CONN_UPDATE_EVT         Event_Id_01
#define CONN_PARAM_TIMEOUT_EVT        Event_Id_02

void SwiFxn(UArg arg)
{
    Event_post(event, START_ADVERTISING_EVT);
}

Queues¶

Queues let applications process messages in a first in, first out (FIFO) order. A project may use a queue to manage internal events coming from application profiles or another task. Clocks must be used when an event must be processed in a time-critical manner. Queues are more useful for message passing across various thread contexts.

The Queue module provides a unidirectional method of message passing between threads using a FIFO. In Figure 22. a queue is configured for unidirectional communication from task A to task B. Task A pushes messages into the queue and task B pops messages from the queue in order. Figure 22. shows the queue messaging process.

Figure 22. Queue Messaging Process

The TI-RTOS Queue functions have been abstracted into functions in the util.c file. See the Queue module in the TI-RTOS Kernel User Guide for the underlying functions. These utility functions combine the Queue module with the ability to notify the recipient task of an available message through TI-RTOS Event Module.

In CC2640R2F software, the event used for this process is the same event that the given task uses for task synchronization through ICall. For an example of this, see the SimpleBLECentral_enqueueMsg() function. Queues are commonly used to limit the processing time of application callbacks in the context of the higher priority threads. In this manner, the higher priority thread queues a message to the application to process later instead of immediate processing in its own context.

The Util module contains a set of abstracted TI-RTOS Queue functions as shown here:

• Util_constructQueue() creates a queue.
• Util_enqueueMsg() puts items into the queue.
• Util_dequeueMsg() gets items from the queue.

1
2
3
4

void SimpleBLECentral_keyChangeHandler(uint8 keys)
{
  SimpleBLECentral_enqueueMsg(SBC_KEY_CHANGE_EVT, keys, NULL);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

static uint8_t SimpleBLECentral_enqueueMsg(uint8_t event, uint8_t state, uint8_t *pData)
{
  sbcEvt_t *pMsg = ICall_malloc(sizeof(sbcEvt_t));

  // Create dynamic pointer to message.
  if (pMsg)
  {
    pMsg->hdr.event = event;
    pMsg->hdr.state = state;
    pMsg->pData = pData;

    // Enqueue the message.
    return Util_enqueueMsg(appMsgQueue, sem, (uint8_t *)pMsg);
  }

  return FALSE;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// If TI-RTOS queue is not empty, process app message
while (!Queue_empty(appMsgQueue))
{
  sbcEvt_t *pMsg = (sbcEvt_t *)Util_dequeueMsg(appMsgQueue);
  if (pMsg)
  {
    // Process message
    SimpleBLECentral_processAppMsg(pMsg);

    // Free the space from the message
    ICall_free(pMsg);
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

static void SimpleBLECentral_processAppMsg(sbcEvt_t *pMsg)
{
  switch (pMsg->hdr.event)
  {
    case SBC_KEY_CHANGE_EVT:
      SimpleBLECentral_handleKeys(0, pMsg->hdr.state);
      break;
    //...
  }
}

Initializing a Task¶

When a task is initialized, it has its own runtime stack for storing local variables as well as further nesting of function calls. All tasks executing within a single program share a common set of global variables, accessed according to the standard rules of scope for C functions. This set of memory is the context of the task. The following is an example of the application task being constructed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

#include <xdc/std.h>
#include <ti/sysbios/BIOS.h>
#include <ti/sysbios/knl/Task.h>

/* Task's stack */
uint8_t sbcTaskStack[TASK_STACK_SIZE];

/* Task object (to be constructed) */
Task_Struct task0;

/* Task function */
void taskFunction(UArg arg0, UArg arg1)
{
    /* Local variables. Variables here go onto task stack!! */

    /* Run one-time code when task starts */

    while (1) /* Run loop forever (unless terminated) */
    {
        /*
         * Block on a signal or for a duration. Examples:
         *  ``Sempahore_pend()``
         *  ``Event_pend()``
         *  ``Task_sleep()``
         *
         * "Process data"
         */
    }
}

int main() {

    Task_Params taskParams;

    // Configure task
    Task_Params_init(&taskParams);
    taskParams.stack = sbcTaskStack;
    taskParams.stackSize = TASK_STACK_SIZE;
    taskParams.priority = TASK_PRIORITY;

    Task_construct(&task0, taskFunction, &taskParams, NULL);

    BIOS_start();
}

The task creation is done in the main() function, before the TI-RTOS Kernel’s scheduler is started by BIOS_start(). The task executes at its assigned priority level after the scheduler is started.

TI recommends using an existing application task for application-specific processing. When adding an additional task to the application project, the priority of the task must be assigned a priority within the TI-RTOS priority-level range, defined in the TI-RTOS configuration file (.cfg).

Task.numPriorities = 6;

Do not add a task with a priority equal to or higher than the Bluetooth low energy protocol stack task and related supporting tasks (for example, the GapRole task). See Standard Project Task Hierarchy for details on the system task hierarchy.

Ensure the task has a minimum task stack size of 512 bytes of predefined memory. At a minimum, each stack must be large enough to handle normal subroutine calls and one task preemption context. A task preemption context is the context that is saved when one task preempts another as a result of an interrupt thread readying a higher priority task. Using the TI-RTOS profiling tools of the IDE, the task can be analyzed to determine the peak task stack usage.

A Task Function¶

When a task is initialized, a function pointer to a task function is passed to the Task_construct function. When the task first gets a chance to process, this is the function which the TI-RTOS runs. Listing 13. shows the general topology of this task function.

In typical use cases, the task spends most of its time in the blocked state, where it calls a _pend() API such as Semaphore_pend(). Often, high priority threads such as Hwis or Swis unblock the task with a _post() API such as Semaphore_post().

Functional Example¶

The following example was taken from the simple_peripheral project in BLE-Stack 3.00.01.

Step 1 in Triggering clock objects constructs the Clock object via Util_constructClock(). After the example entered a connected state, it will then start the clock object via a Util_startClock().

// Clock instances for internal periodic events.
static Clock_Struct periodicClock;

// Create one-shot clocks for internal periodic events.
Util_constructClock(&periodicClock, SimpleBLEPeripheral_clockHandler,
    SBP_PERIODIC_EVT_PERIOD, 0, false, SBP_PERIODIC_EVT);

Step 2 in Triggering clock objects, after the Clock object’s timer expired, it will execute SimpleBLEPeripheral_clockHandler() within a Swi context. As this call cannot be blocked and blocks all Tasks, it is kept short by invoking an Event_post(SBP_PERIODIC_EVT) for post processing in simple_peripheral.

static void SimpleBLEPeripheral_clockHandler(UArg arg)
{
    /* arg is passed in from Clock_construct() */
    Event_post(events, arg);
}

Step 3 in Triggering clock objects, the simple_peripheral task is unblocked due the Event_post(SBP_PERIODIC_EVT), where it proceeds to invoke the SimpleBLEPeripheral_performPeriodicTask() function. Afterwards, to restart the periodic execution of this function, it will restart the periodicClock Clock object.

if (events & SBP_PERIODIC_EVT)
{
  // Perform periodic application task
  SimpleBLEPeripheral_performPeriodicTask();

  Util_startClock(&periodicClock);
}

Adding a Driver¶

Some of the drivers are added to the project as source files in their respective folder under the Drivers folder in the project workspace, as shown in Figure 26.

Figure 26. Drivers Folder

The driver source files can be found in their respective folder at $TI_RTOS_DRIVERS_BASE$\ti\drivers.

The $TI_RTOS_DRIVERS_BASE$ argument variable refers to the installation location and can be viewed in IAR Tools\ Configure Custom Argument Variables menu. For CCS, the corresponding path variables are defined in the Project Options\ Resource\Linked Resources, Path Variables tab.

The ECC and TRNG drivers, for example, are part of the BLE-Stack, not the TIRTOS, and they are located at <SDK_INSTALL_DIR>\source\ti\blestack\common\cc26xx\ecc and <SDK_INSTALL_DIR>\source\ti\blestack\hal\src\target\_common respectively.

To add a driver to a project, include the C and include file of the respective driver in the application file (or files) where the driver APIs are referenced.

For example, to add the PIN driver for reading or controlling an output I/O pin, add the following:

#include <ti/drivers/pin/PINCC26XX.h>

Also add the following TI-RTOS driver files to the project under the Drivers\PIN folder:

• PINCC26XX.c
• PINCC26XX.h
• PIN.h

This is described in more detail in the following sections.

Board File¶

The board file sets the parameters of the fixed driver configuration for a specific board configuration, such as configuring the GPIO table for the PIN driver or defining which pins are allocated to the I2C, SPI, or UART driver.

See the TI Provided Board Files section for more information on board files and how to switch between TI EMs and LPs or port to custom hardware.

Available Drivers¶

This section describes each available driver and provides a basic example of adding the driver to the simple_peripheral project. For more detailed information on each driver, see the TI-RTOS API Reference.

Flash Memory Map¶

This section describes the flash memory map at the system level for split image project configurations. As Figure 27. shows, the application linker file point to symbols with a solid arrow and the stack linker file point to symbols with a dashed arrow.

Figure 27. System Flash Map

Table 8. summarizes the Flash System Map definitions from Figure 27. and provides the associated linker definitions or symbols that can be found in the respective IDE linker files.

Application and Stack Flash Boundary¶

The application and stack code images are based on the common ICALL_STACK0_ADDR and ICALL_STACK0_START predefined symbols. These values define the hard-coded flash address of the entry function for the stack image: it is essentially the word-aligned flash address of the application-stack project boundary. To ensure proper linking, both the application and stack projects must use the same defined symbols. By default, the linker is configured to allocate unused flash to the application project but can be modified manually or automatically through the frontier tool. For information on using the frontier tool to configure the flash boundary address, see Frontier Tool Operation.

Using Simple NV for Flash Storage¶

The Simple NV (SNV) area of flash is used for storing persistent data, such as encryption keys from bonding or to store custom defined parameters. The protocol stack can be configured to reserve up to two 4kB flash pages for SNV, although valid data is only stored in one active flash page. To minimize the number of erase cycles on the flash, the SNV manager performs compaction on the flash sector (or sectors) when the sector has 80% invalidated data. A compaction is the copying of valid data to a temporary area followed by an erase of the sector where the data was previously stored. Depending on the OSAL_SNV value as described in OSAL_SNV Values, this valid data is then either placed back in the newly erased sector or remains in a new sector. The number of flash sectors allocated to SNV can be configured by setting the OSAL_SNV preprocessor symbol in the stack project. Table 9. lists the valid values that can be configured as well as the corresponding trade-offs.

Other values for OSAL_SNV are invalid. Using less than the maximum value has the net effect of allocating more code space to the application or stack project. SNV can be read from or written to using the following APIs.

uint8 osal_snv_read( osalSnvId_t id, osalSnvLen_t len, void *pBuf)

uint8 osal_snv_write( osalSnvId_t id, osalSnvLen_t len, void *pBuf)

Because SNV is shared with other modules in BLE-Stack 3.00.01 such as the GAP Bond Manager, carefully manage the NV item IDs. By default, the IDs available to the customer are defined in bcomdef.h as shown in Listing 26.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// Device NV Items -    Range 0 - 0x1F
#define BLE_NVID_IRK                    0x02  //!< The Device's IRK
#define BLE_NVID_CSRK                   0x03  //!< The Device's CSRK
#define BLE_NVID_SIGNCOUNTER            0x04  //!< The Device's Sign Counter
#define BLE_LRU_BOND_LIST               0x05  //!< The Device's order of bond indexes in least recently used order

// Bonding NV Items -   Range  0x20 - 0x5F    - This allows for 10 bondings
#define BLE_NVID_GAP_BOND_START         0x20  //!< Start of the GAP Bond Manager's NV IDs
#define BLE_NVID_GAP_BOND_END           0x5f  //!< End of the GAP Bond Manager's NV IDs Range

// GATT Configuration NV Items - Range  0x70 - 0x79 - This must match the number of Bonding entries
#define BLE_NVID_GATT_CFG_START         0x70  //!< Start of the GATT Configuration NV IDs
#define BLE_NVID_GATT_CFG_END           0x79  //!< End of the GATT Configuration NV IDs

// Customer NV Items - Range  0x80 - 0x8F - This must match the number of Bonding entries
#define BLE_NVID_CUST_START             0x80  //!< Start of the Customer's NV IDs
#define BLE_NVID_CUST_END               0x8F  //!< End of the Customer's NV IDs

Listing 27. shows how to read and write an array of bytes from SNV flash:

/*********************************************************************
* GLOBAL VARIABLES
*/
#define BUF_LEN 4
#define SNV_ID_APP 0x80
uint8 buf[BUF_LEN] ={0,};

static void SimpleBLEPeripheral_taskFxn(UArg a0, UArg a1)
{
  // Initialize application
  SimpleBLEPeripheral_init();
  uint8 status = SUCCESS;

  status = osal_snv_read(SNV_ID_APP, BUF_LEN, (uint8 *)buf);
  if(status != SUCCESS)
  {
    Display_print1(dispHandle, 0, 0, "SNV READ FAIL: %d", status);
    //Write first time to initialize SNV ID
    osal_snv_write(SNV_ID_APP, BUF_LEN, (uint8 *)buf);
  }

  //Increment first element of array and write to SNV flash
  buf[0]++;
  status = osal_snv_write(SNV_ID_APP, BUF_LEN, (uint8 *)buf);
  if(status != SUCCESS)
  {
    Display_print1(dispHandle, 0, 0, "SNV WRITE FAIL: %d", status);
  }
  else
  {
    Display_print1(dispHandle, 0, 0, "Num of Resets: %d", buf[0]);
  }

  // Application main loop
  for (;;)
  {
  //...
  }
}

No prior initialization of a NV item ID is required; the OSAL SNV manager initializes the NV ID when first accessed by a successful osal_snv_write() call.

When reading or writing large amounts of data to SNV, TI recommends placing the read/write data in statically (linker) allocated arrays or buffers allocated from the heap. Placing large amounts of data in local arrays may result in a task stack overflow.

By default, osalSnvId_t and osalSnvLen_t are type defined as uint8. To use uint16-type definitions, define the preprocessor symbol OSAL_SNV_UINT16_ID in both the application and stack projects.

Using osal_snv_read and osal_snv_write is only permitted from within a task context. Calling this API is not possible from within Swis or Hwis.

Customer Configuration Area¶

The Customer Configuration Area (CCA) occupies the last page of flash and lets a customer configure various chip and system parameters in the Customer Configuration (CCFG) table . The CCFG table is defined in ccfg_app_ble.c, which can be found in the Startup folder of the application project. The last 88 (sizeof(ccfg_t)) bytes of the CCA sector are reserved by the system for the CCFG table. By default, the linker allocates the unused flash of the CCA sector to the application image for code and data use. The linker can be modified to reserve the entire sector for customer parameter data (for example, board serial number and other identity parameters).

The CCA region is defined linker file of the application by the FLASH_LAST_PAGE symbol. Placement is based on the IDE:

For CCS:

MEMORY
{
    ...
    // CCFG Page, contains .ccfg code section and some application code.
    FLASH_LAST_PAGE (RX) :  origin = FLASH_LAST_PAGE_START, length = FLASH_PAGE_LEN
    ...
}

SECTIONS
{
    ...
    .ccfg           :   >  FLASH_LAST_PAGE (HIGH)
    ...
}

For IAR:

////////////////////////////////////////////////////////////////////////////////
// Memory Regions
////////////////////////////////////////////////////////////////////////////////
...
define region FLASH_LAST_PAGE       = mem:[from(FLASH_SIZE - PAGE_SIZE) to FLASH_SIZE-1];
...
////////////////////////////////////////////////////////////////////////////////
...
// CCFG
place at end of FLASH_LAST_PAGE { readonly section .ccfg };
keep { section .ccfg }

See the CC26xx Technical Reference Manual for details on CCFG fields and related configuration options, including how to set the CCFG to disable access to internal flash memory contents.

RAM Memory Map¶

System Memory Map shows the system memory map for the default simple_peripheral project. This is a summary and the exact memory placement for a given compilation can be found in the simple_peripheral_app.map and simple_peripheral_stack.map files in the output folder in IAR or the FlashROM folder in CCS. In Check System Flash and RAM Usage With Map File, the application linker file contains symbols pointed with a solid arrow and the stack linker file contains symbols pointed with a dashed arrow.

System Memory Map

Figure 28. System Memory Map

Application and Stack RAM Boundary¶

The application and stack RAM memory maps are based on the common ICALL_RAM0_START defined symbol. This value defines the hard-coded RAM boundary for the end of the RAM space of the application and the start of the image of the stack .BSS and .DATA sections. Unlike the flash boundary, elements of the stack project (such as task stacks and heaps) are allocated in the application project. To ensure proper linking, both the application and stack projects must use the same ICALL_RAM0_START value. By default, ICALL_RAM0_START is configured to allocate unused RAM to the application project through the frontier tool. For information on using the frontier tool to configure the RAM boundary address, see Frontier Tool Operation.

System Stack¶

Besides the RTOS and ICall heaps, consider other sections of memory. As described in Tasks, each task has its own runtime stack for context switching. Another runtime stack is used by the RTOS for main(), HWIs, and SWIs. This system stack is allocated in the application linker file to be placed at the end of the RAM of the application.

For IAR, this RTOS system stack is defined by the CSTACK symbol:

////////////////////////////////////////////////////////////////////////////////
// Stack
define symbol STACK_SIZE            = 0x400;
define symbol STACK_START           = RAM_END + 1;
define symbol STACK_END             = STACK_START - STACK_SIZE;
//
define symbol STACK_TOP             = RAM_END + 1;
export symbol STACK_TOP;

// Runtime Stack
define block CSTACK with alignment = 8, size = STACK_SIZE { section .stack };
place at end of RAM { block CSTACK };

In IAR, to change the size of the CSTACK, adjust the STACK_SIZE symbol value in the linker file of the application.

For CCS, the RTOS system stack is defined by the Program.stack parameter in the appBLE.cfg RTOS configuration file:

/* main() and Hwi, Swi stack size */
Program.stack = 1024;

and placed by the linker in the RAM space of the application:

/* Create global constant that points to top of stack */
/* CCS: Change stack size under Project Properties */
__STACK_TOP = __stack + __STACK_SIZE;

Dynamic Memory Allocation¶

The system uses two heaps for dynamic memory allocation. The application designer must understand the use of each heap to maximize the use of available memory.

The RTOS is configured with a small heap in the app_ble.cfg RTOS configuration file:

var HeapMem = xdc.useModule('xdc.runtime.HeapMem');

BIOS.heapSize = 1668;

This heap (HeapMem) is used to initialize RTOS objects and allocate the task runtime stack of the Bluetooth low energy protocol stack. TI chose this size of this heap to meet the system initialization requirements. Due to the small size of this heap, TI does not recommend allocating memory from the RTOS heap for general application use. For more information on the TI-RTOS heap configuration, see the Heap Implementations section of the TI-RTOS SYS/BIOS Kernel User’s Guide.

The application must use a separate heap. The ICall module uses an area of application RAM which can be used by the various tasks. The size of this ICall heap is defined by the HEAPMGR_SIZE preprocessor definition in the application project. Using a non-zero value sets the ICall heap to the specified value, while a HEAPMGR_SIZE value of zero (0) auto sizes the heap to a size equal to the amount of available free RAM not allocated by the linker. By default, the simple_peripheral project uses the auto size feature. Although the ICall heap is defined in the application project, this heap is also shared with the Bluetooth low energy protocol stack. APIs that allocate memory (such as GATT_bm_alloc()) allocate memory from the ICall heap.

To profile the amount of ICall heap used, define the HEAPMGR_METRICS preprocessor symbol in the application project. Refer to Profiling the ICall Heap Manager (heapmgr.h) to determine the size of the ICall heap when the auto heap size feature is enabled.

The following is an example of dynamically allocating a variable length (n) array using the ICall heap:

//define pointer
uint8_t *pArray;
// Create dynamic pointer to array.
if (pArray = (uint8_t*)ICall_malloc(n*sizeof(uint8_t)))
{
//fill up array
}
else
{
//not able to allocate
}

The following is an example of freeing the previous array:

ICall_free(pMsg->payload);

Using the Cache as RAM¶

If your application needs more memory, or if you need more space in SRAM, the cache can be re-purposed as RAM. This will allow the linker to store parts of the compiled application in this section of the RAM. This section will be referred to as the general purpose RAM (GPRAM). This will cause the program to run at a slightly reduced speed, and it will increase the device power consumption in sleep. This is because the GPRAM, contrary to a cache, will have to be powered even when the device is sleeping. The current consumption in standby mode with and without cache retained is listed in the CC2640R2F datasheet.

With the cache re-purposed as RAM, the program will run at a slightly decreased speed. This will cause the device to spend more time when active, which again will give a higher power consumption. How this will affect the device power consumption will depend on application. For some applications the added power consumption will be very small, but for processing intensive application it will be slightly higher. Please verify your application current consumption by using the method described in Measuring Bluetooth Low Energy Power Consumption Application Report (SWRA478).

In order to enable using the cache as RAM, two things need to be done. Firstly, the program must be told to retain the cache/GPRAM when it’s being used. Secondly, the linker must be told to allocate the memory region used as cache to GPRAM, and what parts of code to store in the GPRAM. This is done in the linker command/configuration file. The syntax for the linker command/configuration file is slightly different in CCS and IAR. To read more about the CCS linker command file, see the wiki article Linker Command File Primer. To read more about the IAR linker, see IAR C/C++ Development Guide.

Some of the example projects found in the BLE-Stack 3.00.01 have a Build Configuration that allows using the cache as RAM. This is true for e.g. the multi_role project. In this case, cache as RAM can be enabled by choosing that build configuration. In CCS: Project -> Build Configurations -> Set Active -> FlashROM-CacheAsRAM. In IAR: Project -> Edit Configurations -> FlashROM-CacheAsRAM.

Warning

When changing the build configuration of a project, the project properties/options may reset. Please make sure to make changes to the project predefines etc., after changing the build configuration.

If you want to use the cache as RAM in a project which does not have the CacheAsRAM build configuration, follow these steps:

Note

The steps will be different for CCS users and IAR users. The steps will also differ depending on what example project your project is based on. For the example projects found in the blestack folder, only step 1-5 will be required.

1. In the ccfg file, (called app_ble_ccfg.c or ccfg.c), include the following before #include <startup_files/ccfg.c>:

#ifdef CACHE_AS_RAM
  #define SET_CCFG_SIZE_AND_DIS_FLAGS_DIS_GPRAM  0x0 /* Enable GPRAM */
#endif //CACHE_AS_RAM

#include <startup_files/ccfg.c>

2. In main(), add the following code:

Listing 28. Retain cache in sleep.¶

#ifdef CACHE_AS_RAM
// retain cache during standby
Power_setConstraint(PowerCC26XX_SB_VIMS_CACHE_RETAIN);
Power_setConstraint(PowerCC26XX_NEED_FLASH_IN_IDLE);
#else
// Enable iCache pre-fetching
VIMSConfigure(VIMS_BASE, TRUE, TRUE);
// Enable cache
VIMSModeSet(VIMS_BASE, VIMS_MODE_ENABLED);
#endif //CACHE_AS_RAM

Warning

Please make sure your program is not using VIMS while using cache as RAM.

In the same file, include the following files: (In blestack projects, these are already included in main.c.)

/* Power Driver */
#include <ti/drivers/Power.h>
#include <ti/drivers/power/PowerCC26XX.h>
/* Header files required to enable instruction fetch cache */
#include <ti/devices/cc26x0r2/inc/hw_memmap.h>
#include <ti/devices/cc26x0r2/driverlib/vims.h>

3. Go to the compiler predefines and add CACHE_AS_RAM. For the example projects from the blestack folder, this define will bring changes to the executed code in the following files:

• ble_user_config.c
• main.c

4. Go to the linker predefines and add CACHE_AS_RAM=1. This define will bring changes to the executed code in cc26xx_app.cmd/cc26xx_app.icf.

Note

For more information on how to edit compiler and linker symbol settings please see the following sections:

CCS:

• Accessing Preprocessor Symbols
• Accessing Linker Symbols

IAR:

• Accessing Preprocessor Symbols
• Accessing Linker Symbols

5. If your project is based on a blestack project, this will move .bss from SRAM to GPRAM. Other objects can also be moved. See Using the AUX RAM as RAM for an example of this. Rebuild and flash your app project. View the .map file to see what parts of the device memory is occupied. (Alternatively, in CCS: View -> Memory Allocation.)

6. If your project is not based on a blestack project, there are still changes that need to be made in order to use the cache as GPRAM. If your project is using the radio, add 0x00018063 to the radio overrides.

7. The GPRAM memory area must be defined in the linker command file. This syntax is different for the CCS and IAR linker. IAR specific instructions will follow the CCS specific instructions.

In CCS, the linker command file ends with .cmd (e.g. CC2640R2_LAUNCHXL_TIRTOS.cmd).

Listing 29. Under Memory Sizes, add defines for GPRAM start and length.¶

  /*******************************************************************************
   * Memory Sizes
   */
  #define FLASH_BASE   0x00000000
  #define GPRAM_BASE   0x11000000
  #define RAM_BASE     0x20000000
  #define ROM_BASE     0x10000000

  #ifdef CC26X0ROM
    #define FLASH_SIZE 0x00020000
    #define GPRAM_SIZE 0x00002000
    #define RAM_SIZE   0x00005000
    #define ROM_SIZE   0x0001C000
  #endif /* CC26X0ROM */

Listing 30. Add GPRAM under Memory Definitions.¶

  /*******************************************************************************
   * GPRAM
   */

  #ifdef CACHE_AS_RAM
    #define GPRAM_START GPRAM_BASE
    #define GPRAM_END   (GPRAM_START + GPRAM_SIZE - 1)
  #endif /* CACHE_AS_RAM */

Listing 31. In MEMORY{}, allocate room for GPRAM.¶

  #ifdef CACHE_AS_RAM
      GPRAM(RWX) : origin = GPRAM_APP_BASE, length = GPRAM_SIZE
  #endif /* CACHE_AS_RAM */

Listing 32. In SECTIONS{}, move .bss from SRAM to GPRAM.¶

  #ifdef CACHE_AS_RAM
  .bss            :   >  GPRAM
  #endif /* CACHE_AS_RAM */

  #ifndef CACHE_AS_RAM
    .bss            :   > SRAM
  #endif /* CACHE_AS_RAM */

Rebuild your application. This will move .bss from SRAM to GPRAM. Other objects can also be moved. See Using the AUX RAM as RAM for an example of this.

8. In IAR, the linker configuration file ends witth .icf (e.g. CC2640R2_LAUNCHXL_TIRTOS.icf).

Listing 33. Add defines for GPRAM start and length under Memory Definitions.¶

  //////////////////////////////////////////////////////////////////////////////
  // GPRAM
  //
  if ( isdefinedsymbol(CACHE_AS_RAM) )
  {
    define symbol GPRAM_START           = 0x11000000;
    define symbol GPRAM_SIZE            = 8096;
    define symbol GPRAM_END             = GPRAM_START + GPRAM_SIZE;
  }

Listing 34. Under Memory Regions, allocate room for GPRAM.¶

  if ( isdefinedsymbol(CACHE_AS_RAM) )
  {
    define region GPRAM               = mem:[from GPRAM_START to GPRAM_END];
  }

Listing 35. Under Memory Placement, move .bss from SRAM to GPRAM.¶

  if ( isdefinedsymbol(CACHE_AS_RAM) )
  {
    // GPRAM
    define block GPDATA { section .bss };
    place in GPRAM { block GPDATA };
  }

Rebuild your application. This will move .bss from SRAM to GPRAM. Other objects can also be moved. See Using the AUX RAM as RAM for an example of this.

Using the AUX RAM as RAM¶

In order to use the AUX RAM with you application, follow these steps (CCS is first described, then IAR).

1. Make a new define in the linker command file predefines: In CCS; Project -> Properties -> ARM Linker -> Advanced Options -> Command File Preprocessing. In IAR; Options -> Linker -> Config. Add AUX_AS_RAM=1.

2. The linker command/configuration files are somewhat different from CCS to IAR. The instructions for altering the linker configuration file in IAR follows the CCS specific explanations.

• In the linker command file cc26xx_app.cmd, define the AUX_RAM memory area:

  #ifdef AUX_AS_RAM
  #define AUX_RAM_BASE            0x400E0000
  #define AUX_RAM_SIZE            0x800
  #endif /* AUX_AS_RAM */
  

• Create a AUX_RAM memory section in MEMORY{}

#ifdef AUX_AS_RAM
AUX_RAM (RWX) : origin = AUX_RAM_BASE, length = AUX_RAM_SIZE
#endif /* AUX_AS_RAM */

• Add sections of memory or code to AUX_RAM in SECTIONS{}

  Listing 36. Move object files into AUX_RAM. Example from simple_peripheral (cc26xx_app.cmd).¶

  #ifdef AUX_AS_RAM
    reorganized_into_auxram
    {
      simple_peripheral.obj(.data)
      devinfoservice.obj(.data)
      simple_gatt_profile.obj(.data)
      icall.obj(.data)
      board.obj(.bss)
      } > AUX_RAM
  #endif/* AUX_AS_RAM */
  

The .obj files are listed in the FlashROM folder of the app project. They are also listed with size in the .map file. A detailed description of the linker command file and memory sections is given in the wiki article Linker Command File Primer.

If you want more control over what is stored in AUX_RAM, individual variables can be stored there with the #pragma DATA_SECTION command. Please note that this is only possible for global variables.

Listing 37. Move the global display handle variable into a new AUX RAM section called my_section.¶

// Display Interface
#pragma DATA_SECTION(dispHandle, "my_section")
Display_Handle dispHandle = NULL;

Listing 38. In the linker command file (cc26xx_app.cmd), add the section to AUX_RAM.¶

#ifdef AUX_AS_RAM
  reorganized_into_auxram
  {
    simple_peripheral.obj(my_section)
  } > AUX_RAM
#endif /* AUX_AS_RAM */

3. For IAR, open the linker configuration file cc26xx_app.icf. Under Memory Definitions, add

////////////////////////////////////////////////////////////////////////////////
// AUX_RAM
//
if ( isdefinedsymbol(AUX_AS_RAM) )
{
  define symbol AUX_RAM_START        = 0x400E0000;
  define symbol AUX_RAM_SIZE         = 0x800;
  define symbol AUX_RAM_END          = AUX_RAM_START + AUX_RAM_SIZE;
}

• Under Memory Regions, add

  if ( isdefinedsymbol(AUX_AS_RAM) )
  {
    define region AUX_RAM               = mem:[from AUX_RAM_START to AUX_RAM_END];
  }
  

• Under Memory Placement, add

  Listing 39. Move object files into AUX_RAM. Example from simple_peripheral (cc26xx_app.icf).¶

  if ( isdefinedsymbol(AUX_AS_RAM) )
  {
    // AUX_RAM
    define block AUXDATA { section .data object simple_peripheral.o,
                           section .data object devinfoservice.o,
                           section .data object simple_gatt_profile,
                           section .data object icall.o,
                           section .data object board.o};
    place in AUX_RAM { block AUXDATA };
  }
  

The .o-files are listed in the .map file. For more information on the linker configuration file, please see IAR C/C++ Development Guide.

If you want more control over what is stored in AUX_RAM, individual variables can be stored there with the #pragma location command. Please note that this is only possible for global variables.

Listing 40. Move the global display handle variable into a new Cache RAM section called my_section.¶

// Display Interface
#pragma location="my_section"
Display_Handle dispHandle = NULL;

Listing 41. In the linker configuration file (cc26xx_app.cmd), add the section to AUX_RAM.¶

if ( isdefinedsymbol(AUX_AS_RAM) )
{
  // AUX_RAM
  define block AUXDATA { section my_section object simple_peripheral.o };
  place in AUX_RAM { block AUXDATA };
}

Frontier Tool Operation¶

The frontier tool (frontier.exe) is invoked as a CCS or IAR IDE post-build operation of the stack project. If an adjustment to the RAM or flash boundary is required, the frontier tool updates the boundary linker configuration and C definition files listed below. To incorporate the updated configuration values, perform a Project -> Rebuild All on the application project. The stack project must build and link correctly before the application can be rebuilt.

Each project in the SDK has a set of configuration files that the linker and compiler of the IDE use to set or adjust the respective flash and RAM values. These configuration files are shared between the application and stack workspaces, and are stored at the following location:

<SDK_INSTALL_DIR>\examples\rtos\<EVAL_BOARD>\blestack\<PROJECT>\tirtos\<IDE>\config

Where <EVAL_BOARD> is the evaluation platform, <PROJECT> is the sample application (for example, simple_peripheral), and <IDE> is either IAR or CCS.

For example, the simple_peripheral sample application running on the CC2640R2F LaunchPad, the boundary config files are located at the following paths:

CCS: <SDK_INSTALL_DIR>\examples\rtos\CC2640R2_LAUNCHXL\blestack\simple_peripheral\tirtos\ccs\config

IAR: <SDK_INSTALL_DIR>\examples\rtos\CC2640R2_LAUNCHXL\blestack\simple_peripheral\tirtos\iar\config

The following are the boundary config files:

• Boundary linker configuration file: iar_boundary.xcl [IAR] or ccs_linker_defines.cmd [CCS]. Defines the boundary addresses for the linker. This file is in the TOOLS IDE folder and is updated by the frontier tool when an adjustment is required.
• Boundary C definition file: iar_boundary.bdef [IAR] or ccs_compiler_defines.bcfg [CCS]. Defines the boundary addresses for the compiler. This file is in the TOOLS IDE folder and is updated by the frontier tool when an adjustment is required.