c-user: Move deprecated/removed directives

This makes it easier to automatically generate parts of the manager
documentation in the future.

Update #3993.

5 files changed, 413 insertions, 0 deletions

diff --git a/c-user/clock/index.rst b/c-user/clock/index.rst
index 11f2790..d84a37a 100644
--- a/c-user/clock/index.rst
+++ b/c-user/clock/index.rst
@@ -15,3 +15,4 @@ Clock Manager
     background
     operations
     directives
+    removed-directives
diff --git a/c-user/clock/removed-directives.rst b/c-user/clock/removed-directives.rst
new file mode 100644
index 0000000..d7fd775
--- /dev/null
+++ b/c-user/clock/removed-directives.rst
@@ -0,0 +1,81 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Removed Directives
+==================
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_clock_get:
+
+CLOCK_GET - Get date and time information
+-----------------------------------------
+.. index:: obtain the time of day
+.. index:: rtems_clock_get
+
+.. warning::
+
+    This directive was removed in RTEMS 5.1.  See also
+    :ref:`ClockManagerAdviceClockGet`.
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_clock_get(
+           rtems_clock_get_options  option,
+           void                    *time_buffer
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+      :class: rtems-table
+
+      * - ``RTEMS_SUCCESSFUL``
+        - current time obtained successfully
+      * - ``RTEMS_NOT_DEFINED``
+        - system date and time is not set
+      * - ``RTEMS_INVALID_ADDRESS``
+        - ``time_buffer`` is NULL
+
+DESCRIPTION:
+    This directive obtains the system date and time.  If the caller is
+    attempting to obtain the date and time (i.e.  option is set to either
+    ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or
+    ``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with
+    a previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED``
+    status code is returned.  The caller can always obtain the number of ticks
+    per second (option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number
+    of ticks since the executive was initialized option is
+    ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
+
+    The ``option`` argument may taken on any value of the enumerated type
+    ``rtems_clock_get_options``.  The data type expected for ``time_buffer`` is
+    based on the value of ``option`` as indicated below:
+
+    .. index:: rtems_clock_get_options
+
+    +-----------------------------------------+---------------------------+
+    | Option                                  | Return type               |
+    +=========================================+===========================+
+    | ``RTEMS_CLOCK_GET_TOD``                 | ``(rtems_time_of_day *)`` |
+    +-----------------------------------------+---------------------------+
+    | ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)``    |
+    +-----------------------------------------+---------------------------+
+    | ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``    | ``(rtems_interval *)``    |
+    +-----------------------------------------+---------------------------+
+    |``RTEMS_CLOCK_GET_TICKS_PER_SECOND``     | ``(rtems_interval *)``    |
+    +-----------------------------------------+---------------------------+
+    | ``RTEMS_CLOCK_GET_TIME_VALUE``          | ``(struct timeval *)``    |
+    +-----------------------------------------+---------------------------+
+
+NOTES:
+    This directive is callable from an ISR.
+
+    This directive will not cause the running task to be preempted.
+    Re-initializing RTEMS causes the system date and time to be reset to an
+    uninitialized state.  Another call to ``rtems_clock_set`` is required to
+    re-initialize the system date and time to application specific
+    specifications.
diff --git a/c-user/task/deprecated-directives.rst b/c-user/task/deprecated-directives.rst
new file mode 100644
index 0000000..107c5e0
--- /dev/null
+++ b/c-user/task/deprecated-directives.rst
@@ -0,0 +1,46 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Deprecated 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.
diff --git a/c-user/task/index.rst b/c-user/task/index.rst
index 2ce8edb..afe8b76 100644
--- a/c-user/task/index.rst
+++ b/c-user/task/index.rst
@@ -15,3 +15,5 @@ Task Manager
     background
     operations
     directives
+    deprecated-directives
+    removed-directives
diff --git a/c-user/task/removed-directives.rst b/c-user/task/removed-directives.rst
new file mode 100644
index 0000000..8c8aae9
--- /dev/null
+++ b/c-user/task/removed-directives.rst
@@ -0,0 +1,283 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Removed Directives
+==================
+
+.. 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.