You are viewing an older revision! See the latest version
RTOS
RTOS
- mbed RTOS
- CMSIS RTOS
The mbed RTOS API is a simple C++ encapsulation of the CMSIS RTOS C API.
RTOS Library URL: http://mbed.org/projects/libraries-testing/svn/rtos
Thread¶
The Thread
class allows defining, creating, and controlling thread functions in the system. The function main
is a special thread function that is started at system initialization and has the initial priority osPriorityNormal
.
[Not converted]
main
The main
function is already the first thread scheduled by the rtos.
Mutex¶
A Mutex
is used to synchronize the execution of threads: for example to protect the access to a shared resource.
ISR
The Mutex
methods cannot be called from interrupt service routines (ISR).
[Not converted]
C standard library mutexes
The ARM C standard library has already mutexes in place to protect the access to stdio, therefore on the M3 mbed the above example is not necessary. On the contrary, ARM microlib (used on the M0 mbed) does not provide default stdio mutexes making the above example a necessity.
printf in ISR
Because of the mutexes in the ARM C standard library you can not use printf
in ISR!
Semaphore¶
A Semaphore
is particularly useful to manage thread access to a pool of shared resources of a certain type.
[Not converted]
Signals¶
Each Thread
can be notified and wait for signals:
[Not converted]
Queue¶
A Queue
allows you to queue pointers to data from producers threads to consumers threads:
Queue<message_t, 16> queue; message_t *message; queue.put(message); osEvent evt = queue.get(); if (evt.status == osEventMessage) { message_t *message = (message_t*)evt.value.p;
MemoryPool¶
The MemoryPool class is used to define and manage fixed-size memory pools:
MemoryPool<message_t, 16> mpool; message_t *message = mpool.alloc(); mpool.free(message);
[Not converted]
Mail¶
A Mail
works like a queue with the added benefit of providing a memory pool for allocating messages (not only pointers).
[Not converted]
RTOS Timer¶
The RtosTimer
class allows creating and and controlling of timer functions in the system. A timer function is called when a time period expires whereby both on-shot and periodic timers are possible. A timer can be started, restarted, or stopped. Timers are handled in the thread osTimerThread
. Callback functions run under control of this thread and may use CMSIS-RTOS API calls.
[Not converted]
Interrupt Service Routines¶
The same RTOS API can be used in ISR. The only two warnings are:
Mutex
can not be used.- Wait in ISR is not allowed: all the timeouts in method parameters have to be set to 0 (no wait).
[Not converted]
Default Timeouts¶
The mbed rtos API has made the choice of defaulting to 0
timeout (no wait) for the producer methods, and osWaitForever
(infinitive 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.
No wait in ISR
When calling an rtos object method in an ISR all the timeout parameters have to be set to 0 (no wait): waiting in ISR is not allowed.
Stack Configuration¶
The stack configuration is very dependent from the underling CMSIS-RTOS implementation.
As first reference implementation we are using RTX. One of the limitation of the RTX implementation is that it requires to statically configure the maximum number of threads and the size of the memory pool for their stacks.
Our initial RTX configuration choices are likely to change in response to the mbed users feedback:
mbed NXP LPC11U24 | mbed NXP LPC1768 | |
---|---|---|
Max number of user threads + (timer) | 3 + (1) | 7 + (1) |
Default stack size in bytes | 0.5 Kb | 1 Kb |
RAM Usage
Importing the rtos library you will immediately consume 25% of the available RAM on your mbed for stack usage.
configuration
We will soon release the sources of our current RTX implementation and you will be able to edit the configuration as you like.
Additionally, in the future, for the mbed RTOS, we will favour implementations that do not require the editing of a configuration file to specify the maximum number of threads.
The current stack configuration is a temporary implementation detail.
Status and Error Codes¶
The Status and Error Codes section lists all the return values that the CMSIS-RTOS functions will return:
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
: parameter error: a mandatory parameter was missing or specified an incorrect object.osErrorResource
: resource not available: a specified resource was not available.osErrorTimeoutResource
: resource not available within given time: a specified resource was not available within the timeout period.osErrorISR
: not allowed in ISR context: the function cannot be called from interrupt service routines.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: run-time error but no other error message fits.
osEvent¶
The osEvent
data structure is returned by get
methods of Queue
and Mail
objects.
This data structure contains both an error code and a pointer to the actual data:
osEvent
* status [osStatus ]: status code (event or error information) union: either { * value * v [uint32_t ]: message as 32-bit value * p [void * ]: message or mail as void pointer } or { * def * mail_id [osMailQId ]: mail id obtained by osMailCreate * message_id [osMessageQId]: message id obtained by osMessageCreate }