From ccb384b6233c3a31ade96b419026dc9049ad9c5b Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 20 Aug 2020 10:13:23 +0200 Subject: c-user: Split up task manager This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993. --- c-user/index.rst | 2 +- c-user/task/background.rst | 390 ++++++++ c-user/task/directives.rst | 1454 +++++++++++++++++++++++++++++ c-user/task/index.rst | 15 + c-user/task/introduction.rst | 50 + c-user/task/operations.rst | 192 ++++ c-user/task_manager.rst | 2079 ------------------------------------------ 7 files changed, 2102 insertions(+), 2080 deletions(-) create mode 100644 c-user/task/background.rst create mode 100644 c-user/task/directives.rst create mode 100644 c-user/task/index.rst create mode 100644 c-user/task/introduction.rst create mode 100644 c-user/task/operations.rst delete mode 100644 c-user/task_manager.rst diff --git a/c-user/index.rst b/c-user/index.rst index 3628634..344b791 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -30,7 +30,7 @@ RTEMS Classic API Guide (|version|). rtems_data_types scheduling_concepts initialization - task_manager + task/index interrupt/index clock/index timer_manager diff --git a/c-user/task/background.rst b/c-user/task/background.rst new file mode 100644 index 0000000..a55f743 --- /dev/null +++ b/c-user/task/background.rst @@ -0,0 +1,390 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. 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() `. The task name can be obtained +with the `pthread_getname_np() +`_ function. +Optionally, a new task name may be set with the `pthread_setname_np() +`_ function. +The maximum size of a task name is defined by the application configuration +option :ref:`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 + +Task Priority +------------- + +A task's priority determines its importance in relation to the other tasks +executing on the same processor. RTEMS supports 255 levels of priority ranging +from 1 to 255. The data type ``rtems_task_priority`` is used to store task +priorities. + +Tasks of numerically smaller priority values are more important tasks than +tasks of numerically larger priority values. For example, a task at priority +level 5 is of higher privilege than a task at priority level 10. There is no +limit to the number of tasks assigned to the same priority. + +Each task has a priority associated with it at all times. The initial value of +this priority is assigned at task creation time. The priority of a task may be +changed at any subsequent time. + +Priorities are used by the scheduler to determine which ready task will be +allowed to execute. In general, the higher the logical priority of a task, the +more likely it is to receive processor execution time. + +.. 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 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/directives.rst b/c-user/task/directives.rst new file mode 100644 index 0000000..b5574e9 --- /dev/null +++ b/c-user/task/directives.rst @@ -0,0 +1,1454 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Directives +========== + +This section details the task manager's directives. A subsection is dedicated +to each of this manager's directives and describes the calling sequence, +related constants, usage, and status codes. + +.. raw:: latex + + \clearpage + +.. index:: create a task +.. index:: rtems_task_create + +.. _rtems_task_create: + +TASK_CREATE - Create a task +--------------------------- + +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 + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task created successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - invalid task name + * - ``RTEMS_INVALID_PRIORITY`` + - invalid task priority + * - ``RTEMS_TOO_MANY`` + - too many tasks created + * - ``RTEMS_UNSATISFIED`` + - not enough memory for stack/FP context + * - ``RTEMS_UNSATISFIED`` + - non-preemption mode not supported on SMP system + * - ``RTEMS_UNSATISFIED`` + - interrupt level mode not supported on SMP system + * - ``RTEMS_TOO_MANY`` + - too many global objects + +DESCRIPTION: + This directive creates a task which resides on the local node. It + allocates and initializes a TCB, a stack, and an optional floating point + context area. The mode parameter contains values which sets the task's + initial execution mode. The ``RTEMS_FLOATING_POINT`` attribute should be + specified if the created task is to use a numeric coprocessor. For + performance reasons, it is recommended that tasks not using the numeric + coprocessor should specify the ``RTEMS_NO_FLOATING_POINT`` attribute. If + the ``RTEMS_GLOBAL`` attribute is specified, the task can be accessed from + remote nodes. The task id, returned in id, is used in other task related + directives to access the task. When created, a task is placed in the + dormant state and can only be made ready to execute using the directive + ``rtems_task_start``. + +NOTES: + This directive may cause the calling task to be preempted. + + The scheduler of the new task is the scheduler of the executing task at + some point during the task creation. The specified task priority must be + valid for the selected scheduler. + + The task processor affinity is initialized to the set of online processors. + + If the requested stack size is less than the configured minimum stack size, + then RTEMS will use the configured minimum as the stack size for this task. + In addition to being able to specify the task stack size as a integer, + there are two constants which may be specified: + + ``RTEMS_MINIMUM_STACK_SIZE`` + The minimum stack size *RECOMMENDED* for use on this processor. This + value is selected by the RTEMS developers conservatively to minimize the + risk of blown stacks for most user applications. Using this constant + when specifying the task stack size, indicates that the stack size will + be at least ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user + configured minimum stack size is larger than the recommended minimum, + then it will be used. + + ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE`` + Indicates this task is to be created with a stack size of the minimum + stack size that was configured by the application. If not explicitly + configured by the application, the default configured minimum stack size + is the processor dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since + this uses the configured minimum stack size value, you may get a stack + size that is smaller or larger than the recommended minimum. This can be + used to provide large stacks for all tasks on complex applications or + small stacks on applications that are trying to conserve memory. + + Application developers should consider the stack usage of the device + drivers when calculating the stack size required for tasks which utilize + the driver. + + The following task attribute constants are defined by RTEMS: + + .. 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 + + The following task mode constants are defined by RTEMS: + + .. 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 interrupt level portion of the task execution mode supports a maximum + of 256 interrupt levels. These levels are mapped onto the interrupt + levels actually supported by the target processor in a processor dependent + fashion. + + Tasks should not be made global unless remote tasks must interact with + them. This avoids the system overhead incurred by the creation of a + global task. When a global task is created, the task's name and id must + be transmitted to every node in the system for insertion in the local copy + of the global object table. + + The total number of global objects, including tasks, is limited by the + maximum_global_objects field in the Configuration Table. + +.. raw:: latex + + \clearpage + +.. index:: get ID of a task +.. index:: rtems_task_ident + +.. _rtems_task_ident: + +TASK_IDENT - Get ID of a task +----------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - invalid task name + * - ``RTEMS_INVALID_NODE`` + - invalid node id + +DESCRIPTION: + This directive obtains the task id associated with the task name specified + in name. A task may obtain its own id by specifying ``RTEMS_SELF`` or its + own task name in name. If the task name is not unique, then the task id + returned will match one of the tasks with that name. However, this task id + is not guaranteed to correspond to the desired task. The task id, returned + in id, is used in other task related directives to access the task. + +NOTES: + This directive will not cause the running task to be preempted. + + If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the + local node being searched first. All other nodes are searched with the + lowest numbered node searched first. + + If node is a valid node number which does not represent the local node, + then only the tasks exported by the designated node are searched. + + This directive does not generate activity on remote nodes. It accesses + only the local copy of the global object table. + +.. raw:: latex + + \clearpage + +.. index:: obtain ID of caller +.. index:: rtems_task_self + +.. _rtems_task_self: + +TASK_SELF - Obtain ID of caller +------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_id rtems_task_self(void); + +DIRECTIVE STATUS CODES: + Returns the object Id of the calling task. + +DESCRIPTION: + This directive returns the Id of the calling task. + +NOTES: + If called from an interrupt service routine, this directive will return the + Id of the interrupted task. + +.. raw:: latex + + \clearpage + +.. index:: starting a task +.. index:: rtems_task_start + +.. _rtems_task_start: + +TASK_START - Start a task +------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - ask started successfully + * - ``RTEMS_INVALID_ADDRESS`` + - invalid task entry point + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INCORRECT_STATE`` + - task not in the dormant state + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot start remote task + +DESCRIPTION: + This directive readies the task, specified by ``id``, for execution based + on the priority and execution mode specified when the task was created. + The starting address of the task is given in ``entry_point``. The task's + starting argument is contained in argument. This argument can be a single + value or used as an index into an array of parameter blocks. The type of + this numeric argument is an unsigned integer type with the property that + any valid pointer to void can be converted to this type and then converted + back to a pointer to void. The result will compare equal to the original + pointer. + +NOTES: + The calling task will be preempted if its preemption mode is enabled and + the task being started has a higher priority. + + Any actions performed on a dormant task such as suspension or change of + priority are nullified when the task is initiated via the + ``rtems_task_start`` directive. + +.. raw:: latex + + \clearpage + +.. index:: restarting a task +.. index:: rtems_task_restart + +.. _rtems_task_restart: + +TASK_RESTART - Restart a task +----------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task restarted successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_INCORRECT_STATE`` + - task never started + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot restart remote task + +DESCRIPTION: + This directive resets the task specified by id to begin execution at its + original starting address. The task's priority and execution mode are set + to the original creation values. If the task is currently blocked, RTEMS + automatically makes the task ready. A task can be restarted from any + state, except the dormant state. + + The task's starting argument is contained in argument. This argument can + be a single value or an index into an array of parameter blocks. The type + of this numeric argument is an unsigned integer type with the property that + any valid pointer to void can be converted to this type and then converted + back to a pointer to void. The result will compare equal to the original + pointer. This new argument may be used to distinguish between the initial + ``rtems_task_start`` of the task and any ensuing calls to + ``rtems_task_restart`` of the task. This can be beneficial in deleting a + task. Instead of deleting a task using the ``rtems_task_delete`` + directive, a task can delete another task by restarting that task, and + allowing that task to release resources back to RTEMS and then delete + itself. + +NOTES: + If id is ``RTEMS_SELF``, the calling task will be restarted and will not + return from this directive. + + The calling task will be preempted if its preemption mode is enabled and + the task being restarted has a higher priority. + + The task must reside on the local node, even if the task was created with + the ``RTEMS_GLOBAL`` option. + +.. raw:: latex + + \clearpage + +.. index:: deleting a task +.. index:: rtems_task_delete + +.. _rtems_task_delete: + +TASK_DELETE - Delete a task +--------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_delete( + rtems_id id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task deleted successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot restart remote task + +DESCRIPTION: + This directive deletes a task, either the calling task or another task, as + specified by id. RTEMS stops the execution of the task and reclaims the + stack memory, any allocated delay or timeout timers, the TCB, and, if the + task is ``RTEMS_FLOATING_POINT``, its floating point context area. RTEMS + does not reclaim the following resources: region segments, partition + buffers, semaphores, timers, or rate monotonic periods. + +NOTES: + A task is responsible for releasing its resources back to RTEMS before + deletion. To insure proper deallocation of resources, a task should not be + deleted unless it is unable to execute or does not hold any RTEMS + resources. If a task holds RTEMS resources, the task should be allowed to + deallocate its resources before deletion. A task can be directed to + release its resources and delete itself by restarting it with a special + argument or by sending it a message, an event, or a signal. + + Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select + another task to execute. + + When a global task is deleted, the task id must be transmitted to every + node in the system for deletion from the local copy of the global object + table. + + The task must reside on the local node, even if the task was created with + the ``RTEMS_GLOBAL`` option. + +.. raw:: latex + + \clearpage + +.. index:: deleting a task +.. index:: rtems_task_exit + +.. _rtems_task_exit: + +TASK_EXIT - Delete the calling task +----------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + void rtems_task_exit( void ) RTEMS_NO_RETURN; + +DIRECTIVE STATUS CODES: + NONE - This function will not return to the caller. + +DESCRIPTION: + This directive deletes the calling task. + +NOTES: + This directive must be called from a regular task context with enabled + interrupts, otherwise one of the fatal errors + + * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL `, or + * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT ` + + will occur. + + The ``rtems_task_exit()`` call is equivalent to the following code + sequence: + + .. code-block:: c + + pthread_detach(pthread_self()); + pthread_exit(NULL); + + See also :ref:`rtems_task_delete() `. + +.. raw:: latex + + \clearpage + +.. index:: suspending a task +.. index:: rtems_task_suspend + +.. _rtems_task_suspend: + +TASK_SUSPEND - Suspend a task +----------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_suspend( + rtems_id id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task suspended successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_ALREADY_SUSPENDED`` + - task already suspended + +DESCRIPTION: + This directive suspends the task specified by id from further execution by + placing it in the suspended state. This state is additive to any other + blocked state that the task may already be in. The task will not execute + again until another task issues the ``rtems_task_resume`` directive for + this task and any blocked state has been removed. + +NOTES: + The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id. + In this case, the task will be suspended and a successful return code will + be returned when the task is resumed. + + Suspending a global task which does not reside on the local node will + generate a request to the remote node to suspend the specified task. + + If the task specified by id is already suspended, then the + ``RTEMS_ALREADY_SUSPENDED`` status code is returned. + +.. raw:: latex + + \clearpage + +.. index:: resuming a task +.. index:: rtems_task_resume + +.. _rtems_task_resume: + +TASK_RESUME - Resume a task +--------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_resume( + rtems_id id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task resumed successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_INCORRECT_STATE`` + - task not suspended + +DESCRIPTION: + This directive removes the task specified by id from the suspended state. + If the task is in the ready state after the suspension is removed, then it + will be scheduled to run. If the task is still in a blocked state after + the suspension is removed, then it will remain in that blocked state. + +NOTES: + The running task may be preempted if its preemption mode is enabled and the + local task being resumed has a higher priority. + + Resuming a global task which does not reside on the local node will + generate a request to the remote node to resume the specified task. + + If the task specified by id is not suspended, then the + ``RTEMS_INCORRECT_STATE`` status code is returned. + +.. raw:: latex + + \clearpage + +.. index:: is task suspended +.. index:: rtems_task_is_suspended + +.. _rtems_task_is_suspended: + +TASK_IS_SUSPENDED - Determine if a task is Suspended +---------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_is_suspended( + rtems_id id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task is NOT suspended + * - ``RTEMS_ALREADY_SUSPENDED`` + - task is currently suspended + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks + +DESCRIPTION: + This directive returns a status code indicating whether or not the + specified task is currently suspended. + +NOTES: + This operation is not currently supported on remote tasks. + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_set_priority +.. index:: current task priority +.. index:: set task priority +.. index:: get task priority +.. index:: obtain task priority + +.. _rtems_task_set_priority: + +TASK_SET_PRIORITY - Set task priority +------------------------------------- + +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 + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task priority set successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid return argument pointer + * - ``RTEMS_INVALID_PRIORITY`` + - invalid task priority + +DESCRIPTION: + This directive manipulates the priority of the task specified by id. An id + of ``RTEMS_SELF`` is used to indicate the calling task. When new_priority + is not equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous + priority is returned in old_priority. When new_priority is + ``RTEMS_CURRENT_PRIORITY``, the specified task's current priority is + returned in old_priority. Valid priorities range from a high of 1 to a low + of 255. + +NOTES: + The calling task may be preempted if its preemption mode is enabled and it + lowers its own priority or raises another task's priority. + + In case the new priority equals the current priority of the task, then + nothing happens. + + Setting the priority of a global task which does not reside on the local + node will generate a request to the remote node to change the priority of + the specified task. + + If the task specified by id is currently holding any binary semaphores + which use the priority inheritance algorithm, then the task's priority + cannot be lowered immediately. If the task's priority were lowered + immediately, then priority inversion results. The requested lowering of + the task's priority will occur when the task has released all priority + inheritance binary semaphores. The task's priority can be increased + regardless of the task's use of priority inheritance binary semaphores. + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_get_priority +.. index:: current task priority +.. index:: get task priority +.. index:: obtain task priority + +.. _rtems_task_get_priority: + +TASK_GET_PRIORITY - Get task priority +------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_get_priority( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority *priority + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - Successful operation. + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - Directive is illegal on remote tasks. + * - ``RTEMS_INVALID_ADDRESS`` + - The priority parameter is NULL. + * - ``RTEMS_INVALID_ID`` + - Invalid task or scheduler identifier. + * - ``RTEMS_NOT_DEFINED`` + - The task has no priority within the specified scheduler instance. + This error is only possible in SMP configurations. + +DESCRIPTION: + This directive returns the current priority of the task specified by + :c:data:`task_id` with respect to the scheduler instance specified by + :c:data:`scheduler_id`. A task id of :c:macro:`RTEMS_SELF` is used to + indicate the calling task. + +NOTES: + The current priority reflects temporary priority adjustments due to locking + protocols, the rate-monotonic period objects on some schedulers and other + mechanisms. + +.. raw:: latex + + \clearpage + +.. 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 +.. index:: rtems_task_mode + +.. _rtems_task_mode: + +TASK_MODE - Change the current task mode +---------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_mode( + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task mode set successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``previous_mode_set`` is NULL + - not enough memory for stack/FP context + * - ``RTEMS_NOT_IMPLEMENTED`` + - non-preemption mode not supported on SMP system + * - ``RTEMS_NOT_IMPLEMENTED`` + +DESCRIPTION: + This directive manipulates the execution mode of the calling task. A + task's execution mode enables and disables preemption, timeslicing, + asynchronous signal processing, as well as specifying the current interrupt + level. To modify an execution mode, the mode class(es) to be changed must + be specified in the mask parameter and the desired mode(s) must be + specified in the mode parameter. + +NOTES: + The calling task will be preempted if it enables preemption and a higher + priority task is ready to run. + + Enabling timeslicing has no effect if preemption is disabled. For a task + to be timesliced, that task must have both preemption and timeslicing + enabled. + + A task can obtain its current execution mode, without modifying it, by + calling this directive with a mask value of ``RTEMS_CURRENT_MODE``. + + To temporarily disable the processing of a valid ASR, a task should call + this directive with the ``RTEMS_NO_ASR`` indicator specified in mode. + + The set of task mode constants and each mode's corresponding mask constant + is provided in the following table: + + .. 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 + +.. raw:: latex + + \clearpage + +.. index:: delay a task for an interval +.. index:: wake up after an interval +.. index:: rtems_task_wake_after + +.. _rtems_task_wake_after: + +TASK_WAKE_AFTER - Wake up after interval +---------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_wake_after( + rtems_interval ticks + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - always successful + +DESCRIPTION: + This directive blocks the calling task for the specified number of system + clock ticks. When the requested interval has elapsed, the task is made + ready. The clock tick directives automatically updates the delay period. + +NOTES: + Setting the system date and time with the ``rtems_clock_set`` directive has + no effect on a ``rtems_task_wake_after`` blocked task. + + A task may give up the processor and remain in the ready state by + specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks. + + The maximum timer interval that can be specified is the maximum value which + can be represented by the uint32_t type. + + A clock tick is required to support the functionality of this directive. + +.. raw:: latex + + \clearpage + +.. index:: delay a task until a wall time +.. index:: wake up at a wall time +.. index:: rtems_task_wake_when + +.. _rtems_task_wake_when: + +TASK_WAKE_WHEN - Wake up when specified +--------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_wake_when( + rtems_time_of_day *time_buffer + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - awakened at date/time successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``time_buffer`` is NULL + * - ``RTEMS_INVALID_TIME_OF_DAY`` + - invalid time buffer + * - ``RTEMS_NOT_DEFINED`` + - system date and time is not set + +DESCRIPTION: + This directive blocks a task until the date and time specified in + time_buffer. At the requested date and time, the calling task will be + unblocked and made ready to execute. + +NOTES: + The ticks portion of time_buffer structure is ignored. The timing + granularity of this directive is a second. + + A clock tick is required to support the functionality of this directive. + +.. raw:: latex + + \clearpage + +.. _rtems_task_get_scheduler: + +TASK_GET_SCHEDULER - Get scheduler of a task +-------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_get_scheduler( + rtems_id task_id, + rtems_id *scheduler_id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``scheduler_id`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + +DESCRIPTION: + Returns the scheduler identifier of a task identified by ``task_id`` in + ``scheduler_id``. + +NOTES: + None. + +.. raw:: latex + + \clearpage + +.. _rtems_task_set_scheduler: +.. _TASK_SET_SCHEDULER - Set scheduler of a task: + +TASK_SET_SCHEDULER - Set scheduler of a task +-------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_set_scheduler( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority priority + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ID`` + - invalid task or scheduler id + * - ``RTEMS_INVALID_PRIORITY`` + - invalid task priority + * - ``RTEMS_RESOURCE_IN_USE`` + - the task is in the wrong state to perform a scheduler change + * - ``RTEMS_UNSATISFIED`` + - the processor set of the scheduler is empty + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks + +DESCRIPTION: + Sets the scheduler of a task identified by ``task_id`` to the scheduler + identified by ``scheduler_id``. The scheduler of a task is initialized to + the scheduler of the task that created it. The priority of the task is set + to ``priority``. + +NOTES: + It is recommended to set the scheduler of a task before it is started or in + case it is guaranteed that the task owns no resources. Otherwise, sporadic + ``RTEMS_RESOURCE_IN_USE`` errors may occur. + +EXAMPLE: + .. code-block:: c + :linenos: + + #include + #include + + rtems_task task( rtems_task_argument arg ); + + void example( void ) + { + rtems_status_code sc; + rtems_id task_id; + rtems_id scheduler_id; + rtems_name scheduler_name; + + scheduler_name = rtems_build_name( 'W', 'O', 'R', 'K' ); + + sc = rtems_scheduler_ident( scheduler_name, &scheduler_id ); + assert( sc == RTEMS_SUCCESSFUL ); + + sc = rtems_task_create( + rtems_build_name( 'T', 'A', 'S', 'K' ), + 1, + RTEMS_MINIMUM_STACK_SIZE, + RTEMS_DEFAULT_MODES, + RTEMS_DEFAULT_ATTRIBUTES, + &task_id + ); + assert( sc == RTEMS_SUCCESSFUL ); + + sc = rtems_task_set_scheduler( task_id, scheduler_id, 2 ); + assert( sc == RTEMS_SUCCESSFUL ); + + sc = rtems_task_start( task_id, task, 0 ); + assert( sc == RTEMS_SUCCESSFUL ); + } + +.. raw:: latex + + \clearpage + +.. _rtems_task_get_affinity: + +TASK_GET_AFFINITY - Get task processor affinity +----------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_get_affinity( + rtems_id id, + size_t cpusetsize, + cpu_set_t *cpuset + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``cpuset`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - the affinity set buffer is too small for the current processor affinity + set of the task + +DESCRIPTION: + Returns the current processor affinity set of the task in ``cpuset``. A + set bit in the affinity set means that the task can execute on this + processor and a cleared bit means the opposite. + +NOTES: + The task processor affinity is initialized to the set of online processors. + +.. raw:: latex + + \clearpage + +.. _rtems_task_set_affinity: + +TASK_SET_AFFINITY - Set task processor affinity +----------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_set_affinity( + rtems_id id, + size_t cpusetsize, + const cpu_set_t *cpuset + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``cpuset`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid processor affinity set + +DESCRIPTION: + Sets the processor affinity set for the task specified by ``cpuset``. A + set bit in the affinity set means that the task can execute on this + processor and a cleared bit means the opposite. + +NOTES: + This function will not change the scheduler of the task. The intersection + of the processor affinity set and the set of processors owned by the + scheduler of the task must be non-empty. It is not an error if the + processor affinity set contains processors that are not part of the set of + processors owned by the scheduler instance of the task. A task will simply + not run under normal circumstances on these processors since the scheduler + ignores them. Some locking protocols may temporarily use processors that + are not included in the processor affinity set of the task. It is also not + an error if the processor affinity set contains processors that are not + part of the system. + + In case a scheduler without support for task affinites is used for the + task, then the task processor affinity set must contain all online + processors of the system. This prevents odd corner cases if processors are + added/removed at run-time to/from scheduler instances. + +.. raw:: latex + + \clearpage + +.. index:: iterate over all threads +.. index:: rtems_task_iterate + +.. _rtems_task_iterate: + +TASK_ITERATE - Iterate Over Tasks +--------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg ); + + void rtems_task_iterate( + rtems_task_visitor visitor, + void *arg + ); + +DIRECTIVE STATUS CODES: + NONE + +DESCRIPTION: + Iterates over all tasks in the system. This operation covers all tasks of + all APIs. The user should be careful in accessing the contents of the + thread control block :c:data:`tcb`. The visitor argument :c:data:`arg` is + passed to all invocations of :c:data:`visitor` in addition to the thread + control block. The iteration stops immediately in case the visitor + function returns true. + +NOTES: + Must be called from task context. This operation obtains and releases the + objects allocator lock. The task visitor is called while owning the objects + allocator lock. It is possible to perform blocking operations in the task + visitor, however, take care that no deadlocks via the object allocator lock + can occur. + +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. + +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. diff --git a/c-user/task/index.rst b/c-user/task/index.rst new file mode 100644 index 0000000..f4edd40 --- /dev/null +++ b/c-user/task/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + +.. index:: tasks + +Task Manager +************ + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/task/introduction.rst b/c-user/task/introduction.rst new file mode 100644 index 0000000..449b335 --- /dev/null +++ b/c-user/task/introduction.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Introduction +============ + +The task manager provides a comprehensive set of directives to create, delete, +and administer tasks. The directives provided by the task manager are: + +- :ref:`rtems_task_create` + +- :ref:`rtems_task_ident` + +- :ref:`rtems_task_self` + +- :ref:`rtems_task_start` + +- :ref:`rtems_task_restart` + +- :ref:`rtems_task_delete` + +- :ref:`rtems_task_exit` + +- :ref:`rtems_task_suspend` + +- :ref:`rtems_task_resume` + +- :ref:`rtems_task_is_suspended` + +- :ref:`rtems_task_set_priority` + +- :ref:`rtems_task_get_priority` + +- :ref:`rtems_task_mode` + +- :ref:`rtems_task_wake_after` + +- :ref:`rtems_task_wake_when` + +- :ref:`rtems_task_get_scheduler` + +- :ref:`rtems_task_set_scheduler` + +- :ref:`rtems_task_get_affinity` + +- :ref:`rtems_task_set_affinity` + +- :ref:`rtems_task_iterate` diff --git a/c-user/task/operations.rst b/c-user/task/operations.rst new file mode 100644 index 0000000..58174d6 --- /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 (http://www.embedded-brains.de) +.. 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 interval. The task is blocked until the +delay interval has elapsed, at which time the task is unblocked. A task +calling the ``rtems_task_wake_after`` directive with a delay interval of +``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready +task of equal or greater priority and remain ready to execute. + +The ``rtems_task_wake_when`` directive creates a sleep timer which allows a +task to go to sleep until a specified date and time. The calling task is +blocked until the specified date and time has occurred, at which time the task +is unblocked. + +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 + #include + + 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_manager.rst b/c-user/task_manager.rst deleted file mode 100644 index 2db8abc..0000000 --- a/c-user/task_manager.rst +++ /dev/null @@ -1,2079 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: tasks - -Task Manager -************ - -Introduction -============ - -The task manager provides a comprehensive set of directives to create, delete, -and administer tasks. The directives provided by the task manager are: - -- rtems_task_create_ - Create a task - -- rtems_task_ident_ - Get ID of a task - -- rtems_task_self_ - Obtain ID of caller - -- rtems_task_start_ - Start a task - -- rtems_task_restart_ - Restart a task - -- rtems_task_delete_ - Delete a task - -- rtems_task_exit_ - Delete the calling task - -- rtems_task_suspend_ - Suspend a task - -- rtems_task_resume_ - Resume a task - -- rtems_task_is_suspended_ - Determine if a task is suspended - -- rtems_task_set_priority_ - Set task priority - -- rtems_task_get_priority_ - Get task priority - -- rtems_task_mode_ - Change current task's mode - -- rtems_task_wake_after_ - Wake up after interval - -- rtems_task_wake_when_ - Wake up when specified - -- rtems_task_get_scheduler_ - Get scheduler of a task - -- rtems_task_set_scheduler_ - Set scheduler of a task - -- rtems_task_get_affinity_ - Get task processor affinity - -- rtems_task_set_affinity_ - Set task processor affinity - -- rtems_task_iterate_ - Iterate Over Tasks - -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() `. The task name can be obtained -with the `pthread_getname_np() -`_ function. -Optionally, a new task name may be set with the `pthread_setname_np() -`_ function. -The maximum size of a task name is defined by the application configuration -option :ref:`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 - -Task Priority -------------- - -A task's priority determines its importance in relation to the other tasks -executing on the same processor. RTEMS supports 255 levels of priority ranging -from 1 to 255. The data type ``rtems_task_priority`` is used to store task -priorities. - -Tasks of numerically smaller priority values are more important tasks than -tasks of numerically larger priority values. For example, a task at priority -level 5 is of higher privilege than a task at priority level 10. There is no -limit to the number of tasks assigned to the same priority. - -Each task has a priority associated with it at all times. The initial value of -this priority is assigned at task creation time. The priority of a task may be -changed at any subsequent time. - -Priorities are used by the scheduler to determine which ready task will be -allowed to execute. In general, the higher the logical priority of a task, the -more likely it is to receive processor execution time. - -.. 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 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. - -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 interval. The task is blocked until the -delay interval has elapsed, at which time the task is unblocked. A task -calling the ``rtems_task_wake_after`` directive with a delay interval of -``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready -task of equal or greater priority and remain ready to execute. - -The ``rtems_task_wake_when`` directive creates a sleep timer which allows a -task to go to sleep until a specified date and time. The calling task is -blocked until the specified date and time has occurred, at which time the task -is unblocked. - -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 - #include - - 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`. - -Directives -========== - -This section details the task manager's directives. A subsection is dedicated -to each of this manager's directives and describes the calling sequence, -related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a task -.. index:: rtems_task_create - -.. _rtems_task_create: - -TASK_CREATE - Create a task ---------------------------- - -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 - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task created successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - * - ``RTEMS_TOO_MANY`` - - too many tasks created - * - ``RTEMS_UNSATISFIED`` - - not enough memory for stack/FP context - * - ``RTEMS_UNSATISFIED`` - - non-preemption mode not supported on SMP system - * - ``RTEMS_UNSATISFIED`` - - interrupt level mode not supported on SMP system - * - ``RTEMS_TOO_MANY`` - - too many global objects - -DESCRIPTION: - This directive creates a task which resides on the local node. It - allocates and initializes a TCB, a stack, and an optional floating point - context area. The mode parameter contains values which sets the task's - initial execution mode. The ``RTEMS_FLOATING_POINT`` attribute should be - specified if the created task is to use a numeric coprocessor. For - performance reasons, it is recommended that tasks not using the numeric - coprocessor should specify the ``RTEMS_NO_FLOATING_POINT`` attribute. If - the ``RTEMS_GLOBAL`` attribute is specified, the task can be accessed from - remote nodes. The task id, returned in id, is used in other task related - directives to access the task. When created, a task is placed in the - dormant state and can only be made ready to execute using the directive - ``rtems_task_start``. - -NOTES: - This directive may cause the calling task to be preempted. - - The scheduler of the new task is the scheduler of the executing task at - some point during the task creation. The specified task priority must be - valid for the selected scheduler. - - The task processor affinity is initialized to the set of online processors. - - If the requested stack size is less than the configured minimum stack size, - then RTEMS will use the configured minimum as the stack size for this task. - In addition to being able to specify the task stack size as a integer, - there are two constants which may be specified: - - ``RTEMS_MINIMUM_STACK_SIZE`` - The minimum stack size *RECOMMENDED* for use on this processor. This - value is selected by the RTEMS developers conservatively to minimize the - risk of blown stacks for most user applications. Using this constant - when specifying the task stack size, indicates that the stack size will - be at least ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user - configured minimum stack size is larger than the recommended minimum, - then it will be used. - - ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE`` - Indicates this task is to be created with a stack size of the minimum - stack size that was configured by the application. If not explicitly - configured by the application, the default configured minimum stack size - is the processor dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since - this uses the configured minimum stack size value, you may get a stack - size that is smaller or larger than the recommended minimum. This can be - used to provide large stacks for all tasks on complex applications or - small stacks on applications that are trying to conserve memory. - - Application developers should consider the stack usage of the device - drivers when calculating the stack size required for tasks which utilize - the driver. - - The following task attribute constants are defined by RTEMS: - - .. 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 - - The following task mode constants are defined by RTEMS: - - .. 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 interrupt level portion of the task execution mode supports a maximum - of 256 interrupt levels. These levels are mapped onto the interrupt - levels actually supported by the target processor in a processor dependent - fashion. - - Tasks should not be made global unless remote tasks must interact with - them. This avoids the system overhead incurred by the creation of a - global task. When a global task is created, the task's name and id must - be transmitted to every node in the system for insertion in the local copy - of the global object table. - - The total number of global objects, including tasks, is limited by the - maximum_global_objects field in the Configuration Table. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a task -.. index:: rtems_task_ident - -.. _rtems_task_ident: - -TASK_IDENT - Get ID of a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_NODE`` - - invalid node id - -DESCRIPTION: - This directive obtains the task id associated with the task name specified - in name. A task may obtain its own id by specifying ``RTEMS_SELF`` or its - own task name in name. If the task name is not unique, then the task id - returned will match one of the tasks with that name. However, this task id - is not guaranteed to correspond to the desired task. The task id, returned - in id, is used in other task related directives to access the task. - -NOTES: - This directive will not cause the running task to be preempted. - - If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the - local node being searched first. All other nodes are searched with the - lowest numbered node searched first. - - If node is a valid node number which does not represent the local node, - then only the tasks exported by the designated node are searched. - - This directive does not generate activity on remote nodes. It accesses - only the local copy of the global object table. - -.. raw:: latex - - \clearpage - -.. index:: obtain ID of caller -.. index:: rtems_task_self - -.. _rtems_task_self: - -TASK_SELF - Obtain ID of caller -------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_id rtems_task_self(void); - -DIRECTIVE STATUS CODES: - Returns the object Id of the calling task. - -DESCRIPTION: - This directive returns the Id of the calling task. - -NOTES: - If called from an interrupt service routine, this directive will return the - Id of the interrupted task. - -.. raw:: latex - - \clearpage - -.. index:: starting a task -.. index:: rtems_task_start - -.. _rtems_task_start: - -TASK_START - Start a task -------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_start( - rtems_id id, - rtems_task_entry entry_point, - rtems_task_argument argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - ask started successfully - * - ``RTEMS_INVALID_ADDRESS`` - - invalid task entry point - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INCORRECT_STATE`` - - task not in the dormant state - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot start remote task - -DESCRIPTION: - This directive readies the task, specified by ``id``, for execution based - on the priority and execution mode specified when the task was created. - The starting address of the task is given in ``entry_point``. The task's - starting argument is contained in argument. This argument can be a single - value or used as an index into an array of parameter blocks. The type of - this numeric argument is an unsigned integer type with the property that - any valid pointer to void can be converted to this type and then converted - back to a pointer to void. The result will compare equal to the original - pointer. - -NOTES: - The calling task will be preempted if its preemption mode is enabled and - the task being started has a higher priority. - - Any actions performed on a dormant task such as suspension or change of - priority are nullified when the task is initiated via the - ``rtems_task_start`` directive. - -.. raw:: latex - - \clearpage - -.. index:: restarting a task -.. index:: rtems_task_restart - -.. _rtems_task_restart: - -TASK_RESTART - Restart a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_restart( - rtems_id id, - rtems_task_argument argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task restarted successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task never started - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot restart remote task - -DESCRIPTION: - This directive resets the task specified by id to begin execution at its - original starting address. The task's priority and execution mode are set - to the original creation values. If the task is currently blocked, RTEMS - automatically makes the task ready. A task can be restarted from any - state, except the dormant state. - - The task's starting argument is contained in argument. This argument can - be a single value or an index into an array of parameter blocks. The type - of this numeric argument is an unsigned integer type with the property that - any valid pointer to void can be converted to this type and then converted - back to a pointer to void. The result will compare equal to the original - pointer. This new argument may be used to distinguish between the initial - ``rtems_task_start`` of the task and any ensuing calls to - ``rtems_task_restart`` of the task. This can be beneficial in deleting a - task. Instead of deleting a task using the ``rtems_task_delete`` - directive, a task can delete another task by restarting that task, and - allowing that task to release resources back to RTEMS and then delete - itself. - -NOTES: - If id is ``RTEMS_SELF``, the calling task will be restarted and will not - return from this directive. - - The calling task will be preempted if its preemption mode is enabled and - the task being restarted has a higher priority. - - The task must reside on the local node, even if the task was created with - the ``RTEMS_GLOBAL`` option. - -.. raw:: latex - - \clearpage - -.. index:: deleting a task -.. index:: rtems_task_delete - -.. _rtems_task_delete: - -TASK_DELETE - Delete a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task deleted successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot restart remote task - -DESCRIPTION: - This directive deletes a task, either the calling task or another task, as - specified by id. RTEMS stops the execution of the task and reclaims the - stack memory, any allocated delay or timeout timers, the TCB, and, if the - task is ``RTEMS_FLOATING_POINT``, its floating point context area. RTEMS - does not reclaim the following resources: region segments, partition - buffers, semaphores, timers, or rate monotonic periods. - -NOTES: - A task is responsible for releasing its resources back to RTEMS before - deletion. To insure proper deallocation of resources, a task should not be - deleted unless it is unable to execute or does not hold any RTEMS - resources. If a task holds RTEMS resources, the task should be allowed to - deallocate its resources before deletion. A task can be directed to - release its resources and delete itself by restarting it with a special - argument or by sending it a message, an event, or a signal. - - Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select - another task to execute. - - When a global task is deleted, the task id must be transmitted to every - node in the system for deletion from the local copy of the global object - table. - - The task must reside on the local node, even if the task was created with - the ``RTEMS_GLOBAL`` option. - -.. raw:: latex - - \clearpage - -.. index:: deleting a task -.. index:: rtems_task_exit - -.. _rtems_task_exit: - -TASK_EXIT - Delete the calling task ------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_task_exit( void ) RTEMS_NO_RETURN; - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive deletes the calling task. - -NOTES: - This directive must be called from a regular task context with enabled - interrupts, otherwise one of the fatal errors - - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL `, or - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT ` - - will occur. - - The ``rtems_task_exit()`` call is equivalent to the following code - sequence: - - .. code-block:: c - - pthread_detach(pthread_self()); - pthread_exit(NULL); - - See also :ref:`rtems_task_delete() `. - -.. raw:: latex - - \clearpage - -.. index:: suspending a task -.. index:: rtems_task_suspend - -.. _rtems_task_suspend: - -TASK_SUSPEND - Suspend a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_suspend( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task suspended successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ALREADY_SUSPENDED`` - - task already suspended - -DESCRIPTION: - This directive suspends the task specified by id from further execution by - placing it in the suspended state. This state is additive to any other - blocked state that the task may already be in. The task will not execute - again until another task issues the ``rtems_task_resume`` directive for - this task and any blocked state has been removed. - -NOTES: - The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id. - In this case, the task will be suspended and a successful return code will - be returned when the task is resumed. - - Suspending a global task which does not reside on the local node will - generate a request to the remote node to suspend the specified task. - - If the task specified by id is already suspended, then the - ``RTEMS_ALREADY_SUSPENDED`` status code is returned. - -.. raw:: latex - - \clearpage - -.. index:: resuming a task -.. index:: rtems_task_resume - -.. _rtems_task_resume: - -TASK_RESUME - Resume a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_resume( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task resumed successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task not suspended - -DESCRIPTION: - This directive removes the task specified by id from the suspended state. - If the task is in the ready state after the suspension is removed, then it - will be scheduled to run. If the task is still in a blocked state after - the suspension is removed, then it will remain in that blocked state. - -NOTES: - The running task may be preempted if its preemption mode is enabled and the - local task being resumed has a higher priority. - - Resuming a global task which does not reside on the local node will - generate a request to the remote node to resume the specified task. - - If the task specified by id is not suspended, then the - ``RTEMS_INCORRECT_STATE`` status code is returned. - -.. raw:: latex - - \clearpage - -.. index:: is task suspended -.. index:: rtems_task_is_suspended - -.. _rtems_task_is_suspended: - -TASK_IS_SUSPENDED - Determine if a task is Suspended ----------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_is_suspended( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task is NOT suspended - * - ``RTEMS_ALREADY_SUSPENDED`` - - task is currently suspended - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive returns a status code indicating whether or not the - specified task is currently suspended. - -NOTES: - This operation is not currently supported on remote tasks. - -.. raw:: latex - - \clearpage - -.. index:: rtems_task_set_priority -.. index:: current task priority -.. index:: set task priority -.. index:: get task priority -.. index:: obtain task priority - -.. _rtems_task_set_priority: - -TASK_SET_PRIORITY - Set task priority -------------------------------------- - -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 - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task priority set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid return argument pointer - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - -DESCRIPTION: - This directive manipulates the priority of the task specified by id. An id - of ``RTEMS_SELF`` is used to indicate the calling task. When new_priority - is not equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous - priority is returned in old_priority. When new_priority is - ``RTEMS_CURRENT_PRIORITY``, the specified task's current priority is - returned in old_priority. Valid priorities range from a high of 1 to a low - of 255. - -NOTES: - The calling task may be preempted if its preemption mode is enabled and it - lowers its own priority or raises another task's priority. - - In case the new priority equals the current priority of the task, then - nothing happens. - - Setting the priority of a global task which does not reside on the local - node will generate a request to the remote node to change the priority of - the specified task. - - If the task specified by id is currently holding any binary semaphores - which use the priority inheritance algorithm, then the task's priority - cannot be lowered immediately. If the task's priority were lowered - immediately, then priority inversion results. The requested lowering of - the task's priority will occur when the task has released all priority - inheritance binary semaphores. The task's priority can be increased - regardless of the task's use of priority inheritance binary semaphores. - -.. raw:: latex - - \clearpage - -.. index:: rtems_task_get_priority -.. index:: current task priority -.. index:: get task priority -.. index:: obtain task priority - -.. _rtems_task_get_priority: - -TASK_GET_PRIORITY - Get task priority -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_priority( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority *priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - Directive is illegal on remote tasks. - * - ``RTEMS_INVALID_ADDRESS`` - - The priority parameter is NULL. - * - ``RTEMS_INVALID_ID`` - - Invalid task or scheduler identifier. - * - ``RTEMS_NOT_DEFINED`` - - The task has no priority within the specified scheduler instance. - This error is only possible in SMP configurations. - -DESCRIPTION: - This directive returns the current priority of the task specified by - :c:data:`task_id` with respect to the scheduler instance specified by - :c:data:`scheduler_id`. A task id of :c:macro:`RTEMS_SELF` is used to - indicate the calling task. - -NOTES: - The current priority reflects temporary priority adjustments due to locking - protocols, the rate-monotonic period objects on some schedulers and other - mechanisms. - -.. raw:: latex - - \clearpage - -.. 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 -.. index:: rtems_task_mode - -.. _rtems_task_mode: - -TASK_MODE - Change the current task mode ----------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_mode( - rtems_mode mode_set, - rtems_mode mask, - rtems_mode *previous_mode_set - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task mode set successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``previous_mode_set`` is NULL - - not enough memory for stack/FP context - * - ``RTEMS_NOT_IMPLEMENTED`` - - non-preemption mode not supported on SMP system - * - ``RTEMS_NOT_IMPLEMENTED`` - -DESCRIPTION: - This directive manipulates the execution mode of the calling task. A - task's execution mode enables and disables preemption, timeslicing, - asynchronous signal processing, as well as specifying the current interrupt - level. To modify an execution mode, the mode class(es) to be changed must - be specified in the mask parameter and the desired mode(s) must be - specified in the mode parameter. - -NOTES: - The calling task will be preempted if it enables preemption and a higher - priority task is ready to run. - - Enabling timeslicing has no effect if preemption is disabled. For a task - to be timesliced, that task must have both preemption and timeslicing - enabled. - - A task can obtain its current execution mode, without modifying it, by - calling this directive with a mask value of ``RTEMS_CURRENT_MODE``. - - To temporarily disable the processing of a valid ASR, a task should call - this directive with the ``RTEMS_NO_ASR`` indicator specified in mode. - - The set of task mode constants and each mode's corresponding mask constant - is provided in the following table: - - .. 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 - -.. raw:: latex - - \clearpage - -.. index:: delay a task for an interval -.. index:: wake up after an interval -.. index:: rtems_task_wake_after - -.. _rtems_task_wake_after: - -TASK_WAKE_AFTER - Wake up after interval ----------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_wake_after( - rtems_interval ticks - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - always successful - -DESCRIPTION: - This directive blocks the calling task for the specified number of system - clock ticks. When the requested interval has elapsed, the task is made - ready. The clock tick directives automatically updates the delay period. - -NOTES: - Setting the system date and time with the ``rtems_clock_set`` directive has - no effect on a ``rtems_task_wake_after`` blocked task. - - A task may give up the processor and remain in the ready state by - specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks. - - The maximum timer interval that can be specified is the maximum value which - can be represented by the uint32_t type. - - A clock tick is required to support the functionality of this directive. - -.. raw:: latex - - \clearpage - -.. index:: delay a task until a wall time -.. index:: wake up at a wall time -.. index:: rtems_task_wake_when - -.. _rtems_task_wake_when: - -TASK_WAKE_WHEN - Wake up when specified ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_wake_when( - rtems_time_of_day *time_buffer - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - awakened at date/time successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL - * - ``RTEMS_INVALID_TIME_OF_DAY`` - - invalid time buffer - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - -DESCRIPTION: - This directive blocks a task until the date and time specified in - time_buffer. At the requested date and time, the calling task will be - unblocked and made ready to execute. - -NOTES: - The ticks portion of time_buffer structure is ignored. The timing - granularity of this directive is a second. - - A clock tick is required to support the functionality of this directive. - -.. raw:: latex - - \clearpage - -.. _rtems_task_get_scheduler: - -TASK_GET_SCHEDULER - Get scheduler of a task --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_scheduler( - rtems_id task_id, - rtems_id *scheduler_id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``scheduler_id`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - -DESCRIPTION: - Returns the scheduler identifier of a task identified by ``task_id`` in - ``scheduler_id``. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_task_set_scheduler: -.. _TASK_SET_SCHEDULER - Set scheduler of a task: - -TASK_SET_SCHEDULER - Set scheduler of a task --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_scheduler( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ID`` - - invalid task or scheduler id - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - * - ``RTEMS_RESOURCE_IN_USE`` - - the task is in the wrong state to perform a scheduler change - * - ``RTEMS_UNSATISFIED`` - - the processor set of the scheduler is empty - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - Sets the scheduler of a task identified by ``task_id`` to the scheduler - identified by ``scheduler_id``. The scheduler of a task is initialized to - the scheduler of the task that created it. The priority of the task is set - to ``priority``. - -NOTES: - It is recommended to set the scheduler of a task before it is started or in - case it is guaranteed that the task owns no resources. Otherwise, sporadic - ``RTEMS_RESOURCE_IN_USE`` errors may occur. - -EXAMPLE: - .. code-block:: c - :linenos: - - #include - #include - - rtems_task task( rtems_task_argument arg ); - - void example( void ) - { - rtems_status_code sc; - rtems_id task_id; - rtems_id scheduler_id; - rtems_name scheduler_name; - - scheduler_name = rtems_build_name( 'W', 'O', 'R', 'K' ); - - sc = rtems_scheduler_ident( scheduler_name, &scheduler_id ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_create( - rtems_build_name( 'T', 'A', 'S', 'K' ), - 1, - RTEMS_MINIMUM_STACK_SIZE, - RTEMS_DEFAULT_MODES, - RTEMS_DEFAULT_ATTRIBUTES, - &task_id - ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_set_scheduler( task_id, scheduler_id, 2 ); - assert( sc == RTEMS_SUCCESSFUL ); - - sc = rtems_task_start( task_id, task, 0 ); - assert( sc == RTEMS_SUCCESSFUL ); - } - -.. raw:: latex - - \clearpage - -.. _rtems_task_get_affinity: - -TASK_GET_AFFINITY - Get task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_affinity( - rtems_id id, - size_t cpusetsize, - cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - the affinity set buffer is too small for the current processor affinity - set of the task - -DESCRIPTION: - Returns the current processor affinity set of the task in ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - The task processor affinity is initialized to the set of online processors. - -.. raw:: latex - - \clearpage - -.. _rtems_task_set_affinity: - -TASK_SET_AFFINITY - Set task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_affinity( - rtems_id id, - size_t cpusetsize, - const cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid processor affinity set - -DESCRIPTION: - Sets the processor affinity set for the task specified by ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - This function will not change the scheduler of the task. The intersection - of the processor affinity set and the set of processors owned by the - scheduler of the task must be non-empty. It is not an error if the - processor affinity set contains processors that are not part of the set of - processors owned by the scheduler instance of the task. A task will simply - not run under normal circumstances on these processors since the scheduler - ignores them. Some locking protocols may temporarily use processors that - are not included in the processor affinity set of the task. It is also not - an error if the processor affinity set contains processors that are not - part of the system. - - In case a scheduler without support for task affinites is used for the - task, then the task processor affinity set must contain all online - processors of the system. This prevents odd corner cases if processors are - added/removed at run-time to/from scheduler instances. - -.. raw:: latex - - \clearpage - -.. index:: iterate over all threads -.. index:: rtems_task_iterate - -.. _rtems_task_iterate: - -TASK_ITERATE - Iterate Over Tasks ---------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg ); - - void rtems_task_iterate( - rtems_task_visitor visitor, - void *arg - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - Iterates over all tasks in the system. This operation covers all tasks of - all APIs. The user should be careful in accessing the contents of the - thread control block :c:data:`tcb`. The visitor argument :c:data:`arg` is - passed to all invocations of :c:data:`visitor` in addition to the thread - control block. The iteration stops immediately in case the visitor - function returns true. - -NOTES: - Must be called from task context. This operation obtains and releases the - objects allocator lock. The task visitor is called while owning the objects - allocator lock. It is possible to perform blocking operations in the task - visitor, however, take care that no deadlocks via the object allocator lock - can occur. - -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. - -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. -- cgit v1.2.3