RTEMS Tasks. More...

Collaboration diagram for Tasks:

Modules
	Classic Tasks Manager Implementation

Files
file	taskcreate.c
	RTEMS Task Create.

file	taskdata.c
	Instantiate RTEMS Classic API Tasks Data.

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	tasksetnote.c
	RTEMS Set Task Note.

file	tasksetpriority.c
	RTEMS Set Task Priority.

file	taskstart.c
	RTEMS Start Task.

file	tasksuspend.c
	RTEMS Suspend Task.

file	taskvariable_invoke_dtor.c
	RTEMS Tasks Invoke Task Variable Destructor.

file	taskvariableadd.c
	RTEMS Add Task Variable.

file	taskvariabledelete.c
	RTEMS Delete Task Variable.

file	taskvariableget.c
	Get a per-task variable.

file	taskwakeafter.c
	RTEMS Task Wake After.

file	taskwakewhen.c
	RTEMS Task Wake When.

Data Structures
struct	rtems_initialization_tasks_table
	The following records define the Initialization Tasks Table. More...

Macros
#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.

#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_MINIMUM_PRIORITY (PRIORITY_MINIMUM + 1)
	This constant is the least valid value for a Classic API task priority.

#define	RTEMS_MAXIMUM_PRIORITY PRIORITY_MAXIMUM
	This constant is the maximum valid value for a Classic API task priority. More...

#define	RTEMS_CURRENT_PRIORITY PRIORITY_MINIMUM
	The following constant is passed to rtems_task_set_priority when the caller wants to obtain the current priority.

#define	RTEMS_NOTEPAD_FIRST 0
	This is used to indicate the lowest numbered notepad.

#define	RTEMS_NOTEPAD_0 0
	This is used to indicate the notepad location 0. More...

#define	RTEMS_NOTEPAD_1 1
	This is used to indicate the notepad location 1. More...

#define	RTEMS_NOTEPAD_2 2
	This is used to indicate the notepad location 2. More...

#define	RTEMS_NOTEPAD_3 3
	This is used to indicate the notepad location 3. More...

#define	RTEMS_NOTEPAD_4 4
	This is used to indicate the notepad location 4. More...

#define	RTEMS_NOTEPAD_5 5
	This is used to indicate the notepad location 5. More...

#define	RTEMS_NOTEPAD_6 6
	This is used to indicate the notepad location 6. More...

#define	RTEMS_NOTEPAD_7 7
	This is used to indicate the notepad location 7. More...

#define	RTEMS_NOTEPAD_8 8
	This is used to indicate the notepad location 8. More...

#define	RTEMS_NOTEPAD_9 9
	This is used to indicate the notepad location 9. More...

#define	RTEMS_NOTEPAD_10 10
	This is used to indicate the notepad location 10. More...

#define	RTEMS_NOTEPAD_11 11
	This is used to indicate the notepad location 11. More...

#define	RTEMS_NOTEPAD_12 12
	This is used to indicate the notepad location 12. More...

#define	RTEMS_NOTEPAD_13 13
	This is used to indicate the notepad location 13. More...

#define	RTEMS_NOTEPAD_14 14
	This is used to indicate the notepad location 14. More...

#define	RTEMS_NOTEPAD_15 15
	This is used to indicate the notepad location 15. More...

#define	RTEMS_NOTEPAD_LAST RTEMS_NOTEPAD_15
	This is used to indicate the highest numbered notepad. More...

#define	RTEMS_NUMBER_NOTEPADS (RTEMS_NOTEPAD_LAST+1)
	This is used to indicate the number of notepads available. More...

Typedefs
typedef Priority_Control	rtems_task_priority
	Define the type for an RTEMS API task priority.

typedef Thread_Control	rtems_tcb
	External API name for Thread_Control.

typedef void	rtems_task
	The following defines the "return type" of an RTEMS task.

typedef Thread_Entry_numeric_type	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.

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

rtems_status_code	rtems_task_get_note (rtems_id id, uint32_t notepad, uint32_t *note)
	RTEMS Get Task Node. More...

rtems_status_code	rtems_task_set_note (rtems_id id, uint32_t notepad, uint32_t note)
	RTEMS Set Task Note. More...

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, uint32_t arg)
	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_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_variable_add (rtems_id tid, void *ptr, void(dtor)(void *))
	RTEMS Add Task Variable. More...

rtems_status_code	rtems_task_variable_get (rtems_id tid, void ptr, void result)
	Get a per-task variable. More...

rtems_status_code	rtems_task_variable_delete (rtems_id tid, void **ptr)
	RTEMS Delete Task Variable. 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)
	Sets the scheduler of a task. More...

rtems_id	rtems_task_self (void)
	RTEMS Get Self Task Id. More...

rtems_status_code	rtems_scheduler_ident (rtems_name name, rtems_id *id)
	Identifies a scheduler by its name. More...

Detailed Description

RTEMS Tasks.

This encapsulates the functionality of the Classic API Task Manager.

This include file contains all constants and structures associated with RTEMS tasks. This manager provides a comprehensive set of directives to create, delete, and administer tasks.

Directives provided are:

create a task
get an ID of a task
start a task
restart a task
delete a task
suspend a task
resume a task
set a task's priority
change the current task's mode
get a task notepad entry
set a task notepad entry
wake up after interval
wake up when specified

This functionality includes task services such as creation, deletion, delays, suspend/resume, and manipulation of execution mode and priority.

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

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, set of notepad locations, 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.

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.

Task Priority

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

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

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

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

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.

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

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

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.

Floating Point Considerations

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

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

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

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

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

Per Task Variables

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

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

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

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

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

{WARNING}: Per-task variables are fundamentally incorrect in SMP systems and should not be used in SMP applications. They are disabled.

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:

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

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.

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

Macro Definition Documentation

◆ RTEMS_MAXIMUM_PRIORITY

#define RTEMS_MAXIMUM_PRIORITY PRIORITY_MAXIMUM

This constant is the maximum valid value for a Classic API task priority.

Note: This is actually the priority of the IDLE thread so using this priority will result in having a task which never executes. This could be useful if you want to ensure that a task does not executes during certain operations such as a system mode change.

Referenced by _RTEMS_tasks_Priority_is_valid().

◆ RTEMS_NOTEPAD_0

#define RTEMS_NOTEPAD_0 0

This is used to indicate the notepad location 0.

◆ RTEMS_NOTEPAD_1

#define RTEMS_NOTEPAD_1 1

This is used to indicate the notepad location 1.

◆ RTEMS_NOTEPAD_10

#define RTEMS_NOTEPAD_10 10

This is used to indicate the notepad location 10.

◆ RTEMS_NOTEPAD_11

#define RTEMS_NOTEPAD_11 11

This is used to indicate the notepad location 11.

◆ RTEMS_NOTEPAD_12

#define RTEMS_NOTEPAD_12 12

This is used to indicate the notepad location 12.

◆ RTEMS_NOTEPAD_13

#define RTEMS_NOTEPAD_13 13

This is used to indicate the notepad location 13.

◆ RTEMS_NOTEPAD_14

#define RTEMS_NOTEPAD_14 14

This is used to indicate the notepad location 14.

◆ RTEMS_NOTEPAD_15

#define RTEMS_NOTEPAD_15 15

This is used to indicate the notepad location 15.

◆ RTEMS_NOTEPAD_2

#define RTEMS_NOTEPAD_2 2

This is used to indicate the notepad location 2.

◆ RTEMS_NOTEPAD_3

#define RTEMS_NOTEPAD_3 3

This is used to indicate the notepad location 3.

◆ RTEMS_NOTEPAD_4

#define RTEMS_NOTEPAD_4 4

This is used to indicate the notepad location 4.

◆ RTEMS_NOTEPAD_5

#define RTEMS_NOTEPAD_5 5

This is used to indicate the notepad location 5.

◆ RTEMS_NOTEPAD_6

#define RTEMS_NOTEPAD_6 6

This is used to indicate the notepad location 6.

◆ RTEMS_NOTEPAD_7

#define RTEMS_NOTEPAD_7 7

This is used to indicate the notepad location 7.

◆ RTEMS_NOTEPAD_8

#define RTEMS_NOTEPAD_8 8

This is used to indicate the notepad location 8.

◆ RTEMS_NOTEPAD_9

#define RTEMS_NOTEPAD_9 9

This is used to indicate the notepad location 9.

◆ RTEMS_NOTEPAD_LAST

#define RTEMS_NOTEPAD_LAST RTEMS_NOTEPAD_15

This is used to indicate the highest numbered notepad.

Referenced by rtems_task_get_note(), and rtems_task_set_note().

◆ RTEMS_NUMBER_NOTEPADS

#define RTEMS_NUMBER_NOTEPADS (RTEMS_NOTEPAD_LAST+1)

This is used to indicate the number of notepads available.

Function Documentation

◆ rtems_scheduler_ident()

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.

Parameters

[in]	name	The scheduler name.
[out]	id	The scheduler identifier associated with the name.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ADDRESS	The id parameter is `NULL`.
RTEMS_INVALID_NAME	Invalid scheduler name.
RTEMS_UNSATISFIED	A scheduler with this name exists, but the processor set of this scheduler is empty.

References _Scheduler_Count, _Scheduler_Table, Scheduler_Control::name, and RTEMS_INVALID_NAME.

◆ rtems_task_create()

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.

Parameters

[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

Return values

RTEMS_SUCCESSFUL if successful or error code if unsuccessful and *id thread id filled in

◆ rtems_task_delete()

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.

Parameters

[in] id is the thread id

Return values

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_task_get_note()

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

RTEMS Get Task Node.

Deprecated:: Notepads are deprecated and will be removed.

This routine implements the rtems_task_get_note directive. The value of the indicated notepad for the task associated with ID is returned in note.

Parameters

[in]	id	is the thread id
[in]	notepad	is the notepad number
[out]	note	is the pointer to note

Return values

RTEMS_SUCCESSFUL if successful or error code if unsuccessful

References _Objects_Are_ids_equal(), _Thread_Get(), _Thread_Get_executing(), Thread_Control::API_Extensions, Objects_Control::id, RTEMS_API_Control::Notepads, Thread_Control::Object, OBJECTS_ID_OF_SELF, rtems_configuration_get_notepads_enabled, RTEMS_INVALID_ADDRESS, RTEMS_INVALID_NUMBER, RTEMS_NOT_CONFIGURED, RTEMS_NOTEPAD_LAST, RTEMS_SUCCESSFUL, and THREAD_API_RTEMS.

◆ rtems_task_get_scheduler()

rtems_status_code rtems_task_get_scheduler	(	rtems_id	task_id,
		rtems_id *	scheduler_id
	)

Gets the scheduler of a task.

Parameters

[in]	task_id	Identifier of the task. Use RTEMS_SELF to select the executing task.
[out]	scheduler_id	Identifier of the scheduler.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ADDRESS	The scheduler_id parameter is `NULL`.
RTEMS_INVALID_ID	Invalid task identifier.

References _Thread_Get().

◆ rtems_task_ident()

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.

Parameters

[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

Return values

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.

Referenced by rtems_shell_script().

◆ rtems_task_is_suspended()

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.

References _Thread_Get().

◆ rtems_task_mode()

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.

Parameters

[in]	mode_set	is the new mode
[in]	mask	is the mask
[in]	previous_mode_set	is the address of previous mode set

Return values

RTEMS_SUCCESSFUL and previous_mode_set filled in with the previous mode set

◆ rtems_task_restart()

rtems_status_code rtems_task_restart	(	rtems_id	id,
		uint32_t	arg
	)

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.

Parameters

[in]	id	is the thread id
[in]	arg	is the thread argument

Return values

RTEMS_SUCCESSFUL if successful or error code if unsuccessful

References _Thread_Get().

◆ rtems_task_resume()

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.

Parameters

[in] id is the thread id

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References _Thread_Get().

◆ rtems_task_self()

rtems_id rtems_task_self ( void )

RTEMS Get Self Task Id.

This directive returns the ID of the currently executing task.

References _Thread_Get_executing(), Objects_Control::id, and Thread_Control::Object.

◆ rtems_task_set_note()

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

RTEMS Set Task Note.

Deprecated:: Notepads are deprecated and will be removed.

This routine implements the rtems_task_set_note directive. The value of the indicated notepad for the task associated with ID is returned in note.

Parameters

[in]	id	is the thread id
[in]	notepad	is the notepad number
[in]	note	is the note value

Returns: This method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References _Objects_Are_ids_equal(), _Thread_Get(), _Thread_Get_executing(), Thread_Control::API_Extensions, Objects_Control::id, RTEMS_API_Control::Notepads, Thread_Control::Object, OBJECTS_ID_OF_SELF, rtems_configuration_get_notepads_enabled, RTEMS_INVALID_NUMBER, RTEMS_NOT_CONFIGURED, RTEMS_NOTEPAD_LAST, RTEMS_SUCCESSFUL, and THREAD_API_RTEMS.

◆ rtems_task_set_priority()

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.

Parameters

[in]	id	is the thread to extract
[in]	new_priority	is the thread to extract
[in]	old_priority	is the thread to extract

Return values

RTEMS_SUCCESSFUL if successful or error code if unsuccessful and and *old_priority filled in with the previous previous priority

References _RTEMS_tasks_Priority_is_valid(), _Thread_Get(), RTEMS_CURRENT_PRIORITY, RTEMS_INVALID_ADDRESS, and RTEMS_INVALID_PRIORITY.

◆ rtems_task_set_scheduler()

rtems_status_code rtems_task_set_scheduler	(	rtems_id	task_id,
		rtems_id	scheduler_id
	)

Sets the scheduler of a task.

The scheduler of a task is initialized to the scheduler of the task that created it.

Parameters

[in]	task_id	Identifier of the task. Use RTEMS_SELF to select the executing task.
[in]	scheduler_id	Identifier of the scheduler.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	Invalid task or scheduler identifier.

See also: rtems_scheduler_ident().

◆ rtems_task_start()

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.

References _Thread_Get(), and RTEMS_INVALID_ADDRESS.

◆ rtems_task_suspend()

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.

Parameters

[in] id is the thread id

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References _Thread_Get().

◆ rtems_task_variable_add()

rtems_status_code rtems_task_variable_add	(	rtems_id	tid,
		void **	ptr,
		void()(void )	dtor
	)

RTEMS Add Task Variable.

Deprecated:: Task variables are deprecated.

This directive adds a per task variable.

Note: This service is not available in SMP configurations.

References _Thread_Get(), rtems_configuration_is_smp_enabled, RTEMS_INVALID_ADDRESS, and RTEMS_NOT_IMPLEMENTED.

◆ rtems_task_variable_delete()

rtems_status_code rtems_task_variable_delete	(	rtems_id	tid,
		void **	ptr
	)

RTEMS Delete Task Variable.

Deprecated:: Task variables are deprecated.

This directive removes a per task variable.

Note: This service is not available in SMP configurations.

References _Thread_Get(), rtems_configuration_is_smp_enabled, RTEMS_INVALID_ADDRESS, and RTEMS_NOT_IMPLEMENTED.

◆ rtems_task_variable_get()

rtems_status_code rtems_task_variable_get	(	rtems_id	tid,
		void **	ptr,
		void **	result
	)

Get a per-task variable.

Deprecated:: Task variables are deprecated.

This directive gets the value of a task variable.

Note: This service is not available in SMP configurations.

References _Thread_Get(), rtems_configuration_is_smp_enabled, RTEMS_INVALID_ADDRESS, and RTEMS_NOT_IMPLEMENTED.

◆ rtems_task_wake_after()

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.

Parameters

[in] ticks is the number of ticks to wait

Return values

RTEMS_SUCCESSFUL

References _Thread_Dispatch_disable().

◆ rtems_task_wake_when()

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.

Parameters

[in] time_buffer is the pointer to the time and date structure

Return values

RTEMS_SUCCESSFUL if successful or error code if unsuccessful

References _TOD_Is_set(), _TOD_To_seconds(), _TOD_Validate(), RTEMS_INVALID_ADDRESS, RTEMS_INVALID_CLOCK, RTEMS_NOT_DEFINED, and rtems_time_of_day::ticks.

Modules

Files

Data Structures

Macros

Typedefs

Functions

Detailed Description

Task Definition

Task Control Block

Task States

Task Priority

Task Mode

Accessing Task Arguments

Floating Point Considerations

Per Task Variables

Building a Task Attribute Set

Building a Mode and Mask

Macro Definition Documentation

◆ RTEMS_MAXIMUM_PRIORITY

◆ RTEMS_NOTEPAD_0

◆ RTEMS_NOTEPAD_1

◆ RTEMS_NOTEPAD_10

◆ RTEMS_NOTEPAD_11

◆ RTEMS_NOTEPAD_12

◆ RTEMS_NOTEPAD_13

◆ RTEMS_NOTEPAD_14

◆ RTEMS_NOTEPAD_15

◆ RTEMS_NOTEPAD_2

◆ RTEMS_NOTEPAD_3

◆ RTEMS_NOTEPAD_4

◆ RTEMS_NOTEPAD_5

◆ RTEMS_NOTEPAD_6

◆ RTEMS_NOTEPAD_7

◆ RTEMS_NOTEPAD_8

◆ RTEMS_NOTEPAD_9

◆ RTEMS_NOTEPAD_LAST

◆ RTEMS_NUMBER_NOTEPADS

Function Documentation

◆ rtems_scheduler_ident()

◆ rtems_task_create()

◆ rtems_task_delete()

◆ rtems_task_get_note()

◆ rtems_task_get_scheduler()

◆ rtems_task_ident()

◆ rtems_task_is_suspended()

◆ rtems_task_mode()

◆ rtems_task_restart()

◆ rtems_task_resume()

◆ rtems_task_self()

◆ rtems_task_set_note()

◆ rtems_task_set_priority()

◆ rtems_task_set_scheduler()

◆ rtems_task_start()

◆ rtems_task_suspend()

◆ rtems_task_variable_add()

◆ rtems_task_variable_delete()

◆ rtems_task_variable_get()

◆ rtems_task_wake_after()

◆ rtems_task_wake_when()