diff options
Diffstat (limited to 'c-user/task_manager.rst')
-rw-r--r-- | c-user/task_manager.rst | 2038 |
1 files changed, 0 insertions, 2038 deletions
diff --git a/c-user/task_manager.rst b/c-user/task_manager.rst deleted file mode 100644 index fdbf41b..0000000 --- a/c-user/task_manager.rst +++ /dev/null @@ -1,2038 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: tasks - -Task Manager -************ - -Introduction -============ - -The task manager provides a comprehensive set of directives to create, delete, -and administer tasks. The directives provided by the task manager are: - -- rtems_task_create_ - Create a task - -- rtems_task_ident_ - Get ID of a task - -- rtems_task_self_ - Obtain ID of caller - -- rtems_task_start_ - Start a task - -- rtems_task_restart_ - Restart a task - -- rtems_task_delete_ - Delete a task - -- rtems_task_exit_ - Delete the calling task - -- rtems_task_suspend_ - Suspend a task - -- rtems_task_resume_ - Resume a task - -- rtems_task_is_suspended_ - Determine if a task is suspended - -- rtems_task_set_priority_ - Set task priority - -- rtems_task_get_priority_ - Get task priority - -- rtems_task_mode_ - Change current task's mode - -- rtems_task_wake_after_ - Wake up after interval - -- rtems_task_wake_when_ - Wake up when specified - -- rtems_task_get_scheduler_ - Get scheduler of a task - -- rtems_task_set_scheduler_ - Set scheduler of a task - -- rtems_task_get_affinity_ - Get task processor affinity - -- rtems_task_set_affinity_ - Set task processor affinity - -- rtems_task_iterate_ - Iterate Over Tasks - -Background -========== - -.. index:: task, definition - -Task Definition ---------------- - -Many definitions of a task have been proposed in computer literature. -Unfortunately, none of these definitions encompasses all facets of the concept -in a manner which is operating system independent. Several of the more common -definitions are provided to enable each user to select a definition which best -matches their own experience and understanding of the task concept: - -- a "dispatchable" unit. - -- an entity to which the processor is allocated. - -- an atomic unit of a real-time, multiprocessor system. - -- single threads of execution which concurrently compete for resources. - -- a sequence of closely related computations which can execute concurrently - with other computational sequences. - -From RTEMS' perspective, a task is the smallest thread of execution which can -compete on its own for system resources. A task is manifested by the existence -of a task control block (TCB). - -Task Control Block ------------------- - -The Task Control Block (TCB) is an RTEMS defined data structure which contains -all the information that is pertinent to the execution of a task. During -system initialization, RTEMS reserves a TCB for each task configured. A TCB is -allocated upon creation of the task and is returned to the TCB free list upon -deletion of the task. - -The TCB's elements are modified as a result of system calls made by the -application in response to external and internal stimuli. TCBs are the only -RTEMS internal data structure that can be accessed by an application via user -extension routines. The TCB contains a task's name, ID, current priority, -current and starting states, execution mode, TCB user extension pointer, -scheduling control structures, as well as data required by a blocked task. - -A task's context is stored in the TCB when a task switch occurs. When the task -regains control of the processor, its context is restored from the TCB. When a -task is restarted, the initial state of the task is restored from the starting -context area in the task's TCB. - -.. index:: task name - -Task Name ---------- - -By default, the task name is defined by the task object name given to -:ref:`rtems_task_create() <rtems_task_create>`. The task name can be obtained -with the `pthread_getname_np() -<http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_ function. -Optionally, a new task name may be set with the `pthread_setname_np() -<http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_ function. -The maximum size of a task name is defined by the application configuration -option :ref:`CONFIGURE_MAXIMUM_THREAD_NAME_SIZE -<CONFIGURE_MAXIMUM_THREAD_NAME_SIZE>`. - -.. index:: task states - -Task States ------------ - -A task may exist in one of the following five states: - -- *executing* - Currently scheduled to the CPU - -- *ready* - May be scheduled to the CPU - -- *blocked* - Unable to be scheduled to the CPU - -- *dormant* - Created task that is not started - -- *non-existent* - Uncreated or deleted task - -An active task may occupy the executing, ready, blocked or dormant state, -otherwise the task is considered non-existent. One or more tasks may be active -in the system simultaneously. Multiple tasks communicate, synchronize, and -compete for system resources with each other via system calls. The multiple -tasks appear to execute in parallel, but actually each is dispatched to the CPU -for periods of time determined by the RTEMS scheduling algorithm. The -scheduling of a task is based on its current state and priority. - -.. index:: task priority -.. index:: priority, task -.. index:: rtems_task_priority - -Task Priority -------------- - -A task's priority determines its importance in relation to the other tasks -executing on the same processor. RTEMS supports 255 levels of priority ranging -from 1 to 255. The data type ``rtems_task_priority`` is used to store task -priorities. - -Tasks of numerically smaller priority values are more important tasks than -tasks of numerically larger priority values. For example, a task at priority -level 5 is of higher privilege than a task at priority level 10. There is no -limit to the number of tasks assigned to the same priority. - -Each task has a priority associated with it at all times. The initial value of -this priority is assigned at task creation time. The priority of a task may be -changed at any subsequent time. - -Priorities are used by the scheduler to determine which ready task will be -allowed to execute. In general, the higher the logical priority of a task, the -more likely it is to receive processor execution time. - -.. index:: task mode -.. index:: rtems_task_mode - -Task Mode ---------- - -A task's execution mode is a combination of the following four components: - -- preemption - -- ASR processing - -- timeslicing - -- interrupt level - -It is used to modify RTEMS' scheduling process and to alter the execution -environment of the task. The data type ``rtems_task_mode`` is used to manage -the task execution mode. - -.. index:: preemption - -The preemption component allows a task to determine when control of the -processor is relinquished. If preemption is disabled (``RTEMS_NO_PREEMPT``), -the task will retain control of the processor as long as it is in the executing -state - even if a higher priority task is made ready. If preemption is enabled -(``RTEMS_PREEMPT``) and a higher priority task is made ready, then the -processor will be taken away from the current task immediately and given to the -higher priority task. - -.. index:: timeslicing - -The timeslicing component is used by the RTEMS scheduler to determine how the -processor is allocated to tasks of equal priority. If timeslicing is enabled -(``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can -execute before the processor is allocated to another ready task of equal -priority. The length of the timeslice is application dependent and specified in -the Configuration Table. If timeslicing is disabled (``RTEMS_NO_TIMESLICE``), -then the task will be allowed to execute until a task of higher priority is -made ready. If ``RTEMS_NO_PREEMPT`` is selected, then the timeslicing component -is ignored by the scheduler. - -The asynchronous signal processing component is used to determine when received -signals are to be processed by the task. If signal processing is enabled -(``RTEMS_ASR``), then signals sent to the task will be processed the next time -the task executes. If signal processing is disabled (``RTEMS_NO_ASR``), then -all signals received by the task will remain posted until signal processing is -enabled. This component affects only tasks which have established a routine to -process asynchronous signals. - -.. index:: interrupt level, task - -The interrupt level component is used to determine which interrupts will be -enabled when the task is executing. ``RTEMS_INTERRUPT_LEVEL(n)`` specifies that -the task will execute at interrupt level n. - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - enable preemption (default) - * - ``RTEMS_NO_PREEMPT`` - - disable preemption - * - ``RTEMS_NO_TIMESLICE`` - - disable timeslicing (default) - * - ``RTEMS_TIMESLICE`` - - enable timeslicing - * - ``RTEMS_ASR`` - - enable ASR processing (default) - * - ``RTEMS_NO_ASR`` - - disable ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - enable all interrupts (default) - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - execute at interrupt level n - -The set of default modes may be selected by specifying the -``RTEMS_DEFAULT_MODES`` constant. - -.. index:: task arguments -.. index:: task prototype - -Accessing Task Arguments ------------------------- - -All RTEMS tasks are invoked with a single argument which is specified when they -are started or restarted. The argument is commonly used to communicate startup -information to the task. The simplest manner in which to define a task which -accesses it argument is: - -.. index:: rtems_task - -.. code-block:: c - - rtems_task user_task( - rtems_task_argument argument - ); - -Application tasks requiring more information may view this single argument as -an index into an array of parameter blocks. - -.. index:: floating point - -Floating Point Considerations ------------------------------ - -Creating a task with the ``RTEMS_FLOATING_POINT`` attribute flag results in -additional memory being allocated for the TCB to store the state of the numeric -coprocessor during task switches. This additional memory is *NOT* allocated for -``RTEMS_NO_FLOATING_POINT`` tasks. Saving and restoring the context of a -``RTEMS_FLOATING_POINT`` task takes longer than that of a -``RTEMS_NO_FLOATING_POINT`` task because of the relatively large amount of time -required for the numeric coprocessor to save or restore its computational -state. - -Since RTEMS was designed specifically for embedded military applications which -are floating point intensive, the executive is optimized to avoid unnecessarily -saving and restoring the state of the numeric coprocessor. The state of the -numeric coprocessor is only saved when a ``RTEMS_FLOATING_POINT`` task is -dispatched and that task was not the last task to utilize the coprocessor. In -a system with only one ``RTEMS_FLOATING_POINT`` task, the state of the numeric -coprocessor will never be saved or restored. - -Although the overhead imposed by ``RTEMS_FLOATING_POINT`` tasks is minimal, -some applications may wish to completely avoid the overhead associated with -``RTEMS_FLOATING_POINT`` tasks and still utilize a numeric coprocessor. By -preventing a task from being preempted while performing a sequence of floating -point operations, a ``RTEMS_NO_FLOATING_POINT`` task can utilize the numeric -coprocessor without incurring the overhead of a ``RTEMS_FLOATING_POINT`` -context switch. This approach also avoids the allocation of a floating point -context area. However, if this approach is taken by the application designer, -NO tasks should be created as ``RTEMS_FLOATING_POINT`` tasks. Otherwise, the -floating point context will not be correctly maintained because RTEMS assumes -that the state of the numeric coprocessor will not be altered by -``RTEMS_NO_FLOATING_POINT`` tasks. - -If the supported processor type does not have hardware floating capabilities or -a standard numeric coprocessor, RTEMS will not provide built-in support for -hardware floating point on that processor. In this case, all tasks are -considered ``RTEMS_NO_FLOATING_POINT`` whether created as -``RTEMS_FLOATING_POINT`` or ``RTEMS_NO_FLOATING_POINT`` tasks. A floating -point emulation software library must be utilized for floating point -operations. - -On some processors, it is possible to disable the floating point unit -dynamically. If this capability is supported by the target processor, then -RTEMS will utilize this capability to enable the floating point unit only for -tasks which are created with the ``RTEMS_FLOATING_POINT`` attribute. The -consequence of a ``RTEMS_NO_FLOATING_POINT`` task attempting to access the -floating point unit is CPU dependent but will generally result in an exception -condition. - -.. index:: task attributes, building - -Building a Task Attribute Set ------------------------------ - -In general, an attribute set is built by a bitwise OR of the desired -components. The set of valid task attribute components is listed below: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_NO_FLOATING_POINT`` - - does not use coprocessor (default) - * - ``RTEMS_FLOATING_POINT`` - - uses numeric coprocessor - * - ``RTEMS_LOCAL`` - - local task (default) - * - ``RTEMS_GLOBAL`` - - global task - -Attribute values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each attribute -appears exactly once in the component list. A component listed as a default is -not required to appear in the component list, although it is a good programming -practice to specify default components. If all defaults are desired, then -``RTEMS_DEFAULT_ATTRIBUTES`` should be used. - -This example demonstrates the attribute_set parameter needed to create a local -task which utilizes the numeric coprocessor. The attribute_set parameter could -be ``RTEMS_FLOATING_POINT`` or ``RTEMS_LOCAL | RTEMS_FLOATING_POINT``. The -attribute_set parameter can be set to ``RTEMS_FLOATING_POINT`` because -``RTEMS_LOCAL`` is the default for all created tasks. If the task were global -and used the numeric coprocessor, then the attribute_set parameter would be -``RTEMS_GLOBAL | RTEMS_FLOATING_POINT``. - -.. index:: task mode, building - -Building a Mode and Mask ------------------------- - -In general, a mode and its corresponding mask is built by a bitwise OR of the -desired components. The set of valid mode constants and each mode's -corresponding mask constant is listed below: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption - * - ``RTEMS_NO_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption - * - ``RTEMS_NO_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing - * - ``RTEMS_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing - * - ``RTEMS_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing - * - ``RTEMS_NO_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n - -Mode values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each mode appears -exactly once in the component list. A mode component listed as a default is -not required to appear in the mode component list, although it is a good -programming practice to specify default components. If all defaults are -desired, the mode ``RTEMS_DEFAULT_MODES`` and the mask ``RTEMS_ALL_MODE_MASKS`` -should be used. - -The following example demonstrates the mode and mask parameters used with the -``rtems_task_mode`` directive to place a task at interrupt level 3 and make it -non-preemptible. The mode should be set to ``RTEMS_INTERRUPT_LEVEL(3) | -RTEMS_NO_PREEMPT`` to indicate the desired preemption mode and interrupt level, -while the mask parameter should be set to ``RTEMS_INTERRUPT_MASK | -RTEMS_NO_PREEMPT_MASK`` to indicate that the calling task's interrupt level and -preemption mode are being altered. - -Operations -========== - -Creating Tasks --------------- - -The ``rtems_task_create`` directive creates a task by allocating a task control -block, assigning the task a user-specified name, allocating it a stack and -floating point context area, setting a user-specified initial priority, setting -a user-specified initial mode, and assigning it a task ID. Newly created tasks -are initially placed in the dormant state. All RTEMS tasks execute in the most -privileged mode of the processor. - -Obtaining Task IDs ------------------- - -When a task is created, RTEMS generates a unique task ID and assigns it to the -created task until it is deleted. The task ID may be obtained by either of two -methods. First, as the result of an invocation of the ``rtems_task_create`` -directive, the task ID is stored in a user provided location. Second, the task -ID may be obtained later using the ``rtems_task_ident`` directive. The task ID -is used by other directives to manipulate this task. - -Starting and Restarting Tasks ------------------------------ - -The ``rtems_task_start`` directive is used to place a dormant task in the ready -state. This enables the task to compete, based on its current priority, for -the processor and other system resources. Any actions, such as suspension or -change of priority, performed on a task prior to starting it are nullified when -the task is started. - -With the ``rtems_task_start`` directive the user specifies the task's starting -address and argument. The argument is used to communicate some startup -information to the task. As part of this directive, RTEMS initializes the -task's stack based upon the task's initial execution mode and start address. -The starting argument is passed to the task in accordance with the target -processor's calling convention. - -The ``rtems_task_restart`` directive restarts a task at its initial starting -address with its original priority and execution mode, but with a possibly -different argument. The new argument may be used to distinguish between the -original invocation of the task and subsequent invocations. The task's stack -and control block are modified to reflect their original creation values. -Although references to resources that have been requested are cleared, -resources allocated by the task are NOT automatically returned to RTEMS. A -task cannot be restarted unless it has previously been started (i.e. dormant -tasks cannot be restarted). All restarted tasks are placed in the ready state. - -Suspending and Resuming Tasks ------------------------------ - -The ``rtems_task_suspend`` directive is used to place either the caller or -another task into a suspended state. The task remains suspended until a -``rtems_task_resume`` directive is issued. This implies that a task may be -suspended as well as blocked waiting either to acquire a resource or for the -expiration of a timer. - -The ``rtems_task_resume`` directive is used to remove another task from the -suspended state. If the task is not also blocked, resuming it will place it in -the ready state, allowing it to once again compete for the processor and -resources. If the task was blocked as well as suspended, this directive clears -the suspension and leaves the task in the blocked state. - -Suspending a task which is already suspended or resuming a task which is not -suspended is considered an error. The ``rtems_task_is_suspended`` can be used -to determine if a task is currently suspended. - -Delaying the Currently Executing Task -------------------------------------- - -The ``rtems_task_wake_after`` directive creates a sleep timer which allows a -task to go to sleep for a specified interval. The task is blocked until the -delay interval has elapsed, at which time the task is unblocked. A task -calling the ``rtems_task_wake_after`` directive with a delay interval of -``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready -task of equal or greater priority and remain ready to execute. - -The ``rtems_task_wake_when`` directive creates a sleep timer which allows a -task to go to sleep until a specified date and time. The calling task is -blocked until the specified date and time has occurred, at which time the task -is unblocked. - -Changing Task Priority ----------------------- - -The ``rtems_task_set_priority`` directive is used to obtain or change the -current priority of either the calling task or another task. If the new -priority requested is ``RTEMS_CURRENT_PRIORITY`` or the task's actual priority, -then the current priority will be returned and the task's priority will remain -unchanged. If the task's priority is altered, then the task will be scheduled -according to its new priority. - -The ``rtems_task_restart`` directive resets the priority of a task to its -original value. - -Changing Task Mode ------------------- - -The ``rtems_task_mode`` directive is used to obtain or change the current -execution mode of the calling task. A task's execution mode is used to enable -preemption, timeslicing, ASR processing, and to set the task's interrupt level. - -The ``rtems_task_restart`` directive resets the mode of a task to its original -value. - -Task Deletion -------------- - -RTEMS provides the ``rtems_task_delete`` directive to allow a task to delete -itself or any other task. This directive removes all RTEMS references to the -task, frees the task's control block, removes it from resource wait queues, and -deallocates its stack as well as the optional floating point context. The -task's name and ID become inactive at this time, and any subsequent references -to either of them is invalid. In fact, RTEMS may reuse the task ID for another -task which is created later in the application. A specialization of -``rtems_task_delete`` is ``rtems_task_exit`` which deletes the calling task. - -Unexpired delay timers (i.e. those used by ``rtems_task_wake_after`` and -``rtems_task_wake_when``) and timeout timers associated with the task are -automatically deleted, however, other resources dynamically allocated by the -task are NOT automatically returned to RTEMS. Therefore, before a task is -deleted, all of its dynamically allocated resources should be deallocated by -the user. This may be accomplished by instructing the task to delete itself -rather than directly deleting the task. Other tasks may instruct a task to -delete itself by sending a "delete self" message, event, or signal, or by -restarting the task with special arguments which instruct the task to delete -itself. - -Setting Affinity to a Single Processor --------------------------------------- - -On some embedded applications targeting SMP systems, it may be beneficial to -lock individual tasks to specific processors. In this way, one can designate a -processor for I/O tasks, another for computation, etc.. The following -illustrates the code sequence necessary to assign a task an affinity for -processor with index ``processor_index``. - -.. code-block:: c - - #include <rtems.h> - #include <assert.h> - - void pin_to_processor(rtems_id task_id, int processor_index) - { - rtems_status_code sc; - cpu_set_t cpuset; - CPU_ZERO(&cpuset); - CPU_SET(processor_index, &cpuset); - sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset); - assert(sc == RTEMS_SUCCESSFUL); - } - -It is important to note that the ``cpuset`` is not validated until the -``rtems_task_set_affinity`` call is made. At that point, it is validated -against the current system configuration. - -.. index:: rtems_task_get_note -.. index:: rtems_task_set_note - -Transition Advice for Obsolete Notepads ---------------------------------------- - -Task notepads and the associated directives :ref:`rtems_task_get_note` and -:ref:`rtems_task_set_note` were removed in RTEMS 5.1. These were never -thread-safe to access and subject to conflicting use of the notepad index by -libraries which were designed independently. - -It is recommended that applications be modified to use services which are -thread safe and not subject to issues with multiple applications conflicting -over the key (e.g. notepad index) selection. For most applications, POSIX Keys -should be used. These are available in all RTEMS build configurations. It is -also possible that thread-local storage (TLS) is an option for some use cases. - -.. index:: rtems_task_variable_add -.. index:: rtems_task_variable_get -.. index:: rtems_task_variable_delete - -Transition Advice for Obsolete Task Variables ---------------------------------------------- - -Task notepads and the associated directives :ref:`rtems_task_variable_add`, -:ref:`rtems_task_variable_get` and :ref:`rtems_task_variable_delete` were -removed in RTEMS 5.1. Task variables must be replaced by POSIX Keys or -thread-local storage (TLS). POSIX Keys are available in all configurations and -support value destructors. For the TLS support consult the :title:`RTEMS CPU -Architecture Supplement`. - -Directives -========== - -This section details the task manager's directives. A subsection is dedicated -to each of this manager's directives and describes the calling sequence, -related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a task -.. index:: rtems_task_create - -.. _rtems_task_create: - -TASK_CREATE - Create a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_create( - rtems_name name, - rtems_task_priority initial_priority, - size_t stack_size, - rtems_mode initial_modes, - rtems_attribute attribute_set, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task created successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - * - ``RTEMS_MP_NOT_CONFIGURED`` - - multiprocessing not configured - * - ``RTEMS_TOO_MANY`` - - too many tasks created - * - ``RTEMS_UNSATISFIED`` - - not enough memory for stack/FP context - * - ``RTEMS_UNSATISFIED`` - - non-preemption mode not supported on SMP system - * - ``RTEMS_UNSATISFIED`` - - interrupt level mode not supported on SMP system - * - ``RTEMS_TOO_MANY`` - - too many global objects - -DESCRIPTION: - This directive creates a task which resides on the local node. It - allocates and initializes a TCB, a stack, and an optional floating point - context area. The mode parameter contains values which sets the task's - initial execution mode. The ``RTEMS_FLOATING_POINT`` attribute should be - specified if the created task is to use a numeric coprocessor. For - performance reasons, it is recommended that tasks not using the numeric - coprocessor should specify the ``RTEMS_NO_FLOATING_POINT`` attribute. If - the ``RTEMS_GLOBAL`` attribute is specified, the task can be accessed from - remote nodes. The task id, returned in id, is used in other task related - directives to access the task. When created, a task is placed in the - dormant state and can only be made ready to execute using the directive - ``rtems_task_start``. - -NOTES: - This directive may cause the calling task to be preempted. - - The scheduler of the new task is the scheduler of the executing task at - some point during the task creation. The specified task priority must be - valid for the selected scheduler. - - The task processor affinity is initialized to the set of online processors. - - If the requested stack size is less than the configured minimum stack size, - then RTEMS will use the configured minimum as the stack size for this task. - In addition to being able to specify the task stack size as a integer, - there are two constants which may be specified: - - ``RTEMS_MINIMUM_STACK_SIZE`` - The minimum stack size *RECOMMENDED* for use on this processor. This - value is selected by the RTEMS developers conservatively to minimize the - risk of blown stacks for most user applications. Using this constant - when specifying the task stack size, indicates that the stack size will - be at least ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user - configured minimum stack size is larger than the recommended minimum, - then it will be used. - - ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE`` - Indicates this task is to be created with a stack size of the minimum - stack size that was configured by the application. If not explicitly - configured by the application, the default configured minimum stack size - is the processor dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since - this uses the configured minimum stack size value, you may get a stack - size that is smaller or larger than the recommended minimum. This can be - used to provide large stacks for all tasks on complex applications or - small stacks on applications that are trying to conserve memory. - - Application developers should consider the stack usage of the device - drivers when calculating the stack size required for tasks which utilize - the driver. - - The following task attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_NO_FLOATING_POINT`` - - does not use coprocessor (default) - * - ``RTEMS_FLOATING_POINT`` - - uses numeric coprocessor - * - ``RTEMS_LOCAL`` - - local task (default) - * - ``RTEMS_GLOBAL`` - - global task - - The following task mode constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - enable preemption (default) - * - ``RTEMS_NO_PREEMPT`` - - disable preemption - * - ``RTEMS_NO_TIMESLICE`` - - disable timeslicing (default) - * - ``RTEMS_TIMESLICE`` - - enable timeslicing - * - ``RTEMS_ASR`` - - enable ASR processing (default) - * - ``RTEMS_NO_ASR`` - - disable ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - enable all interrupts (default) - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - execute at interrupt level ``n`` - - The interrupt level portion of the task execution mode supports a maximum - of 256 interrupt levels. These levels are mapped onto the interrupt - levels actually supported by the target processor in a processor dependent - fashion. - - Tasks should not be made global unless remote tasks must interact with - them. This avoids the system overhead incurred by the creation of a - global task. When a global task is created, the task's name and id must - be transmitted to every node in the system for insertion in the local copy - of the global object table. - - The total number of global objects, including tasks, is limited by the - maximum_global_objects field in the Configuration Table. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a task -.. index:: rtems_task_ident - -.. _rtems_task_ident: - -TASK_IDENT - Get ID of a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - invalid task name - * - ``RTEMS_INVALID_NODE`` - - invalid node id - -DESCRIPTION: - This directive obtains the task id associated with the task name specified - in name. A task may obtain its own id by specifying ``RTEMS_SELF`` or its - own task name in name. If the task name is not unique, then the task id - returned will match one of the tasks with that name. However, this task id - is not guaranteed to correspond to the desired task. The task id, returned - in id, is used in other task related directives to access the task. - -NOTES: - This directive will not cause the running task to be preempted. - - If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the - local node being searched first. All other nodes are searched with the - lowest numbered node searched first. - - If node is a valid node number which does not represent the local node, - then only the tasks exported by the designated node are searched. - - This directive does not generate activity on remote nodes. It accesses - only the local copy of the global object table. - -.. raw:: latex - - \clearpage - -.. index:: obtain ID of caller -.. index:: rtems_task_self - -.. _rtems_task_self: - -TASK_SELF - Obtain ID of caller -------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_id rtems_task_self(void); - -DIRECTIVE STATUS CODES: - Returns the object Id of the calling task. - -DESCRIPTION: - This directive returns the Id of the calling task. - -NOTES: - If called from an interrupt service routine, this directive will return the - Id of the interrupted task. - -.. raw:: latex - - \clearpage - -.. index:: starting a task -.. index:: rtems_task_start - -.. _rtems_task_start: - -TASK_START - Start a task -------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_start( - rtems_id id, - rtems_task_entry entry_point, - rtems_task_argument argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - ask started successfully - * - ``RTEMS_INVALID_ADDRESS`` - - invalid task entry point - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INCORRECT_STATE`` - - task not in the dormant state - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot start remote task - -DESCRIPTION: - This directive readies the task, specified by ``id``, for execution based - on the priority and execution mode specified when the task was created. - The starting address of the task is given in ``entry_point``. The task's - starting argument is contained in argument. This argument can be a single - value or used as an index into an array of parameter blocks. The type of - this numeric argument is an unsigned integer type with the property that - any valid pointer to void can be converted to this type and then converted - back to a pointer to void. The result will compare equal to the original - pointer. - -NOTES: - The calling task will be preempted if its preemption mode is enabled and - the task being started has a higher priority. - - Any actions performed on a dormant task such as suspension or change of - priority are nullified when the task is initiated via the - ``rtems_task_start`` directive. - -.. raw:: latex - - \clearpage - -.. index:: restarting a task -.. index:: rtems_task_restart - -.. _rtems_task_restart: - -TASK_RESTART - Restart a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_restart( - rtems_id id, - rtems_task_argument argument - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task restarted successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task never started - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot restart remote task - -DESCRIPTION: - This directive resets the task specified by id to begin execution at its - original starting address. The task's priority and execution mode are set - to the original creation values. If the task is currently blocked, RTEMS - automatically makes the task ready. A task can be restarted from any - state, except the dormant state. - - The task's starting argument is contained in argument. This argument can - be a single value or an index into an array of parameter blocks. The type - of this numeric argument is an unsigned integer type with the property that - any valid pointer to void can be converted to this type and then converted - back to a pointer to void. The result will compare equal to the original - pointer. This new argument may be used to distinguish between the initial - ``rtems_task_start`` of the task and any ensuing calls to - ``rtems_task_restart`` of the task. This can be beneficial in deleting a - task. Instead of deleting a task using the ``rtems_task_delete`` - directive, a task can delete another task by restarting that task, and - allowing that task to release resources back to RTEMS and then delete - itself. - -NOTES: - If id is ``RTEMS_SELF``, the calling task will be restarted and will not - return from this directive. - - The calling task will be preempted if its preemption mode is enabled and - the task being restarted has a higher priority. - - The task must reside on the local node, even if the task was created with - the ``RTEMS_GLOBAL`` option. - -.. raw:: latex - - \clearpage - -.. index:: deleting a task -.. index:: rtems_task_delete - -.. _rtems_task_delete: - -TASK_DELETE - Delete a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task deleted successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot restart remote task - -DESCRIPTION: - This directive deletes a task, either the calling task or another task, as - specified by id. RTEMS stops the execution of the task and reclaims the - stack memory, any allocated delay or timeout timers, the TCB, and, if the - task is ``RTEMS_FLOATING_POINT``, its floating point context area. RTEMS - does not reclaim the following resources: region segments, partition - buffers, semaphores, timers, or rate monotonic periods. - -NOTES: - A task is responsible for releasing its resources back to RTEMS before - deletion. To insure proper deallocation of resources, a task should not be - deleted unless it is unable to execute or does not hold any RTEMS - resources. If a task holds RTEMS resources, the task should be allowed to - deallocate its resources before deletion. A task can be directed to - release its resources and delete itself by restarting it with a special - argument or by sending it a message, an event, or a signal. - - Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select - another task to execute. - - When a global task is deleted, the task id must be transmitted to every - node in the system for deletion from the local copy of the global object - table. - - The task must reside on the local node, even if the task was created with - the ``RTEMS_GLOBAL`` option. - -.. raw:: latex - - \clearpage - -.. index:: deleting a task -.. index:: rtems_task_exit - -.. _rtems_task_exit: - -TASK_EXIT - Delete the calling task ------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - void rtems_task_exit( void ) RTEMS_NO_RETURN; - -DIRECTIVE STATUS CODES: - NONE - This function will not return to the caller. - -DESCRIPTION: - This directive deletes the calling task. - -NOTES: - This directive must be called from a regular task context with enabled - interrupts, otherwise one of the fatal errors - - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`, or - * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT <internal_errors>` - - will occur. - - The ``rtems_task_exit()`` call is equivalent to the following code - sequence: - - .. code-block:: c - - pthread_detach(pthread_self()); - pthread_exit(NULL); - - See also :ref:`rtems_task_delete() <rtems_task_delete>`. - -.. raw:: latex - - \clearpage - -.. index:: suspending a task -.. index:: rtems_task_suspend - -.. _rtems_task_suspend: - -TASK_SUSPEND - Suspend a task ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_suspend( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task suspended successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ALREADY_SUSPENDED`` - - task already suspended - -DESCRIPTION: - This directive suspends the task specified by id from further execution by - placing it in the suspended state. This state is additive to any other - blocked state that the task may already be in. The task will not execute - again until another task issues the ``rtems_task_resume`` directive for - this task and any blocked state has been removed. - -NOTES: - The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id. - In this case, the task will be suspended and a successful return code will - be returned when the task is resumed. - - Suspending a global task which does not reside on the local node will - generate a request to the remote node to suspend the specified task. - - If the task specified by id is already suspended, then the - ``RTEMS_ALREADY_SUSPENDED`` status code is returned. - -.. raw:: latex - - \clearpage - -.. index:: resuming a task -.. index:: rtems_task_resume - -.. _rtems_task_resume: - -TASK_RESUME - Resume a task ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_resume( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task resumed successfully - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_INCORRECT_STATE`` - - task not suspended - -DESCRIPTION: - This directive removes the task specified by id from the suspended state. - If the task is in the ready state after the suspension is removed, then it - will be scheduled to run. If the task is still in a blocked state after - the suspension is removed, then it will remain in that blocked state. - -NOTES: - The running task may be preempted if its preemption mode is enabled and the - local task being resumed has a higher priority. - - Resuming a global task which does not reside on the local node will - generate a request to the remote node to resume the specified task. - - If the task specified by id is not suspended, then the - ``RTEMS_INCORRECT_STATE`` status code is returned. - -.. raw:: latex - - \clearpage - -.. index:: is task suspended -.. index:: rtems_task_is_suspended - -.. _rtems_task_is_suspended: - -TASK_IS_SUSPENDED - Determine if a task is Suspended ----------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_is_suspended( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task is NOT suspended - * - ``RTEMS_ALREADY_SUSPENDED`` - - task is currently suspended - * - ``RTEMS_INVALID_ID`` - - task id invalid - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive returns a status code indicating whether or not the - specified task is currently suspended. - -NOTES: - This operation is not currently supported on remote tasks. - -.. raw:: latex - - \clearpage - -.. index:: rtems_task_set_priority -.. index:: current task priority -.. index:: set task priority -.. index:: get task priority -.. index:: obtain task priority - -.. _rtems_task_set_priority: - -TASK_SET_PRIORITY - Set task priority -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_priority( - rtems_id id, - rtems_task_priority new_priority, - rtems_task_priority *old_priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task priority set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid return argument pointer - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - -DESCRIPTION: - This directive manipulates the priority of the task specified by id. An id - of ``RTEMS_SELF`` is used to indicate the calling task. When new_priority - is not equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous - priority is returned in old_priority. When new_priority is - ``RTEMS_CURRENT_PRIORITY``, the specified task's current priority is - returned in old_priority. Valid priorities range from a high of 1 to a low - of 255. - -NOTES: - The calling task may be preempted if its preemption mode is enabled and it - lowers its own priority or raises another task's priority. - - In case the new priority equals the current priority of the task, then - nothing happens. - - Setting the priority of a global task which does not reside on the local - node will generate a request to the remote node to change the priority of - the specified task. - - If the task specified by id is currently holding any binary semaphores - which use the priority inheritance algorithm, then the task's priority - cannot be lowered immediately. If the task's priority were lowered - immediately, then priority inversion results. The requested lowering of - the task's priority will occur when the task has released all priority - inheritance binary semaphores. The task's priority can be increased - regardless of the task's use of priority inheritance binary semaphores. - -.. raw:: latex - - \clearpage - -.. index:: rtems_task_get_priority -.. index:: current task priority -.. index:: get task priority -.. index:: obtain task priority - -.. _rtems_task_get_priority: - -TASK_GET_PRIORITY - Get task priority -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_priority( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority *priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - Successful operation. - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - Directive is illegal on remote tasks. - * - ``RTEMS_INVALID_ADDRESS`` - - The priority parameter is NULL. - * - ``RTEMS_INVALID_ID`` - - Invalid task or scheduler identifier. - * - ``RTEMS_NOT_DEFINED`` - - The task has no priority within the specified scheduler instance. - This error is only possible in SMP configurations. - -DESCRIPTION: - This directive returns the current priority of the task specified by - :c:data:`task_id` with respect to the scheduler instance specified by - :c:data:`scheduler_id`. A task id of :c:macro:`RTEMS_SELF` is used to - indicate the calling task. - -NOTES: - The current priority reflects temporary priority adjustments due to locking - protocols, the rate-monotonic period objects on some schedulers and other - mechanisms. - -.. raw:: latex - - \clearpage - -.. index:: current task mode -.. index:: set task mode -.. index:: get task mode -.. index:: set task preemption mode -.. index:: get task preemption mode -.. index:: obtain task mode -.. index:: rtems_task_mode - -.. _rtems_task_mode: - -TASK_MODE - Change the current task mode ----------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_mode( - rtems_mode mode_set, - rtems_mode mask, - rtems_mode *previous_mode_set - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - task mode set successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``previous_mode_set`` is NULL - - not enough memory for stack/FP context - * - ``RTEMS_NOT_IMPLEMENTED`` - - non-preemption mode not supported on SMP system - * - ``RTEMS_NOT_IMPLEMENTED`` - -DESCRIPTION: - This directive manipulates the execution mode of the calling task. A - task's execution mode enables and disables preemption, timeslicing, - asynchronous signal processing, as well as specifying the current interrupt - level. To modify an execution mode, the mode class(es) to be changed must - be specified in the mask parameter and the desired mode(s) must be - specified in the mode parameter. - -NOTES: - The calling task will be preempted if it enables preemption and a higher - priority task is ready to run. - - Enabling timeslicing has no effect if preemption is disabled. For a task - to be timesliced, that task must have both preemption and timeslicing - enabled. - - A task can obtain its current execution mode, without modifying it, by - calling this directive with a mask value of ``RTEMS_CURRENT_MODE``. - - To temporarily disable the processing of a valid ASR, a task should call - this directive with the ``RTEMS_NO_ASR`` indicator specified in mode. - - The set of task mode constants and each mode's corresponding mask constant - is provided in the following table: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption - * - ``RTEMS_NO_PREEMPT`` - - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption - * - ``RTEMS_NO_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing - * - ``RTEMS_TIMESLICE`` - - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing - * - ``RTEMS_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing - * - ``RTEMS_NO_ASR`` - - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing - * - ``RTEMS_INTERRUPT_LEVEL(0)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts - * - ``RTEMS_INTERRUPT_LEVEL(n)`` - - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n - -.. raw:: latex - - \clearpage - -.. index:: delay a task for an interval -.. index:: wake up after an interval -.. index:: rtems_task_wake_after - -.. _rtems_task_wake_after: - -TASK_WAKE_AFTER - Wake up after interval ----------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_wake_after( - rtems_interval ticks - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - always successful - -DESCRIPTION: - This directive blocks the calling task for the specified number of system - clock ticks. When the requested interval has elapsed, the task is made - ready. The clock tick directives automatically updates the delay period. - -NOTES: - Setting the system date and time with the ``rtems_clock_set`` directive has - no effect on a ``rtems_task_wake_after`` blocked task. - - A task may give up the processor and remain in the ready state by - specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks. - - The maximum timer interval that can be specified is the maximum value which - can be represented by the uint32_t type. - - A clock tick is required to support the functionality of this directive. - -.. raw:: latex - - \clearpage - -.. index:: delay a task until a wall time -.. index:: wake up at a wall time -.. index:: rtems_task_wake_when - -.. _rtems_task_wake_when: - -TASK_WAKE_WHEN - Wake up when specified ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_wake_when( - rtems_time_of_day *time_buffer - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - awakened at date/time successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL - * - ``RTEMS_INVALID_TIME_OF_DAY`` - - invalid time buffer - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - -DESCRIPTION: - This directive blocks a task until the date and time specified in - time_buffer. At the requested date and time, the calling task will be - unblocked and made ready to execute. - -NOTES: - The ticks portion of time_buffer structure is ignored. The timing - granularity of this directive is a second. - - A clock tick is required to support the functionality of this directive. - -.. raw:: latex - - \clearpage - -.. _rtems_task_get_scheduler: - -TASK_GET_SCHEDULER - Get scheduler of a task --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_scheduler( - rtems_id task_id, - rtems_id *scheduler_id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``scheduler_id`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - -DESCRIPTION: - Returns the scheduler identifier of a task identified by ``task_id`` in - ``scheduler_id``. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_task_set_scheduler: -.. _TASK_SET_SCHEDULER - Set scheduler of a task: - -TASK_SET_SCHEDULER - Set scheduler of a task --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_scheduler( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority priority - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ID`` - - invalid task or scheduler id - * - ``RTEMS_INVALID_PRIORITY`` - - invalid task priority - * - ``RTEMS_RESOURCE_IN_USE`` - - the task is in the wrong state to perform a scheduler change - * - ``RTEMS_UNSATISFIED`` - - the processor set of the scheduler is empty - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - Sets the scheduler of a task identified by ``task_id`` to the scheduler - identified by ``scheduler_id``. The scheduler of a task is initialized to - the scheduler of the task that created it. The priority of the task is set - to ``priority``. - -NOTES: - It is recommended to set the scheduler of a task before it is started or in - case it is guaranteed that the task owns no resources. Otherwise, sporadic - ``RTEMS_RESOURCE_IN_USE`` errors may occur. - -EXAMPLE: - .. code-block:: c - :linenos: - - #include <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 ); - } - -.. raw:: latex - - \clearpage - -.. _rtems_task_get_affinity: - -TASK_GET_AFFINITY - Get task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_affinity( - rtems_id id, - size_t cpusetsize, - cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - the affinity set buffer is too small for the current processor affinity - set of the task - -DESCRIPTION: - Returns the current processor affinity set of the task in ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - The task processor affinity is initialized to the set of online processors. - -.. raw:: latex - - \clearpage - -.. _rtems_task_set_affinity: - -TASK_SET_AFFINITY - Set task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_affinity( - rtems_id id, - size_t cpusetsize, - const cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid processor affinity set - -DESCRIPTION: - Sets the processor affinity set for the task specified by ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - This function will not change the scheduler of the task. The intersection - of the processor affinity set and the set of processors owned by the - scheduler of the task must be non-empty. It is not an error if the - processor affinity set contains processors that are not part of the set of - processors owned by the scheduler instance of the task. A task will simply - not run under normal circumstances on these processors since the scheduler - ignores them. Some locking protocols may temporarily use processors that - are not included in the processor affinity set of the task. It is also not - an error if the processor affinity set contains processors that are not - part of the system. - - In case a scheduler without support for task affinites is used for the - task, then the task processor affinity set must contain all online - processors of the system. This prevents odd corner cases if processors are - added/removed at run-time to/from scheduler instances. - -.. raw:: latex - - \clearpage - -.. index:: iterate over all threads -.. index:: rtems_task_iterate - -.. _rtems_task_iterate: - -TASK_ITERATE - Iterate Over Tasks ---------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg ); - - void rtems_task_iterate( - rtems_task_visitor visitor, - void *arg - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - Iterates over all tasks in the system. This operation covers all tasks of - all APIs. The user should be careful in accessing the contents of the - thread control block :c:data:`tcb`. The visitor argument :c:data:`arg` is - passed to all invocations of :c:data:`visitor` in addition to the thread - control block. The iteration stops immediately in case the visitor - function returns true. - -NOTES: - Must be called from task context. This operation obtains and releases the - objects allocator lock. The task visitor is called while owning the objects - allocator lock. It is possible to perform blocking operations in the task - visitor, however, take care that no deadlocks via the object allocator lock - can occur. - -Deprecated and Removed Directives -================================= - -.. raw:: latex - - \clearpage - -.. index:: rtems_iterate_over_all_threads - -.. _rtems_iterate_over_all_threads: - -ITERATE_OVER_ALL_THREADS - Iterate Over Tasks ---------------------------------------------- - -.. warning:: - - This directive is deprecated. Its use is unsafe. Use - :ref:`rtems_task_iterate` instead. - -CALLING SEQUENCE: - .. code-block:: c - - typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); - void rtems_iterate_over_all_threads( - rtems_per_thread_routine routine - ); - -DIRECTIVE STATUS CODES: - NONE - -DESCRIPTION: - This directive iterates over all of the existant threads in the system and - invokes ``routine`` on each of them. The user should be careful in - accessing the contents of ``the_thread``. - - This routine is intended for use in diagnostic utilities and is not - intented for routine use in an operational system. - -NOTES: - There is **no protection** while this routine is called. The thread - control block may be in an inconsistent state or may change due to - interrupts or activity on other processors. - -.. raw:: latex - - \clearpage - -.. index:: get task notepad entry -.. index:: rtems_task_get_note - -.. _rtems_task_get_note: - -TASK_GET_NOTE - Get task notepad entry --------------------------------------- - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_note( - rtems_id id, - uint32_t notepad, - uint32_t *note - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - note value obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``note`` parameter is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid notepad location - -DESCRIPTION: - This directive returns the note contained in the notepad location of the - task specified by id. - -NOTES: - This directive will not cause the running task to be preempted. - - If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. - - The sixteen notepad locations can be accessed using the constants - ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. - - Getting a note of a global task which does not reside on the local node - will generate a request to the remote node to obtain the notepad entry of - the specified task. - -.. raw:: latex - - \clearpage - -.. index:: set task notepad entry -.. index:: rtems_task_set_note - -.. _rtems_task_set_note: - -TASK_SET_NOTE - Set task notepad entry --------------------------------------- - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_note( - rtems_id id, - uint32_t notepad, - uint32_t note - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - note set successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid notepad location - -DESCRIPTION: - This directive sets the notepad entry for the task specified by id to the - value note. - -NOTES: - If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own - notepad. - - This directive will not cause the running task to be preempted. - - The sixteen notepad locations can be accessed using the constants - ``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. - - Setting a note of a global task which does not reside on the local node - will generate a request to the remote node to set the notepad entry of the - specified task. - -.. raw:: latex - - \clearpage - -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data -.. index:: rtems_task_variable_add - -.. _rtems_task_variable_add: - -TASK_VARIABLE_ADD - Associate per task variable ------------------------------------------------ - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_variable_add( - rtems_id tid, - void **task_variable, - void (*dtor)(void *) - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable added successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive adds the memory location specified by the ptr argument to - the context of the given task. The variable will then be private to the - task. The task can access and modify the variable, but the modifications - will not appear to other tasks, and other tasks' modifications to that - variable will not affect the value seen by the task. This is accomplished - by saving and restoring the variable's value each time a task switch occurs - to or from the calling task. If the dtor argument is non-NULL it specifies - the address of a 'destructor' function which will be called when the task - is deleted. The argument passed to the destructor function is the task's - value of the variable. - -NOTES: - Task variables increase the context switch time to and from the tasks that - own them so it is desirable to minimize the number of task variables. One - efficient method is to have a single task variable that is a pointer to a - dynamically allocated structure containing the task's private 'global' - data. In this case the destructor function could be 'free'. - - Per-task variables are disabled in SMP configurations and this service is - not available. - -.. raw:: latex - - \clearpage - -.. index:: get per-task variable -.. index:: obtain per-task variable -.. index:: rtems_task_variable_get - -.. _rtems_task_variable_get: - -TASK_VARIABLE_GET - Obtain value of a per task variable -------------------------------------------------------- - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_variable_get( - rtems_id tid, - void **task_variable, - void **task_variable_value - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable_value`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is not found - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive looks up the private value of a task variable for a - specified task and stores that value in the location pointed to by the - result argument. The specified task is usually not the calling task, which - can get its private value by directly accessing the variable. - -NOTES: - If you change memory which ``task_variable_value`` points to, remember to - declare that memory as volatile, so that the compiler will optimize it - correctly. In this case both the pointer ``task_variable_value`` and data - referenced by ``task_variable_value`` should be considered volatile. - - Per-task variables are disabled in SMP configurations and this service is - not available. - -.. raw:: latex - - \clearpage - -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data -.. index:: rtems_task_variable_delete - -.. _rtems_task_variable_delete: - -TASK_VARIABLE_DELETE - Remove per task variable ------------------------------------------------ - -.. warning:: - - This directive was removed in RTEMS 5.1. - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_variable_delete( - rtems_id id, - void **task_variable - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - per task variable deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_NO_MEMORY`` - - invalid task id - * - ``RTEMS_INVALID_ADDRESS`` - - ``task_variable`` is NULL - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - not supported on remote tasks - -DESCRIPTION: - This directive removes the given location from a task's context. - -NOTES: - Per-task variables are disabled in SMP configurations and this service is - not available. |