summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>1999-11-16 18:28:20 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>1999-11-16 18:28:20 +0000
commitdc2b3376dd0e71c9f485f9429a6f81178d769cfa (patch)
tree3b150cfbfa9f71fff1bc7f5f104fb773115b42dd /doc/user
parent1dbf307fd66ca7da50632ed80d5aee065053fbf1 (diff)
downloadrtems-dc2b3376dd0e71c9f485f9429a6f81178d769cfa.tar.bz2
Added task variable services.
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/Makefile2
-rw-r--r--doc/user/task.t130
2 files changed, 131 insertions, 1 deletions
diff --git a/doc/user/Makefile b/doc/user/Makefile
index 605701b095..c165ee8daa 100644
--- a/doc/user/Makefile
+++ b/doc/user/Makefile
@@ -95,7 +95,7 @@ task.texi: task.t
-n "Interrupt Manager" ${*}.t
intr.texi: intr.t
- $(BMENU) -p "Task Manager TASK_WAKE_WHEN - Wake up when specified" \
+ $(BMENU) -p "Task Manager TASK_VARIABLE_DELETE - Remove per task variable" \
-u "Top" \
-n "Clock Manager" ${*}.t
diff --git a/doc/user/task.t b/doc/user/task.t
index 9a7c03bfba..2951ce5226 100644
--- a/doc/user/task.t
+++ b/doc/user/task.t
@@ -31,6 +31,8 @@ by the task manager are:
@item @code{@value{DIRPREFIX}task_set_note} - Set task notepad entry
@item @code{@value{DIRPREFIX}task_wake_after} - Wake up after interval
@item @code{@value{DIRPREFIX}task_wake_when} - Wake up when specified
+@item @code{@value{DIRPREFIX}task_variable_add} - Associate per task variable
+@item @code{@value{DIRPREFIX}task_variable_delete} - Remove per task variable
@end itemize
@section Background
@@ -286,6 +288,35 @@ attribute. The consequence of a @code{@value{RPREFIX}NO_FLOATING_POINT}
task attempting to access the floating point unit is CPU dependent but will
generally result in an exception condition.
+@subsection Per Task Variables
+
+@cindex per task variables
+
+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 or pre-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.
+
+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
+@code{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.
+
@subsection Building a Task Attribute Set
@cindex task attributes, building
@@ -1544,3 +1575,102 @@ The ticks portion of time_buffer @value{STRUCTURE} is ignored. The
timing granularity of this directive is a second.
A clock tick is required to support the functionality of this directive.
+
+@page
+
+@subsection TASK_VARIABLE_ADD - Associate per task variable
+
+@cindex per-task variable
+@cindex task private variable
+@cindex task private data
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_task_variable_add
+@example
+rtems_status_code rtems_task_variable_add(
+ rtems_id tid,
+ int *ptr
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@example
+procedure Task_Variable_Add (
+ Id : in RTEMS.ID;
+ Ptr : in RTEMS.Address;
+ Result : out RTEMS.Status_Codes
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
+@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
+@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
+@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks
+@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set
+
+@subheading 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.
+
+@subheading 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.
+
+@page
+
+@subsection TASK_VARIABLE_DELETE - Remove per task variable
+
+@cindex per-task variable
+@cindex task private variable
+@cindex task private data
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_task_variable_delete
+@example
+rtems_status_code rtems_task_variable_delete(
+ rtems_id tid,
+ int *ptr
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@example
+procedure Task_Variable_Delete (
+ Id : in RTEMS.ID;
+ Ptr : in RTEMS.Address;
+ Result : out RTEMS.Status_Codes
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
+@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
+@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
+@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks
+@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set
+
+@subheading DESCRIPTION:
+This directive removes the given location from a task's context.
+
+@subheading NOTES:
+
+NONE
+