RTEMS Classic API Guide (6.a3cfaea).¶

5.2.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.2.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.3. Scheduling Modification Mechanisms¶

RTEMS provides four mechanisms which allow the user to alter the task scheduling decisions:

• user-selectable task priority level

• task preemption control

• task timeslicing control

• manual round-robin selection

Each of these methods provides a powerful capability to customize sets of tasks to satisfy the unique and particular requirements encountered in custom real-time applications. Although each mechanism operates independently, there is a precedence relationship which governs the effects of scheduling modifications. The evaluation order for scheduling characteristics is always priority, preemption mode, and timeslicing. When reading the descriptions of timeslicing and manual round-robin it is important to keep in mind that preemption (if enabled) of a task by higher priority tasks will occur as required, overriding the other factors presented in the description.

5.2.4. Dispatching Tasks¶

The dispatcher is the RTEMS component responsible for allocating the processor to a ready task. In order to allocate the processor to one task, it must be deallocated or retrieved from the task currently using it. This involves a concept called a context switch. To perform a context switch, the dispatcher saves the context of the current task and restores the context of the task which has been allocated to the processor. Saving and restoring a task’s context is the storing/loading of all the essential information about a task to enable it to continue execution without any effects of the interruption. For example, the contents of a task’s register set must be the same when it is given the processor as they were when it was taken away. All of the information that must be saved or restored for a context switch is located either in the TCB or on the task’s stacks.

Tasks that utilize a numeric coprocessor and are created with the RTEMS_FLOATING_POINT attribute require additional operations during a context switch. These additional operations are necessary to save and restore the floating point context of RTEMS_FLOATING_POINT tasks. To avoid unnecessary save and restore operations, 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.

5.2.5. Task State Transitions¶

Tasks in an RTEMS system must always be in one of the five allowable task states. These states are: executing, ready, blocked, dormant, and non-existent.

A task occupies the non-existent state before a rtems_task_create has been issued on its behalf. A task enters the non-existent state from any other state in the system when it is deleted with the rtems_task_delete directive. While a task occupies this state it does not have a TCB or a task ID assigned to it; therefore, no other tasks in the system may reference this task.

When a task is created via the rtems_task_create directive, it enters the dormant state. This state is not entered through any other means. Although the task exists in the system, it cannot actively compete for system resources. It will remain in the dormant state until it is started via the rtems_task_start directive, at which time it enters the ready state. The task is now permitted to be scheduled for the processor and to compete for other system resources.

A task occupies the blocked state whenever it is unable to be scheduled to run. A running task may block itself or be blocked by other tasks in the system. The running task blocks itself through voluntary operations that cause the task to wait. The only way a task can block a task other than itself is with the rtems_task_suspend directive. A task enters the blocked state due to any of the following conditions:

• A task issues a rtems_task_suspend directive which blocks either itself or another task in the system.

• The running task issues a rtems_barrier_wait directive.

• The running task issues a rtems_message_queue_receive directive with the wait option, and the message queue is empty.

• The running task issues a rtems_event_receive directive with the wait option, and the currently pending events do not satisfy the request.

• The running task issues a rtems_semaphore_obtain directive with the wait option and the requested semaphore is unavailable.

• The running task issues a rtems_task_wake_after directive which blocks the task for the given count of ticks. If the count of ticks specified is zero, the task yields the processor and remains in the ready state.

• The running task issues a rtems_task_wake_when directive which blocks the task until the requested date and time arrives.

• The running task issues a rtems_rate_monotonic_period directive and must wait for the specified rate monotonic period to conclude.

• The running task issues a rtems_region_get_segment directive with the wait option and there is not an available segment large enough to satisfy the task’s request.

A blocked task may also be suspended. Therefore, both the suspension and the blocking condition must be removed before the task becomes ready to run again.

A task occupies the ready state when it is able to be scheduled to run, but currently does not have control of the processor. Tasks of the same or higher priority will yield the processor by either becoming blocked, completing their timeslice, or being deleted. All tasks with the same priority will execute in FIFO order. A task enters the ready state due to any of the following conditions:

• A running task issues a rtems_task_resume directive for a task that is suspended and the task is not blocked waiting on any resource.

• A running task issues a rtems_message_queue_send, rtems_message_queue_broadcast, or a rtems_message_queue_urgent directive which posts a message to the queue on which the blocked task is waiting.

• A running task issues an rtems_event_send directive which sends an event condition to a task that is blocked waiting on that event condition.

• A running task issues a rtems_semaphore_release directive which releases the semaphore on which the blocked task is waiting.

• The requested count of ticks has elapsed for a task which was blocked by a call to the rtems_task_wake_after directive.

• A timeout period expires for a task which blocked by a call to the rtems_task_wake_when directive.

• A running task issues a rtems_region_return_segment directive which releases a segment to the region on which the blocked task is waiting and a resulting segment is large enough to satisfy the task’s request.

• A rate monotonic period expires for a task which blocked by a call to the rtems_rate_monotonic_period directive.

• A timeout interval expires for a task which was blocked waiting on a message, event, semaphore, or segment with a timeout specified.

• A running task issues a directive which deletes a message queue, a semaphore, or a region on which the blocked task is waiting.

• A running task issues a rtems_task_restart directive for the blocked task.

• The running task, with its preemption mode enabled, may be made ready by issuing any of the directives that may unblock a task with a higher priority. This directive may be issued from the running task itself or from an ISR. A ready task occupies the executing state when it has control of the CPU. A task enters the executing state due to any of the following conditions:

• The task is the highest priority ready task in the system.

• The running task blocks and the task is next in the scheduling queue. The task may be of equal priority as in round-robin scheduling or the task may possess the highest priority of the remaining ready tasks.

• The running task may reenable its preemption mode and a task exists in the ready queue that has a higher priority than the running task.

• The running task lowers its own priority and another task is of higher priority as a result.

• The running task raises the priority of a task above its own and the running task is in preemption mode.

5.3.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.3.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.3.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.3.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.4.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.4.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), see CONFIGURE_MAXIMUM_PRIORITY.

5.4.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.4.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), see CONFIGURE_MAXIMUM_PRIORITY. 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.5.1. rtems_scheduler_ident()¶

Identifies a scheduler by the object name.

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id );

PARAMETERS:

name

This parameter is the scheduler name to look up.

id

This parameter is the pointer to an rtems_id object. When the directive call is successful, the identifier of the scheduler will be stored in this object.

DESCRIPTION:

This directive obtains a scheduler identifier associated with the scheduler name specified in name.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_NAME

There was no scheduler associated with the name.

RTEMS_INVALID_ADDRESS

The id parameter was NULL.

NOTES:

The scheduler name is determined by the scheduler configuration.

The scheduler identifier is used with other scheduler related directives to access the scheduler.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.2. rtems_scheduler_ident_by_processor()¶

Identifies a scheduler by the processor index.

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_ident_by_processor(
  uint32_t  cpu_index,
  rtems_id *id
);

PARAMETERS:

cpu_index

This parameter is the processor index to identify the scheduler.

id

This parameter is the pointer to an rtems_id object. When the directive call is successful, the identifier of the scheduler will be stored in this object.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The id parameter was NULL.

RTEMS_INVALID_NAME

The processor index was invalid.

RTEMS_INCORRECT_STATE

The processor index was valid, however, the corresponding processor was not owned by a scheduler.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.3. rtems_scheduler_ident_by_processor_set()¶

Identifies a scheduler by the processor set.

CALLING SEQUENCE:

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

PARAMETERS:

cpusetsize

This parameter is the size of the processor set referenced by cpuset in bytes. The size shall be positive.

cpuset

This parameter is the pointer to a cpu_set_t. The referenced processor set will be used to identify the scheduler.

id

This parameter is the pointer to an rtems_id object. When the directive call is successful, the identifier of the scheduler will be stored in this object.

DESCRIPTION:

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

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The id parameter was NULL.

RTEMS_INVALID_ADDRESS

The cpuset parameter was NULL.

RTEMS_INVALID_SIZE

The processor set size was invalid.

RTEMS_INVALID_NAME

The processor set contained no online processor.

RTEMS_INCORRECT_STATE

The processor set was valid, however, the highest numbered online processor in the processor set was not owned by a scheduler.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.4. rtems_scheduler_get_maximum_priority()¶

Gets the maximum task priority of the scheduler.

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_get_maximum_priority(
  rtems_id             scheduler_id,
  rtems_task_priority *priority
);

PARAMETERS:

scheduler_id

This parameter is the scheduler identifier.

priority

This parameter is the pointer to an rtems_task_priority object. When the directive the maximum priority of the scheduler will be stored in this object.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ID

There was no scheduler associated with the identifier specified by scheduler_id.

RTEMS_INVALID_ADDRESS

The priority parameter was NULL.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.5. rtems_scheduler_map_priority_to_posix()¶

Maps a Classic API task priority to the corresponding POSIX thread priority.

CALLING SEQUENCE:

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

PARAMETERS:

scheduler_id

This parameter is the scheduler identifier.

priority

This parameter is the Classic API task priority to map.

posix_priority

This parameter is the pointer to an int object. When the directive call is successful, the POSIX thread priority value corresponding to the specified Classic API task priority value will be stored in this object.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The posix_priority parameter was NULL.

RTEMS_INVALID_ID

There was no scheduler associated with the identifier specified by scheduler_id.

RTEMS_INVALID_PRIORITY

The Classic API task priority was invalid.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.6. rtems_scheduler_map_priority_from_posix()¶

Maps a POSIX thread priority to the corresponding Classic API task priority.

CALLING SEQUENCE:

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

PARAMETERS:

scheduler_id

This parameter is the scheduler identifier.

posix_priority

This parameter is the POSIX thread priority to map.

priority

This parameter is the pointer to an rtems_task_priority object. When the directive call is successful, the Classic API task priority value corresponding to the specified POSIX thread priority value will be stored in this object.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The priority parameter was NULL.

RTEMS_INVALID_ID

There was no scheduler associated with the identifier specified by scheduler_id.

RTEMS_INVALID_PRIORITY

The POSIX thread priority was invalid.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.7. rtems_scheduler_get_processor()¶

Returns the index of the current processor.

CALLING SEQUENCE:

uint32_t rtems_scheduler_get_processor( void );

DESCRIPTION:

Where the system was built with SMP support disabled, this directive evaluates to a compile time constant of zero.

Where the system was built with SMP support enabled, this directive returns the index of the current processor. The set of processor indices is the range of integers starting with zero up to rtems_scheduler_get_processor_maximum() minus one.

RETURN VALUES:

Returns the index of the current processor.

NOTES:

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.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.8. rtems_scheduler_get_processor_maximum()¶

Returns the processor maximum supported by the system.

CALLING SEQUENCE:

uint32_t rtems_scheduler_get_processor_maximum( void );

DESCRIPTION:

Where the system was built with SMP support disabled, this directive evaluates to a compile time constant of one.

Where the system was built with SMP support enabled, this directive returns the minimum of the processors (physically or virtually) available at the target and the configured processor maximum (see CONFIGURE_MAXIMUM_PROCESSORS). 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 may be online (online processors have a scheduler assigned).

RETURN VALUES:

Returns the processor maximum supported by the system.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.9. rtems_scheduler_get_processor_set()¶

Gets the set of processors owned by the scheduler.

CALLING SEQUENCE:

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

PARAMETERS:

scheduler_id

This parameter is the scheduler identifier.

cpusetsize

This parameter is the size of the processor set referenced by cpuset in bytes.

cpuset

This parameter is the pointer to a cpu_set_t object. When the directive call is successful, the processor set of the scheduler will be stored in this object. A set bit in the processor set means that the corresponding processor is owned by the scheduler, otherwise the bit is cleared.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The cpuset parameter was NULL.

RTEMS_INVALID_ID

There was no scheduler associated with the identifier specified by scheduler_id.

RTEMS_INVALID_SIZE

The provided processor set was too small for the set of processors owned by the scheduler.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

5.5.10. rtems_scheduler_add_processor()¶

Adds the processor to the set of processors owned by the scheduler.

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_add_processor(
  rtems_id scheduler_id,
  uint32_t cpu_index
);

PARAMETERS:

scheduler_id

This parameter is the scheduler identifier.

cpu_index

This parameter is the index of the processor to add.

DESCRIPTION:

This directive adds the processor specified by the cpu_index to the scheduler specified by scheduler_id.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ID

There was no scheduler associated with the identifier specified by scheduler_id.

RTEMS_NOT_CONFIGURED

The processor was not configured to be used by the application.

RTEMS_INCORRECT_STATE

The processor was configured to be used by the application, however, it was not online.

RTEMS_RESOURCE_IN_USE

The processor was already assigned to a scheduler.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

5.5.11. rtems_scheduler_remove_processor()¶

Removes the processor from the set of processors owned by the scheduler.

CALLING SEQUENCE:

rtems_status_code rtems_scheduler_remove_processor(
  rtems_id scheduler_id,
  uint32_t cpu_index
);

PARAMETERS:

scheduler_id

This parameter is the scheduler identifier.

cpu_index

This parameter is the index of the processor to remove.

DESCRIPTION:

This directive removes the processor specified by the cpu_index from the scheduler specified by scheduler_id.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ID

There was no scheduler associated with the identifier specified by scheduler_id.

RTEMS_INVALID_NUMBER

The processor was not owned by the scheduler.

RTEMS_RESOURCE_IN_USE

The processor was required by at least one non-idle task that used the scheduler as its home scheduler.

RTEMS_RESOURCE_IN_USE

The processor was the last processor owned by the scheduler and there was at least one task that used the scheduler as a helping scheduler.

NOTES:

Removing a processor from a scheduler is a complex operation that involves all tasks of the system.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

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 Classic API initialization task. If no Classic API initialization task exists, then it is carried out by the POSIX API initialization thread. If no initialization task or thread exists, then no global construction is performed. The Classic API task or POSIX API thread which carries out global construction is called the main thread. For configuration options related to initialization tasks, see CONFIGURE_RTEMS_INIT_TASKS_TABLE, CONFIGURE_POSIX_INIT_THREAD_TABLE, and CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION.

Global construction runs before the task entry 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. rtems_initialize_executive()¶

Initializes the system and starts multitasking.

CALLING SEQUENCE:

void rtems_initialize_executive( void );

DESCRIPTION:

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

NOTES:

Errors in the initialization sequence are usually fatal and lead to a system termination.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive should be called by boot_card() only.

• The directive will not return to the caller.

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 processor set owned by a scheduler. Normally, RTEMS supports 256 levels of priority ranging from 0 to 255. The priority level 0 represents a special priority reserved for the operating system. The data type rtems_task_priority is used to store task priorities. The maximum priority level depends on the configured scheduler, see CONFIGURE_MAXIMUM_PRIORITY, Clustered Scheduler Configuration, and Scheduling Concepts.

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. Task Life States¶

Independent of the task state with respect to the scheduler, the task life is determined by several orthogonal states:

• protected or unprotected

• deferred life changes or no deferred life changes

• restarting or not restarting

• terminating or not terminating

• detached or not detached

While the task life is protected, asynchronous task restart and termination requests are blocked. A task may still restart or terminate itself. All tasks are created with an unprotected task life. The task life protection is used by the system to prevent system resources being affected by asynchronous task restart and termination requests. The task life protection can be enabled (PTHREAD_CANCEL_DISABLE) or disabled (PTHREAD_CANCEL_ENABLE) for the calling task through the pthread_setcancelstate() directive.

While deferred life changes are enabled, asynchronous task restart and termination requests are delayed until the task performs a life change itself or calls pthread_testcancel(). Cancellation points are not implemented in RTEMS. Deferred task life changes can be enabled (PTHREAD_CANCEL_DEFERRED) or disabled (PTHREAD_CANCEL_ASYNCHRONOUS) for the calling task through the pthread_setcanceltype() directive. Classic API tasks are created with deferred life changes disabled. POSIX threads are created with deferred life changes enabled.

A task is made restarting by issuing a task restart request through the rtems_task_restart() directive.

A task is made terminating by issuing a task termination request through the rtems_task_exit(), rtems_task_delete(), pthread_exit(), and pthread_cancel() directives.

When a detached task terminates, the termination procedure completes without the need for another task to join with the terminated task. Classic API tasks are created as not detached. The detached state of created POSIX threads is determined by the thread attributes. They are created as not detached by default. The calling task is made detached through the pthread_detach() directive. The rtems_task_exit() directive and self deletion though rtems_task_delete() directive make the calling task detached. In contrast, the pthread_exit() directive does not change the detached state of the calling task.

7.2.9. 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.10. 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.11. 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.12. 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 count of clock ticks. The task is blocked until the count of clock ticks has elapsed, at which time the task is unblocked. A task calling the rtems_task_wake_after directive with a delay 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. rtems_task_create()¶

Creates 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
);

PARAMETERS:

name

This parameter is the object name of the task.

initial_priority

This parameter is the initial task priority.

stack_size

This parameter is the task stack size in bytes.

initial_modes

This parameter is the initial mode set of the task.

attribute_set

This parameter is the attribute set of the task.

id

This parameter is the pointer to an rtems_id object. When the directive call is successful, the identifier of the created task will be stored in this object.

DESCRIPTION:

This directive creates a task which resides on the local node. The task has the user-defined object name specified in name. The assigned object identifier is returned in id. This identifier is used to access the task with other task related directives.

The initial priority of the task is specified in initial_priority. The home scheduler of the created task is the home scheduler of the calling task at some time point during the task creation. The initial task priority specified in initial_priority shall be valid for this scheduler.

The stack size of the task is specified in stack_size. 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. The configured minimum stack size is defined by the CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option. In addition to being able to specify the task stack size as a integer, there are two constants which may be specified:

• The RTEMS_MINIMUM_STACK_SIZE constant can be specified to use the recommended minimum stack size for the target processor. This value is selected by the RTEMS maintainers 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.

• The RTEMS_CONFIGURED_MINIMUM_STACK_SIZE constant can be specified to use 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 target 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.

The initial mode set specified in initial_modes is built through a bitwise or of the mode constants described below. Not all combinations of modes are allowed. Some modes are mutually exclusive. If mutually exclusive modes are combined, the behaviour is undefined. Default task modes can be selected by using the RTEMS_DEFAULT_MODES constant. The task mode set defines

• the preemption mode of the task: RTEMS_PREEMPT (default) or RTEMS_NO_PREEMPT,

• the timeslicing mode of the task: RTEMS_TIMESLICE or RTEMS_NO_TIMESLICE (default),

• the ASR processing mode of the task: RTEMS_ASR (default) or RTEMS_NO_ASR,

• the interrupt level of the task: RTEMS_INTERRUPT_LEVEL() with a default of RTEMS_INTERRUPT_LEVEL( 0 ) which is associated with enabled interrupts.

The initial preemption mode of the task is enabled or disabled.

• An enabled preemption is the default and can be emphasized through the use of the RTEMS_PREEMPT mode constant.

• A disabled preemption is set by the RTEMS_NO_PREEMPT mode constant.

The initial timeslicing mode of the task is enabled or disabled.

• A disabled timeslicing is the default and can be emphasized through the use of the RTEMS_NO_TIMESLICE mode constant.

• An enabled timeslicing is set by the RTEMS_TIMESLICE mode constant.

The initial ASR processing mode of the task is enabled or disabled.

• An enabled ASR processing is the default and can be emphasized through the use of the RTEMS_ASR mode constant.

• A disabled ASR processing is set by the RTEMS_NO_ASR mode constant.

The initial interrupt level mode of the task is defined by RTEMS_INTERRUPT_LEVEL().

• Task execution with interrupts enabled the default and can be emphasized through the use of the RTEMS_INTERRUPT_LEVEL() mode macro with a value of zero (0) for the parameter. An interrupt level of zero is associated with enabled interrupts on all target processors.

• Task execution at a non-zero interrupt level can be specified by the RTEMS_INTERRUPT_LEVEL() mode macro with a non-zero value for the parameter. The interrupt level portion of the task 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.

The attribute set specified in attribute_set is built through a bitwise or of the attribute constants described below. Not all combinations of attributes are allowed. Some attributes are mutually exclusive. If mutually exclusive attributes are combined, the behaviour is undefined. Attributes not mentioned below are not evaluated by this directive and have no effect. Default attributes can be selected by using the RTEMS_DEFAULT_ATTRIBUTES constant. The attribute set defines

• the scope of the task: RTEMS_LOCAL (default) or RTEMS_GLOBAL and

• the floating-point unit use of the task: RTEMS_FLOATING_POINT or RTEMS_NO_FLOATING_POINT (default).

The task has a local or global scope in a multiprocessing network (this attribute does not refer to SMP systems). The scope is selected by the mutually exclusive RTEMS_LOCAL and RTEMS_GLOBAL attributes.

• A local scope is the default and can be emphasized through the use of the RTEMS_LOCAL attribute. A local task can be only used by the node which created it.

• A global scope is established if the RTEMS_GLOBAL attribute is set. Setting the global attribute in a single node system has no effect.the

The use of the floating-point unit is selected by the mutually exclusive RTEMS_FLOATING_POINT and RTEMS_NO_FLOATING_POINT attributes. On some target processors, the use of the floating-point unit can be enabled or disabled for each task. Other target processors may have no hardware floating-point unit or enable the use of the floating-point unit for all tasks. Consult the RTEMS CPU Architecture Supplement for the details.

• A disabled floating-point unit is the default and can be emphasized through use of the RTEMS_NO_FLOATING_POINT attribute. For performance reasons, it is recommended that tasks not using the floating-point unit should specify this attribute.

• An enabled floating-point unit is selected by the RTEMS_FLOATING_POINT attribute.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_NAME

The name parameter was invalid.

RTEMS_INVALID_ADDRESS

The id parameter was NULL.

RTEMS_INVALID_PRIORITY

The initial_priority was invalid.

RTEMS_TOO_MANY

There was no inactive object available to create a task. The number of tasks available to the application is configured through the CONFIGURE_MAXIMUM_TASKS application configuration option.

RTEMS_TOO_MANY

In multiprocessing configurations, there was no inactive global object available to create a global task. The number of global objects available to the application is configured through the CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.

RTEMS_UNSATISFIED

There was not enough memory to allocate the task storage area. The task storage area contains the task stack, the thread-local storage, and the floating point context.

RTEMS_UNSATISFIED

One of the task create extensions failed to create the task.

RTEMS_UNSATISFIED

In SMP configurations, the non-preemption mode was not supported.

RTEMS_UNSATISFIED

In SMP configurations, the interrupt level mode was not supported.

NOTES:

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

When created, a task is placed in the dormant state and can only be made ready to execute using the directive rtems_task_start().

Application developers should consider the stack usage of the device drivers when calculating the stack size required for tasks which utilize the driver. The task stack size shall account for an target processor dependent interrupt stack frame which may be placed on the stack of the interrupted task while servicing an interrupt. The stack checker may be used to monitor the stack usage, see CONFIGURE_STACK_CHECKER_ENABLED.

For control and maintenance of the task, RTEMS allocates a TCB from the local TCB free pool and initializes it.

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

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

• When the directive operates on a global object, the directive sends a message to remote nodes. This may preempt the calling task.

• The number of tasks available to the application is configured through the CONFIGURE_MAXIMUM_TASKS application configuration option.

• Where the object class corresponding to the directive is configured to use unlimited objects, the directive may allocate memory from the RTEMS Workspace.

• The number of global objects available to the application is configured through the CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.

7.4.2. rtems_task_construct()¶

Constructs a task from the specified task configuration.

CALLING SEQUENCE:

rtems_status_code rtems_task_construct(
  const rtems_task_config *config,
  rtems_id                *id
);

PARAMETERS:

config

This parameter is the pointer to an rtems_task_config object. It configures the task.

id

This parameter is the pointer to an rtems_id object. When the directive call is successful, the identifier of the constructed task will be stored in this object.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The config parameter was NULL.

RTEMS_INVALID_NAME

The task name was invalid.

RTEMS_INVALID_ADDRESS

The id parameter was NULL.

RTEMS_INVALID_PRIORITY

The initial task priority was invalid.

RTEMS_INVALID_SIZE

The thread-local storage size is greater than the maximum thread-local storage size specified in the task configuration. The thread-local storage size is determined by the thread-local variables used by the application and CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE.

RTEMS_INVALID_SIZE

The task storage area was too small to provide a task stack of the configured minimum size, see CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the task stack, the thread-local storage, and the floating-point context on architectures with a separate floating-point context.

RTEMS_TOO_MANY

There was no inactive task object available to construct a task.

RTEMS_TOO_MANY

In multiprocessing configurations, there was no inactive global object available to construct a global task.

RTEMS_UNSATISFIED

One of the task create extensions failed during the task construction.

RTEMS_UNSATISFIED

In SMP configurations, the non-preemption mode was not supported.

RTEMS_UNSATISFIED

In SMP configurations, the interrupt level mode was not supported.

NOTES:

In contrast to tasks created by rtems_task_create(), the tasks constructed by this directive use a user-provided task storage area. The task storage area contains the task stack, the thread-local storage, and the floating-point context on architectures with a separate floating-point context.

This directive is intended for applications which do not want to use the RTEMS Workspace and instead statically allocate all operating system resources. It is not recommended to use rtems_task_create() and rtems_task_construct() together in an application. It is also not recommended to use rtems_task_construct() for drivers or general purpose libraries. The reason for these recommendations is that the task configuration needs settings which can be only given with a through knowledge of the application resources.

An application based solely on static allocation can avoid any runtime memory allocators. This can simplify the application architecture as well as any analysis that may be required.

The stack space estimate done by <rtems/confdefs.h> assumes that all tasks are created by rtems_task_create(). The estimate can be adjusted to take user-provided task storage areas into account through the CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application configuration option.

The CONFIGURE_MAXIMUM_TASKS should include tasks constructed by rtems_task_construct().

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

• When the directive operates on a global object, the directive sends a message to remote nodes. This may preempt the calling task.

• The number of tasks available to the application is configured through the CONFIGURE_MAXIMUM_TASKS application configuration option.

• Where the object class corresponding to the directive is configured to use unlimited objects, the directive may allocate memory from the RTEMS Workspace.

• The number of global objects available to the application is configured through the CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.

7.4.3. rtems_task_ident()¶

Identifies a task by the object name.

CALLING SEQUENCE:

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

PARAMETERS:

name

This parameter is the object name to look up.

node

This parameter is the node or node set to search for a matching object.

id

This parameter is the pointer to an rtems_id object. When the directive call is successful, the object identifier of an object with the specified name will be stored in this object.

DESCRIPTION:

This directive obtains a task identifier associated with the task name specified in name.

A task may obtain its own identifier by specifying RTEMS_WHO_AM_I for the name.

The node to search is specified in node. It shall be

• a valid node number,

• the constant RTEMS_SEARCH_ALL_NODES to search in all nodes,

• the constant RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or

• the constant RTEMS_SEARCH_OTHER_NODES to search in all nodes except the local node.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The id parameter was NULL.

RTEMS_INVALID_NAME

There was no object with the specified name on the specified nodes.

RTEMS_INVALID_NODE

In multiprocessing configurations, the specified node was invalid.

NOTES:

If the task name is not unique, then the task identifier will match the first task with that name in the search order. However, this task identifier is not guaranteed to correspond to the desired task.

The objects are searched from lowest to the highest index. If node is RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being searched first. All other nodes are searched from lowest to the highest node number.

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.

The task identifier is used with other task related directives to access the task.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within any runtime context.

• The directive will not cause the calling task to be preempted.

7.4.4. rtems_task_self()¶

Gets the task identifier of the calling task.

CALLING SEQUENCE:

rtems_id rtems_task_self( void );

DESCRIPTION:

This directive returns the task identifier of the calling task.

RETURN VALUES:

Returns the task identifier of the calling task.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive will not cause the calling task to be preempted.

7.4.5. rtems_task_start()¶

Starts the task.

CALLING SEQUENCE:

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

PARAMETERS:

id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

entry_point

This parameter is the task entry point.

argument

This parameter is the task entry point argument.

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 task entry point of the task is given in entry_point. The task’s entry point argument is contained in argument.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The entry_point parameter was NULL.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_INCORRECT_STATE

The task was not in the dormant state.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

NOTES:

The type of the entry point argument is an unsigned integer type. However, the integer type has 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. The type can represent at least 32 bits. Some applications use the entry point argument as an index into a parameter table to get task-specific parameters.

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.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may unblock a task. This may cause the calling task to be preempted.

7.4.6. rtems_task_restart()¶

Restarts the task.

CALLING SEQUENCE:

rtems_status_code rtems_task_restart(
  rtems_id            id,
  rtems_task_argument argument
);

PARAMETERS:

id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

argument

This parameter is the task entry point argument.

DESCRIPTION:

This directive resets the task specified by id to begin execution at its original entry point. 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 entry point argument is contained in argument.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_INCORRECT_STATE

The task never started.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

NOTES:

The type of the entry point argument is an unsigned integer type. However, the integer type has 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. The type can represent at least 32 bits. Some applications use the entry point argument as an index into a parameter table to get task-specific parameters.

A new entry point 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.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may change the priority of a task. This may cause the calling task to be preempted.

• The directive may unblock a task. This may cause the calling task to be preempted.

7.4.7. rtems_task_delete()¶

Deletes the task.

CALLING SEQUENCE:

rtems_status_code rtems_task_delete( rtems_id id );

PARAMETERS:

id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

DESCRIPTION:

This directive deletes the task, either the calling task or another task, as specified by id.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_CALLED_FROM_ISR

The directive was called from within interrupt context.

RTEMS_INCORRECT_STATE

The task termination procedure was started, however, waiting for the terminating task would have resulted in a deadlock.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

NOTES:

The task deletion is done in several steps. Firstly, the task is marked as terminating. While the task life of the terminating task is protected, it executes normally until it disables the task life protection or it deletes itself. A terminating task will eventually stop its normal execution and start its termination procedure. The procedure executes in the context of the terminating task. The task termination procedure involves the destruction of POSIX key values and running the task termination user extensions. Once complete the execution of the task is stopped and task-specific resources are reclaimed by the system, such as 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 explicitly does not reclaim the following resources: region segments, partition buffers, semaphores, timers, or rate monotonic periods.

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 calling task (RTEMS_SELF) will force RTEMS to select another task to execute.

When a task deletes another task, the calling task waits until the task termination procedure of the task being deleted has completed. The terminating task inherits the eligible priorities of the calling task.

When a global task is deleted, the task identifier 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 attribute.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

• When the directive operates on a global object, the directive sends a message to remote nodes. This may preempt the calling task.

• The calling task does not have to be the task that created the object. Any local task that knows the object identifier can delete the object.

• Where the object class corresponding to the directive is configured to use unlimited objects, the directive may free memory to the RTEMS Workspace.

7.4.8. rtems_task_exit()¶

Deletes the calling task.

CALLING SEQUENCE:

void rtems_task_exit( void );

DESCRIPTION:

This directive deletes the calling task.

NOTES:

The directive is an optimized variant of the following code sequences, see also rtems_task_delete():

#include <pthread.h>
#include <rtems.h>

void classic_delete_self( void )
{
  (void) rtems_task_delete( RTEMS_SELF );
}

void posix_delete_self( void )
{
  (void) pthread_detach( pthread_self() );
  (void) pthread_exit( NULL);
}

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within task context.

• The directive will not return to the caller.

• While thread dispatching is disabled, if the directive performs a thread dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will occur.

7.4.9. rtems_task_suspend()¶

Suspends the task.

CALLING SEQUENCE:

rtems_status_code rtems_task_suspend( rtems_id id );

PARAMETERS:

id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

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. The rtems_task_restart() directive will also remove the suspended state.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_ALREADY_SUSPENDED

The task was already suspended.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

NOTES:

The requesting task can suspend itself for example 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.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling task.

7.4.10. rtems_task_resume()¶

Resumes the task.

CALLING SEQUENCE:

rtems_status_code rtems_task_resume( rtems_id id );

PARAMETERS:

id

This parameter is the task identifier.

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.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_INCORRECT_STATE

The task was not suspended.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may unblock a task. This may cause the calling task to be preempted.

• When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling task.

7.4.11. rtems_task_is_suspended()¶

Checks if the task is suspended.

CALLING SEQUENCE:

rtems_status_code rtems_task_is_suspended( rtems_id id );

PARAMETERS:

id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

DESCRIPTION:

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

RETURN VALUES:

RTEMS_SUCCESSFUL

The task was not suspended.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_ALREADY_SUSPENDED

The task was suspended.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive will not cause the calling task to be preempted.

7.4.12. rtems_task_set_priority()¶

Sets the real priority or gets the current priority of the task.

CALLING SEQUENCE:

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

PARAMETERS:

id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

new_priority

This parameter is the new real priority or RTEMS_CURRENT_PRIORITY to get the current priority.

old_priority

This parameter is the pointer to an rtems_task_priority object. When the directive call is successful, the current or previous priority of the task with respect to its home scheduler will be stored in this object.

DESCRIPTION:

This directive manipulates the priority of the task specified by id. 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.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The old_priority parameter was NULL.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_INVALID_PRIORITY

The task priority specified in new_priority was invalid with respect to the home scheduler of the task.

NOTES:

Valid priorities range from one to a maximum value which depends on the configured scheduler. The lower the priority value the higher is the importance of the task.

If the task is currently holding any binary semaphores which use a locking protocol, then the task’s priority cannot be lowered immediately. If the task’s priority were lowered immediately, then this could violate properties of the locking protocol and may result in priority inversion. The requested lowering of the task’s priority will occur when the task has released all binary semaphores which make the task more important. The task’s priority can be increased regardless of the task’s use of binary semaphores with locking protocols.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may change the priority of a task. This may cause the calling task to be preempted.

• When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling task.

7.4.13. rtems_task_get_priority()¶

Gets the current priority of the task with respect to the scheduler.

CALLING SEQUENCE:

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

PARAMETERS:

task_id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

scheduler_id

This parameter is the scheduler identifier.

priority

This parameter is the pointer to an rtems_task_priority object. When the directive call is successful, the current priority of the task with respect to the specified scheduler will be stored in this object.

DESCRIPTION:

This directive returns the current priority in priority of the task specified by task_id with respect to the scheduler specified by scheduler_id.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The priority parameter was NULL.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by task_id.

RTEMS_INVALID_ID

There was no scheduler associated with the identifier specified by scheduler_id.

RTEMS_NOT_DEFINED

The task had no priority with respect to the scheduler.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

NOTES:

The current priority reflects temporary priority adjustments due to locking protocols, the rate-monotonic period objects on some schedulers such as EDF, and the POSIX sporadic server.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive will not cause the calling task to be preempted.

7.4.14. rtems_task_mode()¶

Gets and optionally sets the mode of the calling task.

CALLING SEQUENCE:

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

PARAMETERS:

mode_set

This parameter is the mode set to apply to the calling task. When mask is set to RTEMS_CURRENT_MODE, the value of this parameter is ignored. Only modes requested by mask are applied to the calling task.

mask

This parameter is the mode mask which specifies which modes in mode_set are applied to the calling task. When the value is RTEMS_CURRENT_MODE, the mode of the calling task is not changed.

previous_mode_set

This parameter is the pointer to an rtems_mode object. When the directive call is successful, the mode of the task before any mode changes done by the directive call will be stored in this object.

DESCRIPTION:

This directive queries and optionally 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 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_set parameter.

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

The mode set specified in mode_set is built through a bitwise or of the mode constants described below. Not all combinations of modes are allowed. Some modes are mutually exclusive. If mutually exclusive modes are combined, the behaviour is undefined. Default task modes can be selected by using the RTEMS_DEFAULT_MODES constant. The task mode set defines

• the preemption mode of the task: RTEMS_PREEMPT (default) or RTEMS_NO_PREEMPT,

• the timeslicing mode of the task: RTEMS_TIMESLICE or RTEMS_NO_TIMESLICE (default),

• the ASR processing mode of the task: RTEMS_ASR (default) or RTEMS_NO_ASR,

• the interrupt level of the task: RTEMS_INTERRUPT_LEVEL() with a default of RTEMS_INTERRUPT_LEVEL( 0 ) which is associated with enabled interrupts.

The mode mask specified in mask is built through a bitwise or of the mode mask constants described below.

When the RTEMS_PREEMPT_MASK is set in mask, the preemption mode of the calling task is

• enabled by using the RTEMS_PREEMPT mode constant in mode_set and

• disabled by using the RTEMS_NO_PREEMPT mode constant in mode_set.

When the RTEMS_TIMESLICE_MASK is set in mask, the timeslicing mode of the calling task is

• enabled by using the RTEMS_TIMESLICE mode constant in mode_set and

• disabled by using the RTEMS_NO_TIMESLICE mode constant in mode_set.

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

When the RTEMS_ASR_MASK is set in mask, the ASR processing mode of the calling task is

• enabled by using the RTEMS_ASR mode constant in mode_set and

• disabled by using the RTEMS_NO_ASR mode constant in mode_set.

When the RTEMS_INTERRUPT_MASK is set in mask, interrupts of the calling task are

• enabled by using the RTEMS_INTERRUPT_LEVEL() mode macro with a value of zero (0) in mode_set and

• disabled up to the specified level by using the RTEMS_INTERRUPT_LEVEL() mode macro with a positive value in mode_set.

An interrupt level of zero is associated with enabled interrupts on all target processors. The interrupt level portion of the task 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.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_NOT_IMPLEMENTED

The RTEMS_NO_PREEMPT was set in mode_set and setting the preemption mode was requested by RTEMS_PREEMPT_MASK in mask and the system configuration had no implementation for this mode.

RTEMS_NOT_IMPLEMENTED

The RTEMS_INTERRUPT_LEVEL() was set to a positive level in mode_set and setting the interrupt level was requested by RTEMS_INTERRUPT_MASK in mask and the system configuration had no implementation for this mode.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within task context.

• When the directive enables preemption for the calling task, another task may preempt the calling task.

• While thread dispatching is disabled, if the directive performs a thread dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will occur.

7.4.15. rtems_task_wake_after()¶

Wakes up after a count of clock ticks have occurred or yields the processor.

CALLING SEQUENCE:

rtems_status_code rtems_task_wake_after( rtems_interval ticks );

PARAMETERS:

ticks

This parameter is the count of clock ticks to delay the task or RTEMS_YIELD_PROCESSOR to yield the processor.

DESCRIPTION:

This directive blocks the calling task for the specified ticks count of clock ticks if the value is not equal to RTEMS_YIELD_PROCESSOR. When the requested count of ticks have occurred, the task is made ready. The clock tick directives automatically update the delay period. The calling task may give up the processor and remain in the ready state by specifying a value of RTEMS_YIELD_PROCESSOR in ticks.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

NOTES:

Setting the system date and time with the rtems_clock_set() directive and similar directives which set CLOCK_REALTIME have no effect on a rtems_task_wake_after() blocked task. The delay until first clock tick will never be a whole clock tick interval since this directive will never execute exactly on a clock tick. Applications requiring use of a clock (CLOCK_REALTIME or CLOCK_MONOTONIC) instead of clock ticks should make use of clock_nanosleep().

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within task context.

• The directive requires a Clock Driver.

• While thread dispatching is disabled, if the directive performs a thread dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will occur.

7.4.16. rtems_task_wake_when()¶

Wakes up when specified.

CALLING SEQUENCE:

rtems_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer );

PARAMETERS:

time_buffer

This parameter is the date and time to wake up.

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.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_NOT_DEFINED

The system date and time was not set.

RTEMS_INVALID_ADDRESS

The time_buffer parameter was NULL.

RTEMS_INVALID_CLOCK

The time of day was invalid.

NOTES:

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

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within task context.

• The directive requires a Clock Driver.

• While thread dispatching is disabled, if the directive performs a thread dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will occur.

7.4.17. rtems_task_get_scheduler()¶

Gets the home scheduler of the task.

CALLING SEQUENCE:

rtems_status_code rtems_task_get_scheduler(
  rtems_id  task_id,
  rtems_id *scheduler_id
);

PARAMETERS:

task_id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

scheduler_id

This parameter is the pointer to an rtems_id object. When the directive call is successful, the identifier of the home scheduler of the task will be stored in this object.

DESCRIPTION:

This directive returns the identifier of the home scheduler of the task specified by task_id in scheduler_id.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The scheduler_id parameter was NULL.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by task_id.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive will not cause the calling task to be preempted.

7.4.18. rtems_task_set_scheduler()¶

Sets the home scheduler for the task.

CALLING SEQUENCE:

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

PARAMETERS:

task_id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

scheduler_id

This parameter is the scheduler identifier of the new home scheduler for the task specified by task_id.

priority

This parameter is the new real priority for the task with respect to the scheduler specified by scheduler_id.

DESCRIPTION:

This directive sets the home scheduler to the scheduler specified by scheduler_id for the task specified by task_id.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ID

There was no scheduler associated with the identifier specified by scheduler_id.

RTEMS_INVALID_PRIORITY

The task priority specified by priority was invalid with respect to the scheduler specified by scheduler_id.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by task_id.

RTEMS_RESOURCE_IN_USE

The task specified by task_id was enqueued on a wait queue.

RTEMS_RESOURCE_IN_USE

The task specified by task_id had a current priority which consisted of more than the real priority.

RTEMS_RESOURCE_IN_USE

The task specified by task_id had a helping scheduler.

RTEMS_RESOURCE_IN_USE

The task specified by task_id was pinned.

RTEMS_UNSATISFIED

The scheduler specified by scheduler_id owned no processor.

RTEMS_UNSATISFIED

The scheduler specified by scheduler_id did not support the affinity set of the task specified by task_id.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may change the priority of a task. This may cause the calling task to be preempted.

7.4.19. rtems_task_get_affinity()¶

Gets the processor affinity of the task.

CALLING SEQUENCE:

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

PARAMETERS:

id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

cpusetsize

This parameter is the size of the processor set referenced by cpuset in bytes.

cpuset

This parameter is the pointer to a cpu_set_t object. When the directive call is successful, the processor affinity set of the task will be stored in this object. A set bit in the processor set means that the corresponding processor is in the processor affinity set of the task, otherwise the bit is cleared.

DESCRIPTION:

This directive returns the processor affinity of the task in cpuset of the task specified by id.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The cpuset parameter was NULL.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_INVALID_SIZE

The size specified by cpusetsize of the processor set was too small for the processor affinity set of the task.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive will not cause the calling task to be preempted.

7.4.20. rtems_task_set_affinity()¶

Sets the processor affinity of the task.

CALLING SEQUENCE:

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

PARAMETERS:

id

This parameter is the task identifier. The constant RTEMS_SELF may be used to specify the calling task.

cpusetsize

This parameter is the size of the processor set referenced by cpuset in bytes.

cpuset

This parameter is the pointer to a cpu_set_t object. The processor set defines the new processor affinity set of the task. A set bit in the processor set means that the corresponding processor shall be in the processor affinity set of the task, otherwise the bit shall be cleared.

DESCRIPTION:

This directive sets the processor affinity of the task specified by id.

RETURN VALUES:

RTEMS_SUCCESSFUL

The requested operation was successful.

RTEMS_INVALID_ADDRESS

The cpuset parameter was NULL.

RTEMS_INVALID_ID

There was no task associated with the identifier specified by id.

RTEMS_INVALID_NUMBER

The referenced processor set was not a valid new processor affinity set for the task.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

The task resided on a remote node.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within interrupt context.

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may change the processor affinity of a task. This may cause the calling task to be preempted.

7.4.21. rtems_task_iterate()¶

Iterates over all tasks and invokes the visitor routine for each task.

CALLING SEQUENCE:

void rtems_task_iterate( rtems_task_visitor visitor, void *arg );

PARAMETERS:

visitor

This parameter is the visitor routine invoked for each task.

arg

This parameter is the argument passed to each visitor routine invocation during the iteration.

DESCRIPTION:

This directive 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 TCB. The visitor argument arg is passed to all invocations of visitor in addition to the TCB. The iteration stops immediately in case the visitor routine returns true.

NOTES:

The visitor routine is invoked while owning the objects allocator lock. It is allowed to perform blocking operations in the visitor routine, however, care must be taken so that no deadlocks via the object allocator lock can occur.

CONSTRAINTS:

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.

• The directive may be called from within task context.

• The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.

7.4.22. RTEMS_TASK_STORAGE_SIZE()¶

Gets the recommended task storage area size for the size and task attributes.

CALLING SEQUENCE:

size_t RTEMS_TASK_STORAGE_SIZE( size_t size, rtems_attribute attributes );

PARAMETERS:

size

This parameter is the size dedicated to the task stack and thread-local storage in bytes.

attributes

This parameter is the attribute set of the task using the storage area.

RETURN VALUES:

Returns the recommended task storage area size calculated from the input parameters.

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.