Introduction

This introduction lab introduces the concepts of Tasks, Hwi, Semaphores as well as the PIN driver step by step using TI-RTOS on the CC26xx.

Prerequisites

Software

• CCS 6.1 or later
• TI-RTOS 2.20.01.08 or later
  • Note that the version of TI-RTOS bundled with the TI BLE SDK will work.

Hardware

• 1x CC2650EM Evaluation Module
• 1x SmartRF06 Evaluation Board

Or,

• 1x CC2650ST SensorTag
• 1x CC-DEVPACK-DEBUG

Or,

• 1x CC2650 Launchpad

Getting started

Making sure it works

Start by making sure the kit is properly assembled, either with the EM placed on the SmartRF06 board and turned ON, or the Debug Devpack attached to the SensorTag. Ensure that the board is connected to the PC.

Open Code Composer Studio and import the project.

• Open the Resource Explorer by going to View → Resource Explorer (Examples)
• Open up SimpleLink Academy → TI-RTOS → Projects
• Select Lab 1 for the platform you are using.
• Press the import button on the right side

To test that the software and hardware pre-requisites are fulfilled we are going to try to build and debug the project before going to the first task.

• Our first mission is to build the imported project. Select the project in Project Explorer and choose Project → Build All from the menu.

• When the project is built, we are going to make sure that the hardware and debugger work. To start debugging, press Run → Debug, or press F11.

• When the download is finished, press F8 or the green play button to run.

• After a few seconds you should see LED1 toggling on and off every second. If you see LED1 blink then everything works and you may continue with the lab.

Orienting ourselves in the code

The Lab 1 example comes preconfigured with one TI-RTOS Task already constructed in main(). This task is set up to use the workTaskFunc function as the task function, which in turn uses the PIN Driver to toggle a led.

The task is created using the Task_construct in the main function. The main function also initializes the hardware.

In the main() function, after BIOS_start() is called, the main function will not progress further, but instead give control to the TI-RTOS scheduler which will call the Task functions of the tasks that are constructed. For example workTaskFunc. Normally, task functions will enter an infinite loop and never return, letting TI-RTOS switch to higher priority tasks or temporarliy suspend the current task.

Task 0 - Basic RTOS debugging

First we are going to take a look at some of the built in features of CCS which can aid in the development of firmware running on TI-RTOS, and also give a better understanding of the multitasking.

RTOS Object View

The RTOS Object View, or ROV for short can be used to get a snapshot of the whole RTOS. By default the information is only updated via JTAG when the target is halted. First we are going to halt the code as we are toggling the led.

• Put a breakpoint in the workTaskFunc on the doWork line
  • Do this by double clicking on the area on the left of the line number.
• Run so you hit that breakpoint. Next open the ROV by going to Tools → RTOS Object View (ROV). This will open up a new tab where you can see a lot of information about RTOS objects when you have Instrumentation enabled.

What we are looking for is the Task module's Details tab.

This view shows which task is currently running on the system, what tasks are blocked as well as what tasks are ready to run. We can see that the workTaskFunc is currently running and we can also see that the stack usage for the task has peaked at 112 of 256 bytes so far, so no risk of stack overflow yet!

Execution graph

While the ROV is handy to get a snapshot view over the current state of the system it is not possible to get any information about the state of the system over time. For this we use the Execution graph.

First, before we start up the execution graph, make sure that the application has been running for a short while. After the LED has had time to blink a few times, press Halt/Suspend/Pause button to pause the execution of the program.

Next, open the Execution Analysis menu by going to Tools → RTOS Analyzer → Execution Analysis.

Select only the Execution Graph in the next window, leave everything else as it was and press Start.

In the new Execution Graph tab, expand Cortex_M3_0.*OS to see that Task.workTaskFunc has been executing! In fact, it's the only task executing. The Idle task has not gotten any time at all during the execution of the program. This is usually a sign that one task is hogging all system resources and is in most cases because of a bug.

Task 1 - Sleeping well

After looking at the Execution Graph, we can see that we have a problem with one of our tasks hogging all CPU resources. Let's take a look at our workTaskFunc.

void doWork(void)
{
    PIN_setOutputValue(pinHandle, Board_LED1, 1);
    FakeBlockingWork(); /* Pretend to do something useful but time-consuming */
    PIN_setOutputValue(pinHandle, Board_LED1, 0);
}

Void workTaskFunc(UArg arg0, UArg arg1)
{
    while (1) {

        /* Do work */
        doWork();

        /* Sleep */
        CPUdelay(24e6);
    }
}

The only thing the task does is execute the doWork function and then goes back to 'sleep', except it never does go to sleep. The CPUdelay function is simply a function which burns CPU cycles in a loop. This is not the correct way to pass time in the RTOS.

One of the easiest ways to pass time in a task is to call Task_sleep(numTicks [tick]). Task_sleep will simply make the current task sleep for as many system ticks as is specified in the argument. The current tick rate of the system is needed in order to know how long you will sleep. This is a constant value available via the Clock_tickPeriod variable. The value is the amount of microseconds per clock tick.

Task 1.1

• Replace the use of CPUdelay to sleep with Task_sleep and use it to sleep for 1000ms (1e6 microseconds).
  • How do you convert an argument in microseconds to an argument in system ticks?
• Let the code run for a while and have another look at the Execution Graph, does it look any different?

Task 2 - Executing urgent work

Next we are going to expand on the original code by monitoring a button and execute a doUrgentWork function. In our system, this will represent the most important work processing the system needs to do. This is more important than the work done by the workTask and should execute as quickly as possible. If you want, pretend it's an emergency brake system, and the button is the sensor.

Setting up the new task

• First copy, paste and rename the workTaskFunc function to create a new task function called urgentWorkTaskFunc.

• Copy, paste and rename the doWork function to doUrgentWork as well as modify the new function to use LED2 instead of LED1.

• Let urgentWorkTaskFunc call doUrgentWork.

• Make doUrgentWork call the macro FakeBlockingFastWork()

• Copy, paste and rename the Task_Struct and the task stack storage as well for urgentTask.

• Construct the new task (copy and rename the parameters and the construction) and set the priority of the new task to 1. Note: Higher priority number means higher priority.

Responding to the button press

• Rewrite urgentWorkTaskFunc so it polls the Board_BUTTON0 pin every 10ms using PIN_getInputValue and executes doUrgentWork when the button is pressed. Note that the button is inverted, so positive value means released.

• Does this work as intended?

• Do a check in the Execution Graph as well by

  • Restarting the program
  • Press BUTTON0 while LED1 is on
  • Wait until LED2 is turned on and off
  • Pause the program and check the graph

• Change priorities so that the urgentWorkTask always gets precedence over workTask

• Look at the Execution Graph again

Task 3 - Reacting to interrupts

Polling is for kids.
     — Unknown Wise Programmer

Adding an interrupt handler

Next we are going to implement a HWI to react to the button press instead of polling. Fortunate for us, the HWI to callback mapping is available in the PIN driver itself. The PIN driver will then in turn set up the interrupt for us and register our callback with the RTOS HWI dispatcher.

Start by adding the following two lines in the main function to enable interrupts and register the callback:

PIN_registerIntCb(pinHandle, pinInterruptHandler);
PIN_setInterrupt(pinHandle, Board_BUTTON0 | PIN_IRQ_NEGEDGE);

Next create the pinInterruptHandler with the following signature:

void pinInterruptHandler(PIN_Handle handle, PIN_Id pinId);

Before commencing the task, we want to change the default configuration of the TI-RTOS so that we can see interrupts in the Execution Graph, by default we can only see Tasks.

• Open up the TI-RTOS .cfg file called flash_debug.cfg in this project, and make sure you have the TI-RTOS tab open, not the source.
• On the right hand side in the Outline panel, select LoggingSetup. Alternatively reach this via System Overview → Logging.
• Under RTOS Execution Analysis, make sure that all boxes are checked (SWI, HWI and Semaphores)

Now, next time the code is compiled, this support will be compiled in as a part of the instrumentation.

Task 3.1

• Comment out the construction of the urgentTask.

• Execute the doUrgentWork from the PIN callback instead.

• Take a look in the Execution Graph now.

• If you press the button while the interrupt is executing, does it execute the work again? Why or why not?

• If you press the button twice while the interrupt is executing, does it execute the work twice more? Why or why not?

Moving the processing out of the HWI

It is often not wise to run extensive processing in interrupt process. This is due to the fact that while in an interrupt, it is by default not possible to react to the same or any other lower priority interrupts until finished. It is possible to mitigate some of this by nesting, but keeping the interrupts short is generally the best approach.

What we should have done above is to signal a task when the HWI is run, and then run the processing in the task. We would like to synchronize the task with the HWI. This is a typical use-case for a Semaphore.

Creating a Semaphore

To use Semaphores, first make sure to include the header:

#include <ti/sysbios/knl/Semaphore.h>

Next, we are going to create this Semaphore statically using the TI-RTOS .cfg file instead of instantiate it statically via the code.

• Open the TI-RTOS .cfg file and make sure the TI-RTOS tab is selected.
• On the right side in the Outline window, select Semaphore
• On the top of the main configuration view, select Instance
• Then create a binary semaphore named urgentWorkSem

Note that the newly created semaphore urgentWorkSem is already available in the global namespace. No need to do anything special to get access to it in the source file.

Using a Semaphore

• Go to the TI-RTOS install directory and open docs/Documentation_Overview_cc13xx_cc26xx.html
• Open up the TI-RTOS Kernel User Guide
• Look up Semaphore under Synchronization Modules in the User's Guide and find out how to post to, and pend on, the Semaphore you just created
• Rewrite the code so that the HWI only post the semaphore to which the urgentWorkTask is pending on
• If you press the button several times, can we handle that now? Why?
• Change the Semaphore to be a counting semaphore
• What about now, does it work?

Execution graph example

In the image below you can see the result of the event logging when all of the above is implemented, and the button is pressed while the workTaskFunc is running.

What you are seeing here:

• workTaskFunc running merrily, pretending to do something useful
• Pin interrupt (Hwi) occurring, which posts a Swi to do deferred processing of the interrupt
• Pin Swi running (via BIOS Scheduler), which calls your pinInterruptHandler which posts to the semaphore (flag icon)
• BIOS Scheduler deciding that the urgentWorkTaskFunc is no longer blocked and has higher priority so should run
• urgentWorkTaskFunc running.

When you have implemented a counting semaphore, you should see the urgentWorkTaskFunc running longer (if you press more), and pending on the semaphore until it's out of produced events.

Note the single button press first, and then several button presses which increase the count on the semaphore. The three flags at the end are easy to see and are Semaphore_pend calls made by the thread to see if it has anything more it should do. Which it does until the last flag, which is where the task becomes blocked on urgentWorkSem and BIOS transfers control to a lower priority task.

Epilogue

This first lab has given a quick hands on in how to use the some of the debugging facilities, two different threads (Tasks, HWI), Semaphores as well as some of the general TI-RTOS core APIs.