RTEMS C User’s Guide¶

3.2.1. Object Names¶

An object name is an unsigned thirty-two bit entity associated with the object by the user. The data type rtems_name is used to store object names... index:: rtems_build_name

Although not required by RTEMS, object names are often composed of four ASCII characters which help identify that object. For example, a task which causes a light to blink might be called “LITE”. The rtems_build_name routine is provided to build an object name from four ASCII characters. The following example illustrates this:

rtems_name my_name;
my_name = rtems_build_name( 'L', 'I', 'T', 'E' );

However, it is not required that the application use ASCII characters to build object names. For example, if an application requires one-hundred tasks, it would be difficult to assign meaningful ASCII names to each task. A more convenient approach would be to name them the binary values one through one-hundred, respectively.

RTEMS provides a helper routine, rtems_object_get_name, which can be used to obtain the name of any RTEMS object using just its ID. This routine attempts to convert the name into a printable string.

The following example illustrates the use of this method to print an object name:

#include <rtems.h>
#include <rtems/bspIo.h>
void print_name(rtems_id id)
{
    char  buffer[10];   /* name assumed to be 10 characters or less */
    char *result;
    result = rtems_object_get_name( id, sizeof(buffer), buffer );
    printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
}

3.2.2. Object IDs¶

An object ID is a unique unsigned integer value which uniquely identifies an object instance. Object IDs are passed as arguments to many directives in RTEMS and RTEMS translates the ID to an internal object pointer. The efficient manipulation of object IDs is critical to the performance of RTEMS services. Because of this, there are two object Id formats defined. Each target architecture specifies which format it will use. There is a thirty-two bit format which is used for most of the supported architectures and supports multiprocessor configurations. There is also a simpler sixteen bit format which is appropriate for smaller target architectures and does not support multiprocessor configurations.

31      27 26   24 23          16 15                             0
+---------+-------+--------------+-------------------------------+
|         |       |              |                               |
|  Class  |  API  |     Node     |             Index             |
|         |       |              |                               |
+---------+-------+--------------+-------------------------------+

15      11 10    8 7            0
+---------+-------+--------------+
|         |       |              |
|  Class  |  API  |    Index     |
|         |       |              |
+---------+-------+--------------+

3.2.3. Object ID Description¶

The components of an object ID make it possible to quickly locate any object in even the most complicated multiprocessor system. Object ID’s are associated with an object by RTEMS when the object is created and the corresponding ID is returned by the appropriate object create directive. The object ID is required as input to all directives involving objects, except those which create an object or obtain the ID of an object.

The object identification directives can be used to dynamically obtain a particular object’s ID given its name. This mapping is accomplished by searching the name table associated with this object type. If the name is non-unique, then the ID associated with the first occurrence of the name will be returned to the application. Since object IDs are returned when the object is created, the object identification directives are not necessary in a properly designed single processor application.

In addition, services are provided to portably examine the subcomponents of an RTEMS ID. These services are described in detail later in this manual but are prototyped as follows:

uint32_t rtems_object_id_get_api( rtems_id );
uint32_t rtems_object_id_get_class( rtems_id );
uint32_t rtems_object_id_get_node( rtems_id );
uint32_t rtems_object_id_get_index( rtems_id );

An object control block is a data structure defined by RTEMS which contains the information necessary to manage a particular object type. For efficiency reasons, the format of each object type’s control block is different. However, many of the fields are similar in function. The number of each type of control block is application dependent and determined by the values specified in the user’s Configuration Table. An object control block is allocated at object create time and freed when the object is deleted. With the exception of user extension routines, object control blocks are not directly manipulated by user applications.

5.2.1. Priority Scheduling¶

When using priority based scheduling, RTEMS allocates the processor using a priority-based, preemptive algorithm augmented to provide round-robin characteristics within individual priority groups. The goal of this algorithm is to guarantee that the task which is executing on the processor at any point in time is the one with the highest priority among all tasks in the ready state.

When a task is added to the ready chain, it is placed behind all other tasks of the same priority. This rule provides a round-robin within priority group scheduling characteristic. This means that in a group of equal priority tasks, tasks will execute in the order they become ready or FIFO order. Even though there are ways to manipulate and adjust task priorities, the most important rule to remember is:

Priority scheduling is the most commonly used scheduling algorithm. It should be used by applications in which multiple tasks contend for CPU time or other resources and there is a need to ensure certain tasks are given priority over other tasks.

There are a few common methods of accomplishing the mechanics of this algorithm. These ways involve a list or chain of tasks in the ready state.

• The least efficient method is to randomly place tasks in the ready chain forcing the scheduler to scan the entire chain to determine which task receives the processor.
• A more efficient method is to schedule the task by placing it in the proper place on the ready chain based on the designated scheduling criteria at the time it enters the ready state. Thus, when the processor is free, the first task on the ready chain is allocated the processor.
• Another mechanism is to maintain a list of FIFOs per priority. When a task is readied, it is placed on the rear of the FIFO for its priority. This method is often used with a bitmap to assist in locating which FIFOs have ready tasks on them.

RTEMS currently includes multiple priority based scheduling algorithms as well as other algorithms which incorporate deadline. Each algorithm is discussed in the following sections.

5.2.2. Deterministic Priority Scheduler¶

This is the scheduler implementation which has always been in RTEMS. After the 4.10 release series, it was factored into pluggable scheduler selection. It schedules tasks using a priority based algorithm which takes into account preemption. It is implemented using an array of FIFOs with a FIFO per priority. It maintains a bitmap which is used to track which priorities have ready tasks.

This algorithm is deterministic (e.g. predictable and fixed) in execution time. This comes at the cost of using slightly over three (3) kilobytes of RAM on a system configured to support 256 priority levels.

This scheduler is only aware of a single core.

5.2.3. Simple Priority Scheduler¶

This scheduler implementation has the same behaviour as the Deterministic Priority Scheduler but uses only one linked list to manage all ready tasks. When a task is readied, a linear search of that linked list is performed to determine where to insert the newly readied task.

This algorithm uses much less RAM than the Deterministic Priority Scheduler but is O(n) where n is the number of ready tasks. In a small system with a small number of tasks, this will not be a performance issue. Reducing RAM consumption is often critical in small systems which are incapable of supporting a large number of tasks.

This scheduler is only aware of a single core.

5.2.4. Simple SMP Priority Scheduler¶

This scheduler is based upon the Simple Priority Scheduler and is designed to have the same behaviour on a single core system. But this scheduler is capable of scheduling threads across multiple cores in an SMP system. When given a choice of replacing one of two threads at equal priority on different cores, this algorithm favors replacing threads which are preemptible and have executed the longest.

This algorithm is non-deterministic. When scheduling, it must consider which tasks are to be executed on each core while avoiding superfluous task migrations.

5.2.5. Earliest Deadline First Scheduler¶

This is an alternative scheduler in RTEMS for single core applications. The primary EDF advantage is high total CPU utilization (theoretically up to 100%). It assumes that tasks have priorities equal to deadlines.

This EDF is initially preemptive, however, individual tasks may be declared not-preemptive. Deadlines are declared using only Rate Monotonic manager which goal is to handle periodic behavior. Period is always equal to deadline. All ready tasks reside in a single ready queue implemented using a red-black tree.

This implementation of EDF schedules two different types of task priority types while each task may switch between the two types within its execution. If a task does have a deadline declared using the Rate Monotonic manager, the task is deadline-driven and its priority is equal to deadline. On the contrary if a task does not have any deadline or the deadline is cancelled using the Rate Monotonic manager, the task is considered a background task with priority equal to that assigned upon initialization in the same manner as for priority scheduler. Each background task is of a lower importance than each deadline-driven one and is scheduled when no deadline-driven task and no higher priority background task is ready to run.

Every deadline-driven scheduling algorithm requires means for tasks to claim a deadline. The Rate Monotonic Manager is responsible for handling periodic execution. In RTEMS periods are equal to deadlines, thus if a task announces a period, it has to be finished until the end of this period. The call of rtems_rate_monotonic_period passes the scheduler the length of oncoming deadline. Moreover, the rtems_rate_monotonic_cancel and rtems_rate_monotonic_delete calls clear the deadlines assigned to the task.

5.2.6. Constant Bandwidth Server Scheduling (CBS)¶

This is an alternative scheduler in RTEMS for single core applications. The CBS is a budget aware extension of EDF scheduler. The main goal of this scheduler is to ensure temporal isolation of tasks meaning that a task’s execution in terms of meeting deadlines must not be influenced by other tasks as if they were run on multiple independent processors.

Each task can be assigned a server (current implementation supports only one task per server). The server is characterized by period (deadline) and computation time (budget). The ratio budget/period yields bandwidth, which is the fraction of CPU to be reserved by the scheduler for each subsequent period.

The CBS is equipped with a set of rules applied to tasks attached to servers ensuring that deadline miss because of another task cannot occur. In case a task breaks one of the rules, its priority is pulled to background until the end of its period and then restored again. The rules are:

• Task cannot exceed its registered budget,
• Task cannot be unblocked when a ratio between remaining budget and remaining deadline is higher than declared bandwidth.

The CBS provides an extensive API. Unlike EDF, the rtems_rate_monotonic_period does not declare a deadline because it is carried out using CBS API. This call only announces next period.

5.3.1. Task Priority and Scheduling¶

The most significant task scheduling modification mechanism is the ability for the user to assign a priority level to each individual task when it is created and to alter a task’s priority at run-time. RTEMS supports up to 255 priority levels. Level 255 is the lowest priority and level 1 is the highest.

5.3.2. Preemption¶

Another way the user can alter the basic scheduling algorithm is by manipulating the preemption mode flag (RTEMS_PREEMPT_MASK) of individual tasks. If preemption is disabled for a task (RTEMS_NO_PREEMPT), then the task will not relinquish control of the processor until it terminates, blocks, or re-enables preemption. Even tasks which become ready to run and possess higher priority levels will not be allowed to execute. Note that the preemption setting has no effect on the manner in which a task is scheduled. It only applies once a task has control of the processor.

5.3.3. Timeslicing¶

Timeslicing or round-robin scheduling is an additional method which can be used to alter the basic scheduling algorithm. Like preemption, timeslicing is specified on a task by task basis using the timeslicing mode flag (RTEMS_TIMESLICE_MASK). If timeslicing is enabled for a task (RTEMS_TIMESLICE), then RTEMS will limit the amount of time the task can execute before the processor is allocated to another task. Each tick of the real-time clock reduces the currently running task’s timeslice. When the execution time equals the timeslice, RTEMS will dispatch another task of the same priority to execute. If there are no other tasks of the same priority ready to execute, then the current task is allocated an additional timeslice and continues to run. Remember that a higher priority task will preempt the task (unless preemption is disabled) as soon as it is ready to run, even if the task has not used up its entire timeslice.

5.3.4. Manual Round-Robin¶

The final mechanism for altering the RTEMS scheduling algorithm is called manual round-robin. Manual round-robin is invoked by using the rtems_task_wake_after directive with a time interval of RTEMS_YIELD_PROCESSOR. This allows a task to give up the processor and be immediately returned to the ready chain at the end of its priority group. If no other tasks of the same priority are ready to run, then the task does not lose control of the processor.

6.2.1. Initialization Tasks¶

Initialization task(s) are the mechanism by which RTEMS transfers initial control to the user’s application. Initialization tasks differ from other application tasks in that they are defined in the User Initialization Tasks Table and automatically created and started by RTEMS as part of its initialization sequence. Since the initialization tasks are scheduled using the same algorithm as all other RTEMS tasks, they must be configured at a priority and mode which will ensure that they will complete execution before other application tasks execute. Although there is no upper limit on the number of initialization tasks, an application is required to define at least one.

A typical initialization task will create and start the static set of application tasks. It may also create any other objects used by the application. Initialization tasks which only perform initialization should delete themselves upon completion to free resources for other tasks. Initialization tasks may transform themselves into a “normal” application task. This transformation typically involves changing priority and execution mode. RTEMS does not automatically delete the initialization tasks.

6.2.2. System Initialization¶

System Initialization begins with board reset and continues through RTEMS initialization, initialization of all device drivers, and eventually a context switch to the first user task. Remember, that interrupts are disabled during initialization and the initialization context is not a task in any sense and the user should be very careful during initialization.

The BSP must ensure that the there is enough stack space reserved for the initialization context to successfully execute the initialization routines for all device drivers and, in multiprocessor configurations, the Multiprocessor Communications Interface Layer initialization routine.

6.2.3. The Idle Task¶

The Idle Task is the lowest priority task in a system and executes only when no other task is ready to execute. This default implementation of this task consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by a CPU specific implementation, a BSP specific implementation or an application specific implementation.

The Idle Task is preemptible and WILL be preempted when any other task is made ready to execute. This characteristic is critical to the overall behavior of any application.

6.2.4. Initialization Manager Failure¶

The rtems_fatal_error_occurred directive will be invoked from rtems_initialize_executive for any of the following reasons:

• If either the Configuration Table or the CPU Dependent Information Table is not provided.
• If the starting address of the RTEMS RAM Workspace, supplied by the application in the Configuration Table, is NULL or is not aligned on a four-byte boundary.
• If the size of the RTEMS RAM Workspace is not large enough to initialize and configure the system.
• If the interrupt stack size specified is too small.
• If multiprocessing is configured and the node entry in the Multiprocessor Configuration Table is not between one and the maximum_nodes entry.
• If a multiprocessor system is being configured and no Multiprocessor Communications Interface is specified.
• If no user initialization tasks are configured. At least one initialization task must be configured to allow RTEMS to pass control to the application at the end of the executive initialization sequence.
• If any of the user initialization tasks cannot be created or started successfully.

A discussion of RTEMS actions when a fatal error occurs may be found Chapter 21 Section 3.1 - Announcing a Fatal Error.

6.3.1. Initializing RTEMS¶

The Initialization Manager rtems_initialize_executive directives is called by the boot_card routine. The boot_card routine is invoked by the Board Support Package once a basic C run-time environment is set up. This consists of

• a valid and accessible text section, read-only data, read-write data and zero-initialized data,
• an initialization stack large enough to initialize the rest of the Board Support Package, RTEMS and the device drivers,
• all registers and components mandated by Application Binary Interface, and
• disabled interrupts.

The rtems_initialize_executive directive uses a system initialization linker set to initialize only those parts of the overall RTEMS feature set that is necessary for a particular application. See Chapter 36 - Linker Sets. Each RTEMS feature used the application may optionally register an initialization handler. The system initialization API is available via``#included <rtems/sysinit.h>``.

A list of all initialization steps follows. Some steps are optional depending on the requested feature set of the application. The initialization steps are execute in the order presented here.

RTEMS_SYSINIT_BSP_WORK_AREAS

The work areas consisting of C Program Heap and the RTEMS Workspace are initialized by the Board Support Package. This step is mandatory.

RTEMS_SYSINIT_BSP_START

Basic initialization step provided by the Board Support Package. This step is mandatory.

RTEMS_SYSINIT_DATA_STRUCTURES

This directive is called when the Board Support Package has completed its basic initialization and allows RTEMS to initialize the application environment based upon the information in the Configuration Table, User Initialization Tasks Table, Device Driver Table, User Extension Table, Multiprocessor Configuration Table, and the Multiprocessor Communications Interface (MPCI) Table.

RTEMS_SYSINIT_BSP_LIBC

Depending on the application configuration the IO library and root filesystem is initialized. This step is mandatory.

RTEMS_SYSINIT_BEFORE_DRIVERS

This directive performs initialization that must occur between basis RTEMS data structure initialization and device driver initialization. In particular, in a multiprocessor configuration, this directive will create the MPCI Server Task.

RTEMS_SYSINIT_BSP_PRE_DRIVERS

Initialization step performed right before device drivers are initialized provided by the Board Support Package. This step is mandatory.

RTEMS_SYSINIT_DEVICE_DRIVERS

This step initializes all statically configured device drivers and performs all RTEMS initialization which requires device drivers to be initialized. This step is mandatory. In a multiprocessor configuration, this service will initialize the Multiprocessor Communications Interface (MPCI) and synchronize with the other nodes in the system.

RTEMS_SYSINIT_BSP_POST_DRIVERS

Initialization step performed right after device drivers are initialized provided by the Board Support Package. This step is mandatory.

The final action of the rtems_initialize_executive directive is to start multitasking. RTEMS does not return to the initialization context and the initialization stack may be re-used for interrupt processing.

Many of RTEMS actions during initialization are based upon the contents of the Configuration Table. For more information regarding the format and contents of this table, please refer to the chapter Chapter 24 - Configuring a System.

The final action in the initialization sequence is the initiation of multitasking. When the scheduler and dispatcher are enabled, the highest priority, ready task will be dispatched to run. Control will not be returned to the Board Support Package after multitasking is enabled. The initialization stack may be re-used for interrupt processing.

6.3.2. Shutting Down RTEMS¶

The rtems_shutdown_executive directive is invoked by the application to end multitasking and terminate the system.

6.4.1. INITIALIZE_EXECUTIVE - Initialize RTEMS¶

CALLING SEQUENCE:

void rtems_initialize_executive(void);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

Iterates through the system initialization linker set and invokes the registered handlers. The final step is to start multitasking.

NOTES:

This directive should be called by boot_card only.

This directive does not return to the caller. Errors in the initialization sequence are usually fatal and lead to a system termination.

6.4.2. SHUTDOWN_EXECUTIVE - Shutdown RTEMS¶

CALLING SEQUENCE:

void rtems_shutdown_executive(
    uint32_t result
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive is called when the application wishes to shutdown RTEMS. The system is terminated with a fatal source of RTEMS_FATAL_SOURCE_EXIT and the specified result code.

NOTES:

This directive must be the last RTEMS directive invoked by an application and it does not return to the caller.

This directive may be called any time.

7.2.1. Task Definition¶

Many definitions of a task have been proposed in computer literature. Unfortunately, none of these definitions encompasses all facets of the concept in a manner which is operating system independent. Several of the more common definitions are provided to enable each user to select a definition which best matches their own experience and understanding of the task concept:

• a “dispatchable” unit.
• an entity to which the processor is allocated.
• an atomic unit of a real-time, multiprocessor system.
• single threads of execution which concurrently compete for resources.
• a sequence of closely related computations which can execute concurrently with other computational sequences.

From RTEMS’ perspective, a task is the smallest thread of execution which can compete on its own for system resources. A task is manifested by the existence of a task control block (TCB).

7.2.2. Task Control Block¶

The Task Control Block (TCB) is an RTEMS defined data structure which contains all the information that is pertinent to the execution of a task. During system initialization, RTEMS reserves a TCB for each task configured. A TCB is allocated upon creation of the task and is returned to the TCB free list upon deletion of the task.

The TCB’s elements are modified as a result of system calls made by the application in response to external and internal stimuli. TCBs are the only RTEMS internal data structure that can be accessed by an application via user extension routines. The TCB contains a task’s name, ID, current priority, current and starting states, execution mode, TCB user extension pointer, scheduling control structures, as well as data required by a blocked task.

A task’s context is stored in the TCB when a task switch occurs. When the task regains control of the processor, its context is restored from the TCB. When a task is restarted, the initial state of the task is restored from the starting context area in the task’s TCB.

7.2.3. Task States¶

A task may exist in one of the following five states:

• executing - Currently scheduled to the CPU
• ready - May be scheduled to the CPU
• blocked - Unable to be scheduled to the CPU
• dormant - Created task that is not started
• non-existent - Uncreated or deleted task

An active task may occupy the executing, ready, blocked or dormant state, otherwise the task is considered non-existent. One or more tasks may be active in the system simultaneously. Multiple tasks communicate, synchronize, and compete for system resources with each other via system calls. The multiple tasks appear to execute in parallel, but actually each is dispatched to the CPU for periods of time determined by the RTEMS scheduling algorithm. The scheduling of a task is based on its current state and priority.

7.2.4. Task Priority¶

A task’s priority determines its importance in relation to the other tasks executing on the same processor. RTEMS supports 255 levels of priority ranging from 1 to 255. The data type rtems_task_priority is used to store task priorities.

Tasks of numerically smaller priority values are more important tasks than tasks of numerically larger priority values. For example, a task at priority level 5 is of higher privilege than a task at priority level 10. There is no limit to the number of tasks assigned to the same priority.

Each task has a priority associated with it at all times. The initial value of this priority is assigned at task creation time. The priority of a task may be changed at any subsequent time.

Priorities are used by the scheduler to determine which ready task will be allowed to execute. In general, the higher the logical priority of a task, the more likely it is to receive processor execution time.

7.2.5. Task Mode¶

A task’s execution mode is a combination of the following four components:

• preemption
• ASR processing
• timeslicing
• interrupt level

It is used to modify RTEMS’ scheduling process and to alter the execution environment of the task. The data type rtems_task_mode is used to manage the task execution mode.

The preemption component allows a task to determine when control of the processor is relinquished. If preemption is disabled (RTEMS_NO_PREEMPT), the task will retain control of the processor as long as it is in the executing state - even if a higher priority task is made ready. If preemption is enabled (RTEMS_PREEMPT) and a higher priority task is made ready, then the processor will be taken away from the current task immediately and given to the higher priority task.

The timeslicing component is used by the RTEMS scheduler to determine how the processor is allocated to tasks of equal priority. If timeslicing is enabled (RTEMS_TIMESLICE), then RTEMS will limit the amount of time the task can execute before the processor is allocated to another ready task of equal priority. The length of the timeslice is application dependent and specified in the Configuration Table. If timeslicing is disabled (RTEMS_NO_TIMESLICE), then the task will be allowed to execute until a task of higher priority is made ready. If RTEMS_NO_PREEMPT is selected, then the timeslicing component is ignored by the scheduler.

The asynchronous signal processing component is used to determine when received signals are to be processed by the task. If signal processing is enabled (RTEMS_ASR), then signals sent to the task will be processed the next time the task executes. If signal processing is disabled (RTEMS_NO_ASR), then all signals received by the task will remain posted until signal processing is enabled. This component affects only tasks which have established a routine to process asynchronous signals.

The interrupt level component is used to determine which interrupts will be enabled when the task is executing. RTEMS_INTERRUPT_LEVEL(n) specifies that the task will execute at interrupt level n.

The set of default modes may be selected by specifying the RTEMS_DEFAULT_MODES constant.

7.2.6. Accessing Task Arguments¶

All RTEMS tasks are invoked with a single argument which is specified when they are started or restarted. The argument is commonly used to communicate startup information to the task. The simplest manner in which to define a task which accesses it argument is:

rtems_task user_task(
    rtems_task_argument argument
);

Application tasks requiring more information may view this single argument as an index into an array of parameter blocks.

7.2.7. Floating Point Considerations¶

Creating a task with the RTEMS_FLOATING_POINT attribute flag results in additional memory being allocated for the TCB to store the state of the numeric coprocessor during task switches. This additional memory is NOT allocated for RTEMS_NO_FLOATING_POINT tasks. Saving and restoring the context of a RTEMS_FLOATING_POINT task takes longer than that of a RTEMS_NO_FLOATING_POINT task because of the relatively large amount of time required for the numeric coprocessor to save or restore its computational state.

Since RTEMS was designed specifically for embedded military applications which are floating point intensive, the executive is optimized to avoid unnecessarily saving and restoring the state of the numeric coprocessor. The state of the numeric coprocessor is only saved when a RTEMS_FLOATING_POINT task is dispatched and that task was not the last task to utilize the coprocessor. In a system with only one RTEMS_FLOATING_POINT task, the state of the numeric coprocessor will never be saved or restored.

Although the overhead imposed by RTEMS_FLOATING_POINT tasks is minimal, some applications may wish to completely avoid the overhead associated with RTEMS_FLOATING_POINT tasks and still utilize a numeric coprocessor. By preventing a task from being preempted while performing a sequence of floating point operations, a RTEMS_NO_FLOATING_POINT task can utilize the numeric coprocessor without incurring the overhead of a RTEMS_FLOATING_POINT context switch. This approach also avoids the allocation of a floating point context area. However, if this approach is taken by the application designer, NO tasks should be created as RTEMS_FLOATING_POINT tasks. Otherwise, the floating point context will not be correctly maintained because RTEMS assumes that the state of the numeric coprocessor will not be altered by RTEMS_NO_FLOATING_POINT tasks.

If the supported processor type does not have hardware floating capabilities or a standard numeric coprocessor, RTEMS will not provide built-in support for hardware floating point on that processor. In this case, all tasks are considered RTEMS_NO_FLOATING_POINT whether created as RTEMS_FLOATING_POINT or RTEMS_NO_FLOATING_POINT tasks. A floating point emulation software library must be utilized for floating point operations.

On some processors, it is possible to disable the floating point unit dynamically. If this capability is supported by the target processor, then RTEMS will utilize this capability to enable the floating point unit only for tasks which are created with the RTEMS_FLOATING_POINT attribute. The consequence of a RTEMS_NO_FLOATING_POINT task attempting to access the floating point unit is CPU dependent but will generally result in an exception condition.

7.2.8. Per Task Variables¶

Per task variables are deprecated, see the warning below.

Per task variables are used to support global variables whose value may be unique to a task. After indicating that a variable should be treated as private (i.e. per-task) the task can access and modify the variable, but the modifications will not appear to other tasks, and other tasks’ modifications to that variable will not affect the value seen by the task. This is accomplished by saving and restoring the variable’s value each time a task switch occurs to or from the calling task.

The value seen by other tasks, including those which have not added the variable to their set and are thus accessing the variable as a common location shared among tasks, cannot be affected by a task once it has added a variable to its local set. Changes made to the variable by other tasks will not affect the value seen by a task which has added the variable to its private set.

This feature can be used when a routine is to be spawned repeatedly as several independent tasks. Although each task will have its own stack, and thus separate stack variables, they will all share the same static and global variables. To make a variable not shareable (i.e. a “global” variable that is specific to a single task), the tasks can call rtems_task_variable_add to make a separate copy of the variable for each task, but all at the same physical address.

Task variables increase the context switch time to and from the tasks that own them so it is desirable to minimize the number of task variables. One efficient method is to have a single task variable that is a pointer to a dynamically allocated structure containing the task’s private “global” data.

A critical point with per-task variables is that each task must separately request that the same global variable is per-task private.

7.2.9. Building a Task Attribute Set¶

In general, an attribute set is built by a bitwise OR of the desired components. The set of valid task attribute components is listed below:

Attribute values are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list. A component listed as a default is not required to appear in the component list, although it is a good programming practice to specify default components. If all defaults are desired, then RTEMS_DEFAULT_ATTRIBUTES should be used.

This example demonstrates the attribute_set parameter needed to create a local task which utilizes the numeric coprocessor. The attribute_set parameter could be RTEMS_FLOATING_POINT or RTEMS_LOCAL | RTEMS_FLOATING_POINT. The attribute_set parameter can be set to RTEMS_FLOATING_POINT because RTEMS_LOCAL is the default for all created tasks. If the task were global and used the numeric coprocessor, then the attribute_set parameter would be RTEMS_GLOBAL | RTEMS_FLOATING_POINT.

7.2.10. Building a Mode and Mask¶

In general, a mode and its corresponding mask is built by a bitwise OR of the desired components. The set of valid mode constants and each mode’s corresponding mask constant is listed below:

Mode values are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each mode appears exactly once in the component list. A mode component listed as a default is not required to appear in the mode component list, although it is a good programming practice to specify default components. If all defaults are desired, the mode RTEMS_DEFAULT_MODES and the mask RTEMS_ALL_MODE_MASKS should be used.

The following example demonstrates the mode and mask parameters used with the rtems_task_mode directive to place a task at interrupt level 3 and make it non-preemptible. The mode should be set to RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT to indicate the desired preemption mode and interrupt level, while the mask parameter should be set to RTEMS_INTERRUPT_MASK | RTEMS_NO_PREEMPT_MASK to indicate that the calling task’s interrupt level and preemption mode are being altered.

7.3.1. Creating Tasks¶

The rtems_task_create directive creates a task by allocating a task control block, assigning the task a user-specified name, allocating it a stack and floating point context area, setting a user-specified initial priority, setting a user-specified initial mode, and assigning it a task ID. Newly created tasks are initially placed in the dormant state. All RTEMS tasks execute in the most privileged mode of the processor.

7.3.2. Obtaining Task IDs¶

When a task is created, RTEMS generates a unique task ID and assigns it to the created task until it is deleted. The task ID may be obtained by either of two methods. First, as the result of an invocation of the rtems_task_create directive, the task ID is stored in a user provided location. Second, the task ID may be obtained later using the rtems_task_ident directive. The task ID is used by other directives to manipulate this task.

7.3.3. Starting and Restarting Tasks¶

The rtems_task_start directive is used to place a dormant task in the ready state. This enables the task to compete, based on its current priority, for the processor and other system resources. Any actions, such as suspension or change of priority, performed on a task prior to starting it are nullified when the task is started.

With the rtems_task_start directive the user specifies the task’s starting address and argument. The argument is used to communicate some startup information to the task. As part of this directive, RTEMS initializes the task’s stack based upon the task’s initial execution mode and start address. The starting argument is passed to the task in accordance with the target processor’s calling convention.

The rtems_task_restart directive restarts a task at its initial starting address with its original priority and execution mode, but with a possibly different argument. The new argument may be used to distinguish between the original invocation of the task and subsequent invocations. The task’s stack and control block are modified to reflect their original creation values. Although references to resources that have been requested are cleared, resources allocated by the task are NOT automatically returned to RTEMS. A task cannot be restarted unless it has previously been started (i.e. dormant tasks cannot be restarted). All restarted tasks are placed in the ready state.

7.3.4. Suspending and Resuming Tasks¶

The rtems_task_suspend directive is used to place either the caller or another task into a suspended state. The task remains suspended until a rtems_task_resume directive is issued. This implies that a task may be suspended as well as blocked waiting either to acquire a resource or for the expiration of a timer.

The rtems_task_resume directive is used to remove another task from the suspended state. If the task is not also blocked, resuming it will place it in the ready state, allowing it to once again compete for the processor and resources. If the task was blocked as well as suspended, this directive clears the suspension and leaves the task in the blocked state.

Suspending a task which is already suspended or resuming a task which is not suspended is considered an error. The rtems_task_is_suspended can be used to determine if a task is currently suspended.

7.3.5. Delaying the Currently Executing Task¶

The rtems_task_wake_after directive creates a sleep timer which allows a task to go to sleep for a specified interval. The task is blocked until the delay interval has elapsed, at which time the task is unblocked. A task calling the rtems_task_wake_after directive with a delay interval of RTEMS_YIELD_PROCESSOR ticks will yield the processor to any other ready task of equal or greater priority and remain ready to execute.

The rtems_task_wake_when directive creates a sleep timer which allows a task to go to sleep until a specified date and time. The calling task is blocked until the specified date and time has occurred, at which time the task is unblocked.

7.3.6. Changing Task Priority¶

The rtems_task_set_priority directive is used to obtain or change the current priority of either the calling task or another task. If the new priority requested is RTEMS_CURRENT_PRIORITY or the task’s actual priority, then the current priority will be returned and the task’s priority will remain unchanged. If the task’s priority is altered, then the task will be scheduled according to its new priority.

The rtems_task_restart directive resets the priority of a task to its original value.

7.3.7. Changing Task Mode¶

The rtems_task_mode directive is used to obtain or change the current execution mode of the calling task. A task’s execution mode is used to enable preemption, timeslicing, ASR processing, and to set the task’s interrupt level.

The rtems_task_restart directive resets the mode of a task to its original value.

7.3.8. Notepad Locations¶

RTEMS provides sixteen notepad locations for each task. Each notepad location may contain a note consisting of four bytes of information. RTEMS provides two directives, rtems_task_set_note and rtems_task_get_note, that enable a user to access and change the notepad locations. The rtems_task_set_note directive enables the user to set a task’s notepad entry to a specified note. The rtems_task_get_note directive allows the user to obtain the note contained in any one of the sixteen notepads of a specified task.

7.3.9. Task Deletion¶

RTEMS provides the rtems_task_delete directive to allow a task to delete itself or any other task. This directive removes all RTEMS references to the task, frees the task’s control block, removes it from resource wait queues, and deallocates its stack as well as the optional floating point context. The task’s name and ID become inactive at this time, and any subsequent references to either of them is invalid. In fact, RTEMS may reuse the task ID for another task which is created later in the application.

Unexpired delay timers (i.e. those used by rtems_task_wake_after and rtems_task_wake_when) and timeout timers associated with the task are automatically deleted, however, other resources dynamically allocated by the task are NOT automatically returned to RTEMS. Therefore, before a task is deleted, all of its dynamically allocated resources should be deallocated by the user. This may be accomplished by instructing the task to delete itself rather than directly deleting the task. Other tasks may instruct a task to delete itself by sending a “delete self” message, event, or signal, or by restarting the task with special arguments which instruct the task to delete itself.

7.3.10. Transition Advice for Obsolete Directives¶

7.4.1. TASK_CREATE - Create a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_create(
    rtems_name           name,
    rtems_task_priority  initial_priority,
    size_t               stack_size,
    rtems_mode           initial_modes,
    rtems_attribute      attribute_set,
    rtems_id            *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task created successfully
RTEMS_INVALID_ADDRESS	id is NULL
RTEMS_INVALID_NAME	invalid task name
RTEMS_INVALID_PRIORITY	invalid task priority
RTEMS_MP_NOT_CONFIGURED	multiprocessing not configured
RTEMS_TOO_MANY	too many tasks created
RTEMS_UNSATISFIED	not enough memory for stack/FP context
RTEMS_TOO_MANY	too many global objects

DESCRIPTION:

This directive creates a task which resides on the local node. It allocates and initializes a TCB, a stack, and an optional floating point context area. The mode parameter contains values which sets the task’s initial execution mode. The RTEMS_FLOATING_POINT attribute should be specified if the created task is to use a numeric coprocessor. For performance reasons, it is recommended that tasks not using the numeric coprocessor should specify the RTEMS_NO_FLOATING_POINT attribute. If the RTEMS_GLOBAL attribute is specified, the task can be accessed from remote nodes. The task id, returned in id, is used in other task related directives to access the task. When created, a task is placed in the dormant state and can only be made ready to execute using the directive rtems_task_start.

NOTES:

This directive will not cause the calling task to be preempted.

Valid task priorities range from a high of 1 to a low of 255.

If the requested stack size is less than the configured minimum stack size, then RTEMS will use the configured minimum as the stack size for this task. In addition to being able to specify the task stack size as a integer, there are two constants which may be specified:

RTEMS_MINIMUM_STACK_SIZE

The minimum stack size RECOMMENDED for use on this processor. This value is selected by the RTEMS developers conservatively to minimize the risk of blown stacks for most user applications. Using this constant when specifying the task stack size, indicates that the stack size will be at least RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured minimum stack size is larger than the recommended minimum, then it will be used.

RTEMS_CONFIGURED_MINIMUM_STACK_SIZE

Indicates this task is to be created with a stack size of the minimum stack size that was configured by the application. If not explicitly configured by the application, the default configured minimum stack size is the processor dependent value RTEMS_MINIMUM_STACK_SIZE. Since this uses the configured minimum stack size value, you may get a stack size that is smaller or larger than the recommended minimum. This can be used to provide large stacks for all tasks on complex applications or small stacks on applications that are trying to conserve memory.

Application developers should consider the stack usage of the device drivers when calculating the stack size required for tasks which utilize the driver.

The following task attribute constants are defined by RTEMS:

RTEMS_NO_FLOATING_POINT	does not use coprocessor (default)
RTEMS_FLOATING_POINT	uses numeric coprocessor
RTEMS_LOCAL	local task (default)
RTEMS_GLOBAL	global task

The following task mode constants are defined by RTEMS:

RTEMS_PREEMPT	enable preemption (default)
RTEMS_NO_PREEMPT	disable preemption
RTEMS_NO_TIMESLICE	disable timeslicing (default)
RTEMS_TIMESLICE	enable timeslicing
RTEMS_ASR	enable ASR processing (default)
RTEMS_NO_ASR	disable ASR processing
RTEMS_INTERRUPT_LEVEL(0)	enable all interrupts (default)
RTEMS_INTERRUPT_LEVEL(n)	execute at interrupt level n

The interrupt level portion of the task execution mode supports a maximum of 256 interrupt levels. These levels are mapped onto the interrupt levels actually supported by the target processor in a processor dependent fashion.

Tasks should not be made global unless remote tasks must interact with them. This avoids the system overhead incurred by the creation of a global task. When a global task is created, the task’s name and id must be transmitted to every node in the system for insertion in the local copy of the global object table.

The total number of global objects, including tasks, is limited by the maximum_global_objects field in the Configuration Table.

7.4.2. TASK_IDENT - Get ID of a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_ident(
    rtems_name  name,
    uint32_t    node,
    rtems_id   *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task identified successfully
RTEMS_INVALID_ADDRESS	id is NULL
RTEMS_INVALID_NAME	invalid task name
RTEMS_INVALID_NODE	invalid node id

DESCRIPTION:

This directive obtains the task id associated with the task name specified in name. A task may obtain its own id by specifying RTEMS_SELF or its own task name in name. If the task name is not unique, then the task id returned will match one of the tasks with that name. However, this task id is not guaranteed to correspond to the desired task. The task id, returned in id, is used in other task related directives to access the task.

NOTES:

This directive will not cause the running task to be preempted.

If node is RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being searched first. All other nodes are searched with the lowest numbered node searched first.

If node is a valid node number which does not represent the local node, then only the tasks exported by the designated node are searched.

This directive does not generate activity on remote nodes. It accesses only the local copy of the global object table.

7.4.3. TASK_SELF - Obtain ID of caller¶

CALLING SEQUENCE:

rtems_id rtems_task_self(void);

DIRECTIVE STATUS CODES:

Returns the object Id of the calling task.

DESCRIPTION:

This directive returns the Id of the calling task.

NOTES:

If called from an interrupt service routine, this directive will return the Id of the interrupted task.

7.4.4. TASK_START - Start a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_start(
    rtems_id            id,
    rtems_task_entry    entry_point,
    rtems_task_argument argument
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	ask started successfully
RTEMS_INVALID_ADDRESS	invalid task entry point
RTEMS_INVALID_ID	invalid task id
RTEMS_INCORRECT_STATE	task not in the dormant state
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	cannot start remote task

DESCRIPTION:

This directive readies the task, specified by id, for execution based on the priority and execution mode specified when the task was created. The starting address of the task is given in entry_point. The task’s starting argument is contained in argument. This argument can be a single value or used as an index into an array of parameter blocks. The type of this numeric argument is an unsigned integer type with the property that any valid pointer to void can be converted to this type and then converted back to a pointer to void. The result will compare equal to the original pointer.

NOTES:

The calling task will be preempted if its preemption mode is enabled and the task being started has a higher priority.

Any actions performed on a dormant task such as suspension or change of priority are nullified when the task is initiated via the rtems_task_start directive.

7.4.5. TASK_RESTART - Restart a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_restart(
   rtems_id            id,
   rtems_task_argument argument
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task restarted successfully
RTEMS_INVALID_ID	task id invalid
RTEMS_INCORRECT_STATE	task never started
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	cannot restart remote task

DESCRIPTION:

This directive resets the task specified by id to begin execution at its original starting address. The task’s priority and execution mode are set to the original creation values. If the task is currently blocked, RTEMS automatically makes the task ready. A task can be restarted from any state, except the dormant state.

The task’s starting argument is contained in argument. This argument can be a single value or an index into an array of parameter blocks. The type of this numeric argument is an unsigned integer type with the property that any valid pointer to void can be converted to this type and then converted back to a pointer to void. The result will compare equal to the original pointer. This new argument may be used to distinguish between the initial rtems_task_start of the task and any ensuing calls to rtems_task_restart of the task. This can be beneficial in deleting a task. Instead of deleting a task using the rtems_task_delete directive, a task can delete another task by restarting that task, and allowing that task to release resources back to RTEMS and then delete itself.

NOTES:

If id is RTEMS_SELF, the calling task will be restarted and will not return from this directive.

The calling task will be preempted if its preemption mode is enabled and the task being restarted has a higher priority.

The task must reside on the local node, even if the task was created with the RTEMS_GLOBAL option.

7.4.6. TASK_DELETE - Delete a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_delete(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task deleted successfully
RTEMS_INVALID_ID	task id invalid
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	cannot restart remote task

DESCRIPTION:

This directive deletes a task, either the calling task or another task, as specified by id. RTEMS stops the execution of the task and reclaims the stack memory, any allocated delay or timeout timers, the TCB, and, if the task is RTEMS_FLOATING_POINT, its floating point context area. RTEMS does not reclaim the following resources: region segments, partition buffers, semaphores, timers, or rate monotonic periods.

NOTES:

A task is responsible for releasing its resources back to RTEMS before deletion. To insure proper deallocation of resources, a task should not be deleted unless it is unable to execute or does not hold any RTEMS resources. If a task holds RTEMS resources, the task should be allowed to deallocate its resources before deletion. A task can be directed to release its resources and delete itself by restarting it with a special argument or by sending it a message, an event, or a signal.

Deletion of the current task (RTEMS_SELF) will force RTEMS to select another task to execute.

When a global task is deleted, the task id must be transmitted to every node in the system for deletion from the local copy of the global object table.

The task must reside on the local node, even if the task was created with the RTEMS_GLOBAL option.

7.4.7. TASK_SUSPEND - Suspend a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_suspend(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task suspended successfully
RTEMS_INVALID_ID	task id invalid
RTEMS_ALREADY_SUSPENDED	task already suspended

DESCRIPTION:

This directive suspends the task specified by id from further execution by placing it in the suspended state. This state is additive to any other blocked state that the task may already be in. The task will not execute again until another task issues the rtems_task_resume directive for this task and any blocked state has been removed.

NOTES:

The requesting task can suspend itself by specifying RTEMS_SELF as id. In this case, the task will be suspended and a successful return code will be returned when the task is resumed.

Suspending a global task which does not reside on the local node will generate a request to the remote node to suspend the specified task.

If the task specified by id is already suspended, then the RTEMS_ALREADY_SUSPENDED status code is returned.

7.4.8. TASK_RESUME - Resume a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_resume(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task resumed successfully
RTEMS_INVALID_ID	task id invalid
RTEMS_INCORRECT_STATE	task not suspended

DESCRIPTION:

This directive removes the task specified by id from the suspended state. If the task is in the ready state after the suspension is removed, then it will be scheduled to run. If the task is still in a blocked state after the suspension is removed, then it will remain in that blocked state.

NOTES:

The running task may be preempted if its preemption mode is enabled and the local task being resumed has a higher priority.

Resuming a global task which does not reside on the local node will generate a request to the remote node to resume the specified task.

If the task specified by id is not suspended, then the RTEMS_INCORRECT_STATE status code is returned.

7.4.9. TASK_IS_SUSPENDED - Determine if a task is Suspended¶

CALLING SEQUENCE:

rtems_status_code rtems_task_is_suspended(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task is NOT suspended
RTEMS_ALREADY_SUSPENDED	task is currently suspended
RTEMS_INVALID_ID	task id invalid
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	not supported on remote tasks

DESCRIPTION:

This directive returns a status code indicating whether or not the specified task is currently suspended.

NOTES:

This operation is not currently supported on remote tasks.

7.4.10. TASK_SET_PRIORITY - Set task priority¶

CALLING SEQUENCE:

rtems_status_code rtems_task_set_priority(
    rtems_id             id,
    rtems_task_priority  new_priority,
    rtems_task_priority *old_priority
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task priority set successfully
RTEMS_INVALID_ID	invalid task id
RTEMS_INVALID_ADDRESS	invalid return argument pointer
RTEMS_INVALID_PRIORITY	invalid task priority

DESCRIPTION:

This directive manipulates the priority of the task specified by id. An id of RTEMS_SELF is used to indicate the calling task. When new_priority is not equal to RTEMS_CURRENT_PRIORITY, the specified task’s previous priority is returned in old_priority. When new_priority is RTEMS_CURRENT_PRIORITY, the specified task’s current priority is returned in old_priority. Valid priorities range from a high of 1 to a low of 255.

NOTES:

The calling task may be preempted if its preemption mode is enabled and it lowers its own priority or raises another task’s priority.

In case the new priority equals the current priority of the task, then nothing happens.

Setting the priority of a global task which does not reside on the local node will generate a request to the remote node to change the priority of the specified task.

If the task specified by id is currently holding any binary semaphores which use the priority inheritance algorithm, then the task’s priority cannot be lowered immediately. If the task’s priority were lowered immediately, then priority inversion results. The requested lowering of the task’s priority will occur when the task has released all priority inheritance binary semaphores. The task’s priority can be increased regardless of the task’s use of priority inheritance binary semaphores.

7.4.11. TASK_MODE - Change the current task mode¶

CALLING SEQUENCE:

rtems_status_code rtems_task_mode(
    rtems_mode  mode_set,
    rtems_mode  mask,
    rtems_mode *previous_mode_set
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	task mode set successfully
RTEMS_INVALID_ADDRESS	previous_mode_set is NULL

DESCRIPTION:

This directive manipulates the execution mode of the calling task. A task’s execution mode enables and disables preemption, timeslicing, asynchronous signal processing, as well as specifying the current interrupt level. To modify an execution mode, the mode class(es) to be changed must be specified in the mask parameter and the desired mode(s) must be specified in the mode parameter.

NOTES:

The calling task will be preempted if it enables preemption and a higher priority task is ready to run.

Enabling timeslicing has no effect if preemption is disabled. For a task to be timesliced, that task must have both preemption and timeslicing enabled.

A task can obtain its current execution mode, without modifying it, by calling this directive with a mask value of RTEMS_CURRENT_MODE.

To temporarily disable the processing of a valid ASR, a task should call this directive with the RTEMS_NO_ASR indicator specified in mode.

The set of task mode constants and each mode’s corresponding mask constant is provided in the following table:

RTEMS_PREEMPT	is masked by RTEMS_PREEMPT_MASK and enables preemption
RTEMS_NO_PREEMPT	is masked by RTEMS_PREEMPT_MASK and disables preemption
RTEMS_NO_TIMESLICE	is masked by RTEMS_TIMESLICE_MASK and disables timeslicing
RTEMS_TIMESLICE	is masked by RTEMS_TIMESLICE_MASK and enables timeslicing
RTEMS_ASR	is masked by RTEMS_ASR_MASK and enables ASR processing
RTEMS_NO_ASR	is masked by RTEMS_ASR_MASK and disables ASR processing
RTEMS_INTERRUPT_LEVEL(0)	is masked by RTEMS_INTERRUPT_MASK and enables all interrupts
RTEMS_INTERRUPT_LEVEL(n)	is masked by RTEMS_INTERRUPT_MASK and sets interrupts level n

7.4.12. TASK_GET_NOTE - Get task notepad entry¶

CALLING SEQUENCE:

rtems_status_code rtems_task_get_note(
  rtems_id  id,
  uint32_t  notepad,
  uint32_t *note
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	note value obtained successfully
RTEMS_INVALID_ADDRESS	note parameter is NULL
RTEMS_INVALID_ID	invalid task id
RTEMS_INVALID_NUMBER	invalid notepad location

DESCRIPTION:

This directive returns the note contained in the notepad location of the task specified by id.

NOTES:

This directive will not cause the running task to be preempted.

If id is set to RTEMS_SELF, the calling task accesses its own notepad.

The sixteen notepad locations can be accessed using the constants RTEMS_NOTEPAD_0 through RTEMS_NOTEPAD_15.

Getting a note of a global task which does not reside on the local node will generate a request to the remote node to obtain the notepad entry of the specified task.

7.4.13. TASK_SET_NOTE - Set task notepad entry¶

CALLING SEQUENCE:

rtems_status_code rtems_task_set_note(
  rtems_id  id,
  uint32_t  notepad,
  uint32_t  note
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	note set successfully
RTEMS_INVALID_ID	invalid task id
RTEMS_INVALID_NUMBER	invalid notepad location

DESCRIPTION:

This directive sets the notepad entry for the task specified by id to the value note.

NOTES:

If id is set to RTEMS_SELF, the calling task accesses its own notepad.

This directive will not cause the running task to be preempted.

The sixteen notepad locations can be accessed using the constants RTEMS_NOTEPAD_0 through RTEMS_NOTEPAD_15.

Setting a note of a global task which does not reside on the local node will generate a request to the remote node to set the notepad entry of the specified task.

7.4.14. TASK_WAKE_AFTER - Wake up after interval¶

CALLING SEQUENCE:

rtems_status_code rtems_task_wake_after(
    rtems_interval ticks
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL

always successful

DESCRIPTION:

This directive blocks the calling task for the specified number of system clock ticks. When the requested interval has elapsed, the task is made ready. The clock tick directives automatically updates the delay period.

NOTES:

Setting the system date and time with the rtems_clock_set directive has no effect on a rtems_task_wake_after blocked task.

A task may give up the processor and remain in the ready state by specifying a value of RTEMS_YIELD_PROCESSOR in ticks.

The maximum timer interval that can be specified is the maximum value which can be represented by the uint32_t type.

A clock tick is required to support the functionality of this directive.

7.4.15. TASK_WAKE_WHEN - Wake up when specified¶

CALLING SEQUENCE:

rtems_status_code rtems_task_wake_when(
    rtems_time_of_day *time_buffer
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	awakened at date/time successfully
RTEMS_INVALID_ADDRESS	time_buffer is NULL
RTEMS_INVALID_TIME_OF_DAY	invalid time buffer
RTEMS_NOT_DEFINED	system date and time is not set

DESCRIPTION:

This directive blocks a task until the date and time specified in time_buffer. At the requested date and time, the calling task will be unblocked and made ready to execute.

NOTES:

The ticks portion of time_buffer structure is ignored. The timing granularity of this directive is a second.

A clock tick is required to support the functionality of this directive.

7.4.16. ITERATE_OVER_ALL_THREADS - Iterate Over Tasks¶

CALLING SEQUENCE:

typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread);
void rtems_iterate_over_all_threads(
    rtems_per_thread_routine routine
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive iterates over all of the existant threads in the system and invokes routine on each of them. The user should be careful in accessing the contents of the_thread.

This routine is intended for use in diagnostic utilities and is not intented for routine use in an operational system.

NOTES:

There is NO protection while this routine is called. Thus it is possible that the_thread could be deleted while this is operating. By not having protection, the user is free to invoke support routines from the C Library which require semaphores for data structures.

7.4.17. TASK_VARIABLE_ADD - Associate per task variable¶

CALLING SEQUENCE:

rtems_status_code rtems_task_variable_add(
    rtems_id  tid,
    void    **task_variable,
    void    (*dtor)(void *)
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	per task variable added successfully
RTEMS_INVALID_ADDRESS	task_variable is NULL
RTEMS_INVALID_ID	invalid task id
RTEMS_NO_MEMORY	invalid task id
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	not supported on remote tasks

DESCRIPTION:

This directive adds the memory location specified by the ptr argument to the context of the given task. The variable will then be private to the task. The task can access and modify the variable, but the modifications will not appear to other tasks, and other tasks’ modifications to that variable will not affect the value seen by the task. This is accomplished by saving and restoring the variable’s value each time a task switch occurs to or from the calling task. If the dtor argument is non-NULL it specifies the address of a ‘destructor’ function which will be called when the task is deleted. The argument passed to the destructor function is the task’s value of the variable.

NOTES:

Task variables increase the context switch time to and from the tasks that own them so it is desirable to minimize the number of task variables. One efficient method is to have a single task variable that is a pointer to a dynamically allocated structure containing the task’s private ‘global’ data. In this case the destructor function could be ‘free’.

Per-task variables are disabled in SMP configurations and this service is not available.

7.4.18. TASK_VARIABLE_GET - Obtain value of a per task variable¶

CALLING SEQUENCE:

rtems_status_code rtems_task_variable_get(
    rtems_id  tid,
    void    **task_variable,
    void    **task_variable_value
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	per task variable obtained successfully
RTEMS_INVALID_ADDRESS	task_variable is NULL
RTEMS_INVALID_ADDRESS	task_variable_value is NULL
RTEMS_INVALID_ADDRESS	task_variable is not found
RTEMS_NO_MEMORY	invalid task id
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	not supported on remote tasks

DESCRIPTION:

This directive looks up the private value of a task variable for a specified task and stores that value in the location pointed to by the result argument. The specified task is usually not the calling task, which can get its private value by directly accessing the variable.

NOTES:

If you change memory which task_variable_value points to, remember to declare that memory as volatile, so that the compiler will optimize it correctly. In this case both the pointer task_variable_value and data referenced by task_variable_value should be considered volatile.

Per-task variables are disabled in SMP configurations and this service is not available.

7.4.19. TASK_VARIABLE_DELETE - Remove per task variable¶

CALLING SEQUENCE:

rtems_status_code rtems_task_variable_delete(
    rtems_id  id,
    void    **task_variable
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	per task variable deleted successfully
RTEMS_INVALID_ID	invalid task id
RTEMS_NO_MEMORY	invalid task id
RTEMS_INVALID_ADDRESS	task_variable is NULL
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	not supported on remote tasks

DESCRIPTION:

This directive removes the given location from a task’s context.

NOTES:

Per-task variables are disabled in SMP configurations and this service is not available.

8.2.1. Processing an Interrupt¶

The interrupt manager allows the application to connect a function to a hardware interrupt vector. When an interrupt occurs, the processor will automatically vector to RTEMS. RTEMS saves and restores all registers which are not preserved by the normal C calling convention for the target processor and invokes the user’s ISR. The user’s ISR is responsible for processing the interrupt, clearing the interrupt if necessary, and device specific manipulation.

The rtems_interrupt_catch directive connects a procedure to an interrupt vector. The vector number is managed using the rtems_vector_number data type.

The interrupt service routine is assumed to abide by these conventions and have a prototype similar to the following:

rtems_isr user_isr(
    rtems_vector_number vector
);

The vector number argument is provided by RTEMS to allow the application to identify the interrupt source. This could be used to allow a single routine to service interrupts from multiple instances of the same device. For example, a single routine could service interrupts from multiple serial ports and use the vector number to identify which port requires servicing.

To minimize the masking of lower or equal priority level interrupts, the ISR should perform the minimum actions required to service the interrupt. Other non-essential actions should be handled by application tasks. Once the user’s ISR has completed, it returns control to the RTEMS interrupt manager which will perform task dispatching and restore the registers saved before the ISR was invoked.

The RTEMS interrupt manager guarantees that proper task scheduling and dispatching are performed at the conclusion of an ISR. A system call made by the ISR may have readied a task of higher priority than the interrupted task. Therefore, when the ISR completes, the postponed dispatch processing must be performed. No dispatch processing is performed as part of directives which have been invoked by an ISR.

Applications must adhere to the following rule if proper task scheduling and dispatching is to be performed:

Consider a processor which allows a numerically low interrupt level to interrupt a numerically greater interrupt level. In this example, if an RTEMS directive is used in a level 4 ISR, then all ISRs which execute at levels 0 through 4 must use the interrupt manager.

Interrupts are nested whenever an interrupt occurs during the execution of another ISR. RTEMS supports efficient interrupt nesting by allowing the nested ISRs to terminate without performing any dispatch processing. Only when the outermost ISR terminates will the postponed dispatching occur.

8.2.2. RTEMS Interrupt Levels¶

Many processors support multiple interrupt levels or priorities. The exact number of interrupt levels is processor dependent. RTEMS internally supports 256 interrupt levels which are mapped to the processor’s interrupt levels. For specific information on the mapping between RTEMS and the target processor’s interrupt levels, refer to the Interrupt Processing chapter of the Applications Supplement document for a specific target processor.

8.2.3. Disabling of Interrupts by RTEMS¶

During the execution of directive calls, critical sections of code may be executed. When these sections are encountered, RTEMS disables all maskable interrupts before the execution of the section and restores them to the previous level upon completion of the section. RTEMS has been optimized to ensure that interrupts are disabled for a minimum length of time. The maximum length of time interrupts are disabled by RTEMS is processor dependent and is detailed in the Timing Specification chapter of the Applications Supplement document for a specific target processor.

Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at this level MUST NEVER issue RTEMS system calls. If a directive is invoked, unpredictable results may occur due to the inability of RTEMS to protect its critical sections. However, ISRs that make no system calls may safely execute as non-maskable interrupts.

8.3.1. Establishing an ISR¶

The rtems_interrupt_catch directive establishes an ISR for the system. The address of the ISR and its associated CPU vector number are specified to this directive. This directive installs the RTEMS interrupt wrapper in the processor’s Interrupt Vector Table and the address of the user’s ISR in the RTEMS’ Vector Table. This directive returns the previous contents of the specified vector in the RTEMS’ Vector Table.

8.3.2. Directives Allowed from an ISR¶

Using the interrupt manager ensures that RTEMS knows when a directive is being called from an ISR. The ISR may then use system calls to synchronize itself with an application task. The synchronization may involve messages, events or signals being passed by the ISR to the desired task. Directives invoked by an ISR must operate only on objects which reside on the local node. The following is a list of RTEMS system calls that may be made from an ISR:

• Task Management Although it is acceptable to operate on the RTEMS_SELF task (e.g. the currently executing task), while in an ISR, this will refer to the interrupted task. Most of the time, it is an application implementation error to use RTEMS_SELF from an ISR.
  • rtems_task_suspend
  • rtems_task_resume
• Interrupt Management
  • rtems_interrupt_enable
  • rtems_interrupt_disable
  • rtems_interrupt_flash
  • rtems_interrupt_lock_acquire
  • rtems_interrupt_lock_release
  • rtems_interrupt_lock_acquire_isr
  • rtems_interrupt_lock_release_isr
  • rtems_interrupt_is_in_progress
  • rtems_interrupt_catch
• Clock Management
  • rtems_clock_set
  • rtems_clock_get
  • rtems_clock_get_tod
  • rtems_clock_get_tod_timeval
  • rtems_clock_get_seconds_since_epoch
  • rtems_clock_get_ticks_per_second
  • rtems_clock_get_ticks_since_boot
  • rtems_clock_get_uptime
  • rtems_timecounter_tick
  • rtems_timecounter_simple_downcounter_tick
  • rtems_timecounter_simple_upcounter_tick
• Timer Management
  • rtems_timer_cancel
  • rtems_timer_reset
  • rtems_timer_fire_after
  • rtems_timer_fire_when
  • rtems_timer_server_fire_after
  • rtems_timer_server_fire_when
• Event Management
  • rtems_event_send
  • rtems_event_system_send
  • rtems_event_transient_send
• Semaphore Management
  • rtems_semaphore_release
• Message Management
  • rtems_message_queue_send
  • rtems_message_queue_urgent
• Signal Management
  • rtems_signal_send
• Dual-Ported Memory Management
  • rtems_port_external_to_internal
  • rtems_port_internal_to_external
• IO Management The following services are safe to call from an ISR if and only if the device driver service invoked is also safe. The IO Manager itself is safe but the invoked driver entry point may or may not be.
  • rtems_io_initialize
  • rtems_io_open
  • rtems_io_close
  • rtems_io_read
  • rtems_io_write
  • rtems_io_control
• Fatal Error Management
  • rtems_fatal
  • rtems_fatal_error_occurred
• Multiprocessing
  • rtems_multiprocessing_announce

8.4.1. INTERRUPT_CATCH - Establish an ISR¶

CALLING SEQUENCE:

rtems_status_code rtems_interrupt_catch(
    rtems_isr_entry      new_isr_handler,
    rtems_vector_number  vector,
    rtems_isr_entry     *old_isr_handler
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	ISR established successfully
RTEMS_INVALID_NUMBER	illegal vector number
RTEMS_INVALID_ADDRESS	illegal ISR entry point or invalid old_isr_handler

DESCRIPTION:

This directive establishes an interrupt service routine (ISR) for the specified interrupt vector number. The new_isr_handler parameter specifies the entry point of the ISR. The entry point of the previous ISR for the specified vector is returned in old_isr_handler.

To release an interrupt vector, pass the old handler’s address obtained when the vector was first capture.

NOTES:

This directive will not cause the calling task to be preempted.

8.4.2. INTERRUPT_DISABLE - Disable Interrupts¶

CALLING SEQUENCE:

void rtems_interrupt_disable(
    rtems_interrupt_level  level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive disables all maskable interrupts and returns the previous level. A later invocation of the rtems_interrupt_enable directive should be used to restore the interrupt level.

NOTES:

This directive will not cause the calling task to be preempted.

This directive is only available on uni-processor configurations. The directive rtems_interrupt_local_disable is available on all configurations.

8.4.3. INTERRUPT_ENABLE - Enable Interrupts¶

CALLING SEQUENCE:

void rtems_interrupt_enable(
   rtems_interrupt_level  level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive enables maskable interrupts to the level which was returned by a previous call to rtems_interrupt_disable. Immediately prior to invoking this directive, maskable interrupts should be disabled by a call to rtems_interrupt_disable and will be enabled when this directive returns to the caller.

NOTES:

This directive will not cause the calling task to be preempted.

This directive is only available on uni-processor configurations. The directive rtems_interrupt_local_enable is available on all configurations.

8.4.4. INTERRUPT_FLASH - Flash Interrupts¶

CALLING SEQUENCE:

void rtems_interrupt_flash(
    rtems_interrupt_level level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive temporarily enables maskable interrupts to the level which was returned by a previous call to rtems_interrupt_disable. Immediately prior to invoking this directive, maskable interrupts should be disabled by a call to rtems_interrupt_disable and will be redisabled when this directive returns to the caller.

NOTES:

This directive will not cause the calling task to be preempted.

This directive is only available on uni-processor configurations. The directives rtems_interrupt_local_disable and rtems_interrupt_local_enable is available on all configurations.

8.4.5. INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor¶

CALLING SEQUENCE:

void rtems_interrupt_local_disable(
    rtems_interrupt_level  level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive disables all maskable interrupts and returns the previous level. A later invocation of the rtems_interrupt_local_enable directive should be used to restore the interrupt level.

NOTES:

This directive will not cause the calling task to be preempted.

On SMP configurations this will not ensure system wide mutual exclusion. Use interrupt locks instead.

8.4.6. INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor¶

CALLING SEQUENCE:

void rtems_interrupt_local_enable(
    rtems_interrupt_level  level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive enables maskable interrupts to the level which was returned by a previous call to rtems_interrupt_local_disable. Immediately prior to invoking this directive, maskable interrupts should be disabled by a call to rtems_interrupt_local_disable and will be enabled when this directive returns to the caller.

NOTES:

This directive will not cause the calling task to be preempted.

8.4.7. INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock¶

CALLING SEQUENCE:

void rtems_interrupt_lock_initialize(
    rtems_interrupt_lock *lock
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

Initializes an interrupt lock.

NOTES:

Concurrent initialization leads to unpredictable results.

8.4.8. INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock¶

CALLING SEQUENCE:

void rtems_interrupt_lock_acquire(
    rtems_interrupt_lock *lock,
    rtems_interrupt_level level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

Interrupts will be disabled. On SMP configurations this directive acquires a SMP lock.

NOTES:

This directive will not cause the calling thread to be preempted. This directive can be used in thread and interrupt context.

8.4.9. INTERRUPT_LOCK_RELEASE - Release an ISR Lock¶

CALLING SEQUENCE:

void rtems_interrupt_lock_release(
    rtems_interrupt_lock *lock,
    rtems_interrupt_level level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

The interrupt status will be restored. On SMP configurations this directive releases a SMP lock.

NOTES:

This directive will not cause the calling thread to be preempted. This directive can be used in thread and interrupt context.

8.4.10. INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR¶

CALLING SEQUENCE:

void rtems_interrupt_lock_acquire_isr(
    rtems_interrupt_lock *lock,
    rtems_interrupt_level level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

The interrupt status will remain unchanged. On SMP configurations this directive acquires a SMP lock.

In case the corresponding interrupt service routine can be interrupted by higher priority interrupts and these interrupts enter the critical section protected by this lock, then the result is unpredictable.

NOTES:

This directive should be called from the corresponding interrupt service routine.

8.4.11. INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR¶

CALLING SEQUENCE:

void rtems_interrupt_lock_release_isr(
    rtems_interrupt_lock *lock,
    rtems_interrupt_level level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

The interrupt status will remain unchanged. On SMP configurations this directive releases a SMP lock.

NOTES:

This directive should be called from the corresponding interrupt service routine.

8.4.12. INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress¶

CALLING SEQUENCE:

bool rtems_interrupt_is_in_progress(void);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive returns TRUE if the processor is currently servicing an interrupt and FALSE otherwise. A return value of TRUE indicates that the caller is an interrupt service routine, NOT a task. The directives available to an interrupt service routine are restricted.

NOTES:

This directive will not cause the calling task to be preempted.

9.2.1. Required Support¶

For the features provided by the clock manager to be utilized, periodic timer interrupts are required. Therefore, a real-time clock or hardware timer is necessary to create the timer interrupts. The clock tick directive is normally called by the timer ISR to announce to RTEMS that a system clock tick has occurred. Elapsed time is measured in ticks. A tick is defined to be an integral number of microseconds which is specified by the user in the Configuration Table.

9.2.2. Time and Date Data Structures¶

The clock facilities of the clock manager operate upon calendar time. These directives utilize the following date and time structure for the native time and date format:

struct rtems_tod_control {
    uint32_t year;   /* greater than 1987 */
    uint32_t month;  /* 1 - 12 */
    uint32_t day;    /* 1 - 31 */
    uint32_t hour;   /* 0 - 23 */
    uint32_t minute; /* 0 - 59 */
    uint32_t second; /* 0 - 59 */
    uint32_t ticks;  /* elapsed between seconds */
};
typedef struct rtems_tod_control rtems_time_of_day;

The native date and time format is the only format supported when setting the system date and time using the rtems_clock_set directive. Some applications expect to operate on a UNIX-style date and time data structure. The rtems_clock_get_tod_timeval always returns the date and time in struct timeval format. The rtems_clock_get directive can optionally return the current date and time in this format.

The struct timeval data structure has two fields: tv_sec and tv_usec which are seconds and microseconds, respectively. The tv_sec field in this data structure is the number of seconds since the POSIX epoch of January 1, 1970 but will never be prior to the RTEMS epoch of January 1, 1988.

9.2.3. Clock Tick and Timeslicing¶

Timeslicing is a task scheduling discipline in which tasks of equal priority are executed for a specific period of time before control of the CPU is passed to another task. It is also sometimes referred to as the automatic round-robin scheduling algorithm. The length of time allocated to each task is known as the quantum or timeslice.

The system’s timeslice is defined as an integral number of ticks, and is specified in the Configuration Table. The timeslice is defined for the entire system of tasks, but timeslicing is enabled and disabled on a per task basis.

The clock tick directives implement timeslicing by decrementing the running task’s time-remaining counter when both timeslicing and preemption are enabled. If the task’s timeslice has expired, then that task will be preempted if there exists a ready task of equal priority.

9.2.4. Delays¶

A sleep timer allows a task to delay for a given interval or up until a given time, and then wake and continue execution. This type of timer is created automatically by the rtems_task_wake_after and rtems_task_wake_when directives and, as a result, does not have an RTEMS ID. Once activated, a sleep timer cannot be explicitly deleted. Each task may activate one and only one sleep timer at a time.

9.2.5. Timeouts¶

Timeouts are a special type of timer automatically created when the timeout option is used on the rtems_message_queue_receive, rtems_event_receive, rtems_semaphore_obtain and rtems_region_get_segment directives. Each task may have one and only one timeout active at a time. When a timeout expires, it unblocks the task with a timeout status code.

9.3.1. Announcing a Tick¶

RTEMS provides the several clock tick directives which are called from the user’s real-time clock ISR to inform RTEMS that a tick has elapsed. Depending on the timer hardware capabilities the clock driver must choose the most appropriate clock tick directive. The tick frequency value, defined in microseconds, is a configuration parameter found in the Configuration Table. RTEMS divides one million microseconds (one second) by the number of microseconds per tick to determine the number of calls to the clock tick directive per second. The frequency of clock tick calls determines the resolution (granularity) for all time dependent RTEMS actions. For example, calling the clock tick directive ten times per second yields a higher resolution than calling the clock tick two times per second. The clock tick directives are responsible for maintaining both calendar time and the dynamic set of timers.

9.3.2. Setting the Time¶

The rtems_clock_set directive allows a task or an ISR to set the date and time maintained by RTEMS. If setting the date and time causes any outstanding timers to pass their deadline, then the expired timers will be fired during the invocation of the rtems_clock_set directive.

9.3.3. Obtaining the Time¶

The rtems_clock_get directive allows a task or an ISR to obtain the current date and time or date and time related information. The current date and time can be returned in either native or UNIX-style format. Additionally, the application can obtain date and time related information such as the number of seconds since the RTEMS epoch, the number of ticks since the executive was initialized, and the number of ticks per second. The information returned by the rtems_clock_get directive is dependent on the option selected by the caller. This is specified using one of the following constants associated with the enumerated type rtems_clock_get_options:

RTEMS_CLOCK_GET_TOD

obtain native style date and time

RTEMS_CLOCK_GET_TIME_VALUE

obtain UNIX-style date and time

RTEMS_CLOCK_GET_TICKS_SINCE_BOOT

obtain number of ticks since RTEMS was initialized

RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH

obtain number of seconds since RTEMS epoch

RTEMS_CLOCK_GET_TICKS_PER_SECOND

obtain number of clock ticks per second

Calendar time operations will return an error code if invoked before the date and time have been set.

9.4.1. CLOCK_SET - Set date and time¶

CALLING SEQUENCE:

rtems_status_code rtems_clock_set(
    rtems_time_of_day *time_buffer
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	date and time set successfully
RTEMS_INVALID_ADDRESS	time_buffer is NULL
RTEMS_INVALID_CLOCK	invalid time of day

DESCRIPTION:

This directive sets the system date and time. The date, time, and ticks in the time_buffer structure are all range-checked, and an error is returned if any one is out of its valid range.

NOTES:

Years before 1988 are invalid.

The system date and time are based on the configured tick rate (number of microseconds in a tick).

Setting the time forward may cause a higher priority task, blocked waiting on a specific time, to be made ready. In this case, the calling task will be preempted after the next clock tick.

Re-initializing RTEMS causes the system date and time to be reset to an uninitialized state. Another call to rtems_clock_set is required to re-initialize the system date and time to application specific specifications.

9.4.2. CLOCK_GET - Get date and time information¶

CALLING SEQUENCE:

rtems_status_code rtems_clock_get(
   rtems_clock_get_options  option,
   void                    *time_buffer
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	current time obtained successfully
RTEMS_NOT_DEFINED	system date and time is not set
RTEMS_INVALID_ADDRESS	time_buffer is NULL

DESCRIPTION:

This directive obtains the system date and time. If the caller is attempting to obtain the date and time (i.e. option is set to either RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH, RTEMS_CLOCK_GET_TOD, or RTEMS_CLOCK_GET_TIME_VALUE) and the date and time has not been set with a previous call to rtems_clock_set, then the RTEMS_NOT_DEFINED status code is returned. The caller can always obtain the number of ticks per second (option is RTEMS_CLOCK_GET_TICKS_PER_SECOND) and the number of ticks since the executive was initialized option is RTEMS_CLOCK_GET_TICKS_SINCE_BOOT).

The option argument may taken on any value of the enumerated type rtems_clock_get_options. The data type expected for time_buffer is based on the value of option as indicated below:

Option	Return type
RTEMS_CLOCK_GET_TOD	(rtems_time_of_day *)
RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH	(rtems_interval *)
RTEMS_CLOCK_GET_TICKS_SINCE_BOOT	(rtems_interval *)
RTEMS_CLOCK_GET_TICKS_PER_SECOND	(rtems_interval *)
RTEMS_CLOCK_GET_TIME_VALUE	(struct timeval *)

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted. Re-initializing RTEMS causes the system date and time to be reset to an uninitialized state. Another call to rtems_clock_set is required to re-initialize the system date and time to application specific specifications.

9.4.3. CLOCK_GET_TOD - Get date and time in TOD format¶

CALLING SEQUENCE:

rtems_status_code rtems_clock_get_tod(
    rtems_time_of_day *time_buffer
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	current time obtained successfully
RTEMS_NOT_DEFINED	system date and time is not set
RTEMS_INVALID_ADDRESS	time_buffer is NULL

DESCRIPTION:

This directive obtains the system date and time. If the date and time has not been set with a previous call to rtems_clock_set, then the RTEMS_NOT_DEFINED status code is returned.

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted. Re-initializing RTEMS causes the system date and time to be reset to an uninitialized state. Another call to rtems_clock_set is required to re-initialize the system date and time to application specific specifications.

9.4.4. CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format¶

CALLING SEQUENCE:

rtems_status_code rtems_clock_get_tod_interval(
    struct timeval  *time
);

DIRECTIVE STATUS CODES:

DESCRIPTION:

This directive obtains the system date and time in POSIX struct timeval format. If the date and time has not been set with a previous call to rtems_clock_set, then the RTEMS_NOT_DEFINED status code is returned.

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted. Re-initializing RTEMS causes the system date and time to be reset to an uninitialized state. Another call to rtems_clock_set is required to re-initialize the system date and time to application specific specifications.

9.4.5. CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch¶

CALLING SEQUENCE:

rtems_status_code rtems_clock_get_seconds_since_epoch(
    rtems_interval *the_interval
);

DIRECTIVE STATUS CODES:

DESCRIPTION:

This directive returns the number of seconds since the RTEMS epoch and the current system date and time. If the date and time has not been set with a previous call to rtems_clock_set, then the RTEMS_NOT_DEFINED status code is returned.

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted. Re-initializing RTEMS causes the system date and time to be reset to an uninitialized state. Another call to rtems_clock_set is required to re-initialize the system date and time to application specific specifications.

9.4.6. CLOCK_GET_TICKS_PER_SECOND - Get ticks per second¶

CALLING SEQUENCE:

rtems_interval rtems_clock_get_ticks_per_second(void);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive returns the number of clock ticks per second. This is strictly based upon the microseconds per clock tick that the application has configured.

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted.

9.4.7. CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value¶

CALLING SEQUENCE:

rtems_interval rtems_clock_get_ticks_since_boot(void);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive returns the current tick counter value. With a 1ms clock tick, this counter overflows after 50 days since boot. This is the historical measure of uptime in an RTEMS system. The newer service rtems_clock_get_uptime is another and potentially more accurate way of obtaining similar information.

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted.

9.4.8. CLOCK_TICK_LATER - Get tick value in the future¶

CALLING SEQUENCE:

rtems_interval rtems_clock_tick_later(
    rtems_interval delta
);

DESCRIPTION:

Returns the ticks counter value delta ticks in the future.

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted.

9.4.9. CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds¶

CALLING SEQUENCE:

rtems_interval rtems_clock_tick_later_usec(
    rtems_interval delta_in_usec
);

DESCRIPTION:

Returns the ticks counter value at least delta microseconds in the future.

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted.

9.4.10. CLOCK_TICK_BEFORE - Is tick value is before a point in time¶

CALLING SEQUENCE:

rtems_interval rtems_clock_tick_before(
    rtems_interval tick
);

DESCRIPTION:

Returns true if the current ticks counter value indicates a time before the time specified by the tick value and false otherwise.

NOTES:

This directive is callable from an ISR.

This directive will not cause the running task to be preempted.

EXAMPLE:

status busy( void )
{
    rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
    do {
        if ( ok() ) {
            return success;
        }
    } while ( rtems_clock_tick_before( timeout ) );
    return timeout;
}

9.4.11. CLOCK_GET_UPTIME - Get the time since boot¶

CALLING SEQUENCE:

rtems_status_code rtems_clock_get_uptime(
    struct timespec *uptime
);

DIRECTIVE STATUS CODES:

DESCRIPTION:

This directive returns the seconds and nanoseconds since the system was booted. If the BSP supports nanosecond clock accuracy, the time reported will probably be different on every call.

NOTES:

This directive may be called from an ISR.

9.4.12. CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format¶

CALLING SEQUENCE:

void rtems_clock_get_uptime_timeval(
    struct timeval *uptime
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive returns the seconds and microseconds since the system was booted. If the BSP supports nanosecond clock accuracy, the time reported will probably be different on every call.

NOTES:

This directive may be called from an ISR.

9.4.13. CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot¶

CALLING SEQUENCE:

time_t rtems_clock_get_uptime_seconds(void);

DIRECTIVE STATUS CODES:

The system uptime in seconds.

DESCRIPTION:

This directive returns the seconds since the system was booted.

NOTES:

This directive may be called from an ISR.

9.4.14. CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot¶

CALLING SEQUENCE:

uint64_t rtems_clock_get_uptime_nanoseconds(void);

DIRECTIVE STATUS CODES:

The system uptime in nanoseconds.

DESCRIPTION:

This directive returns the nanoseconds since the system was booted.

NOTES:

This directive may be called from an ISR.

10.2.1. Required Support¶

A clock tick is required to support the functionality provided by this manager.

10.2.2. Timers¶

A timer is an RTEMS object which allows the application to schedule operations to occur at specific times in the future. User supplied timer service routines are invoked by either a clock tick directive or a special Timer Server task when the timer fires. Timer service routines may perform any operations or directives which normally would be performed by the application code which invoked a clock tick directive.

The timer can be used to implement watchdog routines which only fire to denote that an application error has occurred. The timer is reset at specific points in the application to ensure that the watchdog does not fire. Thus, if the application does not reset the watchdog timer, then the timer service routine will fire to indicate that the application has failed to reach a reset point. This use of a timer is sometimes referred to as a “keep alive” or a “deadman” timer.

10.2.3. Timer Server¶

The Timer Server task is responsible for executing the timer service routines associated with all task-based timers. This task executes at a priority higher than any RTEMS application task, and is created non-preemptible, and thus can be viewed logically as the lowest priority interrupt.

By providing a mechanism where timer service routines execute in task rather than interrupt space, the application is allowed a bit more flexibility in what operations a timer service routine can perform. For example, the Timer Server can be configured to have a floating point context in which case it would be safe to perform floating point operations from a task-based timer. Most of the time, executing floating point instructions from an interrupt service routine is not considered safe. However, since the Timer Server task is non-preemptible, only directives allowed from an ISR can be called in the timer service routine.

The Timer Server is designed to remain blocked until a task-based timer fires. This reduces the execution overhead of the Timer Server.

10.2.4. Timer Service Routines¶

The timer service routine should adhere to C calling conventions and have a prototype similar to the following:

rtems_timer_service_routine user_routine(
    rtems_id   timer_id,
    void      *user_data
);

Where the timer_id parameter is the RTEMS object ID of the timer which is being fired and user_data is a pointer to user-defined information which may be utilized by the timer service routine. The argument user_data may be NULL.

10.3.1. Creating a Timer¶

The rtems_timer_create directive creates a timer by allocating a Timer Control Block (TMCB), assigning the timer a user-specified name, and assigning it a timer ID. Newly created timers do not have a timer service routine associated with them and are not active.

10.3.2. Obtaining Timer IDs¶

When a timer is created, RTEMS generates a unique timer ID and assigns it to the created timer until it is deleted. The timer ID may be obtained by either of two methods. First, as the result of an invocation of the rtems_timer_create directive, the timer ID is stored in a user provided location. Second, the timer ID may be obtained later using the rtems_timer_ident directive. The timer ID is used by other directives to manipulate this timer.

10.3.3. Initiating an Interval Timer¶

The rtems_timer_fire_after and rtems_timer_server_fire_after directives initiate a timer to fire a user provided timer service routine after the specified number of clock ticks have elapsed. When the interval has elapsed, the timer service routine will be invoked from a clock tick directive if it was initiated by the rtems_timer_fire_after directive and from the Timer Server task if initiated by the rtems_timer_server_fire_after directive.

10.3.4. Initiating a Time of Day Timer¶

The rtems_timer_fire_when and rtems_timer_server_fire_when directive initiate a timer to fire a user provided timer service routine when the specified time of day has been reached. When the interval has elapsed, the timer service routine will be invoked from a clock tick directive by the rtems_timer_fire_when directive and from the Timer Server task if initiated by the rtems_timer_server_fire_when directive.

10.3.5. Canceling a Timer¶

The rtems_timer_cancel directive is used to halt the specified timer. Once canceled, the timer service routine will not fire unless the timer is reinitiated. The timer can be reinitiated using the rtems_timer_reset, rtems_timer_fire_after, and rtems_timer_fire_when directives.

10.3.6. Resetting a Timer¶

The rtems_timer_reset directive is used to restore an interval timer initiated by a previous invocation of rtems_timer_fire_after or rtems_timer_server_fire_after to its original interval length. If the timer has not been used or the last usage of this timer was by the rtems_timer_fire_when or rtems_timer_server_fire_when directive, then an error is returned. The timer service routine is not changed or fired by this directive.

10.3.7. Initiating the Timer Server¶

The rtems_timer_initiate_server directive is used to allocate and start the execution of the Timer Server task. The application can specify both the stack size and attributes of the Timer Server. The Timer Server executes at a priority higher than any application task and thus the user can expect to be preempted as the result of executing the rtems_timer_initiate_server directive.

10.3.8. Deleting a Timer¶

The rtems_timer_delete directive is used to delete a timer. If the timer is running and has not expired, the timer is automatically canceled. The timer’s control block is returned to the TMCB free list when it is deleted. A timer can be deleted by a task other than the task which created the timer. Any subsequent references to the timer’s name and ID are invalid.

10.4.1. TIMER_CREATE - Create a timer¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_create(
    rtems_name  name,
    rtems_id   *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer created successfully
RTEMS_INVALID_ADDRESS	id is NULL
RTEMS_INVALID_NAME	invalid timer name
RTEMS_TOO_MANY	too many timers created

DESCRIPTION:

This directive creates a timer. The assigned timer id is returned in id. This id is used to access the timer with other timer manager directives. For control and maintenance of the timer, RTEMS allocates a TMCB from the local TMCB free pool and initializes it.

NOTES:

This directive will not cause the calling task to be preempted.

10.4.2. TIMER_IDENT - Get ID of a timer¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_ident(
    rtems_name  name,
    rtems_id   *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer identified successfully
RTEMS_INVALID_ADDRESS	id is NULL
RTEMS_INVALID_NAME	timer name not found

DESCRIPTION:

This directive obtains the timer id associated with the timer name to be acquired. If the timer name is not unique, then the timer id will match one of the timers with that name. However, this timer id is not guaranteed to correspond to the desired timer. The timer id is used to access this timer in other timer related directives.

NOTES:

This directive will not cause the running task to be preempted.

10.4.3. TIMER_CANCEL - Cancel a timer¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_cancel(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer canceled successfully
RTEMS_INVALID_ID	invalid timer id

DESCRIPTION:

This directive cancels the timer id. This timer will be reinitiated by the next invocation of rtems_timer_reset, rtems_timer_fire_after, or rtems_timer_fire_when with this id.

NOTES:

This directive will not cause the running task to be preempted.

10.4.4. TIMER_DELETE - Delete a timer¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_delete(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer deleted successfully
RTEMS_INVALID_ID	invalid timer id

DESCRIPTION:

This directive deletes the timer specified by id. If the timer is running, it is automatically canceled. The TMCB for the deleted timer is reclaimed by RTEMS.

NOTES:

This directive will not cause the running task to be preempted.

A timer can be deleted by a task other than the task which created the timer.

10.4.5. TIMER_FIRE_AFTER - Fire timer after interval¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_fire_after(
    rtems_id                           id,
    rtems_interval                     ticks,
    rtems_timer_service_routine_entry  routine,
    void                              *user_data
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer initiated successfully
RTEMS_INVALID_ADDRESS	routine is NULL
RTEMS_INVALID_ID	invalid timer id
RTEMS_INVALID_NUMBER	invalid interval

DESCRIPTION:

This directive initiates the timer specified by id. If the timer is running, it is automatically canceled before being initiated. The timer is scheduled to fire after an interval ticks clock ticks has passed. When the timer fires, the timer service routine routine will be invoked with the argument user_data.

NOTES:

This directive will not cause the running task to be preempted.

10.4.6. TIMER_FIRE_WHEN - Fire timer when specified¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_fire_when(
    rtems_id                           id,
    rtems_time_of_day                 *wall_time,
    rtems_timer_service_routine_entry  routine,
    void                              *user_data
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer initiated successfully
RTEMS_INVALID_ADDRESS	routine is NULL
RTEMS_INVALID_ADDRESS	wall_time is NULL
RTEMS_INVALID_ID	invalid timer id
RTEMS_NOT_DEFINED	system date and time is not set
RTEMS_INVALID_CLOCK	invalid time of day

DESCRIPTION:

This directive initiates the timer specified by id. If the timer is running, it is automatically canceled before being initiated. The timer is scheduled to fire at the time of day specified by wall_time. When the timer fires, the timer service routine routine will be invoked with the argument user_data.

NOTES:

This directive will not cause the running task to be preempted.

10.4.7. TIMER_INITIATE_SERVER - Initiate server for task-based timers¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_initiate_server(
    uint32_t         priority,
    uint32_t         stack_size,
    rtems_attribute  attribute_set
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Timer Server initiated successfully
RTEMS_TOO_MANY	too many tasks created

DESCRIPTION:

This directive initiates the Timer Server task. This task is responsible for executing all timers initiated via the rtems_timer_server_fire_after or rtems_timer_server_fire_when directives.

NOTES:

This directive could cause the calling task to be preempted.

The Timer Server task is created using the rtems_task_create service and must be accounted for when configuring the system.

Even through this directive invokes the rtems_task_create and rtems_task_start directives, it should only fail due to resource allocation problems.

10.4.8. TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_server_fire_after(
    rtems_id                           id,
    rtems_interval                     ticks,
    rtems_timer_service_routine_entry  routine,
    void                              *user_data
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer initiated successfully
RTEMS_INVALID_ADDRESS	routine is NULL
RTEMS_INVALID_ID	invalid timer id
RTEMS_INVALID_NUMBER	invalid interval
RTEMS_INCORRECT_STATE	Timer Server not initiated

DESCRIPTION:

This directive initiates the timer specified by id and specifies that when it fires it will be executed by the Timer Server.

If the timer is running, it is automatically canceled before being initiated. The timer is scheduled to fire after an interval ticks clock ticks has passed. When the timer fires, the timer service routine routine will be invoked with the argument user_data.

NOTES:

This directive will not cause the running task to be preempted.

10.4.9. TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_server_fire_when(
    rtems_id                           id,
    rtems_time_of_day                 *wall_time,
    rtems_timer_service_routine_entry  routine,
    void                              *user_data
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer initiated successfully
RTEMS_INVALID_ADDRESS	routine is NULL
RTEMS_INVALID_ADDRESS	wall_time is NULL
RTEMS_INVALID_ID	invalid timer id
RTEMS_NOT_DEFINED	system date and time is not set
RTEMS_INVALID_CLOCK	invalid time of day
RTEMS_INCORRECT_STATE	Timer Server not initiated

DESCRIPTION:

This directive initiates the timer specified by id and specifies that when it fires it will be executed by the Timer Server.

If the timer is running, it is automatically canceled before being initiated. The timer is scheduled to fire at the time of day specified by wall_time. When the timer fires, the timer service routine routine will be invoked with the argument user_data.

NOTES:

This directive will not cause the running task to be preempted.

10.4.10. TIMER_RESET - Reset an interval timer¶

CALLING SEQUENCE:

rtems_status_code rtems_timer_reset(
    rtems_id   id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	timer reset successfully
RTEMS_INVALID_ID	invalid timer id
RTEMS_NOT_DEFINED	attempted to reset a when or newly created timer

DESCRIPTION:

This directive resets the timer associated with id. This timer must have been previously initiated with either the rtems_timer_fire_after or rtems_timer_server_fire_after directive. If active the timer is canceled, after which the timer is reinitiated using the same interval and timer service routine which the original rtems_timer_fire_after or rtems_timer_server_fire_after directive used.

NOTES:

If the timer has not been used or the last usage of this timer was by a rtems_timer_fire_when or rtems_timer_server_fire_when directive, then the RTEMS_NOT_DEFINED error is returned.

Restarting a cancelled after timer results in the timer being reinitiated with its previous timer service routine and interval.

This directive will not cause the running task to be preempted.

11.2.1. Rate Monotonic Manager Required Support¶

A clock tick is required to support the functionality provided by this manager.

11.2.2. Period Statistics¶

This manager maintains a set of statistics on each period object. These statistics are reset implictly at period creation time and may be reset or obtained at any time by the application. The following is a list of the information kept:

owner

is the id of the thread that owns this period.

count

is the total number of periods executed.

missed_count

is the number of periods that were missed.

min_cpu_time

is the minimum amount of CPU execution time consumed on any execution of the periodic loop.

max_cpu_time

is the maximum amount of CPU execution time consumed on any execution of the periodic loop.

total_cpu_time

is the total amount of CPU execution time consumed by executions of the periodic loop.

min_wall_time

is the minimum amount of wall time that passed on any execution of the periodic loop.

max_wall_time

is the maximum amount of wall time that passed on any execution of the periodic loop.

total_wall_time

is the total amount of wall time that passed during executions of the periodic loop.

Each period is divided into two consecutive phases. The period starts with the active phase of the task and is followed by the inactive phase of the task. In the inactive phase the task is blocked and waits for the start of the next period. The inactive phase is skipped in case of a period miss. The wall time includes the time during the active phase of the task on which the task is not executing on a processor. The task is either blocked (for example it waits for a resource) or a higher priority tasks executes, thus preventing it from executing. In case the wall time exceeds the period time, then this is a period miss. The gap between the wall time and the period time is the margin between a period miss or success.

The period statistics information is inexpensive to maintain and can provide very useful insights into the execution characteristics of a periodic task loop. But it is just information. The period statistics reported must be analyzed by the user in terms of what the applications is. For example, in an application where priorities are assigned by the Rate Monotonic Algorithm, it would be very undesirable for high priority (i.e. frequency) tasks to miss their period. Similarly, in nearly any application, if a task were supposed to execute its periodic loop every 10 milliseconds and it averaged 11 milliseconds, then application requirements are not being met.

The information reported can be used to determine the “hot spots” in the application. Given a period’s id, the user can determine the length of that period. From that information and the CPU usage, the user can calculate the percentage of CPU time consumed by that periodic task. For example, a task executing for 20 milliseconds every 200 milliseconds is consuming 10 percent of the processor’s execution time. This is usually enough to make it a good candidate for optimization.

However, execution time alone is not enough to gauge the value of optimizing a particular task. It is more important to optimize a task executing 2 millisecond every 10 milliseconds (20 percent of the CPU) than one executing 10 milliseconds every 100 (10 percent of the CPU). As a general rule of thumb, the higher frequency at which a task executes, the more important it is to optimize that task.

11.2.3. Rate Monotonic Manager Definitions¶

A periodic task is one which must be executed at a regular interval. The interval between successive iterations of the task is referred to as its period. Periodic tasks can be characterized by the length of their period and execution time. The period and execution time of a task can be used to determine the processor utilization for that task. Processor utilization is the percentage of processor time used and can be calculated on a per-task or system-wide basis. Typically, the task’s worst-case execution time will be less than its period. For example, a periodic task’s requirements may state that it should execute for 10 milliseconds every 100 milliseconds. Although the execution time may be the average, worst, or best case, the worst-case execution time is more appropriate for use when analyzing system behavior under transient overload conditions... index:: aperiodic task, definition

In contrast, an aperiodic task executes at irregular intervals and has only a soft deadline. In other words, the deadlines for aperiodic tasks are not rigid, but adequate response times are desirable. For example, an aperiodic task may process user input from a terminal.

Finally, a sporadic task is an aperiodic task with a hard deadline and minimum interarrival time. The minimum interarrival time is the minimum period of time which exists between successive iterations of the task. For example, a sporadic task could be used to process the pressing of a fire button on a joystick. The mechanical action of the fire button ensures a minimum time period between successive activations, but the missile must be launched by a hard deadline.

11.2.4. Rate Monotonic Scheduling Algorithm¶

The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems designers because it allows one to guarantee that a set of tasks is schedulable. A set of tasks is said to be schedulable if all of the tasks can meet their deadlines. RMS provides a set of rules which can be used to perform a guaranteed schedulability analysis for a task set. This analysis determines whether a task set is schedulable under worst-case conditions and emphasizes the predictability of the system’s behavior. It has been proven that:

RMS is optimal in the sense that if a set of tasks can be scheduled by any static priority algorithm, then RMS will be able to schedule that task set. RMS bases it schedulability analysis on the processor utilization level below which all deadlines can be met.

RMS calls for the static assignment of task priorities based upon their period. The shorter a task’s period, the higher its priority. For example, a task with a 1 millisecond period has higher priority than a task with a 100 millisecond period. If two tasks have the same period, then RMS does not distinguish between the tasks. However, RTEMS specifies that when given tasks of equal priority, the task which has been ready longest will execute first. RMS’s priority assignment scheme does not provide one with exact numeric values for task priorities. For example, consider the following task set and priority assignments:

RMS only calls for task 1 to have the lowest priority, task 4 to have the highest priority, and tasks 2 and 3 to have an equal priority between that of tasks 1 and 4. The actual RTEMS priorities assigned to the tasks must only adhere to those guidelines.

Many applications have tasks with both hard and soft deadlines. The tasks with hard deadlines are typically referred to as the critical task set, with the soft deadline tasks being the non-critical task set. The critical task set can be scheduled using RMS, with the non-critical tasks not executing under transient overload, by simply assigning priorities such that the lowest priority critical task (i.e. longest period) has a higher priority than the highest priority non-critical task. Although RMS may be used to assign priorities to the non-critical tasks, it is not necessary. In this instance, schedulability is only guaranteed for the critical task set.

11.2.5. Schedulability Analysis¶

RMS allows application designers to ensure that tasks can meet all deadlines, even under transient overload, without knowing exactly when any given task will execute by applying proven schedulability analysis rules.

Utilization = 0
for index = 1 to maximum_tasks
    Utilization = Utilization + (Time(index)/Period(index))

Utilization = maximum_tasks * (2**(1/maximum_tasks) - 1)

11.3.1. Creating a Rate Monotonic Period¶

The rtems_rate_monotonic_create directive creates a rate monotonic period which is to be used by the calling task to delineate a period. RTEMS allocates a Period Control Block (PCB) from the PCB free list. This data structure is used by RTEMS to manage the newly created rate monotonic period. RTEMS returns a unique period ID to the application which is used by other rate monotonic manager directives to access this rate monotonic period.

11.3.2. Manipulating a Period¶

The rtems_rate_monotonic_period directive is used to establish and maintain periodic execution utilizing a previously created rate monotonic period. Once initiated by the rtems_rate_monotonic_period directive, the period is said to run until it either expires or is reinitiated. The state of the rate monotonic period results in one of the following scenarios:

• If the rate monotonic period is running, the calling task will be blocked for the remainder of the outstanding period and, upon completion of that period, the period will be reinitiated with the specified period.
• If the rate monotonic period is not currently running and has not expired, it is initiated with a length of period ticks and the calling task returns immediately.
• If the rate monotonic period has expired before the task invokes the rtems_rate_monotonic_period directive, the period will be initiated with a length of period ticks and the calling task returns immediately with a timeout error status.

11.3.3. Obtaining the Status of a Period¶

If the rtems_rate_monotonic_period directive is invoked with a period of RTEMS_PERIOD_STATUS ticks, the current state of the specified rate monotonic period will be returned. The following table details the relationship between the period’s status and the directive status code returned by the rtems_rate_monotonic_period directive:

Obtaining the status of a rate monotonic period does not alter the state or length of that period.

11.3.4. Canceling a Period¶

The rtems_rate_monotonic_cancel directive is used to stop the period maintained by the specified rate monotonic period. The period is stopped and the rate monotonic period can be reinitiated using the rtems_rate_monotonic_period directive.

11.3.5. Deleting a Rate Monotonic Period¶

The rtems_rate_monotonic_delete directive is used to delete a rate monotonic period. If the period is running and has not expired, the period is automatically canceled. The rate monotonic period’s control block is returned to the PCB free list when it is deleted. A rate monotonic period can be deleted by a task other than the task which created the period.

11.3.6. Examples¶

The following sections illustrate common uses of rate monotonic periods to construct periodic tasks.

11.3.7. Simple Periodic Task¶

This example consists of a single periodic task which, after initialization, executes every 100 clock ticks.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

rtems_task Periodic_task(rtems_task_argument arg)
{
    rtems_name        name;
    rtems_id          period;
    rtems_status_code status;
    name = rtems_build_name( 'P', 'E', 'R', 'D' );
    status = rtems_rate_monotonic_create( name, &period );
    if ( status != RTEMS_STATUS_SUCCESSFUL ) {
        printf( "rtems_monotonic_create failed with status of %d.\n", rc );
        exit( 1 );
    }
    while ( 1 ) {
        if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT )
            break;
        /* Perform some periodic actions */
    }
    /* missed period so delete period and SELF */
    status = rtems_rate_monotonic_delete( period );
    if ( status != RTEMS_STATUS_SUCCESSFUL ) {
        printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status );
        exit( 1 );
    }
    status = rtems_task_delete( SELF );    /* should not return */
    printf( "rtems_task_delete returned with status of %d.\n", status );
    exit( 1 );
}

The above task creates a rate monotonic period as part of its initialization. The first time the loop is executed, the rtems_rate_monotonic_period directive will initiate the period for 100 ticks and return immediately. Subsequent invocations of the rtems_rate_monotonic_period directive will result in the task blocking for the remainder of the 100 tick period. If, for any reason, the body of the loop takes more than 100 ticks to execute, the rtems_rate_monotonic_period directive will return the RTEMS_TIMEOUT status. If the above task misses its deadline, it will delete the rate monotonic period and itself.

11.3.8. Task with Multiple Periods¶

This example consists of a single periodic task which, after initialization, performs two sets of actions every 100 clock ticks. The first set of actions is performed in the first forty clock ticks of every 100 clock ticks, while the second set of actions is performed between the fortieth and seventieth clock ticks. The last thirty clock ticks are not used by this task.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

rtems_task Periodic_task(rtems_task_argument arg)
{
    rtems_name        name_1, name_2;
    rtems_id          period_1, period_2;
    rtems_status_code status;
    name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
    name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
    (void ) rtems_rate_monotonic_create( name_1, &period_1 );
    (void ) rtems_rate_monotonic_create( name_2, &period_2 );
    while ( 1 ) {
        if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT )
            break;
        if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT )
        break;
        /*
         *  Perform first set of actions between clock
         *  ticks 0 and 39 of every 100 ticks.
         */
        if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT )
            break;
        /*
         *  Perform second set of actions between clock 40 and 69
         *  of every 100 ticks.  THEN ...
         *
         *  Check to make sure we didn't miss the period_2 period.
         */
        if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
            break;
        (void) rtems_rate_monotonic_cancel( period_2 );
    }
    /* missed period so delete period and SELF */
    (void ) rtems_rate_monotonic_delete( period_1 );
    (void ) rtems_rate_monotonic_delete( period_2 );
    (void ) task_delete( SELF );
}

The above task creates two rate monotonic periods as part of its initialization. The first time the loop is executed, the rtems_rate_monotonic_period directive will initiate the period_1 period for 100 ticks and return immediately. Subsequent invocations of the rtems_rate_monotonic_period directive for period_1 will result in the task blocking for the remainder of the 100 tick period. The period_2 period is used to control the execution time of the two sets of actions within each 100 tick period established by period_1. The rtems_rate_monotonic_cancel( period_2 ) call is performed to ensure that the period_2 period does not expire while the task is blocked on the period_1 period. If this cancel operation were not performed, every time the rtems_rate_monotonic_period( period_2, 40 ) call is executed, except for the initial one, a directive status of RTEMS_TIMEOUT is returned. It is important to note that every time this call is made, the period_2 period will be initiated immediately and the task will not block.

If, for any reason, the task misses any deadline, the rtems_rate_monotonic_period directive will return the RTEMS_TIMEOUT directive status. If the above task misses its deadline, it will delete the rate monotonic periods and itself.

11.4.1. RATE_MONOTONIC_CREATE - Create a rate monotonic period¶

CALLING SEQUENCE:

rtems_status_code rtems_rate_monotonic_create(
    rtems_name  name,
    rtems_id   *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	rate monotonic period created successfully
RTEMS_INVALID_NAME	invalid period name
RTEMS_TOO_MANY	too many periods created

DESCRIPTION:

This directive creates a rate monotonic period. The assigned rate monotonic id is returned in id. This id is used to access the period with other rate monotonic manager directives. For control and maintenance of the rate monotonic period, RTEMS allocates a PCB from the local PCB free pool and initializes it.

NOTES:

This directive will not cause the calling task to be preempted.

11.4.2. RATE_MONOTONIC_IDENT - Get ID of a period¶

CALLING SEQUENCE:

rtems_status_code rtems_rate_monotonic_ident(
    rtems_name  name,
    rtems_id   *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	period identified successfully
RTEMS_INVALID_NAME	period name not found

DESCRIPTION:

This directive obtains the period id associated with the period name to be acquired. If the period name is not unique, then the period id will match one of the periods with that name. However, this period id is not guaranteed to correspond to the desired period. The period id is used to access this period in other rate monotonic manager directives.

NOTES:

This directive will not cause the running task to be preempted.

11.4.3. RATE_MONOTONIC_CANCEL - Cancel a period¶

CALLING SEQUENCE:

rtems_status_code rtems_rate_monotonic_cancel(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	period canceled successfully
RTEMS_INVALID_ID	invalid rate monotonic period id
RTEMS_NOT_OWNER_OF_RESOURCE	rate monotonic period not created by calling task

DESCRIPTION:

This directive cancels the rate monotonic period id. This period will be reinitiated by the next invocation of rtems_rate_monotonic_period with id.

NOTES:

This directive will not cause the running task to be preempted.

The rate monotonic period specified by id must have been created by the calling task.

11.4.4. RATE_MONOTONIC_DELETE - Delete a rate monotonic period¶

CALLING SEQUENCE:

rtems_status_code rtems_rate_monotonic_delete(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	period deleted successfully
RTEMS_INVALID_ID	invalid rate monotonic period id

DESCRIPTION:

This directive deletes the rate monotonic period specified by id. If the period is running, it is automatically canceled. The PCB for the deleted period is reclaimed by RTEMS.

NOTES:

This directive will not cause the running task to be preempted.

A rate monotonic period can be deleted by a task other than the task which created the period.

11.4.5. RATE_MONOTONIC_PERIOD - Conclude current/Start next period¶

CALLING SEQUENCE:

rtems_status_code rtems_rate_monotonic_period(
    rtems_id       id,
    rtems_interval length
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	period initiated successfully
RTEMS_INVALID_ID	invalid rate monotonic period id
RTEMS_NOT_OWNER_OF_RESOURCE	period not created by calling task
RTEMS_NOT_DEFINED	period has never been initiated (only possible when period is set to PERIOD_STATUS)
RTEMS_TIMEOUT	period has expired

DESCRIPTION:

This directive initiates the rate monotonic period id with a length of period ticks. If id is running, then the calling task will block for the remainder of the period before reinitiating the period with the specified period. If id was not running (either expired or never initiated), the period is immediately initiated and the directive returns immediately.

If invoked with a period of RTEMS_PERIOD_STATUS ticks, the current state of id will be returned. The directive status indicates the current state of the period. This does not alter the state or period of the period.

NOTES:

This directive will not cause the running task to be preempted.

11.4.6. RATE_MONOTONIC_GET_STATUS - Obtain status from a period¶

CALLING SEQUENCE:

rtems_status_code rtems_rate_monotonic_get_status(
    rtems_id                            id,
    rtems_rate_monotonic_period_status *status
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	period initiated successfully
RTEMS_INVALID_ID	invalid rate monotonic period id
RTEMS_INVALID_ADDRESS	invalid address of status

*DESCRIPTION:

This directive returns status information associated with the rate monotonic period id in the following data structure:

typedef struct {
    rtems_id                              owner;
    rtems_rate_monotonic_period_states    state;
    rtems_rate_monotonic_period_time_t    since_last_period;
    rtems_thread_cpu_usage_t              executed_since_last_period;
}  rtems_rate_monotonic_period_status;

A configure time option can be used to select whether the time information is given in ticks or seconds and nanoseconds. The default is seconds and nanoseconds. If the period’s state is RATE_MONOTONIC_INACTIVE, both time values will be set to 0. Otherwise, both time values will contain time information since the last invocation of the rtems_rate_monotonic_period directive. More specifically, the ticks_since_last_period value contains the elapsed time which has occurred since the last invocation of the rtems_rate_monotonic_period directive and the ticks_executed_since_last_period contains how much processor time the owning task has consumed since the invocation of the rtems_rate_monotonic_period directive.

NOTES:

This directive will not cause the running task to be preempted.

11.4.7. RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period¶

CALLING SEQUENCE:

rtems_status_code rtems_rate_monotonic_get_statistics(
    rtems_id                                id,
    rtems_rate_monotonic_period_statistics *statistics
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	period initiated successfully
RTEMS_INVALID_ID	invalid rate monotonic period id
RTEMS_INVALID_ADDRESS	invalid address of statistics

DESCRIPTION:

This directive returns statistics information associated with the rate monotonic period id in the following data structure:

typedef struct {
    uint32_t     count;
    uint32_t     missed_count;
    #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
      struct timespec min_cpu_time;
      struct timespec max_cpu_time;
      struct timespec total_cpu_time;
    #else
      uint32_t  min_cpu_time;
      uint32_t  max_cpu_time;
      uint32_t  total_cpu_time;
    #endif
    #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
      struct timespec min_wall_time;
      struct timespec max_wall_time;
      struct timespec total_wall_time;
    #else
     uint32_t  min_wall_time;
     uint32_t  max_wall_time;
     uint32_t  total_wall_time;
    #endif
}  rtems_rate_monotonic_period_statistics;

This directive returns the current statistics information for the period instance assocaited with id. The information returned is indicated by the structure above.

NOTES:

This directive will not cause the running task to be preempted.

11.4.8. RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period¶

CALLING SEQUENCE:

rtems_status_code rtems_rate_monotonic_reset_statistics(
    rtems_id  id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	period initiated successfully
RTEMS_INVALID_ID	invalid rate monotonic period id

DESCRIPTION:

This directive resets the statistics information associated with this rate monotonic period instance.

NOTES:

This directive will not cause the running task to be preempted.

11.4.9. RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods¶

CALLING SEQUENCE:

void rtems_rate_monotonic_reset_all_statistics(void);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive resets the statistics information associated with all rate monotonic period instances.

NOTES:

This directive will not cause the running task to be preempted.

11.4.10. RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report¶

CALLING SEQUENCE:

void rtems_rate_monotonic_report_statistics(void);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive prints a report on all active periods which have executed at least one period. The following is an example of the output generated by this directive.

ID      OWNER   PERIODS  MISSED    CPU TIME    WALL TIME
MIN/MAX/AVG  MIN/MAX/AVG
0x42010001  TA1       502     0       0/1/0.99    0/0/0.00
0x42010002  TA2       502     0       0/1/0.99    0/0/0.00
0x42010003  TA3       501     0       0/1/0.99    0/0/0.00
0x42010004  TA4       501     0       0/1/0.99    0/0/0.00
0x42010005  TA5        10     0       0/1/0.90    0/0/0.00

NOTES:

This directive will not cause the running task to be preempted.

12.2.1. Nested Resource Access¶

Deadlock occurs when a task owning a binary semaphore attempts to acquire that same semaphore and blocks as result. Since the semaphore is allocated to a task, it cannot be deleted. Therefore, the task that currently holds the semaphore and is also blocked waiting for that semaphore will never execute again.

RTEMS addresses this problem by allowing the task holding the binary semaphore to obtain the same binary semaphore multiple times in a nested manner. Each rtems_semaphore_obtain must be accompanied with a rtems_semaphore_release. The semaphore will only be made available for acquisition by other tasks when the outermost rtems_semaphore_obtain is matched with a rtems_semaphore_release.

Simple binary semaphores do not allow nested access and so can be used for task synchronization.

12.2.2. Priority Inversion¶

Priority inversion is a form of indefinite postponement which is common in multitasking, preemptive executives with shared resources. Priority inversion occurs when a high priority tasks requests access to shared resource which is currently allocated to low priority task. The high priority task must block until the low priority task releases the resource. This problem is exacerbated when the low priority task is prevented from executing by one or more medium priority tasks. Because the low priority task is not executing, it cannot complete its interaction with the resource and release that resource. The high priority task is effectively prevented from executing by lower priority tasks.

12.2.3. Priority Inheritance¶

Priority inheritance is an algorithm that calls for the lower priority task holding a resource to have its priority increased to that of the highest priority task blocked waiting for that resource. Each time a task blocks attempting to obtain the resource, the task holding the resource may have its priority increased.

On SMP configurations, in case the task holding the resource and the task that blocks attempting to obtain the resource are in different scheduler instances, the priority of the holder is raised to the pseudo-interrupt priority (priority boosting). The pseudo-interrupt priority is the highest priority.

RTEMS supports priority inheritance for local, binary semaphores that use the priority task wait queue blocking discipline. When a task of higher priority than the task holding the semaphore blocks, the priority of the task holding the semaphore is increased to that of the blocking task. When the task holding the task completely releases the binary semaphore (i.e. not for a nested release), the holder’s priority is restored to the value it had before any higher priority was inherited.

The RTEMS implementation of the priority inheritance algorithm takes into account the scenario in which a task holds more than one binary semaphore. The holding task will execute at the priority of the higher of the highest ceiling priority or at the priority of the highest priority task blocked waiting for any of the semaphores the task holds. Only when the task releases ALL of the binary semaphores it holds will its priority be restored to the normal value.

12.2.4. Priority Ceiling¶

Priority ceiling is an algorithm that calls for the lower priority task holding a resource to have its priority increased to that of the highest priority task which will EVER block waiting for that resource. This algorithm addresses the problem of priority inversion although it avoids the possibility of changing the priority of the task holding the resource multiple times. The priority ceiling algorithm will only change the priority of the task holding the resource a maximum of one time. The ceiling priority is set at creation time and must be the priority of the highest priority task which will ever attempt to acquire that semaphore.

RTEMS supports priority ceiling for local, binary semaphores that use the priority task wait queue blocking discipline. When a task of lower priority than the ceiling priority successfully obtains the semaphore, its priority is raised to the ceiling priority. When the task holding the task completely releases the binary semaphore (i.e. not for a nested release), the holder’s priority is restored to the value it had before any higher priority was put into effect.

The need to identify the highest priority task which will attempt to obtain a particular semaphore can be a difficult task in a large, complicated system. Although the priority ceiling algorithm is more efficient than the priority inheritance algorithm with respect to the maximum number of task priority changes which may occur while a task holds a particular semaphore, the priority inheritance algorithm is more forgiving in that it does not require this apriori information.

The RTEMS implementation of the priority ceiling algorithm takes into account the scenario in which a task holds more than one binary semaphore. The holding task will execute at the priority of the higher of the highest ceiling priority or at the priority of the highest priority task blocked waiting for any of the semaphores the task holds. Only when the task releases ALL of the binary semaphores it holds will its priority be restored to the normal value.

12.2.5. Multiprocessor Resource Sharing Protocol¶

The Multiprocessor Resource Sharing Protocol (MrsP) is defined in A. Burns and A.J. Wellings, A Schedulability Compatible Multiprocessor Resource Sharing Protocol - MrsP, Proceedings of the 25th Euromicro Conference on Real-Time Systems (ECRTS 2013), July 2013. It is a generalization of the Priority Ceiling Protocol to SMP systems. Each MrsP semaphore uses a ceiling priority per scheduler instance. These ceiling priorities can be specified with rtems_semaphore_set_priority(). A task obtaining or owning a MrsP semaphore will execute with the ceiling priority for its scheduler instance as specified by the MrsP semaphore object. Tasks waiting to get ownership of a MrsP semaphore will not relinquish the processor voluntarily. In case the owner of a MrsP semaphore gets preempted it can ask all tasks waiting for this semaphore to help out and temporarily borrow the right to execute on one of their assigned processors.

12.2.6. Building a Semaphore Attribute Set¶

In general, an attribute set is built by a bitwise OR of the desired attribute components. The following table lists the set of valid semaphore attributes:

Attribute values are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list. An attribute listed as a default is not required to appear in the attribute list, although it is a good programming practice to specify default attributes. If all defaults are desired, the attribute RTEMS_DEFAULT_ATTRIBUTES should be specified on this call.

This example demonstrates the attribute_set parameter needed to create a local semaphore with the task priority waiting queue discipline. The attribute_set parameter passed to the rtems_semaphore_create directive could be either RTEMS_PRIORITY or RTEMS_LOCAL | RTEMS_PRIORITY. The attribute_set parameter can be set to RTEMS_PRIORITY because RTEMS_LOCAL is the default for all created tasks. If a similar semaphore were to be known globally, then the attribute_set parameter would be RTEMS_GLOBAL | RTEMS_PRIORITY.

Some combinatinos of these attributes are invalid. For example, priority ordered blocking discipline must be applied to a binary semaphore in order to use either the priority inheritance or priority ceiling functionality. The following tree figure illustrates the valid combinations.

12.2.7. Building a SEMAPHORE_OBTAIN Option Set¶

In general, an option is built by a bitwise OR of the desired option components. The set of valid options for the rtems_semaphore_obtain directive are listed in the following table:

Option values are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list. An option listed as a default is not required to appear in the list, although it is a good programming practice to specify default options. If all defaults are desired, the option RTEMS_DEFAULT_OPTIONS should be specified on this call.

This example demonstrates the option parameter needed to poll for a semaphore. The option parameter passed to the rtems_semaphore_obtain directive should be RTEMS_NO_WAIT.

12.3.1. Creating a Semaphore¶

The rtems_semaphore_create directive creates a binary or counting semaphore with a user-specified name as well as an initial count. If a binary semaphore is created with a count of zero (0) to indicate that it has been allocated, then the task creating the semaphore is considered the current holder of the semaphore. At create time the method for ordering waiting tasks in the semaphore’s task wait queue (by FIFO or task priority) is specified. Additionally, the priority inheritance or priority ceiling algorithm may be selected for local, binary semaphores that use the priority task wait queue blocking discipline. If the priority ceiling algorithm is selected, then the highest priority of any task which will attempt to obtain this semaphore must be specified. RTEMS allocates a Semaphore Control Block (SMCB) from the SMCB free list. This data structure is used by RTEMS to manage the newly created semaphore. Also, a unique semaphore ID is generated and returned to the calling task.

12.3.2. Obtaining Semaphore IDs¶

When a semaphore is created, RTEMS generates a unique semaphore ID and assigns it to the created semaphore until it is deleted. The semaphore ID may be obtained by either of two methods. First, as the result of an invocation of the rtems_semaphore_create directive, the semaphore ID is stored in a user provided location. Second, the semaphore ID may be obtained later using the rtems_semaphore_ident directive. The semaphore ID is used by other semaphore manager directives to access this semaphore.

12.3.3. Acquiring a Semaphore¶

The rtems_semaphore_obtain directive is used to acquire the specified semaphore. A simplified version of the rtems_semaphore_obtain directive can be described as follows:

If the semaphore’s count is greater than zero then decrement the semaphore’s count else wait for release of semaphore then return SUCCESSFUL.

When the semaphore cannot be immediately acquired, one of the following situations applies:

• By default, the calling task will wait forever to acquire the semaphore.
• Specifying RTEMS_NO_WAIT forces an immediate return with an error status code.
• Specifying a timeout limits the interval the task will wait before returning with an error status code.

If the task waits to acquire the semaphore, then it is placed in the semaphore’s task wait queue in either FIFO or task priority order. If the task blocked waiting for a binary semaphore using priority inheritance and the task’s priority is greater than that of the task currently holding the semaphore, then the holding task will inherit the priority of the blocking task. All tasks waiting on a semaphore are returned an error code when the semaphore is deleted.

When a task successfully obtains a semaphore using priority ceiling and the priority ceiling for this semaphore is greater than that of the holder, then the holder’s priority will be elevated.

12.3.4. Releasing a Semaphore¶

The rtems_semaphore_release directive is used to release the specified semaphore. A simplified version of the rtems_semaphore_release directive can be described as follows:

If there sre no tasks are waiting on this semaphore then increment the semaphore’s count else assign semaphore to a waiting task and return SUCCESSFUL.

If this is the outermost release of a binary semaphore that uses priority inheritance or priority ceiling and the task does not currently hold any other binary semaphores, then the task performing the rtems_semaphore_release will have its priority restored to its normal value.

12.3.5. Deleting a Semaphore¶

The rtems_semaphore_delete directive removes a semaphore from the system and frees its control block. A semaphore can be deleted by any local task that knows the semaphore’s ID. As a result of this directive, all tasks blocked waiting to acquire the semaphore will be readied and returned a status code which indicates that the semaphore was deleted. Any subsequent references to the semaphore’s name and ID are invalid.

12.4.1. SEMAPHORE_CREATE - Create a semaphore¶

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_create(
    rtems_name           name,
    uint32_t             count,
    rtems_attribute      attribute_set,
    rtems_task_priority  priority_ceiling,
    rtems_id            *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	semaphore created successfully
RTEMS_INVALID_NAME	invalid semaphore name
RTEMS_INVALID_ADDRESS	id is NULL
RTEMS_TOO_MANY	too many semaphores created
RTEMS_NOT_DEFINED	invalid attribute set
RTEMS_INVALID_NUMBER	invalid starting count for binary semaphore
RTEMS_MP_NOT_CONFIGURED	multiprocessing not configured
RTEMS_TOO_MANY	too many global objects

DESCRIPTION:

This directive creates a semaphore which resides on the local node. The created semaphore has the user-defined name specified in name and the initial count specified in count. For control and maintenance of the semaphore, RTEMS allocates and initializes a SMCB. The RTEMS-assigned semaphore id is returned in id. This semaphore id is used with other semaphore related directives to access the semaphore.

Specifying PRIORITY in attribute_set causes tasks waiting for a semaphore to be serviced according to task priority. When FIFO is selected, tasks are serviced in First In-First Out order.

NOTES:

This directive will not cause the calling task to be preempted.

The priority inheritance and priority ceiling algorithms are only supported for local, binary semaphores that use the priority task wait queue blocking discipline.

The following semaphore attribute constants are defined by RTEMS:

RTEMS_FIFO	tasks wait by FIFO (default)
RTEMS_PRIORITY	tasks wait by priority
RTEMS_BINARY_SEMAPHORE	restrict values to 0 and 1
RTEMS_COUNTING_SEMAPHORE	no restriction on values (default)
RTEMS_SIMPLE_BINARY_SEMAPHORE	restrict values to 0 and 1, block on nested access, allow deletion of locked semaphore.
RTEMS_NO_INHERIT_PRIORITY	do not use priority inheritance (default)
RTEMS_INHERIT_PRIORITY	use priority inheritance
RTEMS_NO_PRIORITY_CEILING	do not use priority ceiling (default)
RTEMS_PRIORITY_CEILING	use priority ceiling
RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING	do not use Multiprocessor Resource Sharing Protocol (default)
RTEMS_MULTIPROCESSOR_RESOURCE_SHARING	use Multiprocessor Resource Sharing Protocol
RTEMS_LOCAL	local semaphore (default)
RTEMS_GLOBAL	global semaphore

Semaphores should not be made global unless remote tasks must interact with the created semaphore. This is to avoid the system overhead incurred by the creation of a global semaphore. When a global semaphore is created, the semaphore’s name and id must be transmitted to every node in the system for insertion in the local copy of the global object table.

Note, some combinations of attributes are not valid. See the earlier discussion on this.

The total number of global objects, including semaphores, is limited by the maximum_global_objects field in the Configuration Table.

It is not allowed to create an initially locked MrsP semaphore and the RTEMS_INVALID_NUMBER status code will be returned on SMP configurations in this case. This prevents lock order reversal problems with the allocator mutex.

12.4.2. SEMAPHORE_IDENT - Get ID of a semaphore¶

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_ident(
    rtems_name  name,
    uint32_t    node,
    rtems_id   *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	semaphore identified successfully
RTEMS_INVALID_NAME	semaphore name not found
RTEMS_INVALID_NODE	invalid node id

DESCRIPTION:

This directive obtains the semaphore id associated with the semaphore name. If the semaphore name is not unique, then the semaphore id will match one of the semaphores with that name. However, this semaphore id is not guaranteed to correspond to the desired semaphore. The semaphore id is used by other semaphore related directives to access the semaphore.

NOTES:

This directive will not cause the running task to be preempted.

If node is RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being searched first. All other nodes are searched with the lowest numbered node searched first.

If node is a valid node number which does not represent the local node, then only the semaphores exported by the designated node are searched.

This directive does not generate activity on remote nodes. It accesses only the local copy of the global object table.

12.4.3. SEMAPHORE_DELETE - Delete a semaphore¶

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_delete(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	semaphore deleted successfully
RTEMS_INVALID_ID	invalid semaphore id
RTEMS_RESOURCE_IN_USE	binary semaphore is in use
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	cannot delete remote semaphore

DESCRIPTION:

This directive deletes the semaphore specified by id. All tasks blocked waiting to acquire the semaphore will be readied and returned a status code which indicates that the semaphore was deleted. The SMCB for this semaphore is reclaimed by RTEMS.

NOTES:

The calling task will be preempted if it is enabled by the task’s execution mode and a higher priority local task is waiting on the deleted semaphore. The calling task will NOT be preempted if all of the tasks that are waiting on the semaphore are remote tasks.

The calling task does not have to be the task that created the semaphore. Any local task that knows the semaphore id can delete the semaphore.

When a global semaphore is deleted, the semaphore id must be transmitted to every node in the system for deletion from the local copy of the global object table.

The semaphore must reside on the local node, even if the semaphore was created with the RTEMS_GLOBAL option.

Proxies, used to represent remote tasks, are reclaimed when the semaphore is deleted.

12.4.4. SEMAPHORE_OBTAIN - Acquire a semaphore¶

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_obtain(
    rtems_id        id,
    rtems_option    option_set,
    rtems_interval  timeout
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	semaphore obtained successfully
RTEMS_UNSATISFIED	semaphore not available
RTEMS_TIMEOUT	timed out waiting for semaphore
RTEMS_OBJECT_WAS_DELETED	semaphore deleted while waiting
RTEMS_INVALID_ID	invalid semaphore id

DESCRIPTION:

This directive acquires the semaphore specified by id. The RTEMS_WAIT and RTEMS_NO_WAIT components of the options parameter indicate whether the calling task wants to wait for the semaphore to become available or return immediately if the semaphore is not currently available. With either RTEMS_WAIT or RTEMS_NO_WAIT, if the current semaphore count is positive, then it is decremented by one and the semaphore is successfully acquired by returning immediately with a successful return code.

If the calling task chooses to return immediately and the current semaphore count is zero or negative, then a status code is returned indicating that the semaphore is not available. If the calling task chooses to wait for a semaphore and the current semaphore count is zero or negative, then it is decremented by one and the calling task is placed on the semaphore’s wait queue and blocked. If the semaphore was created with the RTEMS_PRIORITY attribute, then the calling task is inserted into the queue according to its priority. However, if the semaphore was created with the RTEMS_FIFO attribute, then the calling task is placed at the rear of the wait queue. If the binary semaphore was created with the RTEMS_INHERIT_PRIORITY attribute, then the priority of the task currently holding the binary semaphore is guaranteed to be greater than or equal to that of the blocking task. If the binary semaphore was created with the RTEMS_PRIORITY_CEILING attribute, a task successfully obtains the semaphore, and the priority of that task is greater than the ceiling priority for this semaphore, then the priority of the task obtaining the semaphore is elevated to that of the ceiling.

The timeout parameter specifies the maximum interval the calling task is willing to be blocked waiting for the semaphore. If it is set to RTEMS_NO_TIMEOUT, then the calling task will wait forever. If the semaphore is available or the RTEMS_NO_WAIT option component is set, then timeout is ignored.

Deadlock situations are detected for MrsP semaphores and the RTEMS_UNSATISFIED status code will be returned on SMP configurations in this case.

NOTES:

The following semaphore acquisition option constants are defined by RTEMS:

RTEMS_WAIT	task will wait for semaphore (default)
RTEMS_NO_WAIT	task should not wait

Attempting to obtain a global semaphore which does not reside on the local node will generate a request to the remote node to access the semaphore. If the semaphore is not available and RTEMS_NO_WAIT was not specified, then the task must be blocked until the semaphore is released. A proxy is allocated on the remote node to represent the task until the semaphore is released.

A clock tick is required to support the timeout functionality of this directive.

It is not allowed to obtain a MrsP semaphore more than once by one task at a time (nested access) and the RTEMS_UNSATISFIED status code will be returned on SMP configurations in this case.

12.4.5. SEMAPHORE_RELEASE - Release a semaphore¶

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_release(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	semaphore released successfully
RTEMS_INVALID_ID	invalid semaphore id
RTEMS_NOT_OWNER_OF_RESOURCE	calling task does not own semaphore
RTEMS_INCORRECT_STATE	invalid unlock order

DESCRIPTION:

This directive releases the semaphore specified by id. The semaphore count is incremented by one. If the count is zero or negative, then the first task on this semaphore’s wait queue is removed and unblocked. The unblocked task may preempt the running task if the running task’s preemption mode is enabled and the unblocked task has a higher priority than the running task.

NOTES:

The calling task may be preempted if it causes a higher priority task to be made ready for execution.

Releasing a global semaphore which does not reside on the local node will generate a request telling the remote node to release the semaphore.

If the task to be unblocked resides on a different node from the semaphore, then the semaphore allocation is forwarded to the appropriate node, the waiting task is unblocked, and the proxy used to represent the task is reclaimed.

The outermost release of a local, binary, priority inheritance or priority ceiling semaphore may result in the calling task having its priority lowered. This will occur if the calling task holds no other binary semaphores and it has inherited a higher priority.

The MrsP semaphores must be released in the reversed obtain order, otherwise the RTEMS_INCORRECT_STATE status code will be returned on SMP configurations in this case.

12.4.6. SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore¶

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_flush(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	semaphore released successfully
RTEMS_INVALID_ID	invalid semaphore id
RTEMS_NOT_DEFINED	operation not defined for the protocol ofthe semaphore
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	not supported for remote semaphores

DESCRIPTION:

This directive unblocks all tasks waiting on the semaphore specified by id. Since there are tasks blocked on the semaphore, the semaphore’s count is not changed by this directive and thus is zero before and after this directive is executed. Tasks which are unblocked as the result of this directive will return from the rtems_semaphore_obtain directive with a status code of RTEMS_UNSATISFIED to indicate that the semaphore was not obtained.

This directive may unblock any number of tasks. Any of the unblocked tasks may preempt the running task if the running task’s preemption mode is enabled and an unblocked task has a higher priority than the running task.

NOTES:

The calling task may be preempted if it causes a higher priority task to be made ready for execution.

If the task to be unblocked resides on a different node from the semaphore, then the waiting task is unblocked, and the proxy used to represent the task is reclaimed.

It is not allowed to flush a MrsP semaphore and the RTEMS_NOT_DEFINED status code will be returned on SMP configurations in this case.

12.4.7. SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore¶

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_set_priority(
    rtems_id             semaphore_id,
    rtems_id             scheduler_id,
    rtems_task_priority  new_priority,
    rtems_task_priority *old_priority
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	successful operation
RTEMS_INVALID_ID	invalid semaphore or scheduler id
RTEMS_INVALID_ADDRESS	old_priority is NULL
RTEMS_INVALID_PRIORITY	invalid new priority value
RTEMS_NOT_DEFINED	operation not defined for the protocol ofthe semaphore
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	not supported for remote semaphores

DESCRIPTION:

This directive sets the priority value with respect to the specified scheduler of a semaphore.

The special priority value RTEMS_CURRENT_PRIORITY can be used to get the current priority value without changing it.

The interpretation of the priority value depends on the protocol of the semaphore object.

• The Multiprocessor Resource Sharing Protocol needs a ceiling priority per scheduler instance. This operation can be used to specify these priority values.
• For the Priority Ceiling Protocol the ceiling priority is used with this operation.
• For other protocols this operation is not defined.

EXAMPLE:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83

#include <assert.h> #include <stdlib.h> #include <rtems.h> #define SCHED_A rtems_build_name(' ', ' ', ' ', 'A') #define SCHED_B rtems_build_name(' ', ' ', ' ', 'B') static void Init(rtems_task_argument arg) { rtems_status_code sc; rtems_id semaphore_id; rtems_id scheduler_a_id; rtems_id scheduler_b_id; rtems_task_priority prio; /* Get the scheduler identifiers */ sc = rtems_scheduler_ident(SCHED_A, &scheduler_a_id); assert(sc == RTEMS_SUCCESSFUL); sc = rtems_scheduler_ident(SCHED_B, &scheduler_b_id); assert(sc == RTEMS_SUCCESSFUL); /* Create a MrsP semaphore object */ sc = rtems_semaphore_create( rtems_build_name('M', 'R', 'S', 'P'), 1, RTEMS_MULTIPROCESSOR_RESOURCE_SHARING | RTEMS_BINARY_SEMAPHORE, 1, &semaphore_id ); assert(sc == RTEMS_SUCCESSFUL); /* * The ceiling priority values per scheduler are equal to the value specified * for object creation. */ prio = RTEMS_CURRENT_PRIORITY; sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio); assert(sc == RTEMS_SUCCESSFUL); assert(prio == 1); /* Check the old value and set a new ceiling priority for scheduler B */ prio = 2; sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio); assert(sc == RTEMS_SUCCESSFUL); assert(prio == 1); /* Check the ceiling priority values */ prio = RTEMS_CURRENT_PRIORITY; sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio); assert(sc == RTEMS_SUCCESSFUL); assert(prio == 1); prio = RTEMS_CURRENT_PRIORITY; sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio); assert(sc == RTEMS_SUCCESSFUL); assert(prio == 2); sc = rtems_semaphore_delete(semaphore_id); assert(sc == RTEMS_SUCCESSFUL); exit(0); } #define CONFIGURE_SMP_APPLICATION #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER #define CONFIGURE_MAXIMUM_TASKS 1 #define CONFIGURE_MAXIMUM_SEMAPHORES 1 #define CONFIGURE_MAXIMUM_MRSP_SEMAPHORES 1 #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 2 #define CONFIGURE_SCHEDULER_SIMPLE_SMP #include <rtems/scheduler.h> RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(a); RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(b); #define CONFIGURE_SCHEDULER_CONTROLS \ RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(a, SCHED_A), \ RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(b, SCHED_B) #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \ RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY) #define CONFIGURE_RTEMS_INIT_TASKS_TABLE #define CONFIGURE_INIT #include <rtems/confdefs.h>

13.2.1. Automatic Versus Manual Barriers¶

Just as with a real-world gate, barriers may be configured to be manually opened or automatically opened. All tasks calling the rtems_barrier_wait directive will block until a controlling task invokes the rtems_barrier_release directive.

Automatic barriers are created with a limit to the number of tasks which may simultaneously block at the barrier. Once this limit is reached, all of the tasks are released. For example, if the automatic limit is ten tasks, then the first nine tasks calling the rtems_barrier_wait directive will block. When the tenth task calls the rtems_barrier_wait directive, the nine blocked tasks will be released and the tenth task returns to the caller without blocking.

13.2.2. Building a Barrier Attribute Set¶

In general, an attribute set is built by a bitwise OR of the desired attribute components. The following table lists the set of valid barrier attributes:

RTEMS_BARRIER_AUTOMATIC_RELEASE

automatically release the barrier when the configured number of tasks are blocked

RTEMS_BARRIER_MANUAL_RELEASE

only release the barrier when the application invokes the rtems_barrier_release directive. (default)

Attribute values are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list. An attribute listed as a default is not required to appear in the attribute list, although it is a good programming practice to specify default attributes. If all defaults are desired, the attribute RTEMS_DEFAULT_ATTRIBUTES should be specified on this call.

This example demonstrates the attribute_set parameter needed to create a barrier with the automatic release policy. The attribute_set parameter passed to the rtems_barrier_create directive will be RTEMS_BARRIER_AUTOMATIC_RELEASE. In this case, the user must also specify the maximum_waiters parameter.

13.3.1. Creating a Barrier¶

The rtems_barrier_create directive creates a barrier with a user-specified name and the desired attributes. RTEMS allocates a Barrier Control Block (BCB) from the BCB free list. This data structure is used by RTEMS to manage the newly created barrier. Also, a unique barrier ID is generated and returned to the calling task.

13.3.2. Obtaining Barrier IDs¶

When a barrier is created, RTEMS generates a unique barrier ID and assigns it to the created barrier until it is deleted. The barrier ID may be obtained by either of two methods. First, as the result of an invocation of the rtems_barrier_create directive, the barrier ID is stored in a user provided location. Second, the barrier ID may be obtained later using the rtems_barrier_ident directive. The barrier ID is used by other barrier manager directives to access this barrier.

13.3.3. Waiting at a Barrier¶

The rtems_barrier_wait directive is used to wait at the specified barrier. Since a barrier is, by definition, never immediately, the task may wait forever for the barrier to be released or it may specify a timeout. Specifying a timeout limits the interval the task will wait before returning with an error status code.

If the barrier is configured as automatic and there are already one less then the maximum number of waiters, then the call will unblock all tasks waiting at the barrier and the caller will return immediately.

When the task does wait to acquire the barrier, then it is placed in the barrier’s task wait queue in FIFO order. All tasks waiting on a barrier are returned an error code when the barrier is deleted.

13.3.4. Releasing a Barrier¶

The rtems_barrier_release directive is used to release the specified barrier. When the rtems_barrier_release is invoked, all tasks waiting at the barrier are immediately made ready to execute and begin to compete for the processor to execute.

13.3.5. Deleting a Barrier¶

The rtems_barrier_delete directive removes a barrier from the system and frees its control block. A barrier can be deleted by any local task that knows the barrier’s ID. As a result of this directive, all tasks blocked waiting for the barrier to be released, will be readied and returned a status code which indicates that the barrier was deleted. Any subsequent references to the barrier’s name and ID are invalid.

13.4.1. BARRIER_CREATE - Create a barrier¶

CALLING SEQUENCE:

rtems_status_code rtems_barrier_create(
    rtems_name           name,
    rtems_attribute      attribute_set,
    uint32_t             maximum_waiters,
    rtems_id            *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	barrier created successfully
RTEMS_INVALID_NAME	invalid barrier name
RTEMS_INVALID_ADDRESS	id is NULL
RTEMS_TOO_MANY	too many barriers created

DESCRIPTION:

This directive creates a barrier which resides on the local node. The created barrier has the user-defined name specified in name and the initial count specified in count. For control and maintenance of the barrier, RTEMS allocates and initializes a BCB. The RTEMS-assigned barrier id is returned in id. This barrier id is used with other barrier related directives to access the barrier.

RTEMS_BARRIER_MANUAL_RELEASE

only release

Specifying RTEMS_BARRIER_AUTOMATIC_RELEASE in attribute_set causes tasks calling the rtems_barrier_wait directive to block until there are maximum_waiters - 1 tasks waiting at the barrier. When the maximum_waiters task invokes the rtems_barrier_wait directive, the previous maximum_waiters - 1 tasks are automatically released and the caller returns.

In contrast, when the RTEMS_BARRIER_MANUAL_RELEASE attribute is specified, there is no limit on the number of tasks that will block at the barrier. Only when the rtems_barrier_release directive is invoked, are the tasks waiting at the barrier unblocked.

NOTES:

This directive will not cause the calling task to be preempted.

The following barrier attribute constants are defined by RTEMS:

RTEMS_BARRIER_AUTOMATIC_RELEASE	automatically release the barrier when the configured number of tasks are blocked
RTEMS_BARRIER_MANUAL_RELEASE	only release the barrier when the application invokes the rtems_barrier_release directive. (default)

13.4.2. BARRIER_IDENT - Get ID of a barrier¶

CALLING SEQUENCE:

rtems_status_code rtems_barrier_ident(
    rtems_name        name,
    rtems_id         *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	barrier identified successfully
RTEMS_INVALID_NAME	barrier name not found
RTEMS_INVALID_NODE	invalid node id

DESCRIPTION:

This directive obtains the barrier id associated with the barrier name. If the barrier name is not unique, then the barrier id will match one of the barriers with that name. However, this barrier id is not guaranteed to correspond to the desired barrier. The barrier id is used by other barrier related directives to access the barrier.

NOTES:

This directive will not cause the running task to be preempted.

13.4.3. BARRIER_DELETE - Delete a barrier¶

CALLING SEQUENCE:

rtems_status_code rtems_barrier_delete(
    rtems_id id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	barrier deleted successfully
RTEMS_INVALID_ID	invalid barrier id

DESCRIPTION:

This directive deletes the barrier specified by id. All tasks blocked waiting for the barrier to be released will be readied and returned a status code which indicates that the barrier was deleted. The BCB for this barrier is reclaimed by RTEMS.

NOTES:

The calling task will be preempted if it is enabled by the task’s execution mode and a higher priority local task is waiting on the deleted barrier. The calling task will NOT be preempted if all of the tasks that are waiting on the barrier are remote tasks.

The calling task does not have to be the task that created the barrier. Any local task that knows the barrier id can delete the barrier.