diff options
Diffstat (limited to '')
| -rw-r--r-- | ada_user/task_manager.rst | 1417 |
1 files changed, 0 insertions, 1417 deletions
diff --git a/ada_user/task_manager.rst b/ada_user/task_manager.rst deleted file mode 100644 index 174409f..0000000 --- a/ada_user/task_manager.rst +++ /dev/null @@ -1,1417 +0,0 @@ -Task Manager -############ - -.. index:: tasks - -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_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_mode`` - Change current task’s mode - -- ``rtems.task_wake_after`` - Wake up after interval - -- ``rtems.task_wake_when`` - Wake up when specified - -- ``rtems.iterate_over_all_threads`` - Iterate Over Tasks - -- ``rtems.task_variable_add`` - Associate per task variable - -- ``rtems.task_variable_get`` - Obtain value of a a per task variable - -- ``rtems.task_variable_delete`` - Remove per task variable - -Background -========== - -Task Definition ---------------- -.. index:: 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. - -Task States ------------ -.. index:: 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. - -Task Priority -------------- -.. index:: task priority -.. index:: priority, task -.. index:: rtems_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. - -Task Mode ---------- -.. index:: task mode -.. index:: rtems_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. - -- ``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. - -Accessing Task Arguments ------------------------- -.. index:: task arguments -.. index:: task prototype - -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: - -.. code:: c - - procedure User_Task ( - Argument : in RTEMS.Task_Argument_Ptr - ); - -Application tasks requiring more information may view this -single argument as an index into an array of parameter blocks. - -Floating Point Considerations ------------------------------ -.. index:: floating point - -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. - -Per Task Variables ------------------- -.. index:: per task variables - -Per task variables are deprecated, see the warning below. - -Per task variables are used to support global variables whose value -may be unique to a task. After indicating that a variable should be -treated as private (i.e. per-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. - -The value seen by other tasks, including those which have not added the -variable to their set and are thus accessing the variable as a common -location shared among tasks, cannot be affected by a task once it has -added a variable to its local set. Changes made to the variable by -other tasks will not affect the value seen by a task which has added the -variable to its private set. - -This feature can be used when a routine is to be spawned repeatedly as -several independent tasks. Although each task will have its own stack, -and thus separate stack variables, they will all share the same static and -global variables. To make a variable not shareable (i.e. a "global" variable -that is specific to a single task), the tasks can call``rtems_task_variable_add`` to make a separate copy of the variable -for each task, but all at the same physical address. - -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. - -A critical point with per-task variables is that each task must separately -request that the same global variable is per-task private. - -*WARNING*: Per-Task variables are inherently broken on SMP systems. They -only work correctly when there is one task executing in the system and -that task is the logical owner of the value in the per-task variable’s -location. There is no way for a single memory image to contain the -correct value for each task executing on each core. Consequently, -per-task variables are disabled in SMP configurations of RTEMS. -Instead the application developer should -consider the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys -are not enabled in all RTEMS configurations. - -Building a Task Attribute Set ------------------------------ -.. index:: task attributes, building - -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: - -- ``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 or 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 or RTEMS.FLOATING_POINT``. - -Building a Mode and Mask ------------------------- -.. index:: task mode, building - -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: - -- ``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) or -RTEMS.NO_PREEMPT`` to indicate the desired preemption mode and -interrupt level, while the mask parameter should be set to``RTEMS.INTERRUPT_MASK or -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. - -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. - -Transition Advice for Obsolete Directives ------------------------------------------ - -Notepads -~~~~~~~~ - -Task notepads and the associated directives``rtems.task_get_note`` and``rtems.task_set_note`` were removed after the 4.11 Release -Series. 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 is -an option for some use cases. - -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. - -TASK_CREATE - Create a task ---------------------------- -.. index:: create a task - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Create ( - Name : in RTEMS.Name; - Initial_Priority : in RTEMS.Task_Priority; - Stack_Size : in RTEMS.Unsigned32; - Initial_Modes : in RTEMS.Mode; - Attribute_Set : in RTEMS.Attribute; - ID : out RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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`` - is 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 that 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: - -- ``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: - -- ``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. - -TASK_IDENT - Get ID of a task ------------------------------ -.. index:: get ID of a task - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Ident ( - Name : in RTEMS.Name; - Node : in RTEMS.Node; - ID : out RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -TASK_SELF - Obtain ID of caller -------------------------------- -.. index:: obtain ID of caller - -**CALLING SEQUENCE:** - -.. code:: c - - function Task_Self return RTEMS.ID; - -**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. - -TASK_START - Start a task -------------------------- -.. index:: starting a task - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Start ( - ID : in RTEMS.ID; - Entry_Point : in RTEMS.Task_Entry; - Argument : in RTEMS.Task_Argument; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -TASK_RESTART - Restart a task ------------------------------ -.. index:: restarting a task - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Restart ( - ID : in RTEMS.ID; - Argument : in RTEMS.Task_Argument; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -TASK_DELETE - Delete a task ---------------------------- -.. index:: deleting a task - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Delete ( - ID : in RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -TASK_SUSPEND - Suspend a task ------------------------------ -.. index:: suspending a task - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Suspend ( - ID : in RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -TASK_RESUME - Resume a task ---------------------------- -.. index:: resuming a task - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Resume ( - ID : in RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -TASK_IS_SUSPENDED - Determine if a task is Suspended ----------------------------------------------------- -.. index:: is task suspended - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Is_Suspended ( - ID : in RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -TASK_SET_PRIORITY - Set task priority -------------------------------------- -.. index:: rtems_task_set_priority -.. index:: current task priority -.. index:: set task priority -.. index:: get task priority -.. index:: obtain task priority - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Set_Priority ( - ID : in RTEMS.ID; - New_Priority : in RTEMS.Task_Priority; - Old_Priority : out RTEMS.Task_Priority; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -TASK_MODE - Change the current task mode ----------------------------------------- -.. index:: current task mode -.. index:: set task mode -.. index:: get task mode -.. index:: set task preemption mode -.. index:: get task preemption mode -.. index:: obtain task mode - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Mode ( - Mode_Set : in RTEMS.Mode; - Mask : in RTEMS.Mode; - Previous_Mode_Set : in RTEMS.Mode; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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: - -- ``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 - -TASK_WAKE_AFTER - Wake up after interval ----------------------------------------- -.. index:: delay a task for an interval -.. index:: wake up after an interval - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Wake_After ( - Ticks : in RTEMS.Interval; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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 ``rtems.clock_tick`` -directive 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. - -TASK_WAKE_WHEN - Wake up when specified ---------------------------------------- -.. index:: delay a task until a wall time -.. index:: wake up at a wall time - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Wake_When ( - Time_Buffer : in RTEMS.Time_Of_Day; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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 record is ignored. The -timing granularity of this directive is a second. - -A clock tick is required to support the functionality of this directive. - -ITERATE_OVER_ALL_THREADS - Iterate Over Tasks ---------------------------------------------- -.. index:: iterate over all threads - -**CALLING SEQUENCE:** - -.. code:: c - - NOT SUPPORTED FROM Ada BINDING - -**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. 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. - -TASK_VARIABLE_ADD - Associate per task variable ------------------------------------------------ -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data - -**CALLING SEQUENCE:** - -.. code:: c - - type Task_Variable_Dtor is access procedure ( - Argument : in RTEMS.Address; - ); - procedure Task_Variable_Add ( - ID : in RTEMS.ID; - Task_Variable : in RTEMS.Address; - Dtor : in RTEMS.Task_Variable_Dtor; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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:** - -This directive is deprecated and task variables will be removed. - -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. - -TASK_VARIABLE_GET - Obtain value of a per task variable -------------------------------------------------------- -.. index:: get per-task variable -.. index:: obtain per-task variable - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Variable_Get ( - ID : in RTEMS.ID; - Task_Variable : out RTEMS.Address; - Task_Variable_Value : out RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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:** - -This directive is deprecated and task variables will be removed. - -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. - -TASK_VARIABLE_DELETE - Remove per task variable ------------------------------------------------ -.. index:: per-task variable -.. index:: task private variable -.. index:: task private data - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Task_Variable_Delete ( - ID : in RTEMS.ID; - Task_Variable : out RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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:** - -This directive is deprecated and task variables will be removed. - -Per-task variables are disabled in SMP configurations and this service -is not available. - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - |