cpukit: deprecate task variables. closes #2293.

4 files changed, 26 insertions, 4 deletions

diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index 237ec19093..dc12d0bdeb 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -462,6 +462,8 @@ rtems_status_code rtems_task_is_suspended(
 /**
  *  @brief RTEMS Add Task Variable
  *
+ *  @deprecated Task variables are deprecated.
+ *
  *  This directive adds a per task variable.
  *
  *  @note This service is not available in SMP configurations.
@@ -470,11 +472,13 @@ rtems_status_code rtems_task_variable_add(
   rtems_id  tid,
   void    **ptr,
   void    (*dtor)(void *)
-);
+) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
 
 /**
  *  @brief Get a per-task variable
  *
+ *  @deprecated Task variables are deprecated.
+ *
  *  This directive gets the value of a task variable.
  *
  *  @note This service is not available in SMP configurations.
@@ -483,11 +487,13 @@ rtems_status_code rtems_task_variable_get(
   rtems_id tid,
   void **ptr,
   void **result
-);
+) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
 
 /**
  *  @brief RTEMS Delete Task Variable
  *
+ *  @deprecated Task variables are deprecated.
+ *
  *  This directive removes a per task variable.
  *
  *  @note This service is not available in SMP configurations.
@@ -495,7 +501,7 @@ rtems_status_code rtems_task_variable_get(
 rtems_status_code rtems_task_variable_delete(
   rtems_id  tid,
   void    **ptr
-);
+) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
 #endif
 
 #if defined(__RTEMS_HAVE_SYS_CPUSET_H__)
diff --git a/cpukit/rtems/include/rtems/rtems/tasksimpl.h b/cpukit/rtems/include/rtems/rtems/tasksimpl.h
index 280be2fac8..b8f91d3607 100644
--- a/cpukit/rtems/include/rtems/rtems/tasksimpl.h
+++ b/cpukit/rtems/include/rtems/rtems/tasksimpl.h
@@ -70,13 +70,15 @@ void _RTEMS_tasks_Initialize_user_tasks( void );
 /**
  *  @brief RTEMS Tasks Invoke Task Variable Destructor
  *
+ *  @deprecated Task variables are deprecated.
+ *
  *  This routine invokes the optional user provided destructor on the
  *  task variable and frees the memory for the task variable.
  */
 void _RTEMS_Tasks_Invoke_task_variable_dtor(
   Thread_Control        *the_thread,
   rtems_task_variable_t *tvp
-);
+) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
 #endif
 
 RTEMS_INLINE_ROUTINE Thread_Control *_RTEMS_tasks_Allocate(void)
diff --git a/cpukit/sapi/include/confdefs.h b/cpukit/sapi/include/confdefs.h
index 0bebb4ed0d..2b4e27fd2a 100644
--- a/cpukit/sapi/include/confdefs.h
+++ b/cpukit/sapi/include/confdefs.h
@@ -1823,6 +1823,8 @@ const rtems_libio_helper rtems_fs_init_helper =
 /**
  * This macro calculates the memory required for task variables.
  *
+ * @deprecated Task variables are deprecated.
+ *
  * Each task variable is individually allocated from the Workspace.
  * Hence, we do the multiplication on the configured size.
  *
@@ -1839,6 +1841,7 @@ const rtems_libio_helper rtems_fs_init_helper =
     #define CONFIGURE_MAXIMUM_TASK_VARIABLES                     0
     #define CONFIGURE_MEMORY_FOR_TASK_VARIABLES(_task_variables) 0
   #else
+    #warning "Per-Task Variables are deprecated and will be removed."
     #define CONFIGURE_MEMORY_FOR_TASK_VARIABLES(_task_variables) \
       (_task_variables) * \
          _Configure_From_workspace(sizeof(rtems_task_variable_t))
diff --git a/doc/user/task.t b/doc/user/task.t
index 5aec9b19cc..5606c4adc3 100644
--- a/doc/user/task.t
+++ b/doc/user/task.t
@@ -308,6 +308,8 @@ generally result in an exception condition.
 
 @cindex 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
@@ -346,6 +348,9 @@ 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.
 
 @subsection Building a Task Attribute Set
 
@@ -1787,6 +1792,8 @@ passed to the destructor function is the task's value of the variable.
 
 @subheading 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
@@ -1844,6 +1851,8 @@ task, which can get its private value by directly accessing the variable.
 
 @subheading NOTES:
 
+This directive is deprecated and task variables will be removed.
+
 If you change memory which @code{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
@@ -1895,6 +1904,8 @@ This directive removes the given location from a task's context.
 
 @subheading 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.