embOS
Real-Time Operating System User Guide & Reference Manual for embOS-Base and embOS-MPU
Document: UM01001
Software Version: 5.20.0
Document revision: 0

Introduction and Basic Concepts

What is embOS?

embOS is a priority-controlled multitasking system, designed to be used as an embedded operating system for the development of real-time applications for a variety of microcontrollers.

embOS is a high-performance tool that has been optimized for minimal memory consumption in both RAM and ROM, as well as high speed and versatility. Throughout the development process of embOS, the limited resources of microcontrollers have always been kept in mind. The internal structure of the real-time operating system (RTOS) has been optimized in a variety of applications with different customers, to fit the needs of industry. Fully source-compatible implementations of embOS are available for a variety of microcontrollers, making it well worth the time and effort to learn how to structure real-time programs with an RTOS.

embOS is highly modular. This means that only those functions that are required are linked into an application, keeping the ROM size very small. A couple of files are supplied in source code to make sure that you do not loose any flexibility by using embOS libraries and that you can customize the system to fully fit your needs.

The tasks you create can easily and safely communicate with each other using a number of communication mechanisms such as semaphores, mailboxes, and events.

Some features of embOS include:

• Time resolution can be freely selected (default is 1 millisecond).
• Easily accessible time variable.
• Preemptive scheduling:
  Guarantees that of all tasks in READY state the one with the highest priority executes, except for situations in which priority inheritance applies.
• Round-robin scheduling for tasks with identical priorities.
• Preemptions can be disabled for entire tasks or for sections of a program.
• Up to 4,294,967,296 priorities. Every task can have an individual priority, which means that the response of tasks can be precisely defined according to the requirements of the application.
• Unlimited number of tasks, software timers and all other synchronization and communication primitives like event objects, semaphores, mutexes, mailboxes and queues. (limited only by the amount of available memory).
• Size and number of messages can be freely defined when initializing mailboxes.
• Up to 32-bit events for every task.
• Power management.
• Calculation time in which embOS is idle can automatically be spent in power save mode. Power-consumption is minimized.
• Full interrupt support:
  Interrupts may call any function except those that require waiting for data, as well as create, delete or change the priority of a task. Interrupts can wake up or suspend tasks and directly communicate with tasks using all available communication methods (mailboxes, semaphores, events).
• Disabling interrupts for very short periods allows minimal interrupt latency.
• Nested interrupts are permitted.
• embOS has its own, optional interrupt stack.
• Application samples for an easy start.
• Debug build performs runtime checks that catch common programming errors early on.
• Profiling and stack-check may be implemented by choosing specified libraries.
• Monitoring during runtime is available using embOSView via UART, Debug Communications Channel (DCC) and memory read/write, or else via Ethernet.
• Very fast and efficient, yet small code.
• Minimal RAM usage.
• API can be called from assembly, C or C++ code.
• Board support packages (BSP) as source code available.

embOS editions

embOS is the general term for four different embOS editions:

• embOS-Base
• embOS-Ultra
• embOS-MPU
• embOS-Safe

embOS-Base

embOS-Base is a preemptive RTOS designed to be the foundation for developing embedded applications. Now in its 4th decade of continuous use and enhancement, its reliability and performance underpin the firmware in every J-Link and J-Trace.

embOS-Ultra

embOS-Ultra is a revolutionary RTOS using cycle-resolution timing to improve timing and performance and to reduce energy consumption. Using SEGGER’s innovative Cycle-based Scheduling, embOS-Ultra is the first choice for applications requiring ultra low power or extremely high precision. Its time resolution is based on the CPU cycle and provides the highest precision possible. Removing iterative scheduler calls from the kernel reduces the energy consumption significantly.

embOS-MPU

embOS-MPU adds comprehensive memory protection to embOS-Base which tightens the safety of embedded devices. All unprivileged tasks are 100% sandboxed, making devices suitable for any safety-critical application. embOS-MPU uses the hardware’s memory protection unit and additional implemented software mechanisms to prevent one task from affecting the entire system. This guarantees that even if a bug occurs in one task, all other tasks and the operating system itself continue their execution, enhancing both the stability and safety of embedded applications.

embOS-Safe

embOS-Safe is the pre-certified version of embOS-Base, embOS-Ultra and embOS-MPU. embOS-Safe has been certified in accordance with TÜV SÜD Germany. Certification is compliant with IEC 61508 SIL 3, IEC 62304 Class C, and ISO 26262 ASIL D.

embOS ports

embOS is available for many core and compiler combinations. The embOS sources are written in C but a small part is written in assembler and therefore core and compiler specific. Hence, an embOS port is always technically limited to one core or core family and one compiler. An embOS port includes several board support packages for different devices and evaluation boards. Each board support package includes a project for a specific IDE. In most embOS ports the same IDE is used for all board support packages.

Additional documentation

Some embOS aspects are core and compiler specific and explained in a separate embOS manual which is shipped in the according embOS port shipment. For example an embOS port could provide additional core specific API functions which are described in the core and compiler specific manual.

Example Cover of embOS-Base Cortex-M ES Manual

Naming convention

All embOS ports use the same naming convention: embOS_<edition>_<core>_<compiler>. For example: embOS_Base_CortexM_ES, embOS-Base for Cortex-M and Embedded Studio

Version number convention

SEGGER releases new embOS versions with new features and bug fixes. As soon as a new embOS version is released embOS ports are updated to this version.

Generic embOS

Each release of the generic embOS sources has a unique version number:

V<Major>.<Minor>.<Patch>

For example:

V5.20.0

Major: 5
Minor: 20
Patch: 0

Major and minor values are used for new features. The patch value is used for bug fixes only.

embOS Ports

An updated embOS port has the same version number as the used generic embOS sources, plus an additional revision for the port. This is because an embOS port may be updated for changes in the CPU/compiler specific part, while still using the same generic embOS sources. The complete version number for a specific embOS port is defined as:

V<Major>.<Minor>.<Patch>.<Revision>

For example:

V5.20.0.0

Major: 5
Minor: 20
Patch: 0
Revision: 0

Singletasking systems (superloop)

The classic way of designing embedded systems does not use the services of an RTOS, which is also called “superloop design”. Typically, no real time kernel is used, so interrupt service routines (ISRs) are used for the real-time parts of the application and for critical operations (at interrupt level). This type of system is typically used in small, simple systems or if real-time behavior is not critical.

Typically, since no real-time kernel and only one stack is used, both program (ROM) size and RAM size are smaller for simple applications when compared to using an RTOS. Obviously, there are no inter-task synchronization problems with a superloop application. However, superloops can become difficult to maintain if the program becomes too large or uses complex interactions. As sequential processes cannot interrupt themselves, reaction times depend on the execution time of the entire sequence, resulting in a poor real-time behavior.

Advantages & disadvantages

Advantages

• Simple structure (for small applications)
• Low stack usage (only one stack required)

Disadvantages

• No “delay” capability
• Higher power consumption due to the lack of a power save mode in most architectures
• Difficult to maintain as program grows
• Timing of all software components depends on all other software components:
  Small change in one place can have major side effects in other places
• Defeats modular programming
• Real time behavior only with interrupts

Using embOS in superloop applications

In a true superloop application, no tasks are used, hence the biggest advantage of using an RTOS cannot be utilized unless the application is re-written for multitasking. However, even with just one single task, using embOS offers the following advantages:

• Software timers are available
• Power saving: Idle mode can be used
• Future extensions can be put in a separate task

Migrating from superloop to multi-tasking

A common situation is that an application exists for some time and has been designed as a single-task super-loop-application. At some point, the disadvantages of this approach result in a decision to use an RTOS. The typical question now usually is: How do I do this?

The easiest way is to start with one of the sample applications that come with embOS and to add the existing “super-loop code” into one task. At this point, you should also ensure that the stack size of this task is sufficient. Later, additional functionality is added to the software and can be put in one or more additional tasks; the functionality of the super-loop can also be distributed over multiple tasks.

Multitasking systems

In a multitasking system, there are different ways to distribute CPU time among different tasks. This process is called scheduling.

Task switches

There are two types of task switches, also called context switches: Cooperative and preemptive task switches.

A cooperative task switch is performed by the task itself. As its name indicates, it requires the cooperation of the task: it suspends itself by calling a blocking RTOS function, e.g. OS_TASK_Delay() or OS_TASKEVENT_GetBlocked().

A preemptive task switch, on the other hand, is a task switch that is caused externally. For example, a task of higher priority becomes ready for execution and, as a result, the scheduler suspends the current task in favor of that task.

Cooperative multitasking

Cooperative multitasking requires all tasks to cooperate by using blocking functions. A task switch can only take place if the running task blocks itself by calling a blocking function such as OS_TASK_Delay() or OS_MAILBOX_GetBlocked(). This is illustrated in the diagram below.

If tasks in a pure cooperative multi-tasking system do not cooperate, the system “hangs”. This means that other tasks have no chance of being executed by the CPU while the first task is being carried out. Even if an ISR makes a higher-priority task ready to run, the interrupted task will be resumed and completes before the task switch is made.

A pure cooperative multi-tasking system has the disadvantage of longer reaction times when high priority tasks become ready for execution. This makes their usage in embedded real-time systems uncommon.

Preemptive multitasking

An RTOS like embOS operates with preemptive multitasking. The highest-priority task in the READY state always executes as long as the task is not suspended by a call of any blocking operating system function. A high-priority task waiting for an event is signaled READY as soon as the event occurs. The event can be set by an interrupt handler, which then activates the task immediately. Other tasks with lower priority are suspended (preempted) for as long as the high-priority task is executing. Usually, an RTOS utilizes a timer interrupt that interrupts tasks and thereby allows to perform task switches whenever timed task switches are necessary.

Preemptive multitasking may be switched off in sections of a program where task switches are prohibited, known as critical regions. embOS itself will also temporarily disable preemptive task switches during critical operations, which might be performed during the execution of some embOS API functions.

Threads vs. Processes

In this context, a task is a program running on the CPU core of a microcontroller. Without a multitasking kernel (an RTOS), only one task can be executed by the CPU. This is called a single-task system. The RTOS, on the other hand, allows the execution of multiple tasks on a single CPU. All tasks execute as if they completely “owned” the entire CPU. The tasks are scheduled for execution, meaning that the RTOS can activate and deactivate each task according to its priority, with the highest priority task being executed in general.

Threads are tasks that share the same memory layout, hence any two threads can access the same memory locations. If virtual memory is used, the same virtual to physical translation and access rights are used.
With embOS, all tasks are threads: they all have the same memory access rights and translation (in systems with virtual memory).

Processes are tasks with their own memory layout. Two processes cannot normally access the same memory locations. Different processes typically have different access rights and (in case of MMUs) different translation tables. Processes are not supported with the current version of embOS.

Scheduling

There are different algorithms used by schedulers to determine which task to execute. But all schedulers have one thing in common: they distinguish between tasks that are ready to be executed (in the READY state) and other tasks that are suspended for some reason (delay, waiting for mailbox, waiting for semaphore, waiting for event, etc). The scheduler selects one of the tasks in the READY state and activates it (executes the body of this task). The task which is currently executing is referred to as the running task. The main difference between schedulers is the way they distribute computation time between tasks in the READY state.

Priority-controlled scheduling algorithm

In real-world applications, different tasks require different response times. For example, in an application that controls a motor, a keyboard, and a display, the motor usually requires faster reaction time than the keyboard and the display. E.g., even while the display is being updated, the motor needs to be controlled. This renders preemptive multitasking essential. Round-robin might work, but as it cannot guarantee any specific reaction time, a more suitable algorithm should be used.

In priority-controlled scheduling, every task is assigned a priority. Depending on these priorities, a task is chosen for execution according to one simple rule:

This means that every time a task with a priority higher than the running task becomes ready, it becomes the running task, and the previous task gets preempted. However, the scheduler can be switched off in sections of a program where task switches are prohibited, known as critical regions.

embOS uses a priority-controlled scheduling algorithm with round-robin between tasks of identical priority. One hint at this point: round-robin scheduling is a nice feature because you do not need to decide whether one task is more important than another. Tasks with identical priority cannot block each other for longer periods than their time slices. But round-robin scheduling also costs time if two or more tasks of identical priority are ready and no task of higher priority is, because execution constantly switches between the identical-priority tasks. It usually is more efficient to assign distinct priority to each task, thereby avoiding unnecessary task switches.

Round-robin scheduling algorithm

With round-robin scheduling, the scheduler has a list of tasks and, when deactivating the running task, it activates the next task that is in the READY state. Round-robin can be used with either preemptive or cooperative multitasking. It works well if you do not need to guarantee response time. Round-robin scheduling can be illustrated as follows:

The possession of the CPU changes periodically after a predefined execution time among all tasks with the same priority. This time is specified in time slices and may be defined individually for each task.

Priority inversion / priority inheritance

The rule the scheduler obeys is:

Activate the task that has the highest priority of all tasks in the READY state.

But what happens if the highest-priority task is blocked because it is waiting for a resource owned by a lower-priority task? According to the above rule, it would wait until the low-priority task is resumed and releases the resource. Up to this point, everything works as expected. Problems arise when a task with medium priority becomes ready during the execution of the higher prioritized task.

When the higher priority task is suspended waiting for the resource, the task with the medium priority will run until it finishes its work, because it has a higher priority than the low-priority task. In this scenario, a task with medium priority runs in place of the task with high priority. This is known as priority inversion.

The low priority task claims the mutex with OS_MUTEX_LockBlocked(). An interrupt activates the high priority task, which also calls OS_MUTEX_LockBlocked(). Meanwhile a task with medium priority becomes ready and runs when the high priority task is suspended. The task with medium priority eventually calls OS_TASK_Delay() and is therefore suspended. The task with lower priority now continues and calls OS_MUTEX_Unlock() to release the mutex. After the low priority task releases the mutex, the high priority task is activated and claims the mutex.

To avoid this situation, embOS temporarily raises the low-priority task to high priority until it releases the resource. This unblocks the task that originally had the highest priority and can now be resumed. This is known as priority inheritance.

With priority inheritance, the low priority task inherits the priority of the waiting high priority task as long as it holds the mutex. The lower priority task is activated instead of the medium priority task when the high priority task tries to claim the mutex.

Change of task status

A task may be in one of several states at any given time. When a task is created, it is placed into the READY state.

A task in the READY state is activated as soon as there is no other task in the READY state with higher priority. Only one task may be running at a time. If a task with higher priority becomes READY, this higher priority task is activated and the preempted task remains in the READY state.

The running task may be delayed for or until a specified time; in this case it is placed into the WAITING state and the next-highest-priority task in the READY state is activated.

The running task might need to wait for an event (or semaphore, mailbox or queue). If the event has not yet occurred, the task is placed into the waiting state and the next-highest-priority task in the READY state is activated.

A non-existent task is one that is not yet available to embOS; it either has been terminated or was not created at all.

The following illustration shows all possible task states and transitions between them.

How task switching works

A real-time multitasking system lets multiple tasks run like multiple single-task programs, quasi-simultaneously, on a single CPU. A task consists of three parts in the multitasking world:

• The program code, which typically resides in ROM
• A stack, residing in a RAM area that can be accessed by the stack pointer
• A task control block, residing in RAM.

The task’s stack has the same function as in a single-task system: storage of return addresses of function calls, parameters and local variables, and temporary storage of intermediate results and register values. Each task can have a different stack size. More information can be found in chapter Stacks.

The task control block (TCB) is a data structure assigned to a task when it is created. The TCB contains status information for the task, including the stack pointer, task priority, current task status (ready, waiting, reason for suspension) and other management data. Knowledge of the stack pointer allows access to the other registers, which are typically stored (pushed onto) the stack when the task is created and each time it is suspended. This information allows an interrupted task to continue execution exactly where it left off. TCBs are only accessed by the RTOS.

Switching stacks

The following diagram demonstrates the process of switching from one stack to another.

The scheduler deactivates the task to be suspended (Task 0) by saving the processor registers on its stack. It then activates the higher-priority task (Task 1) by loading the stack pointer (SP) and the processor registers from the values stored on Task 1’s stack.

Deactivating a task

The scheduler deactivates the task to be suspended (Task 0) as follows:

1. Save (push) the processor registers on the task’s stack.
2. Save the stack pointer in the Task Control Block.

Activating a task

The scheduler activates the higher-priority task (Task 1) by performing the sequence in reverse order:

1. Load (pop) the stack pointer (SP) from the Task Control Block.
2. Load the processor registers from the values stored on Task 1’s stack.

Polling vs. Event based programming

The easiest way to communicate between different pieces of code is by using global variables. In an application without RTOS you could set a flag in an UART interrupt routine and poll in main() for the flag until it is set.

static int           UartRxFlag;
static unsigned char Data;

void UartRxISR(void) {
  UartRxFlag = 1;
  Data = UART_RX_REGISTER;
}

int main(void) {
  while (1) {
    if (UartRxFlag != 0) {
      printf("Uart: %u", Data);
      UartRxFlag = 0;
    }
  }
  return 0;
}

This has the disadvantage that the CPU cannot execute any other part of the application while it waits for new UART characters.

An RTOS offers the opportunity to implement an event based application. Such an event can be an interrupt. UartRxTask() calls OS_MAILBOX_GetBlocked() and is suspended until a new message is stored in the mailbox. UartRxISR() stores a new message (the received character) in the mailbox with OS_MAILBOX_Put(). Therefore UartRxTask() is executed only when a new UART character is received and does not waste any precious computation time and energy. Additionally the CPU can execute other parts of the application in the meantime.

void UartRxISR(void) {
  unsigned char Data;

  OS_INT_Enter();
  Data = UART_RX_REGISTER;
  OS_MAILBOX_Put(&Mailbox, &Data);
  OS_INT_Leave();
}

void UartRxTask(void) {
  unsigned char c;
  while (1) {
     OS_MAILBOX_GetBlocked(&Mailbox, &c);
     printf("Uart: %u", c);
  }
}

Synchronization and communication primitives

Synchronization primitives

In a multitasking (multithreaded) program, multiple tasks work completely separately. Because they all work in the same application, it will be necessary for them to synchronize with each other. Semaphores, mutexes and readers-write locks are used for task synchronization and to manage resources of any kind.

For details and samples, refer to the chapters Mutexes, Semaphores and Readers-Writer Locks.

Event driven primitives

A task can wait for a particular event without consuming any CPU time. The idea is as simple as it is convincing, there is no sense in polling if we can simply activate a task once the event it is waiting for occurs. This saves processor cycles and energy and ensures that the task can respond to the event without delay. Typical applications for events are those where a task waits for some data, a pressed key, a received command or character, or the pulse of an external real-time clock.

For further details, refer to the chapters Task Events and Event Objects.

Communication primitives

A mailbox is a data buffer managed by the RTOS. It is used for sending a message from a task or an ISR to a task. It works without conflicts even if multiple tasks and interrupts try to access the same mailbox simultaneously. embOS activates any task that is waiting for a message in a mailbox the moment it receives new data and, if necessary, switches to this task.
A queue works in a similar manner, but handles larger messages than mailboxes, and each message may have an individual size.

For more information, refer to the chapters Mailboxes and Queues.

How the OS gains control

Upon CPU reset, the special-function registers are set to their default values. After reset, program execution begins: The PC register is set to the start address defined by the start vector or start address (depending on the CPU). This start address is usually in a startup module shipped with the C compiler, and is sometimes part of the standard library.

The startup code performs the following:

• Loads the stack pointer(s) with the default values, which is for most CPUs the end of the defined stack segment(s)
• Initializes all data segments to their respective values
• Calls the main() function.

The main() function is the part of your program which takes control immediately after the C startup. Normally, embOS works with the standard C startup module without any modification. If there are any changes required, they are documented in the CPU & Compiler Specifics manual of the embOS documentation.

With embOS, the main() function is still part of your application program. Essentially, main() creates one or more tasks and then starts multitasking by calling OS_Start(). From this point, the scheduler controls which task is executed.

Startup_code()
  main()
    OS_Init();
    OS_InitHW();
    OS_TASK_CREATE();
    OS_Start();

The main() function will not be interrupted by any of the created tasks because those tasks execute only following the call to OS_Start(). It is therefore usually recommended to create all or most of your tasks here, as well as your control structures such as mailboxes and semaphores. Good practice is to write software in the form of modules which are (up to a point) reusable. These modules usually have an initialization routine, which creates any required task(s) and control structures. A typical main() function looks similar to the following example:

Example

int main(void) {
  OS_Init();      // Initialize embOS (must be first)
  OS_InitHW();    // Initialize hardware for embOS (in RTOSInit.c)
  // Call Init routines of all program modules which in turn will create
  // the tasks they need ... (Order of creation may be important)
  MODULE1_Init();
  MODULE2_Init();
  MODULE3_Init();
  MODULE4_Init();
  MODULE5_Init();
  OS_Start();     // Start multitasking
  return 0;
}

With the call to OS_Start(), the scheduler starts the highest-priority task created in main(). Note that OS_Start() is called only once during the startup process and does not return.

Valid context for embOS API

Some embOS functions may only be called from specific locations inside your application. We distinguish between main() (before the call of OS_Start()), privileged and unprivileged task, interrupt routine and embOS software timer.
With embOS-Base there are privileged tasks only. With embOS-MPU a task is a unprivileged task after the call to OS_MPU_SwitchToUnprivState().

Example

This table entry says it is allowed to call OS_TASK_Delay() from main() and a privileged/unprivileged task but not from an embOS software timer or an interrupt handler. Please note the differentiation between privileged and unprivileged tasks is relevant only for embOS-MPU. With embOS all tasks are privileged.

Debug check

An embOS debug build will check for violations of these rules and call OS_Error() with an according error code:

Blocking and Non blocking embOS API

Most embOS API comes in three different version: Non blocking, blocking and blocking with a timeout. The embOS API uses a specific naming convention for those API functions. API functions which do not block a task have no suffix. API functions which could block a task have the suffix “Blocked”. API functions which could block a task but have a timeout have the suffix “Timed”.
Blocking API functions (with or without a timeout) must not be called from any context other than a task context.

Non blocking API

Non blocking API functions always return at once, irrespective of the state of the OS object. The return value can be checked in order to find out if e.g. new data is available in a mailbox.

static OS_MAILBOX MyMailbox;
static char Buffer[10];

void Task(void) {
  char r;
  while (1) {
    r = OS_MAILBOX_Get(MyMailbox, Buffer);
    if (r == 0u) {
      // Process message
    }
  }
}

Blocking API

Blocking API functions suspend the task until it is activated again by another embOS API function. The task does not cause any CPU load while it is waiting for the next activation.

static OS_MAILBOX MyMailbox;
static char Buffer[10];

void Task(void) {
  while (1) {
    // Suspend task until a new message is available
    OS_MAILBOX_GetBlocked(MyMailbox, Buffer);
    // Process message
  }
}

Blocking API with timeout

These API functions have an additional timeout. They are blocking until the timeout occurs.

static OS_MAILBOX MyMailbox;
static char Buffer[10];

void Task(void) {
  char r;
  while (1) {
    // Suspend task until a new message is available or the timeout occurs
    r = OS_MAILBOX_GetTimed(MyMailbox, Buffer, 10);
    if (r == 0u) {
      // Process message
    }
  }
}

embOS API with timeout

Usage

The embOS system tick in OS_Global.Time is based on a hardware timer. The hardware timer periodically generates an interrupt which increments OS_Global.Time. embOS API functions like OS_TASK_Delay() and OS_TASKEVENT_GetTimed() expect a timeout value as a parameter. The timeout unit is system ticks.

If for example OS_TASK_Delay(1) was called shortly after the timer interrupt the actual timeout is nearly one system tick.

But if OS_TASK_Delay(1) is called shortly before the next timer interrupt the actual timeout will be less than a full system tick or even almost zero.

The actual timeout depends on when the API function is called in relation to the next timer interrupt. A timeout of 1 could cause the API function to almost return immediately.

Implementation details

OS_Global.Time holds the system time (in system ticks) since reset and always is a signed 32-bit variable. OS_Global.Time starts at 0x00000000 and is incremented with every system tick in the interrupt handler (assuming OS_TICK_Config() is not used). After OS_Global.Time reaches 0xFFFFFFFF, it starts at 0x00000000 again. With a typical system tick period of 1 millisecond, this happens after ~49 days.

When calling OS_TASK_Delay(), or an API function with a timeout (e.g. OS_EVENT_GetTimed()), embOS calculates the end time and stores it in OS_Global.TimeDex. The end time is the current time plus the desired timeout. OS_Global.TimeDex is also a signed integer value.

OS_Global.TimeDex = OS_Global.Time + Timeout

Example:
OS_Global.Time = 5

OS_TASK_Delay(10)

OS_Global.TimeDex = 15

With each system tick, embOS checks whether the current system time is equal or greater than OS_Global.TimeDex. This is implemented as a subtraction of signed values. This calculation guarantees that overflows are handled correctly as long as the timeout value limitation (explained below) is respected.

if ((OS_Global.Time - OS_Global.TimeDex) >= 0) {
  // Timeout has expired
} else {
  // Timeout has not yet expired
}

Example

With a 32-bit CPU and a one millisecond system tick the maximum timeout is ~24 days.

Description

The actual width of embOS timing variables is core specific, but for the following examples we assume 8-bit variables for easier understanding. The range is 0x00 to 0xFF, where 0x00 to 0x7F represent positive values and 0x80 to 0xFF negative values.

0x00  0
0x01  1
...
0x7F  127
0x80  -128
...
0xFF  -1

Four cases exist: Both OS_Global.Time and OS_Global.TimeDex are positive values, both are negative values, and one positive and one negative value (and vice versa).

OS_Global.Time and OS_Global.TimeDex are positive

OS_Global.Time    = 100  (0x64)
Timeout           = 20   (0x14)
OS_Global.TimeDex = 120  (0x78)
OS_Global.Time - OS_Global.TimeDex = -20 < 0 => Timeout has not yet expired

OS_Global.Time    = 121  (0x79)
OS_Global.TimeDex = 120  (0x78)
OS_Global.Time - OS_Global.TimeDex = 1 >= 0 => Timeout has expired

OS_Global.Time and OS_Global.TimeDex are negative

OS_Global.Time    = -128  (0x80)
Timeout           = 8     (0x08)
OS_Global.TimeDex = -120  (0x88)
OS_Global.Time - OS_Global.TimeDex = -8 < 0 => Timeout has not yet expired

OS_Global.Time    = -119  (0x89)
OS_Global.TimeDex = -120  (0x78)
OS_Global.Time - OS_Global.TimeDex = 1 >= 0 => Timeout has expired

OS_Global.Time is positive and OS_Global.TimeDex is negative

OS_Global.Time    = 120   (0x88)
Timeout           = 16    (0x10)
OS_Global.TimeDex = -120  (0x88)
OS_Global.Time - OS_Global.TimeDex = -16 < 0 => Timeout has not yet expired

OS_Global.Time    = -119  (0x89)
OS_Global.TimeDex = -120  (0x88)
OS_Global.Time - OS_Global.TimeDex = 1 >= 0 => Timeout has expired

OS_Global.Time is negative and OS_Global.TimeDex is positive

OS_Global.Time    = -1
Timeout           = 16
OS_Global.TimeDex = 15
OS_Global.Time - OS_Global.TimeDex = -16 < 0 => Timeout has not yet expired

OS_Global.Time    = 16
OS_Global.TimeDex = 15
OS_Global.Time - OS_Global.TimeDex = 1 >= 0 => Timeout has expired

Limitation

This check may only be performed if the difference between OS_Global.Time and OS_Global.TimeDex is less than half of the available range minus one. Otherwise, it is undecidable whether OS_Global.Time has lapped OS_Global.TimeDex. The following example shows how the calculation fails if the timeout limit is violated.

8-bit range => Maximum timeout value = 128 - 1 = 127

OS_Global.Time    = 0
Invalid Timeout   = 130
OS_Global.TimeDex = 130
OS_Global.Time - OS_Global.TimeDex = 126 > 0
=> Wrong result, Timeout has not yet expired

Conclusion

As long as the timeout limitation is not violated, an overflow of OS_Global.Time is no problem. As shown in the above examples all calculations are performed correctly. Therefore you will find the timeout limitation in the timeout parameter description of all according API functions.

RTOS objects

Most embOS API functions require an according RTOS object. The RTOS object is based on a C structure and stores application specific information. For example, if you create a new task with OS_TASK_Create(), you will need to specify a task control block. OS_TASK_Create() expects a pointer to an RTOS object of the type OS_TASK to store information like the task priority.

Examples for RTOS objects:

• OS_TASK
• OS_TIMER
• OS_EVENT
• OS_MUTEX
• OS_SEMAPHORE
• OS_RWLOCK
• OS_MAILBOX
• OS_QUEUE
• OS_WD

It is the developer’s responsibility to allocate RAM for the RTOS object. The memory can be allocated statically or dynamically. Whether it is preferable to use static or dynamic memory allocation depends on the application. Both methods can be used with embOS and also within the same embOS application.

The RTOS object must be located in RAM; it is the developer’s responsibility to allocate sufficient memory for it. Furthermore, the RTOS object must not be located at address 0x00. If the target has RAM at address 0x00, the linker file should define the RAM start at e.g. address 0x04. Consequently, NULL must never be passed to an embOS API function that expects an RTOS object as parameter (unless explicitly stated otherwise in the respective API function description).

Static allocation

static OS_MUTEX _Mutex;

int main(void) {
  ...
  OS_MUTEX_Create(&_Mutex);
  ...
  return 0;
}

Dynamic allocation

static OS_MUTEX* _pMutex;

int main(void) {
  ...
  _pMutex = (OS_MUTEX*)malloc(sizeof(OS_MUTEX));
  if (_pMutex != NULL) {
    OS_MUTEX_Create(_pMutex);
  }
  ...
  return 0;
}

Bad examples

Write to a member of an RTOS object:

static OS_MUTEX _Mutex;

int main(void) {
  ...
  OS_MUTEX_Create(&_Mutex);
  _Mutex.UseCnt = 42;
  ...
  return 0;
}

Memory freed while the RTOS object is still in use:

static OS_MUTEX* _pMutex;

void Task(void) {
  while (1) {
    OS_MUTEX_LockBlocked(_pMutex);
  }
}

int main(void) {
  ...
  _pMutex = (OS_MUTEX*)malloc(sizeof(OS_MUTEX));
  OS_MUTEX_Create(_pMutex);
  free(_pMutex);
  ...
  OS_Start();
  return 0;
}

embOS types

In addition to embOS object types, embOS uses further data types for API routine arguments and return values.
Per default they are defined as:

Callback / Hook routines

Both terms are used with embOS and mean the same. Some embOS API functions use a function pointer parameter for a callback routine. The callback routine must be implemented by the application and is defined as determined by the function pointer type. The following function pointer types are used:

Example

void OS_WD_Config(OS_ROUTINE_VOID* pfTrigger, OS_ROUTINE_WD_PTR* pfReset);

static void _TriggerRoutine(void) {
  ...
}

static void _ResetRoutine(OS_CONST_PTR OS_WD* pWD) {
  ...
}

int main(void) {
  ...
  OS_WD_Config(&_TriggerRoutine, &_ResetRoutine);
  ...
  return 0;
}

embOS library modes

embOS comes in different builds or versions of the libraries. The reason for different builds is that requirements vary during development. While developing software, the performance (and resource usage) is not as important as in the final version which usually goes as release build into the product. But during development, even small programming errors should be caught by use of assertions. These assertions are compiled into the debug build of the embOS libraries and make the code a little bigger (about 50%) and also slightly slower than the release or stack-check build used for the final product.

This concept gives you the best of both worlds: a compact and very efficient build for your final product (release or stack-check build of the libraries), and a safer (though bigger and slower) build for development which will catch most common application programming errors. Of course, you may also use the release build of embOS during development, but it will not catch these errors.

The features are enabled and disabled with compile-time switches in the C source code. For example the macro OS_DEBUG controls whether the debug code is included in the build. Please have a look in the chapter Compile time switches for more details.

The following features are included in the different embOS builds:

Debug code

The embOS debug code detects application programming errors like calling an API function from an invalid context. An application using an embOS debug library has to include OS_Error.c. OS_Error.c contains the OS_Error() function which will be called if a debug assertion fails. It is advisable to always use embOS debug code during development.

Stack Check

The embOS stack check detects overflows of task stacks, system stack and interrupt stack. Furthermore, it enables additional information in embOSView and IDE RTOS plug-ins, and provides additional embOS API regarding stack information. An application using an embOS stack check library has to include OS_Error.c. OS_Error.c contains the OS_Error() function which will be called if a stack overflow occurs.

Profiling

The embOS profiling code makes precise information available about the execution time of individual tasks. You may always use the profiling libraries, but they induce larger task control blocks as well as additional ROM and runtime overhead. This overhead is usually acceptable, but for best performance you may want to use non-profiling builds of embOS if you do not use this feature.

Libraries including support for profiling do also include the support for SystemView.

embOS API Trace

embOS API trace saves information about called API in a trace buffer. The trace data can be visualized in e.g. SystemView.

embOSView API Trace

embOSView API trace saves information about called API in a trace buffer. The trace data can be visualized in embOSView.

Round-Robin

Round-Robin lets all tasks at the same priority execute periodically for a pre-defined period of time.

Object Names

Tasks and OS object names can be used to easily identify a task or e.g. a mailbox in tools like embOSView, SystemView or IDE RTOS plug-ins.

Task Context Extension

For some applications it might be useful or required to have individual data in tasks that are unique to the task or to execute specific actions at context switch. With the task context extension support each task control block includes function pointer to a save and a restore routine which are executed during the context switch from and to the task.

Available library modes

In your application program, you need to let the compiler know which build of embOS you are using. This is done by adding the corresponding define to your preprocessor settings and linking the appropriate library file. If the preprocessor setting does not match the library, a linker error will occur. Using the preprocessor define, RTOS.h will set embOS structures to the same configuration that was used during the creation of the library, thus ensuring identical structure definitions in both the application and the library. If no preprocessor setting is given, OS_Config.h will be included and will set a library mode automatically (see OS_Config.h).

OS_Config.h

OS_Config.h is part of every embOS port and located in the Start\Inc folder. Use of OS_Config.h is optional but makes it easier to define the embOS library mode: Instead of defining OS_LIBMODE_* in your preprocessor settings, you may define DEBUG=1 in your preprocessor settings in debug compile configurations and define nothing in the preprocessor settings in release compile configurations. Subsequently, OS_Config.h will automatically define OS_LIBMODE_DP for debug compile configurations and OS_LIBMODE_R for release compile configurations. OS_Config.h will be included only when no OS_LIBMODE_* is defined.

OS_LIBMODE_SAFE

OS_LIBMODE_SAFE is usually used with embOS-Safe only for the safety certified embOS library. OS_LIBMODE_SAFE excludes/adds some embOS features which are not mentioned above:

embOS API not supported with OS_LIBMODE_SAFE

• Heap Type Memory Management
• CPU Load Measurement
• Spinlock API
• embOSView / embOSView trace
• Thread local storage

Additional embOS API supported with OS_LIBMODE_SAFE

• Configurable stack check limit
• MPU sanity check buffer

Kernel

Introduction

The embOS kernel is started with OS_Start() in main() after the kernel was initialized with OS_Init(). Typically, applications will also initialize the required hardware, and create at least one task before calling OS_Start(). OS_Start() usually never returns but runs the embOS scheduler which decides which task to run next. It is possible to stop and de-initialize the kernel with OS_Stop() and OS_DeInit().

Example

int main(void) {
  OS_Init();    // Initialize embOS
  OS_InitHW();  // Initialize required hardware
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_Start();   // Start embOS

  return 0;
}

Interrupts in main()

OS_Start() enables interrupts, but interrupts may also be used in main(). It is not necessary to disable interrupts in main(). When using embOS interrupts in main(), please ensure they are enabled after OS_Init() only. It is good practice to call OS_Init() as first instruction in main().

void UART_ISR(void) {
  // Handle UART interrupt
}

int main(void) {
  OS_Init();    // Initialize embOS
  UART_Init();  // Initialize UART and UART interrupts
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_Start();   // Start embOS

  return 0;
}

API functions

OS_ConfigStop()

Description

Configures the OS_Stop() function.

Prototype

void OS_ConfigStop(OS_MAIN_CONTEXT* pContext,
                   void*            Addr,
                   OS_U32           Size);

Parameters

Additional information

This function configures the OS_Stop() function. When configured, OS_Start() saves the context and stack from within main(), which subsequently are restored by OS_Stop(). The main() context and stack are saved to the resources configured by OS_ConfigStop(). Only the stack that was actually used during main() is saved. Therefore, the size of the buffer depends on the used stack. The structure OS_MAIN_CONTEXT is core and compiler specific; it is specifically defined with each embOS port.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL
227: OS_ERR_ILLEGAL_IN_TASK

For details, refer to the chapter Runtime application errors.

Example

#include "RTOS.h"
#include "stdio.h"

#define BUFFER_SIZE    (32u)
static OS_U8           Buffer[BUFFER_SIZE];  // Buffer for main stack copy
static OS_MAIN_CONTEXT MainContext;          // Main context control structure
static OS_STACKPTR int StackHP[128];         // Task stack
static OS_TASK         TCBHP;                // Task control block

static void HPTask(void) {
  OS_TASK_Delay(50);
  OS_INT_Disable();
  OS_Stop();
}

int main(void) {
  int TheAnswerToEverything = 42;
  OS_Init();      // Initialize embOS
  OS_InitHW();    // Initialize required hardware
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_ConfigStop(&MainContext, Buffer, BUFFER_SIZE);
  OS_Start();     // Start embOS
  //
  // We arrive here because OS_Stop() was called.
  // The local stack variable still has its value.
  //
  printf("%d", TheAnswerToEverything);
  while (TheAnswerToEverything == 42) {
  }
  return 0;
}

OS_DeInit()

Description

De-initializes the embOS kernel.

Prototype

void OS_DeInit(void);

Additional information

OS_DeInit() can be used to de-initializes the embOS kernel and the hardware which was initialized in OS_Init(). OS_DeInit() is usually used after returning from OS_Start(). It does not de-initialize the hardware which was configured in e.g. OS_InitHW() but it resets all embOS variables to their default values.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL
227: OS_ERR_ILLEGAL_IN_TASK

For details, refer to the chapter Runtime application errors.

Example

#define BUFFER_SIZE    (32u)

static OS_STACKPTR int StackHP[128]  // Task stacks
static OS_TASK         TCBHP;        // Task control blocks
static OS_U8           Buffer[BUFFER_SIZE];
static OS_MAIN_CONTEXT MainContext;

static void HPTask(void) {
  while (1) {
    OS_TASK_Delay(50);
    OS_Stop();
  }
}

int main(void) {
  OS_Init();      // Initialize embOS
  OS_InitHW();    // Initialize required hardware
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_ConfigStop(&MainContext, Buffer, BUFFER_SIZE);
  OS_Start();     // Start embOS
  OS_DeInit();
  OS_DeInitHW();
  DoSomeThingElse();
  //
  // Start embOS for the 2nd time
  //
  OS_Init();
  OS_InitHW();
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_ConfigStop(&MainContext, Buffer, BUFFER_SIZE);
  OS_Start();
  return 0;
}

OS_Init()

Description

Initializes the embOS kernel.

Prototype

void OS_Init(void);

Additional information

In library mode OS_LIBMODE_SAFE all RTOS variables are explicitly initialized. All other library modes presume that, according to the C standard, all initialized variables have their initial value and all non initialized variables are set to zero.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL
227: OS_ERR_ILLEGAL_IN_TASK

For details, refer to the chapter Runtime application errors.

Example

#include "RTOS.h"

static OS_STACKPTR int StackHP[128], StackLP[128];  // Task stacks
static OS_TASK         TCBHP, TCBLP;                // Task control blocks

static void HPTask(void) {
  while (1) {
    OS_TASK_Delay(50);
  }
}

static void LPTask(void) {
  while (1) {
    OS_TASK_Delay(200);
  }
}

/*********************************************************************
*
*       main()
*/
int main(void) {
  OS_Init();      // Initialize embOS
  OS_InitHW();    // Initialize required hardware
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_TASK_CREATE(&TCBLP, "LP Task",  50, LPTask, StackLP);
  OS_Start();     // Start embOS
  return 0;
}

OS_IsRunning()

Description

Determines whether the embOS kernel was started by a call to OS_Start().

Prototype

OS_BOOL OS_IsRunning(void);

Return value

Additional information

This function may be helpful for some functions which might be called from main() or from running tasks. As long as the kernel is not started and a function is called from main(), blocking task switches are not allowed. A function which may be called from a task or main() may use OS_IsRunning() to determine whether a subsequent call to a blocking API function is allowed.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintStatus() {
  OS_BOOL b;

  b = OS_ISRunning();
  if (b == 0) {
    printf("embOS scheduler not started, yet.\n");
  } else {
    printf("embOS scheduler is running.\n");
  }
}

OS_Start()

Description

Starts the embOS scheduler.

Prototype

void OS_Start(void);

Additional information

This function starts the embOS scheduler, which will activate and start the task with the highest priority.

OS_Start() marks embOS as running; this may be examined by a call of the function OS_IsRunning(). OS_Start() automatically enables interrupts. It must be called from main() context only.

embOS will reuse the main stack after OS_Start() was called. Therefore, local data located on the main stack may not be used after calling OS_Start(). If OS_Stop() is used, OS_ConfigStop() will save the main stack and restore it upon stopping embOS.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

165: OS_ERR_INIT_NOT_CALLED
228: OS_ERR_ILLEGAL_AFTER_OSSTART

For details, refer to the chapter Runtime application errors.

Example

#include "RTOS.h"

static OS_STACKPTR int StackHP[128], StackLP[128];  // Task stacks
static OS_TASK         TCBHP, TCBLP;                // Task control blocks

static void HPTask(void) {
  while (1) {
    OS_TASK_Delay(50);
  }
}

static void LPTask(void) {
  while (1) {
    OS_TASK_Delay(200);
  }
}

/*********************************************************************
*
*       main()
*/
int main(void) {
  OS_Init();      // Initialize embOS
  OS_InitHW();    // Initialize required hardware
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_TASK_CREATE(&TCBLP, "LP Task",  50, LPTask, StackLP);
  OS_Start();     // Start embOS
  return 0;
}

OS_Stop()

Description

Stops the embOS kernel and returns from OS_Start().

Prototype

void OS_Stop(void);

Additional information

This function stops the embOS kernel and the application returns from OS_Start().
OS_ConfigStop() must be called prior to OS_Stop(). OS_Stop() restores context and stack to their state prior to calling OS_Start(). OS_Stop() does not deinitialize any hardware. It’s the application’s responsibility to de-initialize all hardware that was initialized, for example, during OS_InitHW().

It is possible to restart embOS after OS_Stop(). To do so, OS_Init() must be called and any task must be recreated. It also is the application’s responsibility to initialize all embOS variables to their default values. With the embOS source code, this can easily be achieved using the compile time switch OS_INIT_EXPLICITLY.

With some cores it is not possible to save and restore the main() stack. This is e.g. true for 8051. Hence, in that case no functionality should be implemented that relies on the stack to be preserved. But OS_Stop() can be used anyway.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL
226: OS_ERR_ILLEGAL_IN_MAIN
250: OS_ERR_CONFIG_OSSTOP

For details, refer to the chapter Runtime application errors.

Example

#include "RTOS.h"
#include "stdio.h"

#define BUFFER_SIZE    (32u)
static OS_U8           Buffer[BUFFER_SIZE];
static OS_MAIN_CONTEXT MainContext;

static OS_STACKPTR int StackHP[128];
static OS_TASK         TCBHP;

static void HPTask(void) {
  OS_TASK_Delay(50);
  OS_Stop();
}

int main(void) {
  int TheAnswerToEverything = 42;
  OS_Init();
  OS_InitHW();
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_ConfigStop(&MainContext, Buffer, BUFFER_SIZE);
  OS_Start();
  //
  // We arrive here because OS_Stop() was called.
  // The local stack variable still has its value.
  //
  printf("%d", TheAnswerToEverything);
  while (1) {
  }
  return 0;
}

Task

Introduction

A task that should run under embOS needs a task control block (TCB), a task stack, and a task body written in C. The following rules apply to task routines:

• The task routine can either not take parameters (void parameter list), in which case OS_TASK_Create() is used to create it, or take a single void pointer as parameter, in which case OS_TASK_CreateEx() is used to create it.
• The task routine must not return.
• The task routine must be implemented as an endless loop or it must terminate itself (see examples below).

Example of a task routine as an endless loop

void Task1(void) {
  while(1) {
    DoSomething();      // Do something
    OS_TASK_Delay(10);  // Give other tasks a chance to run
  }
}

Example of a task routine that terminates itself

void Task2(void) {
  char DoSomeMore;
  do {
    DoSomeMore = DoSomethingElse();  // Do something
    OS_TASK_Delay(10);               // Give other tasks a chance to run
  } while (DoSomeMore);
  OS_TASK_Terminate(NULL);           // Terminate this task
}

There are different ways to create a task: On the one hand, embOS offers a simple macro to facilitate task creation, which is sufficient in most cases. However, if you are dynamically creating and deleting tasks, a function is available allowing “fine-tuning” of all parameters. For most applications, at least initially, we recommend using the macro.

Cooperative vs. preemptive task switches

In general, preemptive task switches are an important feature of an RTOS. Preemptive task switches are required to guarantee responsiveness of high-priority, time critical tasks. However, it may be desirable to disable preemptive task switches for certain tasks in some circumstances. The default behavior of embOS is to allow preemptive task switches in all circumstances.

Disabling preemptive task switches for tasks of equal priority

In some situations, preemptive task switches between tasks running at identical priorities are not desirable. To inhibit time slicing of equal-priority tasks, the time slice of the tasks running at identical priorities must be set to zero as in the example below:

#include "RTOS.h"

#define PRIO_COOP       10
#define TIME_SLICE_NULL  0

static OS_STACKPTR int StackHP[128], StackLP[128];  // Task stacks
static OS_TASK         TCBHP, TCBLP;                // Task control blocks

static void TaskEx(void* pData) {
  while (1) {
    OS_TASK_Delay((OS_TIME)pData);
  }
}

/*********************************************************************
*
*       main()
*/
int main(void) {
  OS_Init();      // Initialize embOS
  OS_InitHW();    // Initialize required hardware
  BSP_Init();     // Initialize LED ports
  OS_TASK_CreateEx(&TCBHP, "HP Task", PRIO_COOP, TaskEx, StackHP,
                  sizeof(StackHP), TIME_SLICE_NULL, (void *) 50);
  OS_TASK_CreateEx(&TCBLP, "LP Task", PRIO_COOP, TaskEx, StackLP,
                  sizeof(StackLP), TIME_SLICE_NULL, (void *) 200);
  OS_Start();     // Start embOS
  return 0;
}

Completely disabling preemptions for a task

This is simple: The first line of code should be OS_TASK_EnterRegion() as shown in the following sample:

void MyTask(void* pContext) {
  OS_TASK_EnterRegion();  // Disable preemptive context switches
  while (1) {
    // Do something. In the code, make sure that you call a blocking
    // function periodically to give other tasks a chance to run.
  }
}

This will entirely disable preemptive context switches from that particular task and will therefore affect the timing of higher-priority tasks. Do not use this carelessly.

Extending the task context

For some applications it might be useful or required to have individual data in tasks that are unique to the task. Local variables, declared in the task, are unique to the task and remain valid, even when the task is suspended and resumed again. When the same task function is used for multiple tasks, local variables in the task may be used, but cannot be initialized individually for every task. embOS offers different options to extend the task context.

Passing one parameter to a task during task creation

Very often it is sufficient to have just one individual parameter passed to a task. Using the OS_TASK_CREATEEX() or OS_TASK_CreateEx() function to create a task allows passing a void-pointer to the task. The pointer may point to individual data, or may represent any data type that can be held within a pointer.

Extending the task context individually at runtime

Sometimes it may be required to have an extended task context for individual tasks to store global data or special CPU registers such as floating-point registers in the task context. The standard libraries for file I/O, locale support and others may require task-local storage for specific data like errno and other variables. embOS enables extension of the task context for individual tasks during runtime by a call of OS_TASK_SetContextExtension(). The sample application file OS_ExtendTaskContext.c delivered in the application samples folder of embOS demonstrates how the individual task context extension can be used.

Extending the task context by using own task structures

When complex data is needed for an individual task context, the OS_TASK_CREATEEX() or OS_TASK_CreateEx() functions may be used, passing a pointer to individual data structures to the task. Alternatively you may define your own task structure which can be used. Note, that the first item in the task structure must be an embOS task control structure OS_TASK. This can be followed by any amount and type of additional data of different types.

The following code shows the example application OS_ExtendedTask.c which is delivered in the sample application folder of embOS.

#include "RTOS.h"

/*********************************************************************
*
*       Types, local
*
**********************************************************************
*/

//
// Custom task structure with extended task context.
//
typedef struct {
  OS_TASK Task;     // OS_TASK has to be the first element
  OS_TIME Timeout;  // Any other data type may be used to extend the context
  char*   pString;  // Any number of elements may be used to extend the context
} MY_APP_TASK;

/*********************************************************************
*
*       Static data
*
**********************************************************************
*/
static OS_STACKPTR int StackHP[128], StackLP[128];  // Task stacks
static MY_APP_TASK     TCBHP, TCBLP;                // Task-control-blocks

/*********************************************************************
*
*       Local functions
*
**********************************************************************
*/

/*********************************************************************
*
*       MyTask()
*/
static void MyTask(void) {
  MY_APP_TASK* pThis;
  OS_TIME      Timeout;
  char*        pString;

  pThis = (MY_APP_TASK*)OS_TASK_GetID();
  while (1) {
    Timeout = pThis->Timeout;
    pString = pThis->pString;
    OS_COM_SendString(pString);
    OS_TASK_Delay(Timeout);
  }
}

/*********************************************************************
*
*       Global functions
*
**********************************************************************
*/

/*********************************************************************
*
*       main()
*/
int main(void) {
  OS_Init();    // Initialize embOS
  OS_InitHW();  // Initialize required hardware
  //
  // Create the extended tasks just as normal tasks.
  // Note that the first parameter has to be of type OS_TASK
  //
  OS_TASK_CREATE(&TCBHP.Task, "HP Task", 100, MyTask, StackHP);
  OS_TASK_CREATE(&TCBLP.Task, "LP Task",  50, MyTask, StackLP);
  //
  // Give task contexts individual data
  //
  TCBHP.Timeout = 200;
  TCBHP.pString = "HP task running\n";
  TCBLP.Timeout = 500;
  TCBLP.pString = "LP task running\n";
  OS_Start();   // Start embOS
  return 0;
}

API functions

OS_TASK_AddContextExtension()

Description

Adds the specified task context extension. The task context can be extended with OS_TASK_SetContextExtension() only once. Additional task context extensions can be added with OS_TASK_AddContextExtension(). OS_TASK_AddContextExtension() can also be called for the first task context extension.
The function OS_TASK_AddContextExtension() requires an additional parameter of type OS_EXTEND_TASK_CONTEXT_LINK which is used to create a task specific linked list of task context extensions.

Prototype

void OS_TASK_AddContextExtension
             (OS_EXTEND_TASK_CONTEXT_LINK* pExtendContextLink,
              OS_CONST_PTR                 OS_EXTEND_TASK_CONTEXT *pExtendContext);

Parameters

Additional information

The object of type OS_EXTEND_TASK_CONTEXT_LINK is task specific and must only be used for one task. It can be located e.g. on the task stack. pExtendContext, pExtendContext->pfSave and pExtendContext->pfRestore must not be NULL.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

116: OS_ERR_EXTEND_CONTEXT
128: OS_ERR_INV_TASK
160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL
226: OS_ERR_ILLEGAL_IN_MAIN

For details, refer to the chapter Runtime application errors.

Example

static void HPTask(void) {
  OS_EXTEND_TASK_CONTEXT_LINK p;
  //
  // Extend task context by VFP registers
  //
  OS_TASK_SetContextExtension(&_SaveRestoreVFP);
  //
  // Extend task context by global variable
  //
  OS_TASK_AddContextExtension(&p, &_SaveRestoreGlobalVar);
  a = 1.2;
  while (1) {
    b = 3 * a;
    GlobalVar = 1;
    OS_TASK_Delay(10);
  }
}

OS_TASK_AddTerminateHook()

Description

Adds the specified hook (callback) routine to the list of routines which are called when a task is terminated.

Prototype

void OS_TASK_AddTerminateHook(OS_ON_TERMINATE_HOOK* pHook,
                              OS_ROUTINE_TASK_PTR*  pfRoutine);

Parameters

Additional information

For some applications, it may be useful to allocate memory or objects specific to tasks. For other applications, it may be useful to have task-specific information on the stack. When a task is terminated, the task-specific objects may become invalid. A callback routine may be hooked into OS_TASK_Terminate() by calling OS_TASK_AddTerminateHook() to allow the application to invalidate all task-specific objects before the task is terminated.

The callback routine pfRoutine of type OS_ROUTINE_TASK_PTR receives the address of the terminated task as its parameter (see description in chapter Callback / Hook routines).

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

OS_ON_TERMINATE_HOOK _TerminateHook;

void TerminateHookFunc(OS_CONST_PTR OS_TASK* pTask) {
  // This function is executed upon calling OS_TASK_Terminate().
  if (pTask == &MyTask) {
    free(MytaskBuffer);
  }
}
...
int main(void) {
  OS_TASK_AddTerminateHook(&_TerminateHook, TerminateHookFunc);
  ...
}

OS_TASK_Create()

Description

Creates a new task.

Prototype

void OS_TASK_Create(      OS_TASK*         pTask,
                    const char*            sName,
                          OS_TASK_PRIO     Priority,
                          OS_ROUTINE_VOID* pfRoutine,
                          void             OS_STACKPTR *pStack,
                          OS_UINT          StackSize,
                          OS_UINT          TimeSlice);

Parameters

Additional information

OS_TASK_Create() creates a task and makes it ready for execution. The newly created task will be activated by the scheduler as soon as there is no other task with higher priority ready for execution.

OS_TASK_Create() can be called either from main() during initialization or from any other task. The recommended strategy is to create all tasks during initialization in main() to keep the structure of your application easy to maintain.

The absolute value of Priority is of no importance, only the value in comparison to the priorities of other tasks matters. If there is another task with the same priority, the new task will be scheduled prior to the existing one.
In embOS builds that do not support round-robin, unique priorities must be assigned to each individual task.

The stack indicated by pStack must reside in an area that the CPU can address as stack. Most CPUs cannot use the entire memory area as stack and require the stack to be aligned to a multiple of the processor word size.

A TimeSlice value of zero is allowed and disables round-robin task switches (see sample in chapter Disabling preemptive task switches for tasks of equal priority).

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

120: OS_ERR_TASK_STACK
160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
165: OS_ERR_INIT_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL
170: OS_ERR_2USE_TASK
202: OS_ERR_TASK_PRIORITY

For details, refer to the chapter Runtime application errors.

#define OS_TASK_CREATE(pTask, pName, Priority, pRoutine, pStack) \
  OS_TASK_Create((pTask),                                        \
                 (pName),                                        \
                 (OS_PRIO)(Priority),                            \
                 (pRoutine),                                     \
                 (void OS_STACKPTR*)(pStack),                    \
                 sizeof(pStack),                                 \
                 2u                                              \
                )

Example

#include "RTOS.h"

static OS_STACKPTR int StackHP[128], StackLP[128];  // Task stacks
static OS_TASK         TCBHP, TCBLP;                // Task control blocks

static void HPTask(void) {
  while (1) {
    OS_TASK_Delay(50);
  }
}

static void LPTask(void) {
  while (1) {
    OS_TASK_Delay(200);
  }
}

int main(void) {
  OS_Init();      // Initialize embOS
  OS_InitHW();    // Initialize required hardware
  OS_TASK_Create(&TCBHP, "HP Task", 100, HPTask, StackHP, sizeof(StackHP), 2);
  OS_TASK_CREATE(&TCBLP, "LP Task",  50, LPTask, StackLP);
  OS_Start();     // Start embOS
  return 0;
}

OS_TASK_CreateEx()

Description

Creates a new task and passes a parameter to the task.

Prototype

void OS_TASK_CreateEx(      OS_TASK*             pTask,
                      const char*                sName,
                            OS_TASK_PRIO         Priority,
                            OS_ROUTINE_VOID_PTR* pfRoutine,
                            void                 OS_STACKPTR *pStack,
                            OS_UINT              StackSize,
                            OS_UINT              TimeSlice,
                            void*                pContext);

Parameters

Additional information

This function works the same way as OS_TASK_Create(), but allows passing a parameter, pContext, to the task. Using a void pointer as additional parameter gives the flexibility to pass any kind of data to the task function.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

120: OS_ERR_TASK_STACK
160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
165: OS_ERR_INIT_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL
170: OS_ERR_2USE_TASK
202: OS_ERR_TASK_PRIORITY

For details, refer to the chapter Runtime application errors.

#define OS_TASK_CREATEEX(pTask, pName, Priority, pRoutine, pStack, pContext)
  OS_TASK_CreateEx((pTask),
                   (pName),
                   (OS_PRIO)(Priority),
                   (pRoutine),
                   (void OS_STACKPTR*)(pStack),
                   sizeof(pStack),
                   2u,
                   (pContext)
                  )

Example

#include "RTOS.h"

static OS_STACKPTR int StackHP[128], StackLP[128];  // Task stacks
static OS_TASK         TCBHP, TCBLP;                // Task control blocks

static void Task(void* pContext) {
  while (1) {
    OS_TASK_Delay((int)pContext);
  }
}

int main(void) {
  OS_Init();      // Initialize embOS
  OS_InitHW();    // Initialize required hardware
  OS_TASK_CreateEx(&TCBHP, "HP Task", 100, Task,
                  StackHP, sizeof(StackHP), 2, (void*) 50);
  OS_TASK_CREATEEX(&TCBLP, "LP Task",  50, Task,
                  StackLP, (void*)200);
  OS_Start();     // Start embOS
  return 0;
}

OS_TASK_Delay()

Description

Suspends the calling task for a specified amount of system ticks, or waits actively when called from main().

Prototype

void OS_TASK_Delay(OS_TIME t);

Parameters

Additional information

The parameter t specifies the time interval in system ticks during which the task is suspended. The actual delay will be in the following range: t - 1 ≤ delay ≤ t, depending on when the interrupt for the scheduler occurs. After the expiration of the delay, the task is made ready and activated according to the rules of the scheduler. A delay can be ended prematurely by another task or by an interrupt handler calling OS_TASK_Wake().

If OS_TASK_Delay() is called from main(), it will actively wait for the timeout to expire. Therefore, interrupts must be enabled.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

154: OS_ERR_INTERRUPT_DISABLED
160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void Hello(void) {
  printf("Hello");
  printf("The next output will occur in 5000 system ticks.\n");
  OS_TASK_Delay(5000);
  printf("Delay is over.\n");
}

OS_TASK_DelayUntil()

Description

Suspends the calling task until a specified time, or waits actively when called from main().

Prototype

void OS_TASK_DelayUntil(OS_TIME t);

Parameters

Additional information

OS_TASK_DelayUntil() suspends the calling task until the global time-variable OS_Global.Time (see OS_Global.Time) reaches the specified value. The main advantage of this function is that it avoids potentially accumulating delays. The additional condition towards parameter t ensures proper behavior even when an overflow of the embOS system tick timer occurs.

If OS_TASK_DelayUntil() is called from main(), it will actively wait for the timeout to expire. Therefore, interrupts must be enabled.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

154: OS_ERR_INTERRUPT_DISABLED
160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

int sec, min;

void TaskShowTime(void) {
  OS_TIME t0;
  t0 = OS_TIME_GetTicks();
  while (1) {
    ShowTime();  // Routine to display time
    t0 += 1000;
    OS_TASK_DelayUntil(t0);
    if (sec < 59) {
      sec++;
    } else {
      sec = 0;
      min++;
    }
  }
}

If the example above used OS_TASK_Delay() instead of OS_TASK_DelayUntil(), this could lead to accumulating overhead between delays if OS_TASK_Delay() is not called exactly each second (which may e.g. happen if interrupts or higher priority tasks are executed instead). This would cause the simple “clock” to be slow. Using OS_TASK_DelayUntil() avoids this accumulating overhead.

OS_TASK_Delay_us()

Description

Actively waits for the given time (in microseconds) to expire.

Prototype

void OS_TASK_Delay_us(OS_U16 us);

Parameters

Additional information

This function can be used for short delays. OS_TASK_Delay_us() must only be called with interrupts enabled and after OS_Init() and OS_TIME_ConfigSysTimer() have been called. Furthermore, the embOS system tick timer must be running.

OS_TASK_Delay_us() does not suspend the calling task, thus all tasks with lower priority cannot be scheduled while the calling tasks executes OS_TASK_Delay_us().

OS_TASK_Delay_us() does not block preemptive task switches and does not disable interrupts, which may extend the configured delay period for potentially unlimited periods of time. Furthermore, returning from OS_TASK_Delay_us() adds some overhead to the configured delay period. For these reasons, the actual delay period may not necessarily be exact and the function guarantees a minimum delay only.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

158: OS_ERR_DELAYUS_INTERRUPT_DISABLED
160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void Hello(void) {
  printf("Hello");
  printf("The next output will occur in 500 microseconds.\n");
  OS_TASK_Delay_us(500);
  printf("Delay is over.\n");
}

OS_TASK_GetID()

Description

Returns a pointer to the task control block structure of the currently scheduled task. This pointer is unique for the task and is used as a task Id.

Prototype

OS_TASK *OS_TASK_GetID(void);

Return value

Additional information

When called from a task, this function may be used for determining which task is currently executing. This can be helpful if the action(s) of a function depend(s) on which task is executing it.

If called from an interrupt service routine, this function may be used to determine the interrupted task (if any).

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintCurrentTaskID(void) {
  OS_TASK* pTask;
  pTask = OS_TASK_GetID();
  printf("Task ID 0x%x\n", pTask);
}

OS_TASK_GetName()

Description

Returns a pointer to the name of the specified task.

Prototype

char *OS_TASK_GetName(OS_CONST_PTR OS_TASK *pTask);

Parameters

Return value

A pointer to the name of the task. NULL indicates that the task has no name. If NULL is passed for pTask, the function returns the name of the running task. If there is no currently running task, the return value is “OS_Idle()”. If pTask is not NULL it must specify a valid task.

When using an embOS build without task name support, OS_TASK_GetName() returns “n/a” in any case. The embOS OS_LIBMODE_XR library mode does not support task names.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintTaskName(void) {
  char* s;
  s = OS_TASK_GetName(NULL);
  printf("Task name: %s\n", s);
}

OS_TASK_GetNumTasks()

Description

Returns the number of tasks.

Prototype

int OS_TASK_GetNumTasks(void);

Return value

Number of tasks.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintNumberOfTasks(void) {
  int NumTasks;
  NumTasks = OS_TASK_GetNumTasks();
  printf("Number of tasks %d\n", NumTasks);
}

OS_TASK_GetPriority()

Description

Returns the task priority of the specified task.

Prototype

OS_TASK_PRIO OS_TASK_GetPriority(OS_CONST_PTR OS_TASK *pTask);

Parameters

Return value

Priority of the specified task (range 1 to 255 for 8/16-bit CPUs and up to 4294967295 for 32-bit CPUs).

Additional information

If NULL is passed for pTask, the currently running task is used. If this function is not called from a task context, no task might currently be running and there is no valid task. A debug build of embOS will call OS_Error() in this case. We suggest to call this function from a context other than the task context with a pointer to a valid task control block only.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

128: OS_ERR_INV_TASK
164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintPriority(const OS_TASK* pTask) {
  OS_PRIO Prio;
  Prio = OS_TASK_GetPriority(pTask);
  printf("Priority of task 0x%x = %u\n", pTask, Prio);
}

OS_TASK_GetStatus()

Description

Returns the current task status of the the specified task.

Prototype

OS_TASK_STATUS OS_TASK_GetStatus(OS_CONST_PTR OS_TASK *pTask);

Parameters

Return value

Task status.

Possible return values are:
READY_FOR_EXECUTION
DELAYED
WAITS_FOR_TASKEVENT
WAITS_FOR_TASKEVENT_WITH_TIMEOUT
WAITS_FOR_MUTEX
WAITS_FOR_MUTEX_WITH_TIMEOUT
WAITS_FOR_COMMUNICATION
WAITS_FOR_SEMAPHORE
WAITS_FOR_SEMAPHORE_WITH_TIMEOUT
WAITS_FOR_MEMPOOL
WAITS_FOR_MEMPOOL_WITH_TIMEOUT
WAITS_FOR_MESSAGE_IN_QUEUE
WAITS_FOR_MESSAGE_IN_QUEUE_WITH_TIMEOUT
WAITS_FOR_SPACE_IN_MAILBOX
WAITS_FOR_SPACE_IN_MAILBOX_WITH_TIMEOUT
WAITS_FOR_MESSAGE_IN_MAILBOX
WAITS_FOR_MESSAGE_IN_MAILBOX_WITH_TIMEOUT
WAITS_FOR_EVENTOBJECT
WAITS_FOR_EVENTOBJECT_WITH_TIMEOUT
WAITS_FOR_SPACE_IN_QUEUE
WAITS_FOR_SPACE_IN_QUEUE_WITH_TIMEOUT
WAITS_FOR_MULITPLE_OBJECTS
WAITS_FOR_MULITPLE_OBJECTS_WITH_TIMEOUT
RUNNING
SUSPENDED

Additional information

If NULL is passed for pTask, the currently running task is used. If this function is not called from a task context, no task might currently be running and there is no valid task. A debug build of embOS will call OS_Error() in this case. We suggest to call this function from a context other than the task context with a pointer to a valid task control block only.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

128: OS_ERR_INV_TASK
164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintTaskStatus(void) {
  OS_TASK_STATUS status;

  status = OS_TASK_GetStatus(&TCB);
  printf("Task status: %u\n", status);
}

OS_TASK_GetSuspendCnt()

Description

Returns the suspension count and thus suspension state of the specified task. This function may be used to examine whether a task is suspended by previous calls of OS_TASK_Suspend().

Prototype

OS_U8 OS_TASK_GetSuspendCnt(OS_CONST_PTR OS_TASK *pTask);

Parameters

Return value

Suspension count of the specified task.

Additional information

If NULL is passed for pTask, the currently running task is used. If this function is not called from a task context, no task might currently be running and there is no valid task. A debug build of embOS will call OS_Error() in this case. We suggest to call this function from a context other than the task context with a pointer to a valid task control block only.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

128: OS_ERR_INV_TASK
164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void ResumeTask(OS_TASK* pTask) {
  OS_U8 SuspendCnt;
  SuspendCnt = OS_TASK_GetSuspendCnt(pTask);
  while (SuspendCnt > 0u) {
    OS_TASK_Resume(pTask);  // May cause a task switch
    SuspendCnt--;
  }
}

OS_TASK_GetTimeSliceRem()

Description

Returns the remaining time slice value of the specified task in system ticks.

Prototype

OS_U8 OS_TASK_GetTimeSliceRem(OS_CONST_PTR OS_TASK *pTask);

Parameters

Return value

Remaining time slice value of the task in system ticks.

Additional information

If NULL is passed for pTask, the currently running task is used. If this function is not called from a task context, no task might currently be running and there is no valid task. A debug build of embOS will call OS_Error() in this case. We suggest to call this function from a context other than the task context with a pointer to a valid task control block only.

The return value is valid only when using an embOS build with round-robin support. In all other builds it will be 0. The embOS OS_LIBMODE_XR library mode does not support round-robin.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

128: OS_ERR_INV_TASK
164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintRemainingTimeSlices(void) {
  OS_U8 slices;

  slices = OS_TASK_GetTimeSliceRem(NULL);
  printf("Remaining Time Slices: %d\n", slices);
}

OS_TASK_IsTask()

Description

Determines whether the specified task control block belongs to a valid task.

Prototype

OS_BOOL OS_TASK_IsTask(OS_CONST_PTR OS_TASK *pTask);

Parameters

Return value

Additional information

This function checks if the specified task is present in the internal task list. When a task is terminated it is removed from the internal task list. In applications that create and terminate tasks dynamically, this function may be useful to determine whether the task control block and stack for one task may be reused for another task.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

128: OS_ERR_INV_TASK
164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintTCBStatus(OS_TASK* pTask) {
  OS_BOOL b;

  b = OS_TASK_IsTask(pTask);
  if (b == 0u) {
    printf("TCB can be reused for another task.\n");
  } else {
    printf("TCB refers to a valid task.\n");
  }
}

OS_TASK_Index2Ptr()

Description

Returns the task control block of the task with the specified Index.

Prototype

OS_TASK *OS_TASK_Index2Ptr(int TaskIndex);

Parameters

Return value

Additional information

The order of the tasks in the task list is not defined by the order of task creation and changes at runtime. Tasks are ordered in the task list by their task priority. Therefore OS_TASK_Index2Ptr() is usually used only to iterate through the complete task list (e.g. to print all task names).

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

128: OS_ERR_INV_TASK
164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

void PrintAllTaskNames(void) {
  OS_TASK* pTask;
  int      TaskIndex;

  TaskIndex = 0;
  OS_TASK_EnterRegion();
  do {
    pTask = OS_TASK_Index2Ptr(TaskIndex);
    if (pTask != NULL) {
      printf("%s\n", pTask->sName);
    }
    TaskIndex++;
  } while (pTask != NULL);
  OS_TASK_LeaveRegion();
}

OS_TASK_RemoveAllTerminateHooks()

Description

Removes all hook functions from the OS_ON_TERMINATE_HOOK list which contains the list of functions that are called when a task is terminated.

Prototype

void OS_TASK_RemoveAllTerminateHooks(void);

Additional information

OS_TASK_RemoveAllTerminateHooks() removes all hook functions which were previously added by OS_TASK_AddTerminateHook().

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

OS_ON_TERMINATE_HOOK _TerminateHook;

void TerminateHookFunc(OS_CONST_PTR OS_TASK* pTask) {
  // This function is called when OS_TASK_Terminate() is called.
  if (pTask == &MyTask) {
    free(MytaskBuffer);
  }
}
...
int main(void) {
  OS_TASK_AddTerminateHook(&_TerminateHook, TerminateHookFunc);
  OS_TASK_RemoveAllTerminateHooks();
  ...
}

OS_TASK_RemoveTerminateHook()

Description

OS_TASK_RemoveTerminateHook() removes the specified hook function from the OS_ON_TERMINATE_HOOK list which contains the list of functions that are called when a task is terminated.

Prototype

void OS_TASK_RemoveTerminateHook(OS_CONST_PTR OS_ON_TERMINATE_HOOK *pHook);

Parameters

Additional information

OS_TASK_RemoveTerminateHook() removes the specified hook routine which was previously added by OS_TASK_AddTerminateHook().

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

OS_ON_TERMINATE_HOOK _TerminateHook;

void TerminateHookFunc(OS_CONST_PTR OS_TASK* pTask) {
  // This function is called when OS_TASK_Terminate() is called.
  if (pTask == &MyTask) {
    free(MytaskBuffer);
  }
}
...
int main(void) {
  OS_TASK_AddTerminateHook(&_TerminateHook, TerminateHookFunc);
  OS_TASK_RemoveTerminateHook(&_TerminateHook);
  ...
}

OS_TASK_Resume()

Description

Resumes the specified suspended task.

Prototype

void OS_TASK_Resume(OS_TASK* pTask);

Parameters

Additional information

OS_TASK_Resume() decrements the specified task’s suspend count. When the resulting value is zero, the execution of the specified task is resumed.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

128: OS_ERR_INV_TASK
161: OS_ERR_ILLEGAL_IN_TIMER
164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL
201: OS_ERR_RESUME_BEFORE_SUSPEND

For details, refer to the chapter Runtime application errors.

Example

Please refer to the example of OS_TASK_Suspend().

OS_TASK_ResumeAll()

Description

Decrements the suspend count of all tasks that have a nonzero suspend count and resumes these tasks when their respective suspend count reaches zero.

Prototype

void OS_TASK_ResumeAll(void);

Additional information

This function may be helpful to synchronize or start multiple tasks at the same time. The function resumes all tasks, no specific task must be addressed. The function may be used together with the functions OS_TASK_SuspendAll() and OS_TASK_SetInitialSuspendCnt().
The function may cause a task switch when a task with higher priority than the calling task is resumed. The task switch will be executed after all suspended tasks are resumed.
The function may be called even when no task is suspended.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

161: OS_ERR_ILLEGAL_IN_TIMER
164: OS_ERR_OS_INT_ENTER_NOT_CALLED
167: OS_ERR_CPU_STATE_ILLEGAL

For details, refer to the chapter Runtime application errors.

Example

Please refer to the example of OS_TASK_SetInitialSuspendCnt().

OS_TASK_SetContextExtension()

Description

Makes global variables or processor registers task-specific. The function may be used for a variety of purposes. Typical applications are:

• Global variables such as “errno” in the C library, making the C-lib functions thread-safe.
• Additional, optional CPU / registers such as MAC / EMAC registers (multiply and accumulate unit) if they are not saved in the task context per default.
• Coprocessor registers such as registers of a VFP (floating-point co-processor).
• Data registers of an additional hardware unit such as a CRC calculation unit.

This allows the user to extend the task context as required. A major advantage is that the task extension is task-specific. This means that the additional information (such as floating-point registers) needs to be saved only by tasks that actually use these registers. The advantage is that the task switching time of other tasks is not affected. The same is true for the required stack space: Additional stack space is required only for the tasks which actually save the additional registers.

Prototype

void OS_TASK_SetContextExtension
                             (OS_CONST_PTR OS_EXTEND_TASK_CONTEXT *pExtendContext);

Parameters

Additional information

The OS_EXTEND_TASK_CONTEXT structure is defined as follows:

typedef struct OS_EXTEND_TASK_CONTEXT {
void* (*pfSave) ( void* pStack);
void* (*pfRestore)(const void* pStack);
} OS_EXTEND_TASK_CONTEXT;

typedef struct OS_EXTEND_TASK_CONTEXT_STRUCT {
void (*pfSave) ( void OS_STACKPTR * pStack);
void (*pfRestore)(const void OS_STACKPTR * pStack);
} OS_EXTEND_TASK_CONTEXT;

pExtendContext, pExtendContext->pfSave and pExtendContext->pfRestore must not be NULL. The save and restore functions must be declared according the function type used in the structure. The sample below shows how the task stack must be addressed to save and restore the extended task context.

The embOS kernel pushes during the context switch the task context on the task stack. The stack pointer value after the push operation is stored in the task control block and passed to the Save routine. The Save routine pushes the extended task context data onto the task stack. To do so it must reserve the necessary bytes on the task stack and return the adjusted stack pointer. The adjusted stack pointer is used for the next task context extension Save routine (if any).

The Restore routines are executed in the same order. For example task context extensions A, B and C are used. When the kernel saves the task context the Save routines of task context extensions A, B and C are called. When the kernel restores the task context the Restore routines of the task context extensions A, B and C are called in the same order.

The embOS OS_LIBMODE_XR library mode does not support task context extension.

Error codes

With embOS debug checks enabled erroneous calls to this function result in OS_Error() being called with one of the following application error IDs:

116: OS_ERR_EXTEND_CONTEXT
128: OS_ERR_INV_TASK
160: OS_ERR_ILLEGAL_IN_ISR
161: OS_ERR_ILLEGAL_IN_TIMER
167: OS_ERR_CPU_STATE_ILLEGAL
226: OS_ERR_ILLEGAL_IN_MAIN

For details, refer to the chapter Runtime application errors.

Example

#include "RTOS.h"

//
// Custom structure with task context extension.
// In this case, the extended task context consists of just
// a single member, which is a global variable.
//
typedef struct {
  int GlobalVar;
} CONTEXT_EXTENSION;

static OS_STACKPTR int StackHP[128], StackLP[128];  // Task stacks
static OS_TASK         TCBHP, TCBLP;                // Task control blocks
static int             GlobalVar;

static void OS_STACKPTR* _Save(void OS_STACKPTR* pStack) {
  CONTEXT_EXTENSION* p;

  p = (CONTEXT_EXTENSION*)pStack;
#if (OS_STACK_GROWS_TOWARD_HIGHER_ADDR == 1)
  p++;
#else
  p--;
#endif
  p->GlobalVar = GlobalVar;
  return (void OS_STACKPTR*)p;
}

static void OS_STACKPTR* _Restore(const void OS_STACKPTR* pStack) {
  const CONTEXT_EXTENSION* p;

  p = (CONTEXT_EXTENSION*)pStack;
#if (OS_STACK_GROWS_TOWARD_HIGHER_ADDR == 1)
  p++;
#else
  p--;
#endif
  GlobalVar = p->GlobalVar;
  return (void OS_STACKPTR*)p;
}

const OS_EXTEND_TASK_CONTEXT _SaveRestore = {
  _Save,    // Function pointer to save the task context
  _Restore  // Function pointer to restore the task context
};

static void HPTask(void) {
  OS_TASK_SetContextExtension(&_SaveRestore);
  GlobalVar = 1;
  while (1) {
    OS_TASK_Delay(10);
  }
}

static void LPTask(void) {
  OS_TASK_SetContextExtension(&_SaveRestore);
  GlobalVar = 2;
  while (1) {
    OS_TASK_Delay(50);
  }
}

int main(void) {
  OS_Init();      // Initialize embOS
  OS_InitHW();    // Initialize required hardware
  OS_TASK_CREATE(&TCBHP, "HP Task", 100, HPTask, StackHP);
  OS_TASK_CREATE(&TCBLP, "LP Task",  50, LPTask, StackLP);
  OS_Start();     // Start embOS
  return 0;
}