From dc2b3376dd0e71c9f485f9429a6f81178d769cfa Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 16 Nov 1999 18:28:20 +0000 Subject: Added task variable services. --- doc/user/Makefile | 2 +- doc/user/task.t | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 131 insertions(+), 1 deletion(-) (limited to 'doc/user') 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 + -- cgit v1.2.3