RTEMS Classic API Guide (5.2).¶

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.

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 32-bit 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 some RTEMS services.

31      27 26   24 23          16 15                             0
+---------+-------+--------------+-------------------------------+
|         |       |              |                               |
|  Class  |  API  |     Node     |             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:

Objects_APIs 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 );
uint16_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.

3.4.1. 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 a 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.

3.4.2. Immediate Ceiling Priority Protocol (ICPP)¶

Each mutex using the Immediate Ceiling Priority Protocol (ICPP) has a ceiling priority. The priority of the mutex owner is immediately raised to the ceiling priority of the mutex. In case the thread owning the mutex releases the mutex, then the normal priority of the thread is restored. This locking protocol is beneficial for schedulability analysis, see also [BW01].

This protocol avoids the possibility of changing the priority of the mutex owner multiple times since the ceiling priority must be set to the one of highest priority thread which will ever attempt to acquire that mutex. This requires an overall knowledge of the application as a whole. The need to identify the highest priority thread which will attempt to obtain a particular mutex can be a difficult task in a large, complicated system. Although the priority ceiling protocol is more efficient than the priority inheritance protocol with respect to the maximum number of thread priority changes which may occur while a thread owns a particular mutex, the priority inheritance protocol is more forgiving in that it does not require this apriori information.

3.4.3. Priority Inheritance Protocol¶

The priority of the mutex owner is raised to the highest priority of all threads that currently wait for ownership of this mutex [SRL90]. Since RTEMS 5.1, priority updates due to the priority inheritance protocol take place immediately and are propagated recursively. This means the priority inheritance is transitive since RTEMS 5.1. If a task A owning a priority inheritance mutex blocks on another priority inheritance mutex, then the owner of this mutex inherits the priority of the task A.

3.4.4. Multiprocessor Resource Sharing Protocol (MrsP)¶

The Multiprocessor Resource Sharing Protocol (MrsP) is a generalization of the priority ceiling protocol to clustered scheduling [BW13]. One of the design goals of MrsP is to enable an effective schedulability analysis using the sporadic task model. Each mutex using the MrsP has a ceiling priority for each scheduler instance. The priority of the mutex owner is immediately raised to the ceiling priority of the mutex defined for its home scheduler instance. In case the thread owning the mutex releases the mutex, then the normal priority of the thread is restored. Threads that wait for mutex ownership are not blocked with respect to the scheduler and instead perform a busy wait. The MrsP uses temporary thread migrations to foreign scheduler instances in case of a preemption of the mutex owner. This locking protocol is available since RTEMS 4.11. It was re-implemented in RTEMS 5.1 to overcome some shortcomings of the original implementation [CBHM15].

3.4.5. O(m) Independence-Preserving Protocol (OMIP)¶

The \(O(m)\) Independence-Preserving Protocol (OMIP) is a generalization of the priority inheritance protocol to clustered scheduling which avoids the non-preemptive sections present with priority boosting [Bra13]. The \(m\) denotes the number of processors in the system. Similar to the uniprocessor priority inheritance protocol, the OMIP mutexes do not need any external configuration data, e.g. a ceiling priority. This makes them a good choice for general purpose libraries that need internal locking. The complex part of the implementation is contained in the thread queues and shared with the MrsP support. This locking protocol is available since RTEMS 5.1.

5.1.1. Scheduling Algorithms¶

RTEMS provides a plugin framework that allows it to support multiple scheduling algorithms. RTEMS includes multiple scheduling algorithms, and the user can select which of these they wish to use in their application at link-time. In addition, the user can implement their own scheduling algorithm and configure RTEMS to use it.

Supporting multiple scheduling algorithms gives the end user the option to select the algorithm which is most appropriate to their use case. Most real-time operating systems schedule tasks using a priority based algorithm, possibly with preemption control. The classic RTEMS scheduling algorithm which was the only algorithm available in RTEMS 4.10 and earlier, is a fixed-priority scheduling algorithm. This scheduling algorithm is suitable for uniprocessor (e.g., non-SMP) systems and is known as the Deterministic Priority Scheduler. Unless the user configures another scheduling algorithm, RTEMS will use this on uniprocessor systems.

5.1.2. 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 a 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. This data structure has \(O(1)\) insert, extract and find highest ready run-time complexities.

• A red-black tree may be used for the ready queue with the priority as the key. This data structure has \(O(log(n))\) insert, extract and find highest ready run-time complexities while \(n\) is the count of tasks in the ready queue.

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

5.2.1. Deterministic Priority Scheduler¶

This is the scheduler implementation which has always been in RTEMS. After the 4.10 release series, it was factored into a 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.2. 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 that are incapable of supporting a large number of tasks.

This scheduler is only aware of a single core.

5.2.3. 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 whose goal is to handle periodic behavior. Period is always equal to the 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 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 an oncoming deadline. Moreover, the rtems_rate_monotonic_cancel and rtems_rate_monotonic_delete calls clear the deadlines assigned to the task.

5.2.4. 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. Earliest Deadline First SMP Scheduler¶

This is a job-level fixed-priority scheduler using the Earliest Deadline First (EDF) method. By convention, the maximum priority level is \(min(INT\_MAX, 2^{62} - 1)\) for background tasks. Tasks without an active deadline are background tasks. In case deadlines are not used, then the EDF scheduler behaves exactly like a fixed-priority scheduler. The tasks with an active deadline have a higher priority than the background tasks. This scheduler supports task processor affinities of one-to-one and one-to-all, e.g., a task can execute on exactly one processor or all processors managed by the scheduler instance. The processor affinity set of a task must contain all online processors to select the one-to-all affinity. This is to avoid pathological cases if processors are added/removed to/from the scheduler instance at run-time. In case the processor affinity set contains not all online processors, then a one-to-one affinity will be used selecting the processor with the largest index within the set of processors currently owned by the scheduler instance. This scheduler algorithm supports thread pinning. The ready queues use a red-black tree with the task priority as the key.

This scheduler algorithm is the default scheduler in SMP configurations if more than one processor is configured (CONFIGURE_MAXIMUM_PROCESSORS).

5.3.2. Deterministic Priority SMP Scheduler¶

A fixed-priority scheduler which uses a table of chains with one chain per priority level for the ready tasks. The maximum priority level is configurable. By default, the maximum priority level is 255 (256 priority levels).

5.3.3. Simple Priority SMP Scheduler¶

A fixed-priority scheduler which uses a sorted chain for the ready tasks. By convention, the maximum priority level is 255. The implementation limit is actually \(2^{63} - 1\).

5.3.4. Arbitrary Processor Affinity Priority SMP Scheduler¶

A fixed-priority scheduler which uses a table of chains with one chain per priority level for the ready tasks. The maximum priority level is configurable. By default, the maximum priority level is 255 (256 priority levels). This scheduler supports arbitrary task processor affinities. The worst-case run-time complexity of some scheduler operations exceeds \(O(n)\) while \(n\) is the count of ready tasks.

5.4.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. The maximum priority level depends on the configured scheduler. A lower priority level means higher priority (higher importance). The maximum priority level of the default uniprocessor scheduler is 255.

5.4.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.4.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.4.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.

5.7.1. SCHEDULER_IDENT - Get ID of a scheduler¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_ident(
    rtems_name  name,
    rtems_id   *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ADDRESS	The id parameter is NULL.
RTEMS_INVALID_NAME	Invalid scheduler name.

DESCRIPTION:

Identifies a scheduler by its name. The scheduler name is determined by the scheduler configuration. See Configuration Step 3 - Scheduler Table and CONFIGURE_SCHEDULER_NAME.

NOTES:

None.

5.7.2. SCHEDULER_IDENT_BY_PROCESSOR - Get ID of a scheduler by processor¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_ident_by_processor(
    uint32_t  cpu_index,
    rtems_id *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ADDRESS	The id parameter is NULL.
RTEMS_INVALID_NAME	Invalid processor index.
RTEMS_INCORRECT_STATE	The processor index is valid, however, this processor is not owned by a scheduler.

DESCRIPTION:

Identifies a scheduler by a processor.

NOTES:

None.

5.7.3. SCHEDULER_IDENT_BY_PROCESSOR_SET - Get ID of a scheduler by processor set¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_ident_by_processor_set(
    size_t           cpusetsize,
    const cpu_set_t *cpuset,
    rtems_id        *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ADDRESS	The id parameter is NULL.
RTEMS_INVALID_SIZE	Invalid processor set size.
RTEMS_INVALID_NAME	The processor set contains no online processor.
RTEMS_INCORRECT_STATE	The processor set is valid, however, the highest numbered online processor in the specified processor set is not owned by a scheduler.

DESCRIPTION:

Identifies a scheduler by a processor set. The scheduler is selected according to the highest numbered online processor in the specified processor set.

NOTES:

None.

5.7.4. SCHEDULER_GET_MAXIMUM_PRIORITY - Get maximum task priority of a scheduler¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_get_maximum_priority(
    rtems_id             scheduler_id,
    rtems_task_priority *priority
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	Invalid scheduler instance identifier.
RTEMS_INVALID_ADDRESS	The priority parameter is NULL.

DESCRIPTION:

Returns the maximum task priority of the specified scheduler instance in priority.

NOTES:

None.

5.7.5. SCHEDULER_MAP_PRIORITY_TO_POSIX - Map task priority to POSIX thread prority¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_map_priority_to_posix(
    rtems_id             scheduler_id,
    rtems_task_priority  priority,
    int                 *posix_priority
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ADDRESS	The posix_priority parameter is NULL.
RTEMS_INVALID_ID	Invalid scheduler instance identifier.
RTEMS_INVALID_PRIORITY	Invalid task priority.

DESCRIPTION:

Maps a task priority to the corresponding POSIX thread priority.

NOTES:

None.

5.7.6. SCHEDULER_MAP_PRIORITY_FROM_POSIX - Map POSIX thread prority to task priority¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_map_priority_from_posix(
    rtems_id             scheduler_id,
    int                  posix_priority,
    rtems_task_priority *priority
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ADDRESS	The priority parameter is NULL.
RTEMS_INVALID_ID	Invalid scheduler instance identifier.
RTEMS_INVALID_PRIORITY	Invalid POSIX thread priority.

DESCRIPTION:

Maps a POSIX thread priority to the corresponding task priority.

NOTES:

None.

5.7.7. SCHEDULER_GET_PROCESSOR - Get current processor index¶

CALLING SEQUENCE:

uint32_t rtems_scheduler_get_processor( void );

DIRECTIVE STATUS CODES:

This directive returns the index of the current processor.

DESCRIPTION:

In uniprocessor configurations, a value of zero will be returned.

In SMP configurations, an architecture specific method is used to obtain the index of the current processor in the system. The set of processor indices is the range of integers starting with zero up to the processor count minus one.

Outside of sections with disabled thread dispatching the current processor index may change after every instruction since the thread may migrate from one processor to another. Sections with disabled interrupts are sections with thread dispatching disabled.

NOTES:

None.

5.7.8. SCHEDULER_GET_PROCESSOR_MAXIMUM - Get processor maximum¶

CALLING SEQUENCE:

uint32_t rtems_scheduler_get_processor_maximum( void );

DIRECTIVE STATUS CODES:

This directive returns the processor maximum supported by the system.

DESCRIPTION:

In uniprocessor configurations, a value of one will be returned.

In SMP configurations, this directive returns the minimum of the processors (physically or virtually) available by the platform and the configured processor maximum. Not all processors in the range from processor index zero to the last processor index (which is the processor maximum minus one) may be configured to be used by a scheduler or online (online processors have a scheduler assigned).

NOTES:

None.

5.7.9. SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_get_processor_set(
    rtems_id   scheduler_id,
    size_t     cpusetsize,
    cpu_set_t *cpuset
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	Invalid scheduler instance identifier.
RTEMS_INVALID_ADDRESS	The cpuset parameter is NULL.
RTEMS_INVALID_NUMBER	The processor set buffer is too small for the set of processors owned by the scheduler instance.

DESCRIPTION:

Returns the processor set owned by the scheduler instance in cpuset. A set bit in the processor set means that this processor is owned by the scheduler instance and a cleared bit means the opposite.

NOTES:

None.

5.7.10. SCHEDULER_ADD_PROCESSOR - Add processor to a scheduler¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_add_processor(
    rtems_id scheduler_id,
    uint32_t cpu_index
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	Invalid scheduler instance identifier.
RTEMS_NOT_CONFIGURED	The processor is not configured to be used by the application.
RTEMS_INCORRECT_STATE	The processor is configured to be used by the application, however, it is not online.
RTEMS_RESOURCE_IN_USE	The processor is already assigned to a scheduler instance.

DESCRIPTION:

Adds a processor to the set of processors owned by the specified scheduler instance.

NOTES:

Must be called from task context. This operation obtains and releases the objects allocator lock.

5.7.11. SCHEDULER_REMOVE_PROCESSOR - Remove processor from a scheduler¶

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_remove_processor(
    rtems_id scheduler_id,
    uint32_t cpu_index
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	Invalid scheduler instance identifier.
RTEMS_INVALID_NUMBER	The processor is not owned by the specified scheduler instance.
RTEMS_RESOURCE_IN_USE	The set of processors owned by the specified scheduler instance would be empty after the processor removal and there exists a non-idle task that uses this scheduler instance as its home scheduler instance.
RTEMS_RESOURCE_IN_USE	A task with a restricted processor affinity exists that uses this scheduler instance as its home scheduler instance and it would be no longer possible to allocate a processor for this task after the removal of this processor.

DESCRIPTION:

Removes a processor from set of processors owned by the specified scheduler instance.

NOTES:

Must be called from task context. This operation obtains and releases the objects allocator lock. Removing a processor from a scheduler is a complex operation that involves all tasks of the system.

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. 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. The 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.3. Initialization Manager Failure¶

System initialization errors are fatal. See Internal Error Codes.

6.3.1. Initializing RTEMS¶

The Initialization Manager rtems_initialize_executive() directives is called by the boot_card() routine which 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. 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_RECORD

Initialization of the event recording is the first initialization step. This allows to record the further system initialization. This step is optional and depends on the CONFIGURE_RECORD_PER_PROCESSOR_ITEMS configuration option.

RTEMS_SYSINIT_BSP_EARLY

The Board Support Package may perform an early platform initialization in this step. This step is optional.

RTEMS_SYSINIT_MEMORY

The Board Support Package should initialize everything so that calls to _Memory_Get() can be made after this step. This step is optional.

RTEMS_SYSINIT_DIRTY_MEMORY

The free memory is dirtied in this step. This step is optional and depends on the BSP_DIRTY_MEMORY BSP option.

RTEMS_SYSINIT_ISR_STACK

The stack checker initializes the ISR stacks in this step. This step is optional and depends on the CONFIGURE_STACK_CHECKER_ENABLED configuration option.

RTEMS_SYSINIT_PER_CPU_DATA

The per-CPU data is initialized in this step. This step is mandatory.

RTEMS_SYSINIT_SBRK

The Board Support Package may initialize the sbrk() support in this step. This step is optional.

RTEMS_SYSINIT_WORKSPACE

The workspace is initialized in this step. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_MALLOC

The C program heap is initialized in this step. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_BSP_START

The Board Support Package should perform a general platform initialization in this step (e.g. interrupt controller initialization). This step is mandatory.

RTEMS_SYSINIT_CPU_COUNTER

Initialization of the CPU counter hardware and support functions. The CPU counter is initialized early to allow its use in the tracing and profiling of the system initialization sequence. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_INITIAL_EXTENSIONS

Registers the initial extensions. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_MP_EARLY

In MPCI configurations, an early MPCI initialization is performed in this step. This step is mandatory in MPCI configurations.

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_MP

In MPCI configurations, a general MPCI initialization is performed in this step. This step is mandatory in MPCI configurations.

RTEMS_SYSINIT_USER_EXTENSIONS

Initialization of the User Extensions object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_TASKS

Initialization of the Classic Tasks object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_TASKS_MP

In MPCI configurations, the Classic Tasks MPCI support is initialized in this step. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_TIMER

Initialization of the Classic Timer object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_SIGNAL

Initialization of the Classic Signal support. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_SIGNAL_MP

In MPCI configurations, the Classic Signal MPCI support is initialized in this step. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_EVENT

Initialization of the Classic Event support. This step is optional and depends on the application configuration. This step is only used on MPCI configurations.

RTEMS_SYSINIT_CLASSIC_EVENT_MP

In MPCI configurations, the Classic Event MPCI support is initialized in this step. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_MESSAGE_QUEUE

Initialization of the Classic Message Queue object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_SEMAPHORE

Initialization of the Classic Semaphore object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_SEMAPHORE_MP

In MPCI configurations, the Classic Semaphore MPCI support is initialized in this step. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_PARTITION

Initialization of the Classic Partition object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_PARTITION_MP

In MPCI configurations, the Classic Partition MPCI support is initialized in this step. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_REGION

Initialization of the Classic Region object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_DUAL_PORTED_MEMORY

Initialization of the Classic Dual-Ported Memory object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_RATE_MONOTONIC

Initialization of the Classic Rate-Monotonic object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_CLASSIC_BARRIER

Initialization of the Classic Barrier object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_SIGNALS

Initialization of the POSIX Signals support. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_THREADS

Initialization of the POSIX Threads object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_MESSAGE_QUEUE

Initialization of the POSIX Message Queue object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_SEMAPHORE

Initialization of the POSIX Semaphore object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_TIMER

Initialization of the POSIX Timer object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_SHM

Initialization of the POSIX Shared Memory object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_KEYS

Initialization of the POSIX Keys object class. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_CLEANUP

Initialization of the POSIX Cleanup support. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_IDLE_THREADS

Initialization of idle threads. This step is mandatory.

RTEMS_SYSINIT_LIBIO

Initialization of IO library. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_ROOT_FILESYSTEM

Initialization of the root filesystem. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_DRVMGR

Driver manager initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled.

RTEMS_SYSINIT_MP_SERVER

In MPCI configurations, the MPCI server is initialized in this step. This step is mandatory in MPCI configurations.

RTEMS_SYSINIT_BSP_PRE_DRIVERS

Initialization step performed right before device drivers are initialized. This step is mandatory.

RTEMS_SYSINIT_DRVMGR_LEVEL_1

Driver manager level 1 initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled.

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_DRVMGR_LEVEL_2

Driver manager level 2 initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled.

RTEMS_SYSINIT_DRVMGR_LEVEL_3

Driver manager level 3 initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled.

RTEMS_SYSINIT_DRVMGR_LEVEL_4

Driver manager level 4 initialization. This step is optional and depends on the application configuration. Only available if the driver manager is enabled.

RTEMS_SYSINIT_MP_FINALIZE

Finalize MPCI initialization. This step is mandatory on MPCI configurations.

RTEMS_SYSINIT_CLASSIC_USER_TASKS

Creates and starts the Classic initialization tasks. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_POSIX_USER_THREADS

Creates POSIX initialization threads. This step is optional and depends on the application configuration.

RTEMS_SYSINIT_STD_FILE_DESCRIPTORS

Open the standard input, output and error file descriptors. This step is optional and depends on the application configuration.

The final action of the rtems_initialize_executive() directive is to start multitasking and switch to the highest priority ready thread. 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 Configuring a System.

6.3.2. Global Construction¶

The global construction is carried out by the first Classic API initialization task (first is defined by index zero in the Classic API initialization task configuration table). If no Classic API initialization task exists, then it is carried out by the first POSIX API initialization thread. If no initialization task or thread exists, then no global construction is performed, see for example Specify Idle Task Performs Application Initialization. The Classic API task or POSIX API thread which carries out global construction is called the main thread.

Global construction runs before the entry function of the main thread. The configuration of the main thread must take the global construction into account. In particular, the main thread stack size, priority, attributes and initial modes must be set accordingly. Thread-local objects and POSIX key values created during global construction are accessible by the main thread. If other initialization tasks are configured, and one of them has a higher priority than the main thread and the main thread is preemptible, this task executes before the global construction. In case the main thread blocks during global construction, then other tasks may run. In SMP configurations, other initialization tasks may run in parallel with global construction. Tasks created during global construction may preempt the main thread or run in parallel in SMP configurations. All RTEMS services allowed in task context are allowed during global construction.

Global constructors are C++ global object constructors or functions with the constructor attribute. For example, the following test program

#include <stdio.h>
#include <assert.h>

class A {
  public:
    A()
    {
      puts( "A:A()" );
    }
};

static A a;

static thread_local int i;

static thread_local int j;

static __attribute__(( __constructor__ )) void b( void )
{
  i = 1;
  puts( "b()" );
}

static __attribute__(( __constructor__( 1000 ) )) void c( void )
{
  puts( "c()" );
}

int main( void )
{
  assert( i == 1 );
  assert( j == 0 );
  return 0;
}

should output:

c()
b()
A:A()

6.4.1. INITIALIZE_EXECUTIVE - Initialize RTEMS¶

CALLING SEQUENCE:

void rtems_initialize_executive(void);

DIRECTIVE STATUS CODES:

NONE - This function will not return to the caller.

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.

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 Memory¶

The system uses two separate memory areas to manage a task. One memory area is the Task Control Block. The other memory area is allocated from the stack space or provided by the user and contains

• the task stack,

• the thread-local storage (TLS), and

• an optional architecture-specific floating-point context.

The size of the thread-local storage is determined at link time. A user-provided task stack must take the size of the thread-local storage into account.

On architectures with a dedicated floating-point context, the application configuration assumes that every task is a floating-point task, but whether or not a task is actually floating-point is determined at runtime during task creation (see Floating Point Considerations). In highly memory constrained systems this potential overestimate of the task stack space can be mitigated through the CONFIGURE_MINIMUM_TASK_STACK_SIZE configuration option and aligned task stack sizes for the tasks. A user-provided task stack must take the potential floating-point context into account.

7.2.4. Task Name¶

By default, the task name is defined by the task object name given to rtems_task_create(). The task name can be obtained with the pthread_getname_np() function. Optionally, a new task name may be set with the pthread_setname_np() function. The maximum size of a task name is defined by the application configuration option CONFIGURE_MAXIMUM_THREAD_NAME_SIZE.

7.2.5. 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.6. 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.7. 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.8. 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.9. Floating Point Considerations¶

Please consult the RTEMS CPU Architecture Supplement if this section is relevant on your architecture. On some architectures the floating-point context is contained in the normal task context and this section does not apply.

Creating a task with the RTEMS_FLOATING_POINT attribute flag results in additional memory being allocated for the task 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. In uniprocessor configurations, 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 uniprocessor 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. Some architectures with a dedicated floating-point context raise a processor exception if a task with RTEMS_NO_FLOATING_POINT issues a floating-point instruction, so this approach may not work at all.

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.10. 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.11. 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. 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. A specialization of rtems_task_delete is rtems_task_exit which deletes the calling task.

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.9. Setting Affinity to a Single Processor¶

On some embedded applications targeting SMP systems, it may be beneficial to lock individual tasks to specific processors. In this way, one can designate a processor for I/O tasks, another for computation, etc.. The following illustrates the code sequence necessary to assign a task an affinity for processor with index processor_index.

#include <rtems.h>
#include <assert.h>

void pin_to_processor(rtems_id task_id, int processor_index)
{
    rtems_status_code sc;
    cpu_set_t         cpuset;
    CPU_ZERO(&cpuset);
    CPU_SET(processor_index, &cpuset);
    sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset);
    assert(sc == RTEMS_SUCCESSFUL);
}

It is important to note that the cpuset is not validated until the rtems_task_set_affinity call is made. At that point, it is validated against the current system configuration.

7.3.10. Transition Advice for Removed Notepads¶

Task notepads and the associated directives TASK_GET_NOTE - Get task notepad entry and TASK_SET_NOTE - Set task notepad entry were removed in RTEMS 5.1. These were never thread-safe to access and subject to conflicting use of the notepad index by libraries which were designed independently.

It is recommended that applications be modified to use services which are thread safe and not subject to issues with multiple applications conflicting over the key (e.g. notepad index) selection. For most applications, POSIX Keys should be used. These are available in all RTEMS build configurations. It is also possible that thread-local storage (TLS) is an option for some use cases.

7.3.11. Transition Advice for Removed Task Variables¶

Task notepads and the associated directives TASK_VARIABLE_ADD - Associate per task variable, TASK_VARIABLE_GET - Obtain value of a per task variable and TASK_VARIABLE_DELETE - Remove per task variable were removed in RTEMS 5.1. Task variables must be replaced by POSIX Keys or thread-local storage (TLS). POSIX Keys are available in all configurations and support value destructors. For the TLS support consult the RTEMS CPU Architecture Supplement.

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_TOO_MANY	too many tasks created
RTEMS_UNSATISFIED	not enough memory for stack/FP context
RTEMS_UNSATISFIED	non-preemption mode not supported on SMP system
RTEMS_UNSATISFIED	interrupt level mode not supported on SMP system
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 may cause the calling task to be preempted.

The scheduler of the new task is the scheduler of the executing task at some point during the task creation. The specified task priority must be valid for the selected scheduler.

The task processor affinity is initialized to the set of online processors.

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_EXIT - Delete the calling task¶

CALLING SEQUENCE:

void rtems_task_exit( void ) RTEMS_NO_RETURN;

DIRECTIVE STATUS CODES:

NONE - This function will not return to the caller.

DESCRIPTION:

This directive deletes the calling task.

NOTES:

This directive must be called from a regular task context with enabled interrupts, otherwise one of the fatal errors

• INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL, or

• INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT

will occur.

The rtems_task_exit() call is equivalent to the following code sequence:

pthread_detach(pthread_self());
pthread_exit(NULL);

See also rtems_task_delete().

7.4.8. 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.9. 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.10. 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.11. 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.12. TASK_GET_PRIORITY - Get task priority¶

CALLING SEQUENCE:

rtems_status_code rtems_task_get_priority(
    rtems_id             task_id,
    rtems_id             scheduler_id,
    rtems_task_priority *priority
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	Directive is illegal on remote tasks.
RTEMS_INVALID_ADDRESS	The priority parameter is NULL.
RTEMS_INVALID_ID	Invalid task or scheduler identifier.
RTEMS_NOT_DEFINED	The task has no priority within the specified scheduler instance. This error is only possible in SMP configurations.

DESCRIPTION:

This directive returns the current priority of the task specified by task_id with respect to the scheduler instance specified by scheduler_id. A task id of RTEMS_SELF is used to indicate the calling task.

NOTES:

The current priority reflects temporary priority adjustments due to locking protocols, the rate-monotonic period objects on some schedulers and other mechanisms.

7.4.13. 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:

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.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. TASK_GET_SCHEDULER - Get scheduler of a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_get_scheduler(
    rtems_id  task_id,
    rtems_id *scheduler_id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	successful operation
RTEMS_INVALID_ADDRESS	scheduler_id is NULL
RTEMS_INVALID_ID	invalid task id

DESCRIPTION:

Returns the scheduler identifier of a task identified by task_id in scheduler_id.

NOTES:

None.

7.4.17. TASK_SET_SCHEDULER - Set scheduler of a task¶

CALLING SEQUENCE:

rtems_status_code rtems_task_set_scheduler(
  rtems_id            task_id,
  rtems_id            scheduler_id,
  rtems_task_priority priority
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	successful operation
RTEMS_INVALID_ID	invalid task or scheduler id
RTEMS_INVALID_PRIORITY	invalid task priority
RTEMS_RESOURCE_IN_USE	the task is in the wrong state to perform a scheduler change
RTEMS_UNSATISFIED	the processor set of the scheduler is empty
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	not supported on remote tasks

DESCRIPTION:

Sets the scheduler of a task identified by task_id to the scheduler identified by scheduler_id. The scheduler of a task is initialized to the scheduler of the task that created it. The priority of the task is set to priority.

NOTES:

It is recommended to set the scheduler of a task before it is started or in case it is guaranteed that the task owns no resources. Otherwise, sporadic RTEMS_RESOURCE_IN_USE errors may occur.

EXAMPLE:

 1 #include <rtems.h>
 2 #include <assert.h>
 3 
 4 rtems_task task( rtems_task_argument arg );
 5 
 6 void example( void )
 7 {
 8   rtems_status_code sc;
 9   rtems_id          task_id;
10   rtems_id          scheduler_id;
11   rtems_name        scheduler_name;
12 
13   scheduler_name = rtems_build_name( 'W', 'O', 'R', 'K' );
14 
15   sc = rtems_scheduler_ident( scheduler_name, &scheduler_id );
16   assert( sc == RTEMS_SUCCESSFUL );
17 
18   sc = rtems_task_create(
19     rtems_build_name( 'T', 'A', 'S', 'K' ),
20     1,
21     RTEMS_MINIMUM_STACK_SIZE,
22     RTEMS_DEFAULT_MODES,
23     RTEMS_DEFAULT_ATTRIBUTES,
24     &task_id
25   );
26   assert( sc == RTEMS_SUCCESSFUL );
27 
28   sc = rtems_task_set_scheduler( task_id, scheduler_id, 2 );
29   assert( sc == RTEMS_SUCCESSFUL );
30 
31   sc = rtems_task_start( task_id, task, 0 );
32   assert( sc == RTEMS_SUCCESSFUL );
33 }

7.4.18. TASK_GET_AFFINITY - Get task processor affinity¶

CALLING SEQUENCE:

rtems_status_code rtems_task_get_affinity(
    rtems_id   id,
    size_t     cpusetsize,
    cpu_set_t *cpuset
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	successful operation
RTEMS_INVALID_ADDRESS	cpuset is NULL
RTEMS_INVALID_ID	invalid task id
RTEMS_INVALID_NUMBER	the affinity set buffer is too small for the current processor affinity set of the task

DESCRIPTION:

Returns the current processor affinity set of the task in cpuset. A set bit in the affinity set means that the task can execute on this processor and a cleared bit means the opposite.

NOTES:

The task processor affinity is initialized to the set of online processors.

7.4.19. TASK_SET_AFFINITY - Set task processor affinity¶

CALLING SEQUENCE:

rtems_status_code rtems_task_set_affinity(
    rtems_id         id,
    size_t           cpusetsize,
    const cpu_set_t *cpuset
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL	successful operation
RTEMS_INVALID_ADDRESS	cpuset is NULL
RTEMS_INVALID_ID	invalid task id
RTEMS_INVALID_NUMBER	invalid processor affinity set

DESCRIPTION:

Sets the processor affinity set for the task specified by cpuset. A set bit in the affinity set means that the task can execute on this processor and a cleared bit means the opposite.

NOTES:

This function will not change the scheduler of the task. The intersection of the processor affinity set and the set of processors owned by the scheduler of the task must be non-empty. It is not an error if the processor affinity set contains processors that are not part of the set of processors owned by the scheduler instance of the task. A task will simply not run under normal circumstances on these processors since the scheduler ignores them. Some locking protocols may temporarily use processors that are not included in the processor affinity set of the task. It is also not an error if the processor affinity set contains processors that are not part of the system.

In case a scheduler without support for task affinites is used for the task, then the task processor affinity set must contain all online processors of the system. This prevents odd corner cases if processors are added/removed at run-time to/from scheduler instances.

7.4.20. TASK_ITERATE - Iterate Over Tasks¶

CALLING SEQUENCE:

typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg );

void rtems_task_iterate(
    rtems_task_visitor  visitor,
    void               *arg
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

Iterates over all tasks in the system. This operation covers all tasks of all APIs. The user should be careful in accessing the contents of the thread control block tcb. The visitor argument arg is passed to all invocations of visitor in addition to the thread control block. The iteration stops immediately in case the visitor function returns true.

NOTES:

Must be called from task context. This operation obtains and releases the objects allocator lock. The task visitor is called while owning the objects allocator lock. It is possible to perform blocking operations in the task visitor, however, take care that no deadlocks via the object allocator lock can occur.

7.5.1. 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. The thread control block may be in an inconsistent state or may change due to interrupts or activity on other processors.

7.6.1. 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.6.2. 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.6.3. 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.6.4. 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.6.5. 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_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

• 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_broadcast

  • 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 interrupt level in level.

NOTES:

A later invocation of the rtems_interrupt_enable directive should be used to restore the interrupt level.

This directive is implemented as a macro which sets the level parameter.

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

This directive is only available in uniprocessor configurations. The directive rtems_interrupt_local_disable is available in all configurations.

void critical_section( void )
{
  rtems_interrupt_level level;

  /*
   * Please note that the rtems_interrupt_disable() is a macro.  The
   * previous interrupt level (before the maskable interrupts are
   * disabled) is returned here in the level macro parameter.  This
   * would be wrong:
   *
   * rtems_interrupt_disable( &level );
   */
  rtems_interrupt_disable( level );

  /* Critical section, maskable interrupts are disabled */

  {
    rtems_interrupt_level level2;

    rtems_interrupt_disable( level2 );

    /* Nested critical section */

    rtems_interrupt_enable( level2 );
  }

  /* Maskable interrupts are still disabled */

  rtems_interrupt_enable( level );
}

8.4.3. INTERRUPT_ENABLE - Restore Interrupt Level¶

CALLING SEQUENCE:

void rtems_interrupt_enable(
  rtems_interrupt_level level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive restores the interrupt level specified by level.

NOTES:

The level parameter value must be obtained by a previous call to rtems_interrupt_disable or rtems_interrupt_flash. Using an otherwise obtained value is undefined behaviour.

This directive is unsuitable to enable particular interrupt sources, for example in an interrupt controller.

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

This directive is only available in uniprocessor configurations. The directive rtems_interrupt_local_enable is available in 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 is functionally equivalent to a rtems_interrupt_enable( level ) immediately followed by a rtems_interrupt_disable( level ). On some architectures it is possible to provide an optimized implementation for this sequence.

NOTES:

The level parameter value must be obtained by a previous call to rtems_interrupt_disable or rtems_interrupt_flash. Using an otherwise obtained value is undefined behaviour.

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

This directive is only available in uniprocessor configurations. The directives rtems_interrupt_local_disable and rtems_interrupt_local_enable are available in all configurations.

Historically, the interrupt flash directive was heavily used in the operating system implementation. However, this is no longer the case. The interrupt flash directive is provided for backward compatibility reasons.

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 on the current processor and returns the previous interrupt level in level.

NOTES:

A later invocation of the rtems_interrupt_local_enable directive should be used to restore the interrupt level.

This directive is implemented as a macro which sets the level parameter.

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

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

void local_critical_section( void )
{
  rtems_interrupt_level level;

  /*
   * Please note that the rtems_interrupt_local_disable() is a macro.
   * The previous interrupt level (before the maskable interrupts are
   * disabled) is returned here in the level macro parameter.  This
   * would be wrong:
   *
   * rtems_interrupt_local_disable( &level );
   */
  rtems_interrupt_local_disable( level );

  /*
   * Local critical section, maskable interrupts on the current
   * processor are disabled.
   */

  {
    rtems_interrupt_level level2;

    rtems_interrupt_local_disable( level2 );

    /* Nested local critical section */

    rtems_interrupt_local_enable( level2 );
  }

  /* Maskable interrupts are still disabled */

  rtems_interrupt_local_enable( level );
}

8.4.6. INTERRUPT_LOCAL_ENABLE - Restore Interrupt Level on Current Processor¶

CALLING SEQUENCE:

void rtems_interrupt_local_enable(
  rtems_interrupt_level level
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

This directive restores the interrupt level specified by level on the current processor.

NOTES:

The level parameter value must be obtained by a previous call to rtems_interrupt_local_disable. Using an otherwise obtained value is undefined behaviour.

This directive is unsuitable to enable particular interrupt sources, for example in an interrupt controller.

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,
  const char           *name
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

Initializes an interrupt lock. The name must be persistent throughout the lifetime of the 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_lock_context *lock_context
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

Maskable interrupts will be disabled. In SMP configurations, this directive acquires an SMP lock.

NOTES:

A separate lock context must be provided for each acquire/release pair, for example an automatic variable.

An attempt to recursively acquire the lock may result in an infinite loop with maskable interrupts disabled.

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_lock_context *lock_context
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

The interrupt level will be restored. In SMP configurations, this directive releases an SMP lock.

NOTES:

The lock context must be the one used to acquire the lock, otherwise the result is unpredictable.

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_lock_context *lock_context
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

The interrupt level will remain unchanged. In SMP configurations, this directive acquires an SMP lock.

NOTES:

A separate lock context must be provided for each acquire/release pair, for example an automatic variable.

An attempt to recursively acquire the lock may result in an infinite loop.

This directive is intended for device drivers and should be called from the corresponding interrupt service routine.

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.

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_lock_context *lock_context
);

DIRECTIVE STATUS CODES:

NONE

DESCRIPTION:

The interrupt level will remain unchanged. In SMP configurations, this directive releases an SMP lock.

NOTES:

The lock context must be the one used to acquire the lock, otherwise the result is unpredictable.

This directive is intended for device drivers and 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 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¶

RTEMS provides multiple directives which can be used by an application to obtain the current date and time or date and time related information. These directives allow 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 following directives are available:

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.3.4. Transition Advice for the Removed rtems_clock_get()¶

The directive CLOCK_GET - Get date and time information took an untyped pointer with an options argument to indicate the time information desired. This has been replaced with a set of typed directives:

• CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch

• CLOCK_GET_TICKS_PER_SECOND - Get ticks per second

• CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value

• CLOCK_GET_TOD - Get date and time in TOD format

• CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format

These directives directly correspond to what were previously referred to as clock options. These strongly typed directives were available for multiple releases in parallel with rtems_clock_get() until that directive was removed.

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_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.3. 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.4. 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.5. 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.6. 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.7. 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.8. 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.9. 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.10. 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.11. 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.12. 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.13. 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.

9.5.1. 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.

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 specified by rtems_timer_initiate_server() and it may have a priority of zero (the highest priority). In uniprocessor configurations, it is created non-preemptible.

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. The timer service routines invoked by the Timer Server may block, however, since this blocks the Timer Server itself, other timer service routines that are already pending do not run until the blocked timer service routine finished its work.

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 obtain the allocator mutex and may cause the calling task to be preempted.

In SMP configurations, the processor of the currently executing thread determines the processor used for the created timer. During the life-time of the timer this processor is used to manage the timer internally.

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 obtain the allocator mutex and may cause the calling 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¶