Mistake on this page?
Report an issue in GitHub or email us

RTOS overview

The Arm Mbed RTOS is a C++ wrapper over the Keil RTX code. For more information about Keil RTX, check the Keil CMSIS-RTOS tutorial and the element14 introduction to Keil RTX. You can use these resources as a general introduction to RTOS principles; it is important to be familiar with the concepts behind an RTOS in order to understand this guide.

The code of the Mbed RTOS can be found in the mbed-os repository, in the RTOS subdirectory. See the Doxygen for more information.

SysTick

System tick timer (SysTick) is a standard timer available on most Cortex-M cores. Its main purpose is to raise an interrupt with set frequency (usually 1ms). You can use it to perform any task in the system, but for platforms using RTOS, including Mbed OS, it provides an interval for the OS for counting the time and scheduling tasks.

Mbed OS uses default SysTick source for most targets, but you can override that using the Tick API that CMSIS-RTOS2 provides. In which case you'll need to provide your own source of the interrupts.

RTOS APIs

The RTOS APIs handle creation and destruction of threads in Arm Mbed OS 5, as well as mechanisms for safe interthread communication. Threads are a core component of Mbed OS 5 (even your main function starts in a thread of its own), so understanding how to work with them is an important part of developing applications for Mbed OS 5.

  • Thread: The class that allows defining, creating and controlling parallel tasks.
  • Mutex: The class used to synchronize the execution of threads.
  • Semaphore: The class that manages thread access to a pool of shared resources of a certain type.
  • Queue: The class that allows you to queue pointers to data from producer threads to consumer threads.
  • MemoryPool: This class that you can use to define and manage fixed-size memory pools
  • Mail: The API that provides a queue combined with a memory pool for allocating messages.
  • RtosTimer: A deprecated class used to control timer functions in the system.
  • EventFlags: An event channel that provides a generic way of notifying other threads about conditions or events.
  • Event: The queue to store events, extract them and excute them later.
Default timeouts

The Mbed RTOS API has made the choice of defaulting to 0 timeout (no wait) for the producer methods, and osWaitForever (infinite wait) for the consumer methods.

A typical scenario for a producer could be a peripheral triggering an interrupt to notify an event; in the corresponding interrupt service routine you cannot wait (this would deadlock the entire system). On the other side, the consumer could be a background thread waiting for events; in this case the desired default behaviour is not using CPU cycles until this event is produced, hence the osWaitForever.

Warning: No wait in ISR
When calling an RTOS object method in an ISR, all the timeout parameters must be set to 0 (no wait); waiting in ISR is not allowed.

The main() function

The function main is a special thread function that is started at system initialization and has the initial priority osPriorityNormal; it is the first thread the RTOS schedules.

A Thread can be in the following states:

  • Running: The currently running thread. Only one thread at a time can be in this state.
  • Ready: Threads that are ready to run. Once the running thread has terminated or is waiting, the ready thread with the highest priority becomes the running thread.
  • Waiting: Threads that are waiting for an event to occur.
  • Inactive: Threads that are not created or terminated. These threads typically consume no system resources.

Signals

Each Thread can wait for signals and be notified of events:

#include "mbed.h"

Thread thread;
DigitalOut led(LED1);

void led_thread() {
    while (true) {
        // Signal flags that are reported as event are automatically cleared.
        Thread::signal_wait(0x1);
        led = !led;
    }
}

int main (void) {
    thread.start(callback(led_thread));

    while (true) {
        wait(1);
        thread.signal_set(0x1);
    }
}

Status and error codes

The CMSIS-RTOS functions will return the following statuses:

  • osOK: function completed; no event occurred.
  • osEventSignal: function completed; signal event occurred.
  • osEventMessage: function completed; message event occurred.
  • osEventMail: function completed; mail event occurred.
  • osEventTimeout: function completed; timeout occurred.
  • osErrorParameter: a mandatory parameter was missing or specified an incorrect object.
  • osErrorResource: a specified resource was not available.
  • osErrorTimeoutResource: a specified resource was not available within the timeout period.
  • osErrorISR: the function cannot be called from interrupt service routines (ISR).
  • osErrorISRRecursive: function called multiple times from ISR with same object.
  • osErrorPriority: system cannot determine priority or thread has illegal priority.
  • osErrorNoMemory: system is out of memory; it was impossible to allocate or reserve memory for the operation.
  • osErrorValue: value of a parameter is out of range.
  • osErrorOS: unspecified RTOS error - runtime error but no other error message fits.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.