 |
RTEMS
5.1
|
|
RTEMS
5.1
|
Files | |
| file | tasks.h |
| Classic Task Manager API. | |
| file | schedulermapfromposix.c |
| Implementation of rtems_scheduler_map_priority_from_posix(). | |
| file | schedulermaptoposix.c |
| Implementation of rtems_scheduler_map_priority_to_posix(). | |
| file | taskcreate.c |
| RTEMS Task Create. | |
| file | taskdelete.c |
| RTEMS Delete Task. | |
| file | taskgetaffinity.c |
| RTEMS Task Get Affinity. | |
| file | taskident.c |
| RTEMS Task Name to Id. | |
| file | taskinitusers.c |
| _RTEMS_tasks_Initialize_user_tasks_body | |
| file | taskissuspended.c |
| rtems_task_is_suspended | |
| file | taskmode.c |
| RTEMS Task Mode. | |
| file | taskrestart.c |
| RTEMS Task Restart. | |
| file | taskresume.c |
| RTEMS Resume Task. | |
| file | tasks.c |
| RTEMS Task API Extensions. | |
| file | taskself.c |
| RTEMS Get Self Task Id. | |
| file | tasksetaffinity.c |
| RTEMS Task Set Affinity. | |
| file | tasksetpriority.c |
| RTEMS Set Task Priority. | |
| file | taskstart.c |
| RTEMS Start Task. | |
| file | tasksuspend.c |
| RTEMS Suspend Task. | |
| file | taskwakeafter.c |
| RTEMS Task Wake After. | |
| file | taskwakewhen.c |
| RTEMS Task Wake When. | |
Data Structures | |
| struct | rtems_initialization_tasks_table |
| struct | rtems_time_of_day |
| Data structure to manage and manipulate calendar time. More... | |
Macros | |
| #define | RTEMS_MILLISECONDS_TO_MICROSECONDS(_ms) ((_ms) * 1000UL) |
| Returns the number of micro seconds for the milli seconds value _ms. | |
| #define | RTEMS_MILLISECONDS_TO_TICKS(_ms) |
| Returns the number of ticks for the milli seconds value _ms. More... | |
| #define | RTEMS_MICROSECONDS_TO_TICKS(_us) ((_us) / rtems_configuration_get_microseconds_per_tick()) |
| Returns the number of ticks for the micro seconds value _us. | |
| #define | RTEMS_SELF OBJECTS_ID_OF_SELF |
| #define | RTEMS_YIELD_PROCESSOR WATCHDOG_NO_TIMEOUT |
| #define | RTEMS_NO_PRIORITY RTEMS_CURRENT_PRIORITY |
| #define | RTEMS_MINIMUM_PRIORITY 1 |
| #define | RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() |
| #define | RTEMS_CURRENT_PRIORITY 0 |
| #define | rtems_scheduler_get_processor() _SMP_Get_current_processor() |
| Returns the index of the current processor. More... | |
| #define | rtems_scheduler_get_processor_maximum() _SMP_Get_processor_maximum() |
| Returns the processor maximum supported by the system. More... | |
| #define | RTEMS_ID_NONE OBJECTS_ID_NONE |
| Invalid object identifier value. More... | |
Typedefs | |
| typedef uint32_t | rtems_task_priority |
| typedef struct _Thread_Control | rtems_tcb |
| typedef void | rtems_task |
| typedef CPU_Uint32ptr | rtems_task_argument |
| typedef rtems_task(* | rtems_task_entry) (rtems_task_argument) |
| typedef bool(* | rtems_task_visitor) (rtems_tcb *tcb, void *arg) |
| Task visitor. More... | |
| typedef uint32_t | rtems_name |
| Classic API object name type. More... | |
| typedef Objects_Id | rtems_id |
| Used to manage and manipulate RTEMS object identifiers. | |
| typedef Context_Control rtems_context | RTEMS_DEPRECATED |
| Public name for task context area. More... | |
| typedef CPU_Interrupt_frame | rtems_interrupt_frame |
| Defines the format of the interrupt stack frame as it appears to a user ISR. More... | |
| typedef Watchdog_Interval | rtems_interval |
| Used to manage and manipulate intervals specified by clock ticks. | |
Functions | |
| RTEMS_INLINE_ROUTINE bool | rtems_is_name_valid (rtems_name name) |
Returns true if the name is valid, and false otherwise. | |
| RTEMS_INLINE_ROUTINE void | rtems_name_to_characters (rtems_name name, char *c1, char *c2, char *c3, char *c4) |
| Breaks the object name into the four component characters c1, c2, c3, and c4. | |
| rtems_task_priority | _RTEMS_Maximum_priority (void) |
| 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) |
| RTEMS Task Create. More... | |
| rtems_status_code | rtems_task_ident (rtems_name name, uint32_t node, rtems_id *id) |
| RTEMS Task Name to Id. More... | |
| rtems_status_code | rtems_task_delete (rtems_id id) |
| RTEMS Delete Task. More... | |
| void | rtems_task_exit (void) RTEMS_NO_RETURN |
| rtems_status_code | rtems_task_mode (rtems_mode mode_set, rtems_mode mask, rtems_mode *previous_mode_set) |
| RTEMS Task Mode. More... | |
| rtems_status_code | rtems_task_restart (rtems_id id, rtems_task_argument argument) |
| RTEMS Task Restart. More... | |
| rtems_status_code | rtems_task_suspend (rtems_id id) |
| RTEMS Suspend Task. More... | |
| rtems_status_code | rtems_task_resume (rtems_id id) |
| RTEMS Resume Task. More... | |
| rtems_status_code | rtems_task_set_priority (rtems_id id, rtems_task_priority new_priority, rtems_task_priority *old_priority) |
| RTEMS Set Task Priority. More... | |
| rtems_status_code | rtems_task_get_priority (rtems_id task_id, rtems_id scheduler_id, rtems_task_priority *priority) |
| Gets the current priority of the specified task with respect to the specified scheduler instance. More... | |
| rtems_status_code | rtems_task_start (rtems_id id, rtems_task_entry entry_point, rtems_task_argument argument) |
| RTEMS Start Task. More... | |
| rtems_status_code | rtems_task_wake_when (rtems_time_of_day *time_buffer) |
| RTEMS Task Wake When. More... | |
| rtems_status_code | rtems_task_wake_after (rtems_interval ticks) |
| RTEMS Task Wake After. More... | |
| rtems_status_code | rtems_task_is_suspended (rtems_id id) |
| rtems_task_is_suspended More... | |
| rtems_status_code | rtems_task_get_affinity (rtems_id id, size_t cpusetsize, cpu_set_t *cpuset) |
| Gets the processor affinity set of a task. More... | |
| rtems_status_code | rtems_task_set_affinity (rtems_id id, size_t cpusetsize, const cpu_set_t *cpuset) |
| Sets the processor affinity set of a task. More... | |
| rtems_status_code | rtems_task_get_scheduler (rtems_id task_id, rtems_id *scheduler_id) |
| Gets the scheduler of a task. More... | |
| rtems_status_code | rtems_task_set_scheduler (rtems_id task_id, rtems_id scheduler_id, rtems_task_priority priority) |
| Sets the scheduler instance of a task. More... | |
| rtems_id | rtems_task_self (void) |
| RTEMS Get Self Task Id. More... | |
| void | rtems_task_iterate (rtems_task_visitor visitor, void *arg) |
| Iterates over all tasks in the system. More... | |
| rtems_status_code | rtems_scheduler_ident (rtems_name name, rtems_id *id) |
| Identifies a scheduler by its name. More... | |
| rtems_status_code | rtems_scheduler_ident_by_processor (uint32_t cpu_index, rtems_id *id) |
| Identifies a scheduler by a processor index. More... | |
| rtems_status_code | rtems_scheduler_ident_by_processor_set (size_t cpusetsize, const cpu_set_t *cpuset, rtems_id *id) |
| Identifies a scheduler by a processor set. More... | |
| RTEMS_DEPRECATED RTEMS_INLINE_ROUTINE uint32_t | rtems_get_current_processor (void) |
| Returns the index of the current processor. More... | |
| RTEMS_DEPRECATED RTEMS_INLINE_ROUTINE uint32_t | rtems_get_processor_count (void) |
| Returns the processor maximum supported by the system. More... | |
| rtems_status_code | rtems_scheduler_get_processor_set (rtems_id scheduler_id, size_t cpusetsize, cpu_set_t *cpuset) |
| Gets the set of processors owned by the specified scheduler instance. More... | |
| rtems_status_code | rtems_scheduler_add_processor (rtems_id scheduler_id, uint32_t cpu_index) |
| Adds a processor to the set of processors owned by the specified scheduler instance. More... | |
| rtems_status_code | rtems_scheduler_remove_processor (rtems_id scheduler_id, uint32_t cpu_index) |
| Removes a processor from set of processors owned by the specified scheduler instance. More... | |
| rtems_status_code | rtems_scheduler_get_maximum_priority (rtems_id scheduler_id, rtems_task_priority *priority) |
| Gets the maximum task priority of the specified scheduler instance. More... | |
| rtems_status_code | rtems_scheduler_map_priority_to_posix (rtems_id scheduler_id, rtems_task_priority priority, int *posix_priority) |
| Map a task priority to the corresponding POSIX thread priority. More... | |
| rtems_status_code | rtems_scheduler_map_priority_from_posix (rtems_id scheduler_id, int posix_priority, rtems_task_priority *priority) |
| Map a POSIX thread priority to the corresponding task priority. More... | |
This encapsulates the functionality of the Classic API Task Manager. This functionality includes task services such as creation, deletion, delays, suspend/resume, and manipulation of execution mode and priority.
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:
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).
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.
A task may exist in one of the following five states:
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.
A task's priority determines its importance in relation to the other tasks executing on the same processor. RTEMS supports 255 levels of priority ranging from 1 to 255. The data type rtems_task_priority() is used to store task priorities.
Tasks of numerically smaller priority values are more important tasks than tasks of numerically larger priority values. For example, a task at priority level 5 is of higher privilege than a task at priority level 10. There is no limit to the number of tasks assigned to the same priority.
Each task has a priority associated with it at all times. The initial value of this priority is assigned at task creation time. The priority of a task may be changed at any subsequent time.
Priorities are used by the scheduler to determine which ready task will be allowed to execute. In general, the higher the logical priority of a task, the more likely it is to receive processor execution time.
A task's execution mode is a combination of the following four components:
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.
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:
Application tasks requiring more information may view this single argument as an index into an array of parameter blocks.
Creating a task with the RTEMS_FLOATING_POINT attribute flag results in additional memory being allocated for the TCB to store the state of the numeric coprocessor during task switches. This additional memory is NOT allocated for RTEMS_NO_FLOATING_POINT tasks. Saving and restoring the context of a RTEMS_FLOATING_POINT task takes longer than that of a RTEMS_NO_FLOATING_POINT task because of the relatively large amount of time required for the numeric coprocessor to save or restore its computational state.
Since RTEMS was designed specifically for embedded military applications which are floating point intensive, the executive is optimized to avoid unnecessarily saving and restoring the state of the numeric coprocessor. The state of the numeric coprocessor is only saved when a RTEMS_FLOATING_POINT task is dispatched and that task was not the last task to utilize the coprocessor. In a system with only one RTEMS_FLOATING_POINT task, the state of the numeric coprocessor will never be saved or restored.
Although the overhead imposed by RTEMS_FLOATING_POINT tasks is minimal, some applications may wish to completely avoid the overhead associated with RTEMS_FLOATING_POINT tasks and still utilize a numeric coprocessor. By preventing a task from being preempted while performing a sequence of floating point operations, a RTEMS_NO_FLOATING_POINT task can utilize the numeric coprocessor without incurring the overhead of a RTEMS_FLOATING_POINT context switch. This approach also avoids the allocation of a floating point context area. However, if this approach is taken by the application designer, NO tasks should be created as RTEMS_FLOATING_POINT tasks. Otherwise, the floating point context will not be correctly maintained because RTEMS assumes that the state of the numeric coprocessor will not be altered by RTEMS_NO_FLOATING_POINT tasks.
If the supported processor type does not have hardware floating capabilities or a standard numeric coprocessor, RTEMS will not provide built-in support for hardware floating point on that processor. In this case, all tasks are considered RTEMS_NO_FLOATING_POINT whether created as RTEMS_FLOATING_POINT or RTEMS_NO_FLOATING_POINT tasks. A floating point emulation software library must be utilized for floating point operations.
On some processors, it is possible to disable the floating point unit dynamically. If this capability is supported by the target processor, then RTEMS will utilize this capability to enable the floating point unit only for tasks which are created with the RTEMS_FLOATING_POINT attribute. The consequence of a RTEMS_NO_FLOATING_POINT task attempting to access the floating point unit is CPU dependent but will generally result in an exception condition.
Per task variables are no longer available. In particular the rtems_task_variable_add(), rtems_task_variable_get() and rtems_task_variable_delete() functions are neither declared nor defined anymore. Use thread local storage or POSIX Keys instead.
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.
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 Constant | Mask Constant | Description |
|---|---|---|
| RTEMS_PREEMPT | RTEMS_PREEMPT_MASK | enables preemption |
| RTEMS_NO_PREEMPT | RTEMS_PREEMPT_MASK | disables preemption |
| RTEMS_NO_TIMESLICE | RTEMS_TIMESLICE_MASK | disables timeslicing |
| RTEMS_TIMESLICE | RTEMS_TIMESLICE_MASK | enables timeslicing |
| RTEMS_ASR | RTEMS_ASR_MASK | enables ASR processing |
| RTEMS_NO_ASR | RTEMS_ASR_MASK | disables ASR processing |
| RTEMS_INTERRUPT_LEVEL(0) | RTEMS_INTERRUPT_MASK | enables all interrupts |
| RTEMS_INTERRUPT_LEVEL(n) | RTEMS_INTERRUPT_MASK | sets interrupts level n |
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_PREEMPT_MASK to indicate that the calling task's interrupt level and preemption mode are being altered.
| #define RTEMS_CURRENT_PRIORITY 0 |
The following constant is passed to rtems_task_set_priority when the caller wants to obtain the current priority.
| #define RTEMS_ID_NONE OBJECTS_ID_NONE |
Invalid object identifier value.
No object can have this identifier value.
| #define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() |
This run-time constant is the maximum valid value for a Classic API task priority.
| #define RTEMS_MILLISECONDS_TO_TICKS | ( | _ms | ) |
Returns the number of ticks for the milli seconds value _ms.
| #define RTEMS_MINIMUM_PRIORITY 1 |
This constant is the least valid value for a Classic API task priority.
| #define RTEMS_NO_PRIORITY RTEMS_CURRENT_PRIORITY |
This is the constant used with the rtems_task_set_priority directive to indicate that the caller wants to obtain its current priority rather than set it as the name of the directive indicates.
| #define rtems_scheduler_get_processor | ( | ) | _SMP_Get_current_processor() |
Returns the index of the current processor.
In uniprocessor configurations, a value of zero will be returned.
In SMP configurations, an architecture specific method is used to obtain the index of the current processor in the system. The set of processor indices is the range of integers starting with zero up to the processor count minus one.
Outside of sections with disabled thread dispatching the current processor index may change after every instruction since the thread may migrate from one processor to another. Sections with disabled interrupts are sections with thread dispatching disabled.
| #define rtems_scheduler_get_processor_maximum | ( | ) | _SMP_Get_processor_maximum() |
Returns the processor maximum supported by the system.
In uniprocessor configurations, a value of one will be returned.
In SMP configurations, this function returns the minimum of the processors (physically or virtually) available by the platform and the configured processor maximum. Not all processors in the range from processor index zero to the last processor index (which is the processor maximum minus one) may be configured to be used by a scheduler or online (online processors have a scheduler assigned).
| #define RTEMS_SELF OBJECTS_ID_OF_SELF |
Constant to be used as the ID of current task
| #define RTEMS_YIELD_PROCESSOR WATCHDOG_NO_TIMEOUT |
This constant is passed to the rtems_task_wake_after directive as the interval when a task wishes to yield the CPU.
| typedef struct timespec rtems_thread_cpu_usage_t RTEMS_DEPRECATED |
Public name for task context area.
Represents the CPU usage per thread.
Information structure returned by the Heap Handler via the Region Manager.
Public name for task floating point context area.
When using nanoseconds granularity timing, RTEMS may internally use a variety of representations.
Defines the format of the interrupt stack frame as it appears to a user ISR.
This data structure is only provided if the interrupt stack frame is passed to the ISR handler.
| typedef uint32_t rtems_name |
Classic API object name type.
Contains the name of a Classic API object. It is an unsigned 32-bit integer which can be treated as a numeric value or initialized using rtems_build_name() to contain four ASCII characters.
| typedef void rtems_task |
The following defines the "return type" of an RTEMS task.
| typedef CPU_Uint32ptr rtems_task_argument |
The following defines the argument to an RTEMS task.
| typedef rtems_task( * rtems_task_entry) (rtems_task_argument) |
The following defines the type for the entry point of an RTEMS task.
| typedef uint32_t rtems_task_priority |
Define the type for an RTEMS API task priority.
| typedef bool( * rtems_task_visitor) (rtems_tcb *tcb, void *arg) |
Task visitor.
| [in] | tcb | The task control block. |
| [in] | arg | The visitor argument. |
| true | Stop the iteration. |
| false | Otherwise. |
| typedef struct _Thread_Control rtems_tcb |
External API name for Thread_Control
| RTEMS_DEPRECATED RTEMS_INLINE_ROUTINE uint32_t rtems_get_current_processor | ( | void | ) |
Returns the index of the current processor.
Use rtems_scheduler_get_processor() instead.
| RTEMS_DEPRECATED RTEMS_INLINE_ROUTINE uint32_t rtems_get_processor_count | ( | void | ) |
Returns the processor maximum supported by the system.
Use rtems_scheduler_get_processor_maximum() instead.
| rtems_status_code rtems_scheduler_add_processor | ( | rtems_id | scheduler_id, |
| uint32_t | cpu_index | ||
| ) |
Adds a processor to the set of processors owned by the specified scheduler instance.
Must be called from task context. This operation obtains and releases the objects allocator lock.
| [in] | scheduler_id | Identifier of the scheduler instance. |
| [in] | cpu_index | Index of the processor to add. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ID | Invalid scheduler instance identifier. |
| RTEMS_NOT_CONFIGURED | The processor is not configured to be used by the application. |
| RTEMS_INCORRECT_STATE | The processor is configured to be used by the application, however, it is not online. |
| RTEMS_RESOURCE_IN_USE | The processor is already assigned to a scheduler instance. |
| rtems_status_code rtems_scheduler_get_maximum_priority | ( | rtems_id | scheduler_id, |
| rtems_task_priority * | priority | ||
| ) |
Gets the maximum task priority of the specified scheduler instance.
| [in] | scheduler_id | Identifier of the scheduler instance. |
| [out] | priority | Pointer to a task priority value. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The priority parameter is NULL. |
| RTEMS_INVALID_ID | Invalid scheduler instance identifier. |
| rtems_status_code rtems_scheduler_get_processor_set | ( | rtems_id | scheduler_id, |
| size_t | cpusetsize, | ||
| cpu_set_t * | cpuset | ||
| ) |
Gets the set of processors owned by the specified scheduler instance.
| [in] | scheduler_id | Identifier of the scheduler instance. |
| [in] | cpusetsize | Size of the specified processor set buffer in bytes. This value must be positive. |
| [out] | cpuset | The processor set owned by the scheduler. A set bit in the processor set means that this processor is owned by the scheduler and a cleared bit means the opposite. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The cpuset parameter is NULL. |
| RTEMS_INVALID_ID | Invalid scheduler instance identifier. |
| RTEMS_INVALID_NUMBER | The processor set buffer is too small for the set of processors owned by the scheduler. |
| rtems_status_code rtems_scheduler_ident | ( | rtems_name | name, |
| rtems_id * | id | ||
| ) |
Identifies a scheduler by its name.
The scheduler name is determined by the scheduler configuration.
| [in] | name | The scheduler name. |
| [out] | id | The scheduler identifier associated with the name. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The id parameter is NULL. |
| RTEMS_INVALID_NAME | Invalid scheduler name. |
| rtems_status_code rtems_scheduler_ident_by_processor | ( | uint32_t | cpu_index, |
| rtems_id * | id | ||
| ) |
Identifies a scheduler by a processor index.
| [in] | cpu_index | The processor index. |
| [out] | id | The scheduler identifier associated with the processor index. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The id parameter is NULL. |
| RTEMS_INVALID_NAME | Invalid processor index. |
| RTEMS_INCORRECT_STATE | The processor index is valid, however, this processor is not owned by a scheduler. |
| rtems_status_code rtems_scheduler_ident_by_processor_set | ( | size_t | cpusetsize, |
| const cpu_set_t * | cpuset, | ||
| rtems_id * | id | ||
| ) |
Identifies a scheduler by a processor set.
The scheduler is selected according to the highest numbered online processor in the specified processor set.
| [in] | cpusetsize | Size of the specified processor set buffer in bytes. This value must be positive. |
| [out] | cpuset | The processor set to identify the scheduler. |
| [out] | id | The scheduler identifier associated with the processor set. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The id parameter is NULL. |
| RTEMS_INVALID_SIZE | Invalid processor set size. |
| RTEMS_INVALID_NAME | The processor set contains no online processor. |
| RTEMS_INCORRECT_STATE | The processor set is valid, however, the highest numbered online processor in the specified processor set is not owned by a scheduler. |
| rtems_status_code rtems_scheduler_map_priority_from_posix | ( | rtems_id | scheduler_id, |
| int | posix_priority, | ||
| rtems_task_priority * | priority | ||
| ) |
Map a POSIX thread priority to the corresponding task priority.
| scheduler_id | Identifier of the scheduler instance. | |
| posix_priority | The POSIX thread priority to map. | |
| [out] | priority | Pointer to a task priority value. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The priority parameter is NULL. |
| RTEMS_INVALID_ID | Invalid scheduler instance identifier. |
| RTEMS_INVALID_PRIORITY | Invalid POSIX thread priority. |
| rtems_status_code rtems_scheduler_map_priority_to_posix | ( | rtems_id | scheduler_id, |
| rtems_task_priority | priority, | ||
| int * | posix_priority | ||
| ) |
Map a task priority to the corresponding POSIX thread priority.
| scheduler_id | Identifier of the scheduler instance. | |
| priority | The task priority to map. | |
| [out] | posix_priority | Pointer to a POSIX thread priority value. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The posix_priority parameter is NULL. |
| RTEMS_INVALID_ID | Invalid scheduler instance identifier. |
| RTEMS_INVALID_PRIORITY | Invalid task priority. |
| rtems_status_code rtems_scheduler_remove_processor | ( | rtems_id | scheduler_id, |
| uint32_t | cpu_index | ||
| ) |
Removes a processor from set of processors owned by the specified scheduler instance.
Must be called from task context. This operation obtains and releases the objects allocator lock. Removing a processor from a scheduler is a complex operation that involves all tasks of the system.
| [in] | scheduler_id | Identifier of the scheduler instance. |
| [in] | cpu_index | Index of the processor to add. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ID | Invalid scheduler instance identifier. |
| RTEMS_INVALID_NUMBER | The processor is not owned by the specified scheduler instance. |
| RTEMS_RESOURCE_IN_USE | The set of processors owned by the specified scheduler instance would be empty after the processor removal and there exists a non-idle task that uses this scheduler instance as its home scheduler instance. |
| rtems_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 | ||
| ) |
RTEMS Task Create.
This routine implements the rtems_task_create directive. The task will have the name name. The attribute_set can be used to indicate that the task will be globally accessible or utilize floating point. The task's stack will be stack_size bytes. The task will begin execution with initial_priority and initial_modes. It returns the id of the created task in ID.
| [in] | name | is the user defined thread name |
| [in] | initial_priority | is the thread priority |
| [in] | stack_size | is the stack size in bytes |
| [in] | initial_modes | is the initial thread mode |
| [in] | attribute_set | is the thread attributes |
| [in] | id | is the pointer to thread id |
| RTEMS_SUCCESSFUL | if successful or error code if unsuccessful and *id thread id filled in |
| rtems_status_code rtems_task_delete | ( | rtems_id | id | ) |
RTEMS Delete Task.
This routine implements the rtems_task_delete directive. The task indicated by ID is deleted. The executive halts execution of the thread and frees the thread control block.
| [in] | id | is the thread id |
| This | method returns RTEMS_SUCCESSFUL if there was not an error and id is not the requesting thread. Status code is returned indicating the source of the error. Nothing is returned if id is the requesting thread (always succeeds). |
| rtems_status_code rtems_task_get_affinity | ( | rtems_id | id, |
| size_t | cpusetsize, | ||
| cpu_set_t * | cpuset | ||
| ) |
Gets the processor affinity set of a task.
| [in] | id | Identifier of the task. Use RTEMS_SELF to select the executing task. |
| [in] | cpusetsize | Size of the specified affinity set buffer in bytes. This value must be positive. |
| [out] | cpuset | The current processor affinity set of the task. A set bit in the affinity set means that the task can execute on this processor and a cleared bit means the opposite. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The cpuset parameter is NULL. |
| RTEMS_INVALID_ID | Invalid task identifier. |
| RTEMS_INVALID_NUMBER | The affinity set buffer is too small for the current processor affinity set of the task. |
| rtems_status_code rtems_task_get_priority | ( | rtems_id | task_id, |
| rtems_id | scheduler_id, | ||
| rtems_task_priority * | priority | ||
| ) |
Gets the current priority of the specified task with respect to the specified scheduler instance.
The current priority reflects temporary priority adjustments due to locking protocols, the rate-monotonic period objects on some schedulers and other mechanisms.
| [in] | task_id | Identifier of the task. Use RTEMS_SELF to select the executing task. |
| [in] | scheduler_id | Identifier of the scheduler instance. |
| [out] | priority | Returns the current priority of the specified task with respect to the specified scheduler instance. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_ILLEGAL_ON_REMOTE_OBJECT | Directive is illegal on remote tasks. |
| RTEMS_INVALID_ADDRESS | The priority parameter is NULL. |
| RTEMS_INVALID_ID | Invalid task or scheduler identifier. |
| RTEMS_NOT_DEFINED | The task has no priority within the specified scheduler instance. This error is only possible on SMP configurations. |
| rtems_status_code rtems_task_get_scheduler | ( | rtems_id | task_id, |
| rtems_id * | scheduler_id | ||
| ) |
Gets the scheduler of a task.
| [in] | task_id | Identifier of the task. Use RTEMS_SELF to select the executing task. |
| [out] | scheduler_id | Identifier of the scheduler instance. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The scheduler_id parameter is NULL. |
| RTEMS_INVALID_ID | Invalid task identifier. |
| rtems_status_code rtems_task_ident | ( | rtems_name | name, |
| uint32_t | node, | ||
| rtems_id * | id | ||
| ) |
RTEMS Task Name to Id.
This routine implements the rtems_task_ident directive. This directive returns the task ID associated with name. If more than one task is named name, then the task to which the ID belongs is arbitrary. node indicates the extent of the search for the ID of the task named name. The search can be limited to a particular node or allowed to encompass all nodes.
| [in] | name | is the user defined thread name |
| [in] | node | is(are) the node(s) to be searched |
| [in] | id | is the pointer to thread id |
| This | method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error. If successful, the id will be filled in with the thread id. |
| rtems_status_code rtems_task_is_suspended | ( | rtems_id | id | ) |
rtems_task_is_suspended
This directive returns a status indicating whether or not the specified task is suspended.
| void rtems_task_iterate | ( | rtems_task_visitor | visitor, |
| void * | arg | ||
| ) |
Iterates over all tasks in the system.
This operation covers all tasks of all APIs.
Must be called from task context. This operation obtains and releases the objects allocator lock. The task visitor is called while owning the objects allocator lock. It is possible to perform blocking operations in the task visitor, however, take care that no deadlocks via the object allocator lock can occur.
| [in] | visitor | The task visitor. |
| [in] | arg | The visitor argument. |
| rtems_status_code rtems_task_mode | ( | rtems_mode | mode_set, |
| rtems_mode | mask, | ||
| rtems_mode * | previous_mode_set | ||
| ) |
RTEMS Task Mode.
This routine implements the rtems_task_mode directive. The current values of the modes indicated by mask of the calling task are changed to that indicated in mode_set. The former mode of the task is returned in mode_set.
| [in] | mode_set | is the new mode |
| [in] | mask | is the mask |
| [in] | previous_mode_set | is the address of previous mode set |
| RTEMS_SUCCESSFUL | and previous_mode_set filled in with the previous mode set |
| rtems_status_code rtems_task_restart | ( | rtems_id | id, |
| rtems_task_argument | argument | ||
| ) |
RTEMS Task Restart.
This routine implements the rtems_task_restart directive. The task associated with ID is restarted at its initial entry point with the new argument.
| [in] | id | is the thread id |
| [in] | argument | is the thread argument |
| RTEMS_SUCCESSFUL | if successful or error code if unsuccessful |
| rtems_status_code rtems_task_resume | ( | rtems_id | id | ) |
RTEMS Resume Task.
This routine implements the rtems_task_resume Directive. The SUSPENDED state is cleared for task associated with ID.
| [in] | id | is the thread id |
| This | method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error. |
| rtems_id rtems_task_self | ( | void | ) |
RTEMS Get Self Task Id.
This directive returns the ID of the currently executing task.
| rtems_status_code rtems_task_set_affinity | ( | rtems_id | id, |
| size_t | cpusetsize, | ||
| const cpu_set_t * | cpuset | ||
| ) |
Sets the processor affinity set of a task.
This function will not change the scheduler of the task. The intersection of the processor affinity set and the set of processors owned by the scheduler of the task must be non-empty. It is not an error if the processor affinity set contains processors that are not part of the set of processors owned by the scheduler instance of the task. A task will simply not run under normal circumstances on these processors since the scheduler ignores them. Some locking protocols may temporarily use processors that are not included in the processor affinity set of the task. It is also not an error if the processor affinity set contains processors that are not part of the system.
| [in] | id | Identifier of the task. Use RTEMS_SELF to select the executing task. |
| [in] | cpusetsize | Size of the specified affinity set buffer in bytes. This value must be positive. |
| [in] | cpuset | The new processor affinity set for the task. A set bit in the affinity set means that the task can execute on this processor and a cleared bit means the opposite. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_INVALID_ADDRESS | The cpuset parameter is NULL. |
| RTEMS_INVALID_ID | Invalid task identifier. |
| RTEMS_INVALID_NUMBER | Invalid processor affinity set. |
| rtems_status_code rtems_task_set_priority | ( | rtems_id | id, |
| rtems_task_priority | new_priority, | ||
| rtems_task_priority * | old_priority | ||
| ) |
RTEMS Set Task Priority.
This routine implements the rtems_task_set_priority directive. The current priority of the task associated with ID is set to new_priority. The former priority of that task is returned in old_priority.
| [in] | id | is the thread to extract |
| [in] | new_priority | is the thread to extract |
| [in] | old_priority | is the thread to extract |
| RTEMS_SUCCESSFUL | if successful or error code if unsuccessful and and *old_priority filled in with the previous previous priority |
| rtems_status_code rtems_task_set_scheduler | ( | rtems_id | task_id, |
| rtems_id | scheduler_id, | ||
| rtems_task_priority | priority | ||
| ) |
Sets the scheduler instance of a task.
Initially, the scheduler instance of a task is set to the scheduler instance of the task that created it. This directive allows to move a task from its current scheduler instance to another specified by the scheduler identifier.
| [in] | task_id | Identifier of the task. Use RTEMS_SELF to select the executing task. |
| [in] | scheduler_id | Identifier of the scheduler instance. |
| [in] | priority | The task priority with respect to the new scheduler instance. The real and initial priority of the task is set to this value. The initial priority is used by rtems_task_restart() for example. |
| RTEMS_SUCCESSFUL | Successful operation. |
| RTEMS_ILLEGAL_ON_REMOTE_OBJECT | Directive is illegal on remote tasks. |
| RTEMS_INVALID_ID | Invalid task or scheduler identifier. |
| RTEMS_INVALID_PRIORITY | Invalid priority. |
| RTEMS_RESOURCE_IN_USE | The task owns resources which deny a scheduler change. |
| rtems_status_code rtems_task_start | ( | rtems_id | id, |
| rtems_task_entry | entry_point, | ||
| rtems_task_argument | argument | ||
| ) |
RTEMS Start Task.
RTEMS Task Manager
This routine implements the rtems_task_start directive. The starting execution point of the task associated with ID is set to entry_point with the initial argument.
| rtems_status_code rtems_task_suspend | ( | rtems_id | id | ) |
RTEMS Suspend Task.
This routine implements the rtems_task_suspend directive. The SUSPENDED state is set for task associated with ID. Note that the suspended state can be in addition to other waiting states.
| [in] | id | is the thread id |
| This | method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error. |
| rtems_status_code rtems_task_wake_after | ( | rtems_interval | ticks | ) |
RTEMS Task Wake After.
This routine implements the rtems_task_wake_after directive. The calling task is blocked until the indicated number of clock ticks have occurred.
| [in] | ticks | is the number of ticks to wait |
| RTEMS_SUCCESSFUL |
| rtems_status_code rtems_task_wake_when | ( | rtems_time_of_day * | time_buffer | ) |
RTEMS Task Wake When.
This routine implements the rtems_task_wake_when directive. The calling task is blocked until the current time of day is equal to that indicated by time_buffer.
| [in] | time_buffer | is the pointer to the time and date structure |
| RTEMS_SUCCESSFUL | if successful or error code if unsuccessful |
1.8.15