TI-RTOS Overview¶

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’, Swis’ 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 19. to illustrate such a use-case.

Figure 19. 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 20. 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 20. 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 rudimentry 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 acutally 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 21. 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 21. shows the queue messaging process.

Figure 21. 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 later processing instead of immediate processing in its own context.

The Util modules 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

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 15. 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.00.

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 25.

Figure 25. 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>\examples\rtos\CC2640R2_LAUNCHXL\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.

The board files for the CC2640R2 Launchpad are in the following path: <SDK_INSTALL_DIR>\examples\rtos\CC2640R2_LAUNCHXL\blestack\target\<Board_Type>

<Board_Type> is the actual device. To view the actual path to the board files, see the following:

• IAR: Tools→ Configure Custom Argument Variables
• CCS: Project Options→ Resources→ Linked Resources, Path Variables tab

In the path above, the <Board_Type> is selected based on a preprocessor symbol in the application project.

The top-level board file (board.c) then uses this symbol to include the correct board file into the project. This top-level board file can be found at <SDK_INSTALL_DIR>\examples\rtos\CC2640R2_LAUNCHXL\blestack\target\board.c, and is located under the Startup folder in the project workspace:

The board file links in another gateway board file located at <SDK_INSTALL_DIR>\examples\rtos\CC2640R2_LAUNCHXL\blestack\target\<board_type>, which finally links in the actual board file from <SDK_INSTALL_DIR>\source\ti\boards\<board_type>.

Board Level Drivers¶

There are also several board driver files which are a layer of abstraction on top of TI-RTOS drivers, to function for a specific board, for example Board_key.c. If desired, these files can be adapted to work for a custom board.

Creating a Custom Board File¶

A custom board file must be created to design a project for a custom hardware board. TI recommends starting with an existing board file and modifying it as needed. The easiest way to add a custom board file to a project is to replace the top-level board file. If flexibility is desired to switch back to an included board file, the linking scheme defined in Adding a Driver should be used.

At minimum, the board file must contain a PIN_Config structure that places all configured and unused pins in a default, safe state and defines the state when the pin is used. This structure is used to initialize the pins in main() as described in Pre-main initialization. The board schematic layout must match the pin table for the custom board file Improper pin configurations can lead to run-time exceptions:

PIN_init(BoardGpioInitTable);

See the PIN driver documentation for more information on configuring this table.

Available Drivers¶

This section describes each available driver and provide 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.

Using 32-kHz Crystal-Less Mode¶

BLE-Stack 3.00.00 includes support for operating the CC2640R2F in a 32-kHz crystal-less mode for peripheral and broadcaster (beacon) configurations. By using the internal low-frequency RC oscillator (RCOSC_LF), the 32-kHz crystal can be removed from the board layout.

There are a few steps that must be taken to enable this feature. For any peripheral project, the following change is require for IAR. For CCS user, please see the Running Bluetooth Low Energy on CC2640 Without 32 kHz Crystal for the needed steps to enable RCOSC_LF in your project. You will find more detail regarding this feature in the aforementioned application note.

1. Include rcosc_calibration.c, rcosc_calibration.h and ccfg_app_ble_rcosc.c files which locate at <SDK_INSTALL_DIR>\examples\tos\CC2640R2_LAUNCHXL\ble\common\cc26xx\rcosc

2. Exclude ccfg_app_ble.c from build.

3. Add USE_RCOSC to Defined symbols.

4. Add the following code to your peripheralproject.c

   Listing 23. RCOSC calibration include¶

   #ifdef USE_RCOSC
   #include "rcosc_calibration.h"
   #endif //USE_RCOSC
   

5. Add the following code to your peripheralproject_init function in peripheralproject.c

   Listing 24. RCOSC calibration enable¶

   #ifdef USE_RCOSC
   RCOSC_enableCalibration();
   #endif // USE_RCOSC
   

6. If using a custom board file, enable the RCOSC in the power policy. The board files included with the BLE-Stack:

   Listing 25. Power driver configuration¶

   PowerCC26XX_Config PowerCC26XX_config = {
     .policyInitFxn     = NULL,
     .policyFxn         = &PowerCC26XX_standbyPolicy,
     .calibrateFxn      = &PowerCC26XX_calibrate,
     .enablePolicy      = TRUE,
     .calibrateRCOSC_LF = TRUE,
     .calibrateRCOSC_HF = TRUE,
   };
   

7. Constrain the temperature variation to be less than 1°C/sec. If the temperature is to change faster than 1°C/sec, then a short calibration interval must be used. Calibration interval can be tuned in rcosc_calibration.h

   Listing 26. RCOSCLF calibration interval¶

   // 1000 ms
   #define RCOSC_CALIBRATION_PERIOD   1000