diff options
Diffstat (limited to 'c-user/task_manager.rst')
| -rw-r--r-- | c-user/task_manager.rst | 1571 |
1 files changed, 782 insertions, 789 deletions
diff --git a/c-user/task_manager.rst b/c-user/task_manager.rst index f88e660..beaef3b 100644 --- a/c-user/task_manager.rst +++ b/c-user/task_manager.rst @@ -37,9 +37,9 @@ and administer tasks. The directives provided by the task manager are: - rtems_task_mode_ - Change current task's mode -- rtems_task_get_note_ - Get task notepad entry +- rtems_task_get_note_ - Get task notepad entry -- rtems_task_set_note_ - Set task notepad entry +- rtems_task_set_note_ - Set task notepad entry - rtems_task_wake_after_ - Wake up after interval @@ -590,530 +590,532 @@ This section details the task manager's directives. A subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes. +.. raw:: latex + + \clearpage + .. _rtems_task_create: TASK_CREATE - Create a task --------------------------- .. index:: create a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_create -.. 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_MP_NOT_CONFIGURED`` - - multiprocessing not configured - * - ``RTEMS_TOO_MANY`` - - too many tasks created - * - ``RTEMS_UNSATISFIED`` - - not enough memory for stack/FP context - * - ``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 will not cause the calling task to be preempted. - -Valid task priorities range from a high of 1 to a low of 255. - -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. +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_MP_NOT_CONFIGURED`` + - multiprocessing not configured + * - ``RTEMS_TOO_MANY`` + - too many tasks created + * - ``RTEMS_UNSATISFIED`` + - not enough memory for stack/FP context + * - ``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 will not cause the calling task to be preempted. + + Valid task priorities range from a high of 1 to a low of 255. + + If the requested stack size is less than the configured minimum stack size, + then RTEMS will use the configured minimum as the stack size for this task. + In addition to being able to specify the task stack size as a integer, + there are two constants which may be specified: + + ``RTEMS_MINIMUM_STACK_SIZE`` + The minimum stack size *RECOMMENDED* for use on this processor. This + value is selected by the RTEMS developers conservatively to minimize the + risk of blown stacks for most user applications. Using this constant + when specifying the task stack size, indicates that the stack size will + be at least ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user + configured minimum stack size is larger than the recommended minimum, + then it will be used. + + ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE`` + Indicates this task is to be created with a stack size of the minimum + stack size that was configured by the application. If not explicitly + configured by the application, the default configured minimum stack size + is the processor dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since + this uses the configured minimum stack size value, you may get a stack + size that is smaller or larger than the recommended minimum. This can be + used to provide large stacks for all tasks on complex applications or + small stacks on applications that are trying to conserve memory. + + Application developers should consider the stack usage of the device + drivers when calculating the stack size required for tasks which utilize + the driver. + + The following task attribute constants are defined by RTEMS: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_NO_FLOATING_POINT`` + - does not use coprocessor (default) + * - ``RTEMS_FLOATING_POINT`` + - uses numeric coprocessor + * - ``RTEMS_LOCAL`` + - local task (default) + * - ``RTEMS_GLOBAL`` + - global task + + The following task mode constants are defined by RTEMS: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_PREEMPT`` + - enable preemption (default) + * - ``RTEMS_NO_PREEMPT`` + - disable preemption + * - ``RTEMS_NO_TIMESLICE`` + - disable timeslicing (default) + * - ``RTEMS_TIMESLICE`` + - enable timeslicing + * - ``RTEMS_ASR`` + - enable ASR processing (default) + * - ``RTEMS_NO_ASR`` + - disable ASR processing + * - ``RTEMS_INTERRUPT_LEVEL(0)`` + - enable all interrupts (default) + * - ``RTEMS_INTERRUPT_LEVEL(n)`` + - execute at interrupt level ``n`` + + The interrupt level portion of the task execution mode supports a maximum + of 256 interrupt levels. These levels are mapped onto the interrupt + levels actually supported by the target processor in a processor dependent + fashion. + + Tasks should not be made global unless remote tasks must interact with + them. This avoids the system overhead incurred by the creation of a + global task. When a global task is created, the task's name and id must + be transmitted to every node in the system for insertion in the local copy + of the global object table. + + The total number of global objects, including tasks, is limited by the + maximum_global_objects field in the Configuration Table. + +.. raw:: latex + + \clearpage .. _rtems_task_ident: TASK_IDENT - Get ID of a task ----------------------------- .. index:: get ID of a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_ident -.. code-block:: c - - rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_task_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - task identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_NODE`` - - invalid node id + * - ``RTEMS_SUCCESSFUL`` + - task identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - invalid task name + * - ``RTEMS_INVALID_NODE`` + - invalid node id -**DESCRIPTION:** +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. -This directive obtains the task id associated with the task name specified in -name. A task may obtain its own id by specifying ``RTEMS_SELF`` or its own -task name in name. If the task name is not unique, then the task id returned -will match one of the tasks with that name. However, this task id is not -guaranteed to correspond to the desired task. The task id, returned in id, is -used in other task related directives to access the task. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** + 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 will not cause the running task to be preempted. + 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. -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 does not generate activity on remote nodes. It accesses + only the local copy of the global object table. -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. +.. raw:: latex -This directive does not generate activity on remote nodes. It accesses only -the local copy of the global object table. + \clearpage .. _rtems_task_self: TASK_SELF - Obtain ID of caller ------------------------------- .. index:: obtain ID of caller - -**CALLING SEQUENCE:** - .. index:: rtems_task_self -.. code-block:: c - - rtems_id rtems_task_self(void); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_id rtems_task_self(void); -Returns the object Id of the calling task. +DIRECTIVE STATUS CODES: + Returns the object Id of the calling task. -**DESCRIPTION:** +DESCRIPTION: + This directive returns the Id of the calling task. -This directive returns the Id of the calling task. +NOTES: + If called from an interrupt service routine, this directive will return the + Id of the interrupted task. -**NOTES:** +.. raw:: latex -If called from an interrupt service routine, this directive will return the Id -of the interrupted task. + \clearpage .. _rtems_task_start: TASK_START - Start a task ------------------------- .. index:: starting a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_start -.. 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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - ask started successfully + * - ``RTEMS_INVALID_ADDRESS`` + - invalid task entry point + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INCORRECT_STATE`` + - task not in the dormant state + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot start remote task + +DESCRIPTION: + This directive readies the task, specified by ``id``, for execution based + on the priority and execution mode specified when the task was created. + The starting address of the task is given in ``entry_point``. The task's + starting argument is contained in argument. This argument can be a single + value or used as an index into an array of parameter blocks. The type of + this numeric argument is an unsigned integer type with the property that + any valid pointer to void can be converted to this type and then converted + back to a pointer to void. The result will compare equal to the original + pointer. + +NOTES: + The calling task will be preempted if its preemption mode is enabled and + the task being started has a higher priority. + + Any actions performed on a dormant task such as suspension or change of + priority are nullified when the task is initiated via the + ``rtems_task_start`` directive. + +.. raw:: latex + + \clearpage .. _rtems_task_restart: TASK_RESTART - Restart a task ----------------------------- .. index:: restarting a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_restart -.. 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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task restarted successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_INCORRECT_STATE`` + - task never started + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot restart remote task + +DESCRIPTION: + This directive resets the task specified by id to begin execution at its + original starting address. The task's priority and execution mode are set + to the original creation values. If the task is currently blocked, RTEMS + automatically makes the task ready. A task can be restarted from any + state, except the dormant state. + + The task's starting argument is contained in argument. This argument can + be a single value or an index into an array of parameter blocks. The type + of this numeric argument is an unsigned integer type with the property that + any valid pointer to void can be converted to this type and then converted + back to a pointer to void. The result will compare equal to the original + pointer. This new argument may be used to distinguish between the initial + ``rtems_task_start`` of the task and any ensuing calls to + ``rtems_task_restart`` of the task. This can be beneficial in deleting a + task. Instead of deleting a task using the ``rtems_task_delete`` + directive, a task can delete another task by restarting that task, and + allowing that task to release resources back to RTEMS and then delete + itself. + +NOTES: + If id is ``RTEMS_SELF``, the calling task will be restarted and will not + return from this directive. + + The calling task will be preempted if its preemption mode is enabled and + the task being restarted has a higher priority. + + The task must reside on the local node, even if the task was created with + the ``RTEMS_GLOBAL`` option. + +.. raw:: latex + + \clearpage .. _rtems_task_delete: TASK_DELETE - Delete a task --------------------------- .. index:: deleting a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_delete -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_delete( - rtems_id id - ); + rtems_status_code rtems_task_delete( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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. -**DESCRIPTION:** +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. -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. + Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select + another task to execute. -**NOTES:** + 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. -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. + The task must reside on the local node, even if the task was created with + the ``RTEMS_GLOBAL`` option. -Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select -another task to execute. +.. raw:: latex -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. + \clearpage .. _rtems_task_suspend: TASK_SUSPEND - Suspend a task ----------------------------- .. index:: suspending a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_suspend -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_suspend( - rtems_id id - ); + rtems_status_code rtems_task_suspend( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - task suspended successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_ALREADY_SUSPENDED`` + - task already suspended - * - ``RTEMS_SUCCESSFUL`` - - task suspended successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ALREADY_SUSPENDED`` - - task already suspended +DESCRIPTION: + This directive suspends the task specified by id from further execution by + placing it in the suspended state. This state is additive to any other + blocked state that the task may already be in. The task will not execute + again until another task issues the ``rtems_task_resume`` directive for + this task and any blocked state has been removed. -**DESCRIPTION:** +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. -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. + 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. -**NOTES:** + If the task specified by id is already suspended, then the + ``RTEMS_ALREADY_SUSPENDED`` status code is returned. -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. +.. raw:: latex -Suspending a global task which does not reside on the local node will generate -a request to the remote node to suspend the specified task. - -If the task specified by id is already suspended, then the -``RTEMS_ALREADY_SUSPENDED`` status code is returned. + \clearpage .. _rtems_task_resume: TASK_RESUME - Resume a task --------------------------- .. index:: resuming a task - -**CALLING SEQUENCE:** - .. index:: rtems_task_resume -.. code-block:: c - - rtems_status_code rtems_task_resume( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_task_resume( + rtems_id id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - task resumed successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task not suspended + * - ``RTEMS_SUCCESSFUL`` + - task resumed successfully + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_INCORRECT_STATE`` + - task not suspended -**DESCRIPTION:** +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. -This directive removes the task specified by id from the suspended state. If -the task is in the ready state after the suspension is removed, then it will be -scheduled to run. If the task is still in a blocked state after the suspension -is removed, then it will remain in that blocked state. +NOTES: + The running task may be preempted if its preemption mode is enabled and the + local task being resumed has a higher priority. -**NOTES:** + 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. -The running task may be preempted if its preemption mode is enabled and the -local task being resumed has a higher priority. + If the task specified by id is not suspended, then the + ``RTEMS_INCORRECT_STATE`` status code is returned. -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. +.. raw:: latex -If the task specified by id is not suspended, then the -``RTEMS_INCORRECT_STATE`` status code is returned. + \clearpage .. _rtems_task_is_suspended: TASK_IS_SUSPENDED - Determine if a task is Suspended ---------------------------------------------------- .. index:: is task suspended - -**CALLING SEQUENCE:** - .. index:: rtems_task_is_suspended -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_is_suspended( - rtems_id id - ); + rtems_status_code rtems_task_is_suspended( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - task is NOT suspended - * - ``RTEMS_ALREADY_SUSPENDED`` - - task is currently suspended - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks + * - ``RTEMS_SUCCESSFUL`` + - task is NOT suspended + * - ``RTEMS_ALREADY_SUSPENDED`` + - task is currently suspended + * - ``RTEMS_INVALID_ID`` + - task id invalid + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks -**DESCRIPTION:** +DESCRIPTION: + This directive returns a status code indicating whether or not the + specified task is currently suspended. -This directive returns a status code indicating whether or not the specified -task is currently suspended. +NOTES: + This operation is not currently supported on remote tasks. -**NOTES:** +.. raw:: latex -This operation is not currently supported on remote tasks. + \clearpage .. _rtems_task_set_priority: @@ -1125,58 +1127,59 @@ TASK_SET_PRIORITY - Set task priority .. index:: get task priority .. index:: obtain 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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_set_priority( + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - task priority set successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid return argument pointer + * - ``RTEMS_INVALID_PRIORITY`` + - invalid task priority + +DESCRIPTION: + This directive manipulates the priority of the task specified by id. An id + of ``RTEMS_SELF`` is used to indicate the calling task. When new_priority + is not equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous + priority is returned in old_priority. When new_priority is + ``RTEMS_CURRENT_PRIORITY``, the specified task's current priority is + returned in old_priority. Valid priorities range from a high of 1 to a low + of 255. + +NOTES: + The calling task may be preempted if its preemption mode is enabled and it + lowers its own priority or raises another task's priority. + + In case the new priority equals the current priority of the task, then + nothing happens. + + Setting the priority of a global task which does not reside on the local + node will generate a request to the remote node to change the priority of + the specified task. + + If the task specified by id is currently holding any binary semaphores + which use the priority inheritance algorithm, then the task's priority + cannot be lowered immediately. If the task's priority were lowered + immediately, then priority inversion results. The requested lowering of + the task's priority will occur when the task has released all priority + inheritance binary semaphores. The task's priority can be increased + regardless of the task's use of priority inheritance binary semaphores. + +.. raw:: latex + + \clearpage .. _rtems_task_mode: @@ -1188,172 +1191,171 @@ TASK_MODE - Change the current task mode .. index:: set task preemption mode .. index:: get task preemption mode .. index:: obtain task mode - -**CALLING SEQUENCE:** - .. index:: rtems_task_mode -.. 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 - -**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 +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 + +DESCRIPTION: + This directive manipulates the execution mode of the calling task. A + task's execution mode enables and disables preemption, timeslicing, + asynchronous signal processing, as well as specifying the current interrupt + level. To modify an execution mode, the mode class(es) to be changed must + be specified in the mask parameter and the desired mode(s) must be + specified in the mode parameter. + +NOTES: + The calling task will be preempted if it enables preemption and a higher + priority task is ready to run. + + Enabling timeslicing has no effect if preemption is disabled. For a task + to be timesliced, that task must have both preemption and timeslicing + enabled. + + A task can obtain its current execution mode, without modifying it, by + calling this directive with a mask value of ``RTEMS_CURRENT_MODE``. + + To temporarily disable the processing of a valid ASR, a task should call + this directive with the ``RTEMS_NO_ASR`` indicator specified in mode. + + The set of task mode constants and each mode's corresponding mask constant + is provided in the following table: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_PREEMPT`` + - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption + * - ``RTEMS_NO_PREEMPT`` + - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption + * - ``RTEMS_NO_TIMESLICE`` + - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing + * - ``RTEMS_TIMESLICE`` + - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing + * - ``RTEMS_ASR`` + - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing + * - ``RTEMS_NO_ASR`` + - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing + * - ``RTEMS_INTERRUPT_LEVEL(0)`` + - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts + * - ``RTEMS_INTERRUPT_LEVEL(n)`` + - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n + +.. raw:: latex + + \clearpage .. _rtems_task_get_note: TASK_GET_NOTE - Get task notepad entry -------------------------------------- .. index:: get task notepad entry - -**CALLING SEQUENCE:** - .. index:: rtems_task_get_note -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_get_note( - rtems_id id, - uint32_t notepad, - uint32_t *note - ); + rtems_status_code rtems_task_get_note( + rtems_id id, + uint32_t notepad, + uint32_t *note + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - note value obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``note`` parameter is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid notepad location + * - ``RTEMS_SUCCESSFUL`` + - note value obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``note`` parameter is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid notepad location -**DESCRIPTION:** +DESCRIPTION: + This directive returns the note contained in the notepad location of the + task specified by id. -This directive returns the note contained in the notepad location of -the task specified by id. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** + If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. -This directive will not cause the running task to be preempted. + The sixteen notepad locations can be accessed using the constants + ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. -If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. + 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 sixteen notepad locations can be accessed using the constants -``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. +.. raw:: latex -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. + \clearpage .. _rtems_task_set_note: TASK_SET_NOTE - Set task notepad entry -------------------------------------- .. index:: set task notepad entry - -**CALLING SEQUENCE:** - .. index:: rtems_task_set_note -.. code-block:: c - - rtems_status_code rtems_task_set_note( - rtems_id id, - uint32_t notepad, - uint32_t note - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_task_set_note( + rtems_id id, + uint32_t notepad, + uint32_t note + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - note set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid notepad location + * - ``RTEMS_SUCCESSFUL`` + - note set successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid notepad location -**DESCRIPTION:** +DESCRIPTION: + This directive sets the notepad entry for the task specified by id to the + value note. -This directive sets the notepad entry for the task specified by -id to the value note. +NOTES: + If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own + notepad. -**NOTES:** + This directive will not cause the running task to be preempted. -If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own notepad. + The sixteen notepad locations can be accessed using the constants + ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. -This directive will not cause the running task to be preempted. + 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. -The sixteen notepad locations can be accessed using the constants -``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. +.. raw:: latex -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. + \clearpage .. _rtems_task_wake_after: @@ -1361,43 +1363,42 @@ TASK_WAKE_AFTER - Wake up after interval ---------------------------------------- .. index:: delay a task for an interval .. index:: wake up after an interval - -**CALLING SEQUENCE:** - .. index:: rtems_task_wake_after -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_task_wake_after( - rtems_interval ticks - ); + rtems_status_code rtems_task_wake_after( + rtems_interval ticks + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - always successful + * - ``RTEMS_SUCCESSFUL`` + - always successful -**DESCRIPTION:** +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. -This directive blocks the calling task for the specified number of system clock -ticks. When the requested interval has elapsed, the task is made ready. The -clock tick directives automatically updates the delay period. +NOTES: + Setting the system date and time with the ``rtems_clock_set`` directive has + no effect on a ``rtems_task_wake_after`` blocked task. -**NOTES:** + A task may give up the processor and remain in the ready state by + specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks. -Setting the system date and time with the ``rtems_clock_set`` directive has no -effect on a ``rtems_task_wake_after`` blocked task. + The maximum timer interval that can be specified is the maximum value which + can be represented by the uint32_t type. -A task may give up the processor and remain in the ready state by specifying a -value of ``RTEMS_YIELD_PROCESSOR`` in ticks. + A clock tick is required to support the functionality of this directive. -The maximum timer interval that can be specified is the maximum value which can -be represented by the uint32_t type. +.. raw:: latex -A clock tick is required to support the functionality of this directive. + \clearpage .. _rtems_task_wake_when: @@ -1405,80 +1406,78 @@ TASK_WAKE_WHEN - Wake up when specified --------------------------------------- .. index:: delay a task until a wall time .. index:: wake up at a wall time - -**CALLING SEQUENCE:** - .. index:: rtems_task_wake_when -.. code-block:: c - - rtems_status_code rtems_task_wake_when( - rtems_time_of_day *time_buffer - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_task_wake_when( + rtems_time_of_day *time_buffer + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - awakened at date/time successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL - * - ``RTEMS_INVALID_TIME_OF_DAY`` - - invalid time buffer - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set + * - ``RTEMS_SUCCESSFUL`` + - awakened at date/time successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``time_buffer`` is NULL + * - ``RTEMS_INVALID_TIME_OF_DAY`` + - invalid time buffer + * - ``RTEMS_NOT_DEFINED`` + - system date and time is not set -**DESCRIPTION:** +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. -This directive blocks a task until the date and time specified in time_buffer. -At the requested date and time, the calling task will be unblocked and made -ready to execute. +NOTES: + The ticks portion of time_buffer structure is ignored. The timing + granularity of this directive is a second. -**NOTES:** + A clock tick is required to support the functionality of this directive. -The ticks portion of time_buffer structure is ignored. The timing granularity -of this directive is a second. +.. raw:: latex -A clock tick is required to support the functionality of this directive. + \clearpage .. _rtems_iterate_over_all_threads: ITERATE_OVER_ALL_THREADS - Iterate Over Tasks --------------------------------------------- .. index:: iterate over all threads - -**CALLING SEQUENCE:** - .. index:: rtems_iterate_over_all_threads -.. code-block:: c - - typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); - void rtems_iterate_over_all_threads( - rtems_per_thread_routine routine - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); + void rtems_iterate_over_all_threads( + rtems_per_thread_routine routine + ); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This directive iterates over all of the existant threads in the system and + invokes ``routine`` on each of them. The user should be careful in + accessing the contents of ``the_thread``. -This directive iterates over all of the existant threads in the system and -invokes ``routine`` on each of them. The user should be careful in accessing -the contents of ``the_thread``. + This routine is intended for use in diagnostic utilities and is not + intented for routine use in an operational system. -This routine is intended for use in diagnostic utilities and is not intented -for routine use in an operational system. +NOTES: + There is NO protection while this routine is called. Thus it is possible + that ``the_thread`` could be deleted while this is operating. By not + having protection, the user is free to invoke support routines from the C + Library which require semaphores for data structures. -**NOTES:** +.. raw:: latex -There is NO protection while this routine is called. Thus it is possible that -``the_thread`` could be deleted while this is operating. By not having -protection, the user is free to invoke support routines from the C Library -which require semaphores for data structures. + \clearpage .. _rtems_task_variable_add: @@ -1487,61 +1486,61 @@ TASK_VARIABLE_ADD - Associate per task variable .. index:: per-task variable .. index:: task private variable .. index:: task private data +.. index:: rtems_task_variable_add .. warning:: This directive is deprecated and task variables will be removed. -**CALLING SEQUENCE:** - -.. index:: rtems_task_variable_add - -.. 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. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_add( + rtems_id tid, + void **task_variable, + void (*dtor)(void *) + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - per task variable added successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_NO_MEMORY`` + - invalid task id + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks + +DESCRIPTION: + This directive adds the memory location specified by the ptr argument to + the context of the given task. The variable will then be private to the + task. The task can access and modify the variable, but the modifications + will not appear to other tasks, and other tasks' modifications to that + variable will not affect the value seen by the task. This is accomplished + by saving and restoring the variable's value each time a task switch occurs + to or from the calling task. If the dtor argument is non-NULL it specifies + the address of a 'destructor' function which will be called when the task + is deleted. The argument passed to the destructor function is the task's + value of the variable. + +NOTES: + Task variables increase the context switch time to and from the tasks that + own them so it is desirable to minimize the number of task variables. One + efficient method is to have a single task variable that is a pointer to a + dynamically allocated structure containing the task's private 'global' + data. In this case the destructor function could be 'free'. + + Per-task variables are disabled in SMP configurations and this service is + not available. + +.. raw:: latex + + \clearpage .. _rtems_task_variable_get: @@ -1549,57 +1548,56 @@ TASK_VARIABLE_GET - Obtain value of a per task variable ------------------------------------------------------- .. index:: get per-task variable .. index:: obtain per-task variable +.. index:: rtems_task_variable_get .. warning:: This directive is deprecated and task variables will be removed. -**CALLING SEQUENCE:** - -.. index:: rtems_task_variable_get - -.. code-block:: c - - rtems_status_code rtems_task_variable_get( - rtems_id tid, - void **task_variable, - void **task_variable_value - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable_value`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is not found - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -**DESCRIPTION:** - -This directive looks up the private value of a task variable for a specified -task and stores that value in the location pointed to by the result argument. -The specified task is usually not the calling task, which can get its private -value by directly accessing the variable. - -**NOTES:** - -If you change memory which ``task_variable_value`` points to, remember to -declare that memory as volatile, so that the compiler will optimize it -correctly. In this case both the pointer ``task_variable_value`` and data -referenced by ``task_variable_value`` should be considered volatile. - -Per-task variables are disabled in SMP configurations and this service is not -available. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_get( + rtems_id tid, + void **task_variable, + void **task_variable_value + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - per task variable obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable_value`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable`` is not found + * - ``RTEMS_NO_MEMORY`` + - invalid task id + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks + +DESCRIPTION: + This directive looks up the private value of a task variable for a + specified task and stores that value in the location pointed to by the + result argument. The specified task is usually not the calling task, which + can get its private value by directly accessing the variable. + +NOTES: + If you change memory which ``task_variable_value`` points to, remember to + declare that memory as volatile, so that the compiler will optimize it + correctly. In this case both the pointer ``task_variable_value`` and data + referenced by ``task_variable_value`` should be considered volatile. + + Per-task variables are disabled in SMP configurations and this service is + not available. + +.. raw:: latex + + \clearpage .. _rtems_task_variable_delete: @@ -1608,43 +1606,38 @@ TASK_VARIABLE_DELETE - Remove per task variable .. index:: per-task variable .. index:: task private variable .. index:: task private data +.. index:: rtems_task_variable_delete .. warning:: This directive is deprecated and task variables will be removed. -**CALLING SEQUENCE:** - -.. index:: rtems_task_variable_delete - -.. code-block:: c - - rtems_status_code rtems_task_variable_delete( - rtems_id id, - void **task_variable - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -**DESCRIPTION:** - -This directive removes the given location from a task's context. - -**NOTES:** - -Per-task variables are disabled in SMP configurations and this service -is not available. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_variable_delete( + rtems_id id, + void **task_variable + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - per task variable deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_NO_MEMORY`` + - invalid task id + * - ``RTEMS_INVALID_ADDRESS`` + - ``task_variable`` is NULL + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - not supported on remote tasks + +DESCRIPTION: + This directive removes the given location from a task's context. + +NOTES: + Per-task variables are disabled in SMP configurations and this service is + not available. |