diff options
| -rw-r--r-- | c-user/fatal-error/background.rst | 2 | ||||
| -rw-r--r-- | c-user/task/directives.rst | 2842 | ||||
| -rw-r--r-- | c-user/task/introduction.rst | 104 |
3 files changed, 1761 insertions, 1187 deletions
diff --git a/c-user/fatal-error/background.rst b/c-user/fatal-error/background.rst index 571da10..6932846 100644 --- a/c-user/fatal-error/background.rst +++ b/c-user/fatal-error/background.rst @@ -44,6 +44,8 @@ a register), and halt the processor. The precise actions of the RTEMS fatal error are discussed in the Default Fatal Error Processing chapter of the Applications Supplement document for a specific target processor. +.. _FatalErrorSources: + Fatal Sources ------------- diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst index b5574e9..2bfb8af 100644 --- a/c-user/task/directives.rst +++ b/c-user/task/directives.rst @@ -1,1454 +1,1970 @@ .. 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) +.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _TaskManagerDirectives: Directives ========== -This section details the 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. +This section details the directives of the Task Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/task/if/create .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_create() .. 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. + +.. _InterfaceRtemsTaskCreate: + +rtems_task_create() +------------------- + +Creates a task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_create( + rtems_name name, + rtems_task_priority initial_priority, + size_t stack_size, + rtems_mode initial_modes, + rtems_attribute attribute_set, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the object name of the task. + +``initial_priority`` + This parameter is the initial task priority. + +``stack_size`` + This parameter is the task stack size in bytes. + +``initial_modes`` + This parameter is the initial mode set of the task. + +``attribute_set`` + This parameter is the attribute set of the task. + +``id`` + This parameter is the pointer to an object identifier variable. When the + directive call is successful, the identifier of the created task will be + stored in this variable. + +.. rubric:: DESCRIPTION: + +This directive creates a task which resides on the local node. The task has +the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the task +with other task related directives. + +The **initial priority** of the task is specified in ``initial_priority``. The +scheduler of the created task is the scheduler of the calling task at some +point during the task creation. The initial task priority specified in +``initial_priority`` shall be valid for this scheduler. + +The **stack size** of the task is specified in ``stack_size``. If the +requested stack size is less than the configured minimum stack size, then RTEMS +will use the configured minimum as the stack size for this task. The +configured minimum stack size is defined by the +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` application configuration option. In +addition to being able to specify the task stack size as a integer, there are +two constants which may be specified: + +* The :c:macro:`RTEMS_MINIMUM_STACK_SIZE` constant can be specified to use the + **recommended minimum stack size** for the target processor. This value is + selected by the RTEMS maintainers conservatively to minimize the risk of + blown stacks for most user applications. Using this constant when specifying + the task stack size, indicates that the stack size will be at least + :c:macro:`RTEMS_MINIMUM_STACK_SIZE` bytes in size. If the user configured + minimum stack size is larger than the recommended minimum, then it will be + used. + +* The :c:macro:`RTEMS_CONFIGURED_MINIMUM_STACK_SIZE` constant can be specified + to use the minimum stack size that was configured by the application. If not + explicitly configured by the application, the default configured minimum + stack size is the target processor dependent value + :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. Since this uses the configured minimum + stack size value, you may get a stack size that is smaller or larger than the + recommended minimum. This can be used to provide large stacks for all tasks + on complex applications or small stacks on applications that are trying to + conserve memory. + +The **initial mode set** specified in ``initial_modes`` is built through a +*bitwise or* of the mode constants described below. Not all combinations of +modes are allowed. Some modes are mutually exclusive. If mutually exclusive +modes are combined, the behaviour is undefined. Default task modes can be +selected by using the :c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode +set defines + +* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or + :c:macro:`RTEMS_NO_PREEMPT`, + +* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or + :c:macro:`RTEMS_NO_TIMESLICE` (default), + +* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default) + or :c:macro:`RTEMS_NO_ASR`, + +* the interrupt level of the task: :c:func:`RTEMS_INTERRUPT_LEVEL` with a + default of ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled + interrupts. + +The **initial preemption mode** of the task is enabled or disabled. + +* An **enabled preemption** is the default and can be emphasized through the + use of the :c:macro:`RTEMS_PREEMPT` mode constant. + +* A **disabled preemption** is set by the :c:macro:`RTEMS_NO_PREEMPT` mode + constant. + +The **initial timeslicing mode** of the task is enabled or disabled. + +* A **disabled timeslicing** is the default and can be emphasized through the + use of the :c:macro:`RTEMS_NO_TIMESLICE` mode constant. + +* An **enabled timeslicing** is set by the :c:macro:`RTEMS_TIMESLICE` mode + constant. + +The **initial ASR processing mode** of the task is enabled or disabled. + +* An **enabled ASR processing** is the default and can be emphasized through + the use of the :c:macro:`RTEMS_ASR` mode constant. + +* A **disabled ASR processing** is set by the :c:macro:`RTEMS_NO_ASR` mode + constant. + +The **initial interrupt level mode** of the task is defined by +:c:func:`RTEMS_INTERRUPT_LEVEL`. + +* Task execution with **interrupts enabled** the default and can be emphasized + through the use of the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a + value of zero (0) for the parameter. An interrupt level of zero is + associated with enabled interrupts on all target processors. + +* Task execution at a **non-zero interrupt level** can be specified by the + :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a non-zero value for the + parameter. The interrupt level portion of the task mode supports a maximum + of 256 interrupt levels. These levels are mapped onto the interrupt levels + actually supported by the target processor in a processor dependent fashion. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. The attribute set defines + +* the scope of the task: :c:macro:`RTEMS_LOCAL` (default) or + :c:macro:`RTEMS_GLOBAL` and + +* the floating-point unit use of the task: :c:macro:`RTEMS_FLOATING_POINT` or + :c:macro:`RTEMS_NO_FLOATING_POINT` (default). + +The task has a local or global **scope** in a multiprocessing network (this +attribute does not refer to SMP systems). The scope is selected by the +mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL` +attributes. + +* A **local scope** is the default and can be emphasized through the use of the + :c:macro:`RTEMS_LOCAL` attribute. A local task can be only used by the node + which created it. + +* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is + set. Setting the global attribute in a single node system has no effect.the + +The **use of the floating-point unit** is selected by the mutually exclusive +:c:macro:`RTEMS_FLOATING_POINT` and :c:macro:`RTEMS_NO_FLOATING_POINT` +attributes. On some target processors, the use of the floating-point unit can +be enabled or disabled for each task. Other target processors may have no +hardware floating-point unit or enable the use of the floating-point unit for +all tasks. Consult the *RTEMS CPU Architecture Supplement* for the details. + +* A **disabled floating-point unit** is the default and can be emphasized + through use of the :c:macro:`RTEMS_NO_FLOATING_POINT` attribute. For + performance reasons, it is recommended that tasks not using the + floating-point unit should specify this attribute. + +* An **enabled floating-point unit** is selected by the + :c:macro:`RTEMS_FLOATING_POINT` attribute. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NAME` + The ``name`` parameter was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The ``initial_priority`` was invalid. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive object available to create a task. The number of + tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to create a global task. The number of global objects available + to the application is configured through the + :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration + option. + +:c:macro:`RTEMS_UNSATISFIED` + There was not enough memory to allocate the task storage area. The task + storage area contains the task stack, the thread-local storage, and the + floating point context. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed to create the task. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the non-preemption mode was not supported. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the interrupt level mode was not supported. + +.. rubric:: NOTES: + +The task processor affinity is initialized to the set of online processors. + +When created, a task is placed in the dormant state and can only be made ready +to execute using the directive :ref:`InterfaceRtemsTaskStart`. + +Application developers should consider the stack usage of the device drivers +when calculating the stack size required for tasks which utilize the driver. +The task stack size shall account for an target processor dependent interrupt +stack frame which may be placed on the stack of the interrupted task while +servicing an interrupt. The stack checker may be used to monitor the stack +usage, see :ref:`CONFIGURE_STACK_CHECKER_ENABLED`. + +For control and maintenance of the task, RTEMS allocates a :term:`TCB` from the +local TCB free pool and initializes it. + +The TCB for a global task is allocated on the local node. Task should not be +made global unless remote tasks must interact with the task. This is to avoid +the system overhead incurred by the creation of a global task. When a global +task is created, the task's name and identifier must be transmitted to every +node in the system for insertion in the local copy of the global object table. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/task/if/construct .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_construct() + +.. _InterfaceRtemsTaskConstruct: + +rtems_task_construct() +---------------------- + +Constructs a task from the specified task configuration. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_construct( + const rtems_task_config *config, + rtems_id *id + ); + +.. rubric:: PARAMETERS: + +``config`` + This parameter is the task configuration. + +``id`` + This parameter is the pointer to an object identifier variable. When the + directive call is successful, the identifier of the constructed task will + be stored in this variable. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``config`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + The task name was invalid. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The initial task priority was invalid. + +:c:macro:`RTEMS_INVALID_SIZE` + The thread-local storage size is greater than the maximum thread-local + storage size specified in the task configuration. The thread-local storage + size is determined by the thread-local variables used by the application + and :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`. + +:c:macro:`RTEMS_INVALID_SIZE` + The task storage area was too small to provide a task stack of the + configured minimum size, see :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. The + task storage area contains the task stack, the thread-local storage, and + the floating-point context on architectures with a separate floating-point + context. + +:c:macro:`RTEMS_TOO_MANY` + There was no inactive task object available to construct a task. + +:c:macro:`RTEMS_TOO_MANY` + In multiprocessing configurations, there was no inactive global object + available to construct a global task. + +:c:macro:`RTEMS_UNSATISFIED` + One of the task create extensions failed during the task construction. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the non-preemption mode was not supported. + +:c:macro:`RTEMS_UNSATISFIED` + In SMP configurations, the interrupt level mode was not supported. + +.. rubric:: NOTES: + +In contrast to tasks created by :ref:`InterfaceRtemsTaskCreate`, the tasks +constructed by this directive use a user-provided task storage area. The task +storage area contains the task stack, the thread-local storage, and the +floating-point context on architectures with a separate floating-point context. + +This directive is intended for applications which do not want to use the RTEMS +Workspace and instead statically allocate all operating system resources. It +is not recommended to use :ref:`InterfaceRtemsTaskCreate` and +:ref:`InterfaceRtemsTaskConstruct` together in an application. It is also not +recommended to use :ref:`InterfaceRtemsTaskConstruct` for drivers or general +purpose libraries. The reason for these recommendations is that the task +configuration needs settings which can be only given with a through knowledge +of the application resources. + +An application based solely on static allocation can avoid any runtime memory +allocators. This can simplify the application architecture as well as any +analysis that may be required. + +The stack space estimate done by <rtems/confdefs.h> assumes that all tasks are +created by :ref:`InterfaceRtemsTaskCreate`. The estimate can be adjusted to +take user-provided task storage areas into account through the +:ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE` application +configuration option. + +The :ref:`CONFIGURE_MAXIMUM_TASKS` should include tasks constructed by +:ref:`InterfaceRtemsTaskConstruct`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The number of tasks available to the application is configured through the + :ref:`CONFIGURE_MAXIMUM_TASKS` application configuration option. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may allocate memory from the RTEMS + Workspace. + +* The number of global objects available to the application is configured + through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application + configuration option. + +.. Generated from spec:/rtems/task/if/ident + +.. raw:: latex + + \clearpage + +.. index:: rtems_task_ident() + +.. _InterfaceRtemsTaskIdent: + +rtems_task_ident() +------------------ -.. index:: get ID of a task -.. index:: rtems_task_ident +Identifies a task by the object name. -.. _rtems_task_ident: +.. rubric:: CALLING SEQUENCE: -TASK_IDENT - Get ID of a task ------------------------------ +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + rtems_status_code rtems_task_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); - rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); +.. rubric:: PARAMETERS: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``name`` + This parameter is the object name to look up. - * - ``RTEMS_SUCCESSFUL`` - - task identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_NODE`` - - invalid node id +``node`` + This parameter is the node or node set to search for a matching object. -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. +``id`` + This parameter is the pointer to an object identifier variable. When the + directive call is successful, the object identifier of an object with the + specified name will be stored in this variable. -NOTES: - This directive will not cause the running task to be preempted. +.. rubric:: DESCRIPTION: - 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. +This directive obtains a task identifier associated with the task name +specified in ``name``. - 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. +A task may obtain its own identifier by specifying :c:macro:`RTEMS_SELF` for +the name. - This directive does not generate activity on remote nodes. It accesses - only the local copy of the global object table. +The node to search is specified in ``node``. It shall be + +* a valid node number, + +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes, + +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node + only, or + +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes + except the local node. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_NAME` + There was no object with the specified name on the specified nodes. + +:c:macro:`RTEMS_INVALID_NODE` + In multiprocessing configurations, the specified node was invalid. + +.. rubric:: NOTES: + +If the task name is not unique, then the task identifier will match the first +task with that name in the search order. However, this task identifier is not +guaranteed to correspond to the desired task. + +The objects are searched from lowest to the highest index. If ``node`` is +:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node +being searched first. All other nodes are searched from lowest to the highest +node number. + +If node is a valid node number which does not represent the local node, then +only the tasks exported by the designated node are searched. + +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +The task identifier is used with other task related directives to access the +task. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/self .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_self() .. index:: obtain ID of caller -.. index:: rtems_task_self -.. _rtems_task_self: +.. _InterfaceRtemsTaskSelf: + +rtems_task_self() +----------------- + +Gets the task identifier of the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_id rtems_task_self( void ); + +.. rubric:: DESCRIPTION: + +This directive returns the task identifier of the calling task. + +.. rubric:: RETURN VALUES: -TASK_SELF - Obtain ID of caller -------------------------------- +Returns the task identifier of the calling task. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CONSTRAINTS: - rtems_id rtems_task_self(void); +The following constraints apply to this directive: -DIRECTIVE STATUS CODES: - Returns the object Id of the calling task. +* The directive may be called from within device driver initialization context. -DESCRIPTION: - This directive returns the Id of the calling task. +* The directive may be called from within task context. -NOTES: - If called from an interrupt service routine, this directive will return the - Id of the interrupted task. +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/start .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_start() .. index:: starting a task -.. index:: rtems_task_start -.. _rtems_task_start: +.. _InterfaceRtemsTaskStart: -TASK_START - Start a task -------------------------- +rtems_task_start() +------------------ + +Starts the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``entry_point`` + This parameter is the task entry point. + +``argument`` + This parameter is the task entry point argument. + +.. rubric:: DESCRIPTION: + +This directive readies the task, specified by ``id``, for execution based on +the priority and execution mode specified when the task was created. The entry +point of the task is given in ``entry_point``. The task's entry point argument +is contained in ``argument``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``entry_point`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task was not in the dormant state. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The type of the entry point argument is an unsigned integer type. However, the +integer type has the property that any valid pointer to ``void`` can be +converted to this type and then converted back to a pointer to ``void``. The +result will compare equal to the original pointer. The type can represent at +least 32 bits. Some applications use the entry point argument as an index into +a parameter table to get task-specific parameters. + +Any actions performed on a dormant task such as suspension or change of +priority are nullified when the task is initiated via the +:ref:`InterfaceRtemsTaskStart` directive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. -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. +.. Generated from spec:/rtems/task/if/restart .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_restart() .. 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. + +.. _InterfaceRtemsTaskRestart: + +rtems_task_restart() +-------------------- + +Restarts the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``argument`` + This parameter is the task entry point argument. + +.. rubric:: DESCRIPTION: + +This directive resets the task specified by ``id`` to begin execution at its +original entry point. The task's priority and execution mode are set to the +original creation values. If the task is currently blocked, RTEMS +automatically makes the task ready. A task can be restarted from any state, +except the dormant state. The task's entry point argument is contained in +``argument``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INCORRECT_STATE` + The task never started. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The type of the entry point argument is an unsigned integer type. However, the +integer type has the property that any valid pointer to ``void`` can be +converted to this type and then converted back to a pointer to ``void``. The +result will compare equal to the original pointer. The type can represent at +least 32 bits. Some applications use the entry point argument as an index into +a parameter table to get task-specific parameters. + +A new entry point argument may be used to distinguish between the initial +:ref:`InterfaceRtemsTaskStart` of the task and any ensuing calls to +:ref:`InterfaceRtemsTaskRestart` of the task. This can be beneficial in +deleting a task. Instead of deleting a task using the +:ref:`InterfaceRtemsTaskDelete` directive, a task can delete another task by +restarting that task, and allowing that task to release resources back to RTEMS +and then delete itself. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +.. Generated from spec:/rtems/task/if/delete .. raw:: latex - \clearpage + \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. +.. index:: rtems_task_delete() +.. index:: delete a task + +.. _InterfaceRtemsTaskDelete: + +rtems_task_delete() +------------------- + +Deletes the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_delete( rtems_id id ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +.. rubric:: DESCRIPTION: + +This directive deletes the task, either the calling task or another task, as +specified by ``id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +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 +:c:macro:`RTEMS_FLOATING_POINT`, its floating point context area. RTEMS +explicitly does not reclaim the following resources: region segments, partition +buffers, semaphores, timers, or rate monotonic periods. + +A task is responsible for releasing its resources back to RTEMS before +deletion. To insure proper deallocation of resources, a task should not be +deleted unless it is unable to execute or does not hold any RTEMS resources. If +a task holds RTEMS resources, the task should be allowed to deallocate its +resources before deletion. A task can be directed to release its resources and +delete itself by restarting it with a special argument or by sending it a +message, an event, or a signal. + +Deletion of the current task (:c:macro:`RTEMS_SELF`) will force RTEMS to select +another task to execute. + +The :term:`TCB` for the deleted task is reclaimed by RTEMS. + +When a global task is deleted, the task identifier must be transmitted to every +node in the system for deletion from the local copy of the global object table. + +The task must reside on the local node, even if the task was created with the +:c:macro:`RTEMS_GLOBAL` attribute. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +* When the directive operates on a global object, the directive sends a message + to remote nodes. This may preempt the calling task. + +* The calling task does not have to be the task that created the object. Any + local task that knows the object identifier can delete the object. + +* Where the object class corresponding to the directive is configured to use + unlimited objects, the directive may free memory to the RTEMS Workspace. + +.. Generated from spec:/rtems/task/if/exit .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_exit() .. index:: deleting a task -.. index:: rtems_task_exit -.. _rtems_task_exit: +.. _InterfaceRtemsTaskExit: + +rtems_task_exit() +----------------- + +Deletes the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c -TASK_EXIT - Delete the calling task ------------------------------------ + void rtems_task_exit( void ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: DESCRIPTION: - void rtems_task_exit( void ) RTEMS_NO_RETURN; +This directive deletes the calling task. -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. +.. rubric:: NOTES: -DESCRIPTION: - This directive deletes the calling task. +The directive is an optimized variant of the following code sequences, see also +:ref:`InterfaceRtemsTaskDelete`: -NOTES: - This directive must be called from a regular task context with enabled - interrupts, otherwise one of the fatal errors +.. code-block:: c - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`, or - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT <internal_errors>` + #include <pthread.h> + #include <rtems.h> - will occur. + void classic_delete_self( void ) + { + (void) rtems_task_delete( RTEMS_SELF ); + } - The ``rtems_task_exit()`` call is equivalent to the following code - sequence: + void posix_delete_self( void ) + { + (void) pthread_detach( pthread_self() ); + (void) pthread_exit( NULL); + } - .. code-block:: c +.. rubric:: CONSTRAINTS: - pthread_detach(pthread_self()); - pthread_exit(NULL); +The following constraints apply to this directive: - See also :ref:`rtems_task_delete() <rtems_task_delete>`. +* The directive may be called from within task context. + +* The directive will not return to the caller. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/suspend .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_suspend() .. index:: suspending a task -.. index:: rtems_task_suspend -.. _rtems_task_suspend: +.. _InterfaceRtemsTaskSuspend: + +rtems_task_suspend() +-------------------- + +Suspends the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c -TASK_SUSPEND - Suspend a task ------------------------------ + rtems_status_code rtems_task_suspend( rtems_id id ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - rtems_status_code rtems_task_suspend( - rtems_id id - ); +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: DESCRIPTION: - * - ``RTEMS_SUCCESSFUL`` - - task suspended successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ALREADY_SUSPENDED`` - - task already suspended +This directive suspends the task specified by ``id`` from further execution by +placing it in the suspended state. This state is additive to any other blocked +state that the task may already be in. The task will not execute again until +another task issues the :ref:`InterfaceRtemsTaskResume` directive for this task +and any blocked state has been removed. The :ref:`InterfaceRtemsTaskRestart` +directive will also remove the suspended state. -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. +.. rubric:: RETURN VALUES: -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. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - 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. +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. - If the task specified by id is already suspended, then the - ``RTEMS_ALREADY_SUSPENDED`` status code is returned. +:c:macro:`RTEMS_ALREADY_SUSPENDED` + The task was already suspended. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The requesting task can suspend itself for example by specifying +:c:macro:`RTEMS_SELF` as ``id``. In this case, the task will be suspended and +a successful return code will be returned when the task is resumed. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/resume .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_resume() .. index:: resuming a task -.. index:: rtems_task_resume -.. _rtems_task_resume: +.. _InterfaceRtemsTaskResume: + +rtems_task_resume() +------------------- + +Resumes the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c -TASK_RESUME - Resume a task ---------------------------- + rtems_status_code rtems_task_resume( rtems_id id ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - rtems_status_code rtems_task_resume( - rtems_id id - ); +``id`` + This parameter is the task identifier. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: DESCRIPTION: - * - ``RTEMS_SUCCESSFUL`` - - task resumed successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task not suspended +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. -DESCRIPTION: - This directive removes the task specified by id from the suspended state. - If the task is in the ready state after the suspension is removed, then it - will be scheduled to run. If the task is still in a blocked state after - the suspension is removed, then it will remain in that blocked state. +.. rubric:: RETURN VALUES: -NOTES: - The running task may be preempted if its preemption mode is enabled and the - local task being resumed has a higher priority. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - 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. +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. - If the task specified by id is not suspended, then the - ``RTEMS_INCORRECT_STATE`` status code is returned. +:c:macro:`RTEMS_INCORRECT_STATE` + The task was not suspended. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/is-suspended .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_is_suspended() + +.. _InterfaceRtemsTaskIsSuspended: + +rtems_task_is_suspended() +------------------------- + +Checks if the task is suspended. + +.. rubric:: CALLING SEQUENCE: -.. index:: is task suspended -.. index:: rtems_task_is_suspended +.. code-block:: c -.. _rtems_task_is_suspended: + rtems_status_code rtems_task_is_suspended( rtems_id id ); -TASK_IS_SUSPENDED - Determine if a task is Suspended ----------------------------------------------------- +.. rubric:: PARAMETERS: -CALLING SEQUENCE: - .. code-block:: c +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. - rtems_status_code rtems_task_is_suspended( - rtems_id id - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +This directive returns a status code indicating whether or not the task +specified by ``id`` is currently suspended. - * - ``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 +.. rubric:: RETURN VALUES: -DESCRIPTION: - This directive returns a status code indicating whether or not the - specified task is currently suspended. +:c:macro:`RTEMS_SUCCESSFUL` + The task was **not** suspended. -NOTES: - This operation is not currently supported on remote tasks. +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_ALREADY_SUSPENDED` + The task was suspended. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/set-priority .. raw:: latex - \clearpage + \clearpage -.. index:: rtems_task_set_priority +.. 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. +.. _InterfaceRtemsTaskSetPriority: + +rtems_task_set_priority() +------------------------- + +Sets the real priority or gets the current priority of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_set_priority( + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority + ); + +.. rubric:: PARAMETERS: + +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``new_priority`` + This parameter is the new real priority or + :c:macro:`RTEMS_CURRENT_PRIORITY` to get the current priority. + +``old_priority`` + This parameter is the pointer to an :c:type:`rtems_task_priority` variable. + When the directive call is successful, the current or previous priority of + the task with respect to its :term:`home scheduler` will be stored in this + variable. + +.. rubric:: DESCRIPTION: + +This directive manipulates the priority of the task specified by ``id``. When +``new_priority`` is not equal to :c:macro:`RTEMS_CURRENT_PRIORITY`, the +specified task's previous priority is returned in ``old_priority``. When +``new_priority`` is :c:macro:`RTEMS_CURRENT_PRIORITY`, the specified task's +current priority is returned in ``old_priority``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_PRIORITY` + The task priority specified in ``new_priority`` was invalid with respect to + the :term:`home scheduler` of the task. + +.. rubric:: NOTES: + +Valid priorities range from one to a maximum value which depends on the +configured scheduler. The lower the priority value the higher is the +importance of the task. + +If the task is currently holding any binary semaphores which use a locking +protocol, then the task's priority cannot be lowered immediately. If the +task's priority were lowered immediately, then this could violate properties of +the locking protocol and may result in priority inversion. The requested +lowering of the task's priority will occur when the task has released all +binary semaphores which make the task more important. The task's priority can +be increased regardless of the task's use of binary semaphores with locking +protocols. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +* When the directive operates on a remote object, the directive sends a message + to the remote node and waits for a reply. This will preempt the calling + task. + +.. Generated from spec:/rtems/task/if/get-priority .. raw:: latex - \clearpage + \clearpage -.. index:: rtems_task_get_priority +.. 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. +.. _InterfaceRtemsTaskGetPriority: + +rtems_task_get_priority() +------------------------- + +Gets the current priority of the task with respect to the scheduler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_priority( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority *priority + ); + +.. rubric:: PARAMETERS: + +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. + +``scheduler_id`` + This parameter is the scheduler identifier. + +``priority`` + This parameter is the pointer to an :c:type:`rtems_task_priority` variable. + When the directive call is successful, the current priority of the task + with respect to the specified scheduler will be stored in this variable. + +.. rubric:: DESCRIPTION: + +This directive returns the current priority in ``priority`` of the task +specified by ``task_id`` with respect to the scheduler specified by +``scheduler_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``priority`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. + +:c:macro:`RTEMS_NOT_DEFINED` + The task had no priority with respect to the scheduler. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: NOTES: + +The current priority reflects temporary priority adjustments due to locking +protocols, the rate-monotonic period objects on some schedulers, and other +mechanisms. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/mode .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_mode() .. index:: current task mode .. index:: set task mode .. index:: get task mode .. index:: set task preemption mode .. index:: get task preemption mode .. index:: obtain task mode -.. 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 + +.. _InterfaceRtemsTaskMode: + +rtems_task_mode() +----------------- + +Gets and optionally sets the mode of the calling task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_mode( + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set + ); + +.. rubric:: PARAMETERS: + +``mode_set`` + This parameter is the mode set to apply to the calling task. When ``mask`` + is set to :c:macro:`RTEMS_CURRENT_MODE`, the value of this parameter is + ignored. Only modes requested by ``mask`` are applied to the calling task. + +``mask`` + This parameter is the mode mask which specifies which modes in ``mode_set`` + are applied to the calling task. When the value is + :c:macro:`RTEMS_CURRENT_MODE`, the mode of the calling task is not changed. + +``previous_mode_set`` + This parameter is the pointer to a mode variable. When the directive call + is successful, the mode of the task before any mode changes done by the + directive call will be stored in this variable. + +.. rubric:: DESCRIPTION: + +This directive queries and optionally manipulates the execution mode of the +calling task. A task's execution mode enables and disables preemption, +timeslicing, asynchronous signal processing, as well as specifying the +interrupt level. To modify an execution mode, the mode class(es) to be changed +must be specified in the ``mask`` parameter and the desired mode(s) must be +specified in the ``mode_set`` parameter. + +A task can obtain its current execution mode, without modifying it, by calling +this directive with a ``mask`` value of :c:macro:`RTEMS_CURRENT_MODE`. + +The **mode set** specified in ``mode_set`` is built through a *bitwise or* of +the mode constants described below. Not all combinations of modes are allowed. +Some modes are mutually exclusive. If mutually exclusive modes are combined, +the behaviour is undefined. Default task modes can be selected by using the +:c:macro:`RTEMS_DEFAULT_MODES` constant. The task mode set defines + +* the preemption mode of the task: :c:macro:`RTEMS_PREEMPT` (default) or + :c:macro:`RTEMS_NO_PREEMPT`, + +* the timeslicing mode of the task: :c:macro:`RTEMS_TIMESLICE` or + :c:macro:`RTEMS_NO_TIMESLICE` (default), + +* the :term:`ASR` processing mode of the task: :c:macro:`RTEMS_ASR` (default) + or :c:macro:`RTEMS_NO_ASR`, + +* the interrupt level of the task: :c:func:`RTEMS_INTERRUPT_LEVEL` with a + default of ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled + interrupts. + +The **mode mask** specified in ``mask`` is built through a *bitwise or* of the +mode mask constants described below. + +When the :c:macro:`RTEMS_PREEMPT_MASK` is set in ``mask``, the **preemption +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_PREEMPT` mode constant in ``mode_set`` + and + +* disabled by using the :c:macro:`RTEMS_NO_PREEMPT` mode constant in + ``mode_set``. + +When the :c:macro:`RTEMS_TIMESLICE_MASK` is set in ``mask``, the **timeslicing +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_TIMESLICE` mode constant in ``mode_set`` + and + +* disabled by using the :c:macro:`RTEMS_NO_TIMESLICE` mode constant in + ``mode_set``. + +Enabling timeslicing has no effect if preemption is disabled. For a task to be +timesliced, that task must have both preemption and timeslicing enabled. + +When the :c:macro:`RTEMS_ASR_MASK` is set in ``mask``, the **ASR processing +mode** of the calling task is + +* enabled by using the :c:macro:`RTEMS_ASR` mode constant in ``mode_set`` and + +* disabled by using the :c:macro:`RTEMS_NO_ASR` mode constant in ``mode_set``. + +When the :c:macro:`RTEMS_INTERRUPT_MASK` is set in ``mask``, **interrupts** of +the calling task are + +* enabled by using the :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a value + of zero (0) in ``mode_set`` and + +* disabled up to the specified level by using the + :c:func:`RTEMS_INTERRUPT_LEVEL` mode macro with a positive value in + ``mode_set``. + +An interrupt level of zero is associated with enabled interrupts on all target +processors. The interrupt level portion of the task mode supports a maximum of +256 interrupt levels. These levels are mapped onto the interrupt levels +actually supported by the target processor in a processor dependent fashion. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:macro:`RTEMS_NO_PREEMPT` was set in ``mode_set`` and setting the + preemption mode was requested by :c:macro:`RTEMS_PREEMPT_MASK` in ``mask`` + and the system configuration had no implementation for this mode. + +:c:macro:`RTEMS_NOT_IMPLEMENTED` + The :c:func:`RTEMS_INTERRUPT_LEVEL` was set to a positive level in + ``mode_set`` and setting the interrupt level was requested by + :c:macro:`RTEMS_INTERRUPT_MASK` in ``mask`` and the system configuration + had no implementation for this mode. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* When the directive enables preemption for the calling task, another task may + preempt the calling task. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/wake-after .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_wake_after() .. index:: delay a task for an interval .. index:: wake up after an interval -.. index:: rtems_task_wake_after -.. _rtems_task_wake_after: +.. _InterfaceRtemsTaskWakeAfter: + +rtems_task_wake_after() +----------------------- -TASK_WAKE_AFTER - Wake up after interval ----------------------------------------- +Wakes up after an interval in :term:`clock ticks <clock tick>` or yields the +processor. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CALLING SEQUENCE: - rtems_status_code rtems_task_wake_after( - rtems_interval ticks - ); +.. code-block:: c -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table + rtems_status_code rtems_task_wake_after( rtems_interval ticks ); - * - ``RTEMS_SUCCESSFUL`` - - always successful +.. rubric:: PARAMETERS: -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. +``ticks`` + This parameter is the interval in :term:`clock ticks <clock tick>` to delay + the task or :c:macro:`RTEMS_YIELD_PROCESSOR` to yield the processor. -NOTES: - Setting the system date and time with the ``rtems_clock_set`` directive has - no effect on a ``rtems_task_wake_after`` blocked task. +.. rubric:: DESCRIPTION: - A task may give up the processor and remain in the ready state by - specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks. +This directive blocks the calling task for the specified ``ticks`` of clock +ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. When the +requested interval has elapsed, the task is made ready. The clock tick +directives automatically updates the delay period. The calling task may give +up the processor and remain in the ready state by specifying a value of +:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``. - The maximum timer interval that can be specified is the maximum value which - can be represented by the uint32_t type. +.. rubric:: RETURN VALUES: - A clock tick is required to support the functionality of this directive. +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +.. rubric:: NOTES: + +Setting the system date and time with the :ref:`InterfaceRtemsClockSet` +directive and similar directives which set :term:`CLOCK_REALTIME` have no +effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within task context. + +* The directive requires a :term:`Clock Driver`. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. + +.. Generated from spec:/rtems/task/if/wake-when .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_task_wake_when() .. index:: delay a task until a wall time .. index:: wake up at a wall time -.. index:: rtems_task_wake_when -.. _rtems_task_wake_when: +.. _InterfaceRtemsTaskWakeWhen: -TASK_WAKE_WHEN - Wake up when specified ---------------------------------------- +rtems_task_wake_when() +---------------------- -CALLING SEQUENCE: - .. code-block:: c +Wakes up when specified. - rtems_status_code rtems_task_wake_when( - rtems_time_of_day *time_buffer - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. code-block:: c - * - ``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 + rtems_status_code rtems_task_wake_when( rtems_time_of_day *time_buffer ); -DESCRIPTION: - This directive blocks a task until the date and time specified in - time_buffer. At the requested date and time, the calling task will be - unblocked and made ready to execute. +.. rubric:: PARAMETERS: -NOTES: - The ticks portion of time_buffer structure is ignored. The timing - granularity of this directive is a second. +``time_buffer`` + This parameter is the date and time to wake up. - A clock tick is required to support the functionality of this directive. +.. rubric:: DESCRIPTION: -.. raw:: latex +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. - \clearpage +.. rubric:: RETURN VALUES: -.. _rtems_task_get_scheduler: +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -TASK_GET_SCHEDULER - Get scheduler of a task --------------------------------------------- +:c:macro:`RTEMS_NOT_DEFINED` + The system date and time was not set. -CALLING SEQUENCE: - .. code-block:: c +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_buffer`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. - rtems_status_code rtems_task_get_scheduler( - rtems_id task_id, - rtems_id *scheduler_id - ); +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day was invalid. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: NOTES: - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``scheduler_id`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id +The ticks portion of ``time_buffer`` structure is ignored. The timing +granularity of this directive is a second. -DESCRIPTION: - Returns the scheduler identifier of a task identified by ``task_id`` in - ``scheduler_id``. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The following constraints apply to this directive: -.. raw:: latex +* The directive may be called from within task context. + +* The directive requires a :term:`Clock Driver`. + +* While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` and the fatal code + :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>` + will occur. - \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 <rtems.h> - #include <assert.h> - - 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 ); - } +.. Generated from spec:/rtems/task/if/get-scheduler .. raw:: latex - \clearpage + \clearpage -.. _rtems_task_get_affinity: +.. index:: rtems_task_get_scheduler() -TASK_GET_AFFINITY - Get task processor affinity ------------------------------------------------ +.. _InterfaceRtemsTaskGetScheduler: -CALLING SEQUENCE: - .. code-block:: c +rtems_task_get_scheduler() +-------------------------- - rtems_status_code rtems_task_get_affinity( - rtems_id id, - size_t cpusetsize, - cpu_set_t *cpuset - ); +Gets the home scheduler of the task. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: CALLING SEQUENCE: - * - ``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 +.. code-block:: c -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. + rtems_status_code rtems_task_get_scheduler( + rtems_id task_id, + rtems_id *scheduler_id + ); -NOTES: - The task processor affinity is initialized to the set of online processors. +.. rubric:: PARAMETERS: -.. raw:: latex +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. - \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. +``scheduler_id`` + This parameter is the pointer to an :c:type:`rtems_id` variable. When the + directive call is successful, the identifier of the :term:`home scheduler` + of the task will be stored in this variable. -.. raw:: latex +.. rubric:: DESCRIPTION: + +This directive returns the identifier of the :term:`home scheduler` of the task +specified by ``task_id`` in ``scheduler_id``. + +.. rubric:: RETURN VALUES: - \clearpage +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -.. index:: iterate over all threads -.. index:: rtems_task_iterate +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``scheduler_id`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -.. _rtems_task_iterate: +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. -TASK_ITERATE - Iterate Over Tasks ---------------------------------- +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CONSTRAINTS: - typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg ); +The following constraints apply to this directive: - void rtems_task_iterate( - rtems_task_visitor visitor, - void *arg - ); +* The directive may be called from within interrupt context. -DIRECTIVE STATUS CODES: - NONE +* The directive may be called from within device driver initialization context. -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. +* The directive may be called from within task context. -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. +* The directive will not cause the calling task to be preempted. -Deprecated Directives -===================== +.. Generated from spec:/rtems/task/if/set-scheduler .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_set_scheduler() + +.. _InterfaceRtemsTaskSetScheduler: + +rtems_task_set_scheduler() +-------------------------- -.. index:: rtems_iterate_over_all_threads +Sets the home scheduler for the task. -.. _rtems_iterate_over_all_threads: +.. rubric:: CALLING SEQUENCE: -ITERATE_OVER_ALL_THREADS - Iterate Over Tasks ---------------------------------------------- +.. code-block:: c -.. warning:: + rtems_status_code rtems_task_set_scheduler( + rtems_id task_id, + rtems_id scheduler_id, + rtems_task_priority priority + ); - This directive is deprecated. Its use is unsafe. Use - :ref:`rtems_task_iterate` instead. +.. rubric:: PARAMETERS: -CALLING SEQUENCE: - .. code-block:: c +``task_id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. - typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); - void rtems_iterate_over_all_threads( - rtems_per_thread_routine routine - ); +``scheduler_id`` + This parameter is the scheduler identifier of the new :term:`home + scheduler` for the task specified by ``task_id``. + +``priority`` + This parameter is the new real priority for the task with respect to the + scheduler specified by ``scheduler_id``. + +.. rubric:: DESCRIPTION: + +This directive sets the :term:`home scheduler` to the scheduler specified by +``scheduler_id`` for the task specified by ``task_id``. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ID` + There was no scheduler associated with the identifier specified by + ``scheduler_id``. -DIRECTIVE STATUS CODES: - NONE +:c:macro:`RTEMS_INVALID_PRIORITY` + There task priority specified in ``priority`` was invalid with respect to + the scheduler specified by ``scheduler_id``. -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``. +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``task_id``. - This routine is intended for use in diagnostic utilities and is not - intented for routine use in an operational system. +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. -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. +.. rubric:: CONSTRAINTS: -Removed Directives -================== +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +.. Generated from spec:/rtems/task/if/get-affinity .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_get_affinity() + +.. _InterfaceRtemsTaskGetAffinity: + +rtems_task_get_affinity() +------------------------- + +Gets the processor affinity of the task. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_task_get_affinity( + rtems_id id, + size_t cpusetsize, + cpu_set_t *cpuset + ); -.. index:: get task notepad entry -.. index:: rtems_task_get_note +.. rubric:: PARAMETERS: -.. _rtems_task_get_note: +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. -TASK_GET_NOTE - Get task notepad entry --------------------------------------- +``cpusetsize`` + This parameter is the size of the referenced processor set variable in + bytes. -.. warning:: +``cpuset`` + This parameter is the pointer to a processor set variable. When the + directive call is successful, the processor affinity set of the task will + be stored in this variable. A set bit in the processor set means that the + corresponding processor is in the processor affinity set of the task, + otherwise the bit is cleared. - This directive was removed in RTEMS 5.1. +.. rubric:: DESCRIPTION: -CALLING SEQUENCE: - .. code-block:: c +This directive returns the processor affinity of the task in ``cpuset`` of the +task specified by ``id``. - rtems_status_code rtems_task_get_note( - rtems_id id, - uint32_t notepad, - uint32_t *note - ); +.. rubric:: RETURN VALUES: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. - * - ``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 +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -DESCRIPTION: - This directive returns the note contained in the notepad location of the - task specified by id. +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. -NOTES: - This directive will not cause the running task to be preempted. +:c:macro:`RTEMS_INVALID_SIZE` + The provided processor set was too small for the processor affinity set of + the task. - If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. - The sixteen notepad locations can be accessed using the constants - ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. +.. rubric:: CONSTRAINTS: - 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. +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/set-affinity .. raw:: latex - \clearpage + \clearpage -.. index:: set task notepad entry -.. index:: rtems_task_set_note +.. index:: rtems_task_set_affinity() -.. _rtems_task_set_note: +.. _InterfaceRtemsTaskSetAffinity: -TASK_SET_NOTE - Set task notepad entry --------------------------------------- +rtems_task_set_affinity() +------------------------- -.. warning:: +Sets the processor affinity of the task. - This directive was removed in RTEMS 5.1. +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - rtems_status_code rtems_task_set_note( - rtems_id id, - uint32_t notepad, - uint32_t note - ); + 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 +.. rubric:: PARAMETERS: - * - ``RTEMS_SUCCESSFUL`` - - note set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid notepad location +``id`` + This parameter is the task identifier. The constant :c:macro:`RTEMS_SELF` + may be used to specify the calling task. -DESCRIPTION: - This directive sets the notepad entry for the task specified by id to the - value note. +``cpusetsize`` + This parameter is the size of the referenced processor set variable in + bytes. -NOTES: - If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own - notepad. +``cpuset`` + This parameter is the pointer to a processor set variable. The processor + set defines the new processor affinity set of the task. A set bit in the + processor set means that the corresponding processor shall be in the + processor affinity set of the task, otherwise the bit shall be cleared. - This directive will not cause the running task to be preempted. +.. rubric:: DESCRIPTION: - The sixteen notepad locations can be accessed using the constants - ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. +This directive sets the processor affinity of the task specified by ``id``. - 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. +.. rubric:: RETURN VALUES: -.. raw:: latex +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``cpuset`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ID` + There was no task associated with the identifier specified by ``id``. + +:c:macro:`RTEMS_INVALID_NUMBER` + The referenced processor set was not a valid new processor affinity set for + the task. + +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` + The task resided on a remote node. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within interrupt context. - \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. +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may change the processor affinity of a task. This may cause + the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/iterate .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_task_iterate() + +.. _InterfaceRtemsTaskIterate: + +rtems_task_iterate() +-------------------- + +Iterates over all tasks and invokes the visitor routine for each task. -.. index:: get per-task variable -.. index:: obtain per-task variable -.. index:: rtems_task_variable_get +.. rubric:: CALLING SEQUENCE: -.. _rtems_task_variable_get: +.. code-block:: c -TASK_VARIABLE_GET - Obtain value of a per task variable -------------------------------------------------------- + void rtems_task_iterate( rtems_task_visitor visitor, void *arg ); -.. warning:: +.. rubric:: PARAMETERS: - This directive was removed in RTEMS 5.1. +``visitor`` + This parameter is the visitor routine invoked for each task. -CALLING SEQUENCE: - .. code-block:: c +``arg`` + This parameter is the argument passed to each visitor routine invocation + during the iteration. - rtems_status_code rtems_task_variable_get( - rtems_id tid, - void **task_variable, - void **task_variable_value - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +This directive iterates over all tasks in the system. This operation covers +all tasks of all APIs. The user should be careful in accessing the contents of +the :term:`TCB`. The visitor argument ``arg`` is passed to all invocations of +``visitor`` in addition to the TCB. The iteration stops immediately in case the +visitor routine returns true. - * - ``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 +.. rubric:: NOTES: -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. +The visitor routine is invoked while owning the objects allocator lock. It is +allowed to perform blocking operations in the visitor routine, however, care +must be taken so that no deadlocks via the object allocator lock can occur. -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. +.. rubric:: CONSTRAINTS: - Per-task variables are disabled in SMP configurations and this service is - not available. +The following constraints apply to this directive: + +* The directive may be called from within device driver initialization context. + +* The directive may be called from within task context. + +* The directive may obtain and release the object allocator mutex. This may + cause the calling task to be preempted. + +.. Generated from spec:/rtems/task/if/storage-size .. raw:: latex - \clearpage + \clearpage + +.. index:: RTEMS_TASK_STORAGE_SIZE() -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data -.. index:: rtems_task_variable_delete +.. _InterfaceRTEMSTASKSTORAGESIZE: -.. _rtems_task_variable_delete: +RTEMS_TASK_STORAGE_SIZE() +------------------------- -TASK_VARIABLE_DELETE - Remove per task variable ------------------------------------------------ +Gets the recommended task storage area size for the size and task attributes. -.. warning:: +.. rubric:: CALLING SEQUENCE: - This directive was removed in RTEMS 5.1. +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + #define RTEMS_TASK_STORAGE_SIZE( size, attributes ) - rtems_status_code rtems_task_variable_delete( - rtems_id id, - void **task_variable - ); +.. rubric:: PARAMETERS: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``size`` + This parameter is the size dedicated to the task stack and thread-local + storage in bytes. - * - ``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 +``attributes`` + This parameter is the attribute set of the task using the storage area. -DESCRIPTION: - This directive removes the given location from a task's context. +.. rubric:: RETURN VALUES: -NOTES: - Per-task variables are disabled in SMP configurations and this service is - not available. +Returns the recommended task storage area size calculated from the input +parameters. diff --git a/c-user/task/introduction.rst b/c-user/task/introduction.rst index 449b335..5d6eba4 100644 --- a/c-user/task/introduction.rst +++ b/c-user/task/introduction.rst @@ -1,50 +1,106 @@ .. 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) +.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/task/if/group + +.. _TaskManagerIntroduction: Introduction ============ -The task manager provides a comprehensive set of directives to create, delete, -and administer tasks. The directives provided by the task manager are: +.. The following list was generated from: +.. spec:/rtems/task/if/create +.. spec:/rtems/task/if/construct +.. spec:/rtems/task/if/ident +.. spec:/rtems/task/if/self +.. spec:/rtems/task/if/start +.. spec:/rtems/task/if/restart +.. spec:/rtems/task/if/delete +.. spec:/rtems/task/if/exit +.. spec:/rtems/task/if/suspend +.. spec:/rtems/task/if/resume +.. spec:/rtems/task/if/is-suspended +.. spec:/rtems/task/if/set-priority +.. spec:/rtems/task/if/get-priority +.. spec:/rtems/task/if/mode +.. spec:/rtems/task/if/wake-after +.. spec:/rtems/task/if/wake-when +.. spec:/rtems/task/if/get-scheduler +.. spec:/rtems/task/if/set-scheduler +.. spec:/rtems/task/if/get-affinity +.. spec:/rtems/task/if/set-affinity +.. spec:/rtems/task/if/iterate +.. spec:/rtems/task/if/storage-size -- :ref:`rtems_task_create` +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_ident` +* :ref:`InterfaceRtemsTaskCreate` - Creates a task. -- :ref:`rtems_task_self` +* :ref:`InterfaceRtemsTaskConstruct` - Constructs a task from the specified + task configuration. -- :ref:`rtems_task_start` +* :ref:`InterfaceRtemsTaskIdent` - Identifies a task by the object name. -- :ref:`rtems_task_restart` +* :ref:`InterfaceRtemsTaskSelf` - Gets the task identifier of the calling task. -- :ref:`rtems_task_delete` +* :ref:`InterfaceRtemsTaskStart` - Starts the task. -- :ref:`rtems_task_exit` +* :ref:`InterfaceRtemsTaskRestart` - Restarts the task. -- :ref:`rtems_task_suspend` +* :ref:`InterfaceRtemsTaskDelete` - Deletes the task. -- :ref:`rtems_task_resume` +* :ref:`InterfaceRtemsTaskExit` - Deletes the calling task. -- :ref:`rtems_task_is_suspended` +* :ref:`InterfaceRtemsTaskSuspend` - Suspends the task. -- :ref:`rtems_task_set_priority` +* :ref:`InterfaceRtemsTaskResume` - Resumes the task. -- :ref:`rtems_task_get_priority` +* :ref:`InterfaceRtemsTaskIsSuspended` - Checks if the task is suspended. -- :ref:`rtems_task_mode` +* :ref:`InterfaceRtemsTaskSetPriority` - Sets the real priority or gets the + current priority of the task. -- :ref:`rtems_task_wake_after` +* :ref:`InterfaceRtemsTaskGetPriority` - Gets the current priority of the task + with respect to the scheduler. -- :ref:`rtems_task_wake_when` +* :ref:`InterfaceRtemsTaskMode` - Gets and optionally sets the mode of the + calling task. -- :ref:`rtems_task_get_scheduler` +* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after an interval in + :term:`clock ticks <clock tick>` or yields the processor. -- :ref:`rtems_task_set_scheduler` +* :ref:`InterfaceRtemsTaskWakeWhen` - Wakes up when specified. -- :ref:`rtems_task_get_affinity` +* :ref:`InterfaceRtemsTaskGetScheduler` - Gets the home scheduler of the task. -- :ref:`rtems_task_set_affinity` +* :ref:`InterfaceRtemsTaskSetScheduler` - Sets the home scheduler for the task. -- :ref:`rtems_task_iterate` +* :ref:`InterfaceRtemsTaskGetAffinity` - Gets the processor affinity of the + task. + +* :ref:`InterfaceRtemsTaskSetAffinity` - Sets the processor affinity of the + task. + +* :ref:`InterfaceRtemsTaskIterate` - Iterates over all tasks and invokes the + visitor routine for each task. + +* :ref:`InterfaceRTEMSTASKSTORAGESIZE` - Gets the recommended task storage area + size for the size and task attributes. |