TOSThreads Tutorial

This lesson demonstrates how to use the TOSThreads library. You will learn how to do the following:

• Use the nesC API to create and manipulate both static and dynamic threads.
• Use the C API to create and manipulate threads.
• Add TOSThreads support to new system services.

Note: TOSThreads is part of TinyOS 2.1.

Introduction

TOSThreads is an attempt to combine the ease of a threaded programming model with the efficiency of a fully event-based OS. Unlike earlier threads packages designed for TinyOS, TOSThreads offers the following benefits:

1. It supports fully-preemptive application-level threads.
2. It does not need explicit continuation management, such as state variables between corresponding commands and events.
3. It does not violate TinyOS's concurrency model.
4. It requires minimal changes to the existing TinyOS code base. In addition, adding TOSThreads support to a new platform is a fairly easy process.
5. It offers both nesC and C APIs.

In TOSThreads, TinyOS runs inside a single high-priority kernel thread, while the application logic is implemented in user-level threads. User-level threads execute whenever the TinyOS core becomes idle. This approach is a natural extension to the existing TinyOS concurrency model: adding support for long-running computations while preserving the timing-sensitive nature of TinyOS itself.

In this model, application threads access underlying TinyOS services using a kernel API of blocking system calls. The kernel API defines the set of TinyOS services provided to applications, such as radio, collection [TEP119], and so on. Each system call in the API is comprised of a thin blocking wrapper built on top of one of these services. The blocking wrapper is responsible for maintaining states across the non-blocking split-phase operations. TOSThreads allows system developers to re-define the kernel API by appropriately selecting an existing set or implementing their own blocking system call wrappers.

Please refer to TEP134 for more details on the TOSThreads implementation.

The TOSThreads library

At the time of writing, TOSThreads supports the following platforms: telosb, micaZ, and mica2. And, it supports various generic split-phase operations, such as the Read interface and the SplitControl interface, and system services, such as radio, serial, external flash (both Block and Log abstractions), CTP (Collection Tree Protocol), and so on. You can find the code in tinyos-2.x/tos/lib/tosthreads as described below.

TOSThreads system files are located in several subdirectories under tinyos-2.x/tos/lib/tosthreads.

1. chips: Some chip-specific files that shadow tinyos-2.x/tos/chips to add code such as the interrupt postamble.
2. csystem: Contain C API system files and the header file for different system services.
3. interfaces: Contain nesC API interfaces.
4. lib: Shadow some files in tinyos-2.x/tos/lib, and contain the blocking wrapper for CTP.
5. platforms: Shadow some files in tinyos-2.x/tos/platforms.
6. sensorboards: Contain blocking wrappers for telosb's onboard SHT11 sensors, and an universal sensor that generates a sine wave.
7. system: Contain nesC API system files and the blocking wrappers for different system services.
8. types: Define the structs used by TOSThreads system files.

You can find example TOSThreads applications are in tinyos-2.x/apps/tosthreads.

nesC API

Static threads

We will use RadioStress as an example to illustrate manipulating static threads with nesC API. The application creates three threads to stress the radio operations. The nesC version is located in tinyos-2.x/apps/tosthreads/apps/RadioStress. Type make telosb threads to compile.

- RadioStressAppC.nc -

.....
components new ThreadC(300) as RadioStressThread0;	Statically create a thread that has 300-byte stack space
components new BlockingAMSenderC(220) as BlockingAMSender0;	Blocking wrapper for AM Sender (AM ID is 220)
components new BlockingAMReceiverC(220) as BlockingAMReceiver0;	Blocking wrapper for AM Receiver (AM ID is 220)
RadioStressC.RadioStressThread0 -> RadioStressThread0;
RadioStressC.BlockingAMSend0 -> BlockingAMSender0;
RadioStressC.BlockingReceive0 -> BlockingAMReceiver0;
.....

- RadioStressC.nc -

.....
event void Boot.booted() {
call RadioStressThread0.start(NULL);	Singal the thread scheduler to start executing thread's main function with NULL arguments
call RadioStressThread1.start(NULL);
call RadioStressThread2.start(NULL);
}			.....
event void RadioStressThread0.run(void* arg) {	RadioStressThread0 thread's main function
call BlockingAMControl.start();	Start the radio. The thread will be blocked until the operation completes
for(;;) {
if(TOS_NODE_ID == 0) {
call BlockingReceive0.receive(&m0, 5000);	Try to listen for an incoming packet for 5000 ms. The thread is blocked until the operation completes
call Leds.led0Toggle();
}
else {
call BlockingAMSend0.send(!TOS_NODE_ID, &m0, 0);	Send a packet m0 of length 0 byte. The thread is blocked until the operation completes
call Leds.led0Toggle();
}
}
}			.....

The ThreadC component provides a Thread interface for creating and manipulating static threads:

- Thread.nc -

interface Thread {
command error_t start(void* arg);
command error_t stop();
command error_t pause();
command error_t resume();
command error_t sleep(uint32_t milli);
event void run(void* arg);
command error_t join();
}

Calling start() on a thread signals to the TOSThreads thread scheduler that the thread should begin executing (at some time later, the run() event will be signaled). The argument is a pointer to a data structure passed to the thread once it starts executing. Calls to start() return either SUCCESS or FAIL.

Calling stop() on a thread signals to the TOSThreads thread scheduler that the thread should stop executing. Once a thread is stopped it cannot be restarted. Calls to stop() return SUCCESS if a thread was successfully stopped, and FAIL otherwise. stop() MUST NOT be called from within the thread being stopped; it MUST be called from either the TinyOS thread or another application thread.

Calling pause() on a thread signals to the TOSThreads thread scheduler that the thread should be paused. Unlike a stopped thread, a paused thread can be restarted later by calling resume() on it. pause() MUST ONLY be called from within the thread itself that is being paused.

Calling sleep() puts a thread to sleep for the interval specified in its single 'milli' parameter. sleep() MUST ONLY be called from within the thread itself that is being put to sleep. SUCCESS is returned if the thread was successfully put to sleep, FAIL otherwise.

Dynamic threads

Other than running static threads as the example shows, nesC API can also create dynamic threads at run time. The nesC interface for creating and manipulating dynamic threads is DynamicThread:

- DynamicThread.nc -

interface DynamicThread {
command error_t create(tosthread_t* t, void (*start_routine)(void*), void* arg,
void* arg, uint16_t stack_size);
command error_t destroy(tosthread_t* t);
command error_t pause(tosthread_t* t);
command error_t resume(tosthread_t* t);
command error_t sleep(uint32_t milli);
}

Blink_DynamicThreads is an example application that demostrates how to use dynamic threads.

Synchronization primitives

TOSThreads supports the following synchronization primitives:

1. Mutex: The interface file is tinyos-2.x/tos/lib/tosthreads/interfaces/Mutex.nc.
2. Semaphore: This is an implementation of counting semaphore. The interface file is tinyos-2.x/tos/lib/tosthreads/interfaces/Semaphore.nc.
3. Barrier: All threads that call Barrier.block() are paused until v threads have made the block call. The interface file is tinyos-2.x/tos/lib/tosthreads/interfaces/Barrier.nc.
4. Condition variable: The interface file is The interface file is tinyos-2.x/tos/lib/tosthreads/interfaces/ConditionVariable.nc.
5. Blocking reference counter: A thread can wait for the maintained counter to reach count. The interface provides a way for other threads to increment and decrement the maintained counter. The interface is tinyos-2.x/tos/lib/tosthreads/interfaces/ReferenceCounter.nc.

Bounce is an example application that demostrates how to use the barrier synchronization primitive.

Related documentation

• TEP 134: The TOSThreads Thread Library