diff options
Diffstat (limited to 'c-user/task')
| -rw-r--r-- | c-user/task/background.rst | 448 | ||||
| -rw-r--r-- | c-user/task/deprecated-directives.rst | 46 | ||||
| -rw-r--r-- | c-user/task/directives.rst | 2014 | ||||
| -rw-r--r-- | c-user/task/index.rst | 19 | ||||
| -rw-r--r-- | c-user/task/introduction.rst | 106 | ||||
| -rw-r--r-- | c-user/task/operations.rst | 192 | ||||
| -rw-r--r-- | c-user/task/removed-directives.rst | 283 |
7 files changed, 3108 insertions, 0 deletions
diff --git a/c-user/task/background.rst b/c-user/task/background.rst new file mode 100644 index 0000000..c7645b1 --- /dev/null +++ b/c-user/task/background.rst @@ -0,0 +1,448 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: task, definition + +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). + +.. _TaskControlBlock: + +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. + +.. index:: task memory + +Task Memory +----------- + +The system uses two separate memory areas to manage a task. One memory area is +the :ref:`TaskControlBlock`. The other memory area is allocated from the stack +space or provided by the user and contains + +* the task stack, + +* the thread-local storage (:term:`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 :ref:`TaskFloatingPointConsiderations`). In highly memory +constrained systems this potential overestimate of the task stack space can be +mitigated through the :ref:`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. + +.. index:: task name + +Task Name +--------- + +By default, the task name is defined by the task object name given to +:ref:`rtems_task_create() <rtems_task_create>`. The task name can be obtained +with the `pthread_getname_np() +<http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_ function. +Optionally, a new task name may be set with the `pthread_setname_np() +<http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_ function. +The maximum size of a task name is defined by the application configuration +option :ref:`CONFIGURE_MAXIMUM_THREAD_NAME_SIZE +<CONFIGURE_MAXIMUM_THREAD_NAME_SIZE>`. + +.. index:: task states + +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. + +.. index:: task priority +.. index:: priority, task +.. index:: rtems_task_priority + +.. _TaskPriority: + +Task Priority +------------- + +A task's :term:`priority` determines its importance in relation to the other +tasks executing on the processor set owned by a :term:`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 :c:type:`rtems_task_priority` is used to store task priorities. The +maximum priority level depends on the configured scheduler, see +:ref:`CONFIGURE_MAXIMUM_PRIORITY`, :ref:`ConfigurationSchedulersClustered`, and +:ref:`RTEMSAPIClassicScheduler`. + +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. + +.. index:: task mode +.. index:: rtems_task_mode + +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. + +.. index:: preemption + +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. + +.. index:: timeslicing + +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. + +.. index:: interrupt level, task + +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. + +.. list-table:: + :class: rtems-table + + * - ``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. + +.. index:: task life states + +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 +:ref:`InterfaceRtemsTaskRestart` directive. + +A task is made *terminating* by issuing a task termination request through the +:ref:`InterfaceRtemsTaskExit`, :ref:`InterfaceRtemsTaskDelete`, +``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 :ref:`InterfaceRtemsTaskExit` directive and self deletion +though :ref:`InterfaceRtemsTaskDelete` directive make the calling task +detached. In contrast, the ``pthread_exit()`` directive does not change the +detached state of the calling task. + +.. index:: task arguments +.. index:: task prototype + +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: + +.. index:: rtems_task + +.. code-block:: c + + 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. + +.. index:: floating point + +.. _TaskFloatingPointConsiderations: + +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. + +.. index:: task attributes, building + +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: + +.. list-table:: + :class: rtems-table + + * - ``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``. + +.. index:: task mode, building + +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: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_PREEMPT`` + - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption + * - ``RTEMS_NO_PREEMPT`` + - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption + * - ``RTEMS_NO_TIMESLICE`` + - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing + * - ``RTEMS_TIMESLICE`` + - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing + * - ``RTEMS_ASR`` + - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing + * - ``RTEMS_NO_ASR`` + - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing + * - ``RTEMS_INTERRUPT_LEVEL(0)`` + - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts + * - ``RTEMS_INTERRUPT_LEVEL(n)`` + - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n + +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. diff --git a/c-user/task/deprecated-directives.rst b/c-user/task/deprecated-directives.rst new file mode 100644 index 0000000..949d499 --- /dev/null +++ b/c-user/task/deprecated-directives.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Deprecated Directives +===================== + +.. raw:: latex + + \clearpage + +.. index:: rtems_iterate_over_all_threads() + +.. _rtems_iterate_over_all_threads: + +ITERATE_OVER_ALL_THREADS - Iterate Over Tasks +--------------------------------------------- + +.. warning:: + + This directive is deprecated. Its use is unsafe. Use + :ref:`rtems_task_iterate` instead. + +CALLING SEQUENCE: + .. code-block:: c + + 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. diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst new file mode 100644 index 0000000..d976905 --- /dev/null +++ b/c-user/task/directives.rst @@ -0,0 +1,2014 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _TaskManagerDirectives: + +Directives +========== + +This section details the directives of the Task Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/task/if/create + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_create() +.. index:: create a task + +.. _InterfaceRtemsTaskCreate: + +rtems_task_create() +------------------- + +Creates a task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + 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 + ); + +.. rubric:: 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 :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created task will + be stored in this object. + +.. rubric:: 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 +:term:`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 +:ref:`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 :c:macro:`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 + :c:macro:`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 :c:macro:`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 + :c:macro:`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 :c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode +set defines + +* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or + :c:macro:`RTEMS_NO_PREEMPT`, + +* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or + :c:macro:`RTEMS_NO_TIMESLICE` (default), + +* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default) + or :c:macro:`RTEMS_NO_ASR`, + +* the interrupt level of the task: :c:func:`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 :c:macro:`RTEMS_PREEMPT` mode constant. + +* A **disabled preemption** is set by the :c:macro:`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 :c:macro:`RTEMS_NO_TIMESLICE` mode constant. + +* An **enabled timeslicing** is set by the :c:macro:`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 :c:macro:`RTEMS_ASR` mode constant. + +* A **disabled ASR processing** is set by the :c:macro:`RTEMS_NO_ASR` mode + constant. + +The **initial interrupt level mode** of the task is defined by +:c:func:`RTEMS_INTERRUPT_LEVEL`. + +* Task execution with **interrupts enabled** the default and can be emphasized + through the use of the :c:func:`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 + :c:func:`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 +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines + +* the scope of the task: :c:macro:`RTEMS_LOCAL` (default) or + :c:macro:`RTEMS_GLOBAL` and + +* the floating-point unit use of the task: :c:macro:`RTEMS_FLOATING_POINT` or + :c:macro:`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 :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL` +attributes. + +* A **local scope** is the default and can be emphasized through the use of the + :c:macro:`RTEMS_LOCAL` attribute. A local task can be only used by the node + which created it. + +* A **global scope** is established if the :c:macro:`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 +:c:macro:`RTEMS_FLOATING_POINT` and :c:macro:`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 :c:macro:`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 + :c:macro:`RTEMS_FLOATING_POINT` attribute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The ``initial_priority`` was invalid. + +:c:macro:`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 + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +:c:macro:`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 + :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration + option. + +:c:macro:`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. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed to create the task. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the non-preemption mode was not supported. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the interrupt level mode was not supported. + +.. rubric:: 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 :ref:`InterfaceRtemsTaskStart`. + +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 :ref:`CONFIGURE_STACK_CHECKER_ENABLED`. + +For control and maintenance of the task, RTEMS allocates a :term:`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. + +.. rubric:: 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 + :ref:`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 :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/task/if/construct + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_construct() + +.. _InterfaceRtemsTaskConstruct: + +rtems_task_construct() +---------------------- + +Constructs a task from the specified task configuration. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_construct( + const rtems_task_config *config, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``config`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskConfig` object. + It configures the task. + +``id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the constructed task + will be stored in this object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``config`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The task name was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The initial task priority was invalid. + +:c:macro:`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 :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`. + +:c:macro:`RTEMS_INVALID_SIZE` + The task storage area was too small to provide a task stack of the + configured minimum size, see :ref:`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. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive task object available to construct a task. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to construct a global task. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed during the task construction. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the non-preemption mode was not supported. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the interrupt level mode was not supported. + +.. rubric:: NOTES: + +In contrast to tasks created by :ref:`InterfaceRtemsTaskCreate`, 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 :ref:`InterfaceRtemsTaskCreate` and +:ref:`InterfaceRtemsTaskConstruct` together in an application. It is also not +recommended to use :ref:`InterfaceRtemsTaskConstruct` 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 :ref:`InterfaceRtemsTaskCreate`. The estimate can be adjusted +to take user-provided task storage areas into account through the +:ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE` application +configuration option. + +The :ref:`CONFIGURE_MAXIMUM_TASKS` should include tasks constructed by +:ref:`InterfaceRtemsTaskConstruct`. + +.. rubric:: 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 + :ref:`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 :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/task/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_ident() + +.. _InterfaceRtemsTaskIdent: + +rtems_task_ident() +------------------ + +Identifies a task by the object name. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +.. rubric:: 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 :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive obtains a task identifier associated with the task name +specified in ``name``. + +A task may obtain its own identifier by specifying :c:macro:`RTEMS_WHO_AM_I` +for the name. + +The node to search is specified in ``node``. It shall be + +* a valid node number, + +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes, + +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node + only, or + +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes + except the local node. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the specified nodes. + +:c:macro:`RTEMS_INVALID_NODE` + In multiprocessing configurations, the specified node was invalid. + +.. rubric:: 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 +:c:macro:`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. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/self + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_self() +.. index:: obtain ID of caller + +.. _InterfaceRtemsTaskSelf: + +rtems_task_self() +----------------- + +Gets the task identifier of the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_id rtems_task_self( void ); + +.. rubric:: DESCRIPTION: + +This directive returns the task identifier of the calling task. + +.. rubric:: RETURN VALUES: + +Returns the task identifier of the calling task. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/start + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_start() +.. index:: starting a task + +.. _InterfaceRtemsTaskStart: + +rtems_task_start() +------------------ + +Starts the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`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. + +.. rubric:: 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 +:term:`task entry` point of the task is given in ``entry_point``. The task's +entry point argument is contained in ``argument``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``entry_point`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task was not in the dormant state. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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 +:ref:`InterfaceRtemsTaskStart` directive. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/restart + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_restart() +.. index:: restarting a task + +.. _InterfaceRtemsTaskRestart: + +rtems_task_restart() +-------------------- + +Restarts the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``argument`` + This parameter is the task entry point argument. + +.. rubric:: 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``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task never started. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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 +:ref:`InterfaceRtemsTaskStart` of the task and any ensuing calls to +:ref:`InterfaceRtemsTaskRestart` of the task. This can be beneficial in +deleting a task. Instead of deleting a task using the +:ref:`InterfaceRtemsTaskDelete` 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. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/delete + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_delete() +.. index:: delete a task + +.. _InterfaceRtemsTaskDelete: + +rtems_task_delete() +------------------- + +Deletes the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +.. rubric:: DESCRIPTION: + +This directive deletes the task, either the calling task or another task, as +specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_CALLED_FROM_ISR` + The directive was called from within interrupt context. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task termination procedure was started, however, waiting for the + terminating task would have resulted in a deadlock. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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 :term:`TCB`, and, if the task is +:c:macro:`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 (:c:macro:`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 :term:`eligible priorities <eligible priority>` 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 +:c:macro:`RTEMS_GLOBAL` attribute. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/exit + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_exit() +.. index:: deleting a task + +.. _InterfaceRtemsTaskExit: + +rtems_task_exit() +----------------- + +Deletes the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_task_exit( void ); + +.. rubric:: DESCRIPTION: + +This directive deletes the calling task. + +.. rubric:: NOTES: + +The directive is an optimized variant of the following code sequences, see also +:ref:`InterfaceRtemsTaskDelete`: + +.. code-block:: c + + #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); + } + +.. rubric:: 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 + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/suspend + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_suspend() +.. index:: suspending a task + +.. _InterfaceRtemsTaskSuspend: + +rtems_task_suspend() +-------------------- + +Suspends the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_suspend( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +.. rubric:: 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 :ref:`InterfaceRtemsTaskResume` directive for this task +and any blocked state has been removed. The :ref:`InterfaceRtemsTaskRestart` +directive will also remove the suspended state. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ALREADY_SUSPENDED` + The task was already suspended. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The requesting task can suspend itself for example by specifying +:c:macro:`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. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/resume + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_resume() +.. index:: resuming a task + +.. _InterfaceRtemsTaskResume: + +rtems_task_resume() +------------------- + +Resumes the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_resume( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. + +.. rubric:: 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. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task was not suspended. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/is-suspended + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_is_suspended() + +.. _InterfaceRtemsTaskIsSuspended: + +rtems_task_is_suspended() +------------------------- + +Checks if the task is suspended. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_is_suspended( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +.. rubric:: DESCRIPTION: + +This directive returns a status code indicating whether or not the task +specified by ``id`` is currently suspended. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The task was **not** suspended. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ALREADY_SUSPENDED` + The task was suspended. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/set-priority + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_set_priority() +.. index:: current task priority +.. index:: set task priority +.. index:: get task priority +.. index:: obtain task priority + +.. _InterfaceRtemsTaskSetPriority: + +rtems_task_set_priority() +------------------------- + +Sets the real priority or gets the current priority of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_priority( + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``new_priority`` + This parameter is the new real priority or + :c:macro:`RTEMS_CURRENT_PRIORITY` to get the current priority. + +``old_priority`` + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the current or previous + priority of the task with respect to its :term:`home scheduler` will be + stored in this object. + +.. rubric:: DESCRIPTION: + +This directive manipulates the priority of the task specified by ``id``. When +``new_priority`` is not equal to :c:macro:`RTEMS_CURRENT_PRIORITY`, the +specified task's previous priority is returned in ``old_priority``. When +``new_priority`` is :c:macro:`RTEMS_CURRENT_PRIORITY`, the specified task's +current priority is returned in ``old_priority``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The task priority specified in ``new_priority`` was invalid with respect to + the :term:`home scheduler` of the task. + +.. rubric:: 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. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/get-priority + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_get_priority() +.. index:: current task priority +.. index:: get task priority +.. index:: obtain task priority + +.. _InterfaceRtemsTaskGetPriority: + +rtems_task_get_priority() +------------------------- + +Gets the current priority of the task with respect to the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_priority( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority *priority + ); + +.. rubric:: PARAMETERS: + +``task_id`` + This parameter is the task identifier. The constant :c:macro:`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 :ref:`InterfaceRtemsTaskPriority` + 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. + +.. rubric:: 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``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_NOT_DEFINED` + The task had no priority with respect to the scheduler. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/mode + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_mode() +.. index:: current task mode +.. index:: set task mode +.. index:: get task mode +.. index:: set task preemption mode +.. index:: get task preemption mode +.. index:: obtain task mode + +.. _InterfaceRtemsTaskMode: + +rtems_task_mode() +----------------- + +Gets and optionally sets the mode of the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_mode( + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set + ); + +.. rubric:: PARAMETERS: + +``mode_set`` + This parameter is the mode set to apply to the calling task. When ``mask`` + is set to :c:macro:`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 + :c:macro:`RTEMS_CURRENT_MODE`, the mode of the calling task is not changed. + +``previous_mode_set`` + This parameter is the pointer to an :c:type:`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. + +.. rubric:: 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 :c:macro:`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 +:c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode set defines + +* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or + :c:macro:`RTEMS_NO_PREEMPT`, + +* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or + :c:macro:`RTEMS_NO_TIMESLICE` (default), + +* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default) + or :c:macro:`RTEMS_NO_ASR`, + +* the interrupt level of the task: :c:func:`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 :c:macro:`RTEMS_PREEMPT_MASK` is set in ``mask``, the **preemption +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_PREEMPT` mode constant in ``mode_set`` + and + +* disabled by using the :c:macro:`RTEMS_NO_PREEMPT` mode constant in + ``mode_set``. + +When the :c:macro:`RTEMS_TIMESLICE_MASK` is set in ``mask``, the **timeslicing +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_TIMESLICE` mode constant in ``mode_set`` + and + +* disabled by using the :c:macro:`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 :c:macro:`RTEMS_ASR_MASK` is set in ``mask``, the **ASR processing +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_ASR` mode constant in ``mode_set`` and + +* disabled by using the :c:macro:`RTEMS_NO_ASR` mode constant in ``mode_set``. + +When the :c:macro:`RTEMS_INTERRUPT_MASK` is set in ``mask``, **interrupts** of +the calling task are + +* enabled by using the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a value + of zero (0) in ``mode_set`` and + +* disabled up to the specified level by using the + :c:func:`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. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:macro:`RTEMS_NO_PREEMPT` was set in ``mode_set`` and setting the + preemption mode was requested by :c:macro:`RTEMS_PREEMPT_MASK` in ``mask`` + and the system configuration had no implementation for this mode. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:func:`RTEMS_INTERRUPT_LEVEL` was set to a positive level in + ``mode_set`` and setting the interrupt level was requested by + :c:macro:`RTEMS_INTERRUPT_MASK` in ``mask`` and the system configuration + had no implementation for this mode. + +.. rubric:: 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 + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/wake-after + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_wake_after() +.. index:: delay a task for a count of clock ticks +.. index:: wake up after a count of clock ticks + +.. _InterfaceRtemsTaskWakeAfter: + +rtems_task_wake_after() +----------------------- + +Wakes up after a count of :term:`clock ticks <clock tick>` have occurred or +yields the processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_wake_after( rtems_interval ticks ); + +.. rubric:: PARAMETERS: + +``ticks`` + This parameter is the count of :term:`clock ticks <clock tick>` to delay + the task or :c:macro:`RTEMS_YIELD_PROCESSOR` to yield the processor. + +.. rubric:: DESCRIPTION: + +This directive blocks the calling task for the specified ``ticks`` count of +clock ticks if the value is not equal to :c:macro:`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 +:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +.. rubric:: NOTES: + +Setting the system date and time with the :ref:`InterfaceRtemsClockSet` +directive and similar directives which set :term:`CLOCK_REALTIME` have no +effect on a :ref:`InterfaceRtemsTaskWakeAfter` 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 (:term:`CLOCK_REALTIME` or :term:`CLOCK_MONOTONIC`) instead of clock +ticks should make use of `clock_nanosleep() +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_nanosleep.html>`_. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive requires a :term:`Clock Driver`. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/wake-when + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_wake_when() +.. index:: delay a task until a wall time +.. index:: wake up at a wall time + +.. _InterfaceRtemsTaskWakeWhen: + +rtems_task_wake_when() +---------------------- + +Wakes up when specified. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer ); + +.. rubric:: PARAMETERS: + +``time_buffer`` + This parameter is the date and time to wake up. + +.. rubric:: 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. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_NOT_DEFINED` + The system date and time was not set. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day was invalid. + +.. rubric:: NOTES: + +The ticks portion of ``time_buffer`` structure is ignored. The timing +granularity of this directive is a second. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive requires a :term:`Clock Driver`. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/get-scheduler + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_get_scheduler() + +.. _InterfaceRtemsTaskGetScheduler: + +rtems_task_get_scheduler() +-------------------------- + +Gets the home scheduler of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_scheduler( + rtems_id task_id, + rtems_id *scheduler_id + ); + +.. rubric:: PARAMETERS: + +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``scheduler_id`` + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the :term:`home + scheduler` of the task will be stored in this object. + +.. rubric:: DESCRIPTION: + +This directive returns the identifier of the :term:`home scheduler` of the task +specified by ``task_id`` in ``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``scheduler_id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/set-scheduler + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_set_scheduler() + +.. _InterfaceRtemsTaskSetScheduler: + +rtems_task_set_scheduler() +-------------------------- + +Sets the home scheduler for the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_scheduler( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority priority + ); + +.. rubric:: PARAMETERS: + +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``scheduler_id`` + This parameter is the scheduler identifier of the new :term:`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``. + +.. rubric:: DESCRIPTION: + +This directive sets the :term:`home scheduler` to the scheduler specified by +``scheduler_id`` for the task specified by ``task_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The :term:`task priority` specified by ``priority`` was invalid with + respect to the scheduler specified by ``scheduler_id``. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` was enqueued on a :term:`wait queue`. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` had a :term:`current priority` which + consisted of more than the :term:`real priority`. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` had a :term:`helping scheduler`. + +:c:macro:`RTEMS_RESOURCE_IN_USE` + The task specified by ``task_id`` was pinned. + +:c:macro:`RTEMS_UNSATISFIED` + The scheduler specified by ``scheduler_id`` owned no processor. + +:c:macro:`RTEMS_UNSATISFIED` + The scheduler specified by ``scheduler_id`` did not support the affinity + set of the task specified by ``task_id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/get-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_get_affinity() + +.. _InterfaceRtemsTaskGetAffinity: + +rtems_task_get_affinity() +------------------------- + +Gets the processor affinity of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_affinity( + rtems_id id, + size_t cpusetsize, + cpu_set_t *cpuset + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`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 :c:type:`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. + +.. rubric:: DESCRIPTION: + +This directive returns the processor affinity of the task in ``cpuset`` of the +task specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_SIZE` + The size specified by ``cpusetsize`` of the processor set was too small for + the processor affinity set of the task. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/set-affinity + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_set_affinity() + +.. _InterfaceRtemsTaskSetAffinity: + +rtems_task_set_affinity() +------------------------- + +Sets the processor affinity of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_affinity( + rtems_id id, + size_t cpusetsize, + const cpu_set_t *cpuset + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`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 :c:type:`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. + +.. rubric:: DESCRIPTION: + +This directive sets the processor affinity of the task specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_NUMBER` + The referenced processor set was not a valid new processor affinity set for + the task. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/iterate + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_iterate() + +.. _InterfaceRtemsTaskIterate: + +rtems_task_iterate() +-------------------- + +Iterates over all tasks and invokes the visitor routine for each task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_task_iterate( rtems_task_visitor visitor, void *arg ); + +.. rubric:: 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. + +.. rubric:: 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 :term:`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. + +.. rubric:: 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. + +.. rubric:: 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. + +.. Generated from spec:/rtems/task/if/storage-size + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_TASK_STORAGE_SIZE() + +.. _InterfaceRTEMSTASKSTORAGESIZE: + +RTEMS_TASK_STORAGE_SIZE() +------------------------- + +Gets the recommended task storage area size for the size and task attributes. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t RTEMS_TASK_STORAGE_SIZE( size_t size, rtems_attribute attributes ); + +.. rubric:: 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. + +.. rubric:: RETURN VALUES: + +Returns the recommended task storage area size calculated from the input +parameters. diff --git a/c-user/task/index.rst b/c-user/task/index.rst new file mode 100644 index 0000000..f5e8a64 --- /dev/null +++ b/c-user/task/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. index:: tasks + +.. _RTEMSAPIClassicTasks: + +Task Manager +************ + +.. toctree:: + + introduction + background + operations + directives + deprecated-directives + removed-directives diff --git a/c-user/task/introduction.rst b/c-user/task/introduction.rst new file mode 100644 index 0000000..f174b42 --- /dev/null +++ b/c-user/task/introduction.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/task/if/group + +.. _TaskManagerIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/task/if/create +.. spec:/rtems/task/if/construct +.. spec:/rtems/task/if/ident +.. spec:/rtems/task/if/self +.. spec:/rtems/task/if/start +.. spec:/rtems/task/if/restart +.. spec:/rtems/task/if/delete +.. spec:/rtems/task/if/exit +.. spec:/rtems/task/if/suspend +.. spec:/rtems/task/if/resume +.. spec:/rtems/task/if/is-suspended +.. spec:/rtems/task/if/set-priority +.. spec:/rtems/task/if/get-priority +.. spec:/rtems/task/if/mode +.. spec:/rtems/task/if/wake-after +.. spec:/rtems/task/if/wake-when +.. spec:/rtems/task/if/get-scheduler +.. spec:/rtems/task/if/set-scheduler +.. spec:/rtems/task/if/get-affinity +.. spec:/rtems/task/if/set-affinity +.. spec:/rtems/task/if/iterate +.. spec:/rtems/task/if/storage-size + +The Task Manager provides a comprehensive set of directives to create, delete, +and administer tasks. The directives provided by the Task Manager are: + +* :ref:`InterfaceRtemsTaskCreate` - Creates a task. + +* :ref:`InterfaceRtemsTaskConstruct` - Constructs a task from the specified + task configuration. + +* :ref:`InterfaceRtemsTaskIdent` - Identifies a task by the object name. + +* :ref:`InterfaceRtemsTaskSelf` - Gets the task identifier of the calling task. + +* :ref:`InterfaceRtemsTaskStart` - Starts the task. + +* :ref:`InterfaceRtemsTaskRestart` - Restarts the task. + +* :ref:`InterfaceRtemsTaskDelete` - Deletes the task. + +* :ref:`InterfaceRtemsTaskExit` - Deletes the calling task. + +* :ref:`InterfaceRtemsTaskSuspend` - Suspends the task. + +* :ref:`InterfaceRtemsTaskResume` - Resumes the task. + +* :ref:`InterfaceRtemsTaskIsSuspended` - Checks if the task is suspended. + +* :ref:`InterfaceRtemsTaskSetPriority` - Sets the real priority or gets the + current priority of the task. + +* :ref:`InterfaceRtemsTaskGetPriority` - Gets the current priority of the task + with respect to the scheduler. + +* :ref:`InterfaceRtemsTaskMode` - Gets and optionally sets the mode of the + calling task. + +* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after a count of :term:`clock + ticks <clock tick>` have occurred or yields the processor. + +* :ref:`InterfaceRtemsTaskWakeWhen` - Wakes up when specified. + +* :ref:`InterfaceRtemsTaskGetScheduler` - Gets the home scheduler of the task. + +* :ref:`InterfaceRtemsTaskSetScheduler` - Sets the home scheduler for the task. + +* :ref:`InterfaceRtemsTaskGetAffinity` - Gets the processor affinity of the + task. + +* :ref:`InterfaceRtemsTaskSetAffinity` - Sets the processor affinity of the + task. + +* :ref:`InterfaceRtemsTaskIterate` - Iterates over all tasks and invokes the + visitor routine for each task. + +* :ref:`InterfaceRTEMSTASKSTORAGESIZE` - Gets the recommended task storage area + size for the size and task attributes. diff --git a/c-user/task/operations.rst b/c-user/task/operations.rst new file mode 100644 index 0000000..438eea5 --- /dev/null +++ b/c-user/task/operations.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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``. + +.. code-block:: c + + #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. + +.. index:: rtems_task_get_note() +.. index:: rtems_task_set_note() + +Transition Advice for Removed Notepads +--------------------------------------- + +Task notepads and the associated directives :ref:`rtems_task_get_note` and +:ref:`rtems_task_set_note` 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. + +.. index:: rtems_task_variable_add() +.. index:: rtems_task_variable_get() +.. index:: rtems_task_variable_delete() + +Transition Advice for Removed Task Variables +--------------------------------------------- + +Task notepads and the associated directives :ref:`rtems_task_variable_add`, +:ref:`rtems_task_variable_get` and :ref:`rtems_task_variable_delete` 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 :title:`RTEMS CPU +Architecture Supplement`. diff --git a/c-user/task/removed-directives.rst b/c-user/task/removed-directives.rst new file mode 100644 index 0000000..677e810 --- /dev/null +++ b/c-user/task/removed-directives.rst @@ -0,0 +1,283 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Removed Directives +================== + +.. raw:: latex + + \clearpage + +.. index:: get task notepad entry +.. index:: rtems_task_get_note() + +.. _rtems_task_get_note: + +TASK_GET_NOTE - Get task notepad entry +-------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_get_note( + rtems_id id, + uint32_t notepad, + uint32_t *note + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``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. + +.. raw:: latex + + \clearpage + +.. index:: set task notepad entry +.. index:: rtems_task_set_note() + +.. _rtems_task_set_note: + +TASK_SET_NOTE - Set task notepad entry +-------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_set_note( + rtems_id id, + uint32_t notepad, + uint32_t note + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``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. + +.. raw:: latex + + \clearpage + +.. index:: per-task variable +.. index:: task private variable +.. index:: task private data +.. index:: rtems_task_variable_add() + +.. _rtems_task_variable_add: + +TASK_VARIABLE_ADD - Associate per task variable +----------------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_add( + rtems_id tid, + void **task_variable, + void (*dtor)(void *) + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``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. + +.. raw:: latex + + \clearpage + +.. index:: get per-task variable +.. index:: obtain per-task variable +.. index:: rtems_task_variable_get() + +.. _rtems_task_variable_get: + +TASK_VARIABLE_GET - Obtain value of a per task variable +------------------------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_get( + rtems_id tid, + void **task_variable, + void **task_variable_value + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``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. + +.. raw:: latex + + \clearpage + +.. index:: per-task variable +.. index:: task private variable +.. index:: task private data +.. index:: rtems_task_variable_delete() + +.. _rtems_task_variable_delete: + +TASK_VARIABLE_DELETE - Remove per task variable +----------------------------------------------- + +.. warning:: + + This directive was removed in RTEMS 5.1. + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_delete( + rtems_id id, + void **task_variable + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``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. |