[rtems-docs commit] c-user: Move deprecated/removed directives
Sebastian Huber
sebh at rtems.org
Wed Feb 17 17:46:36 UTC 2021
Module: rtems-docs
Branch: master
Commit: 698580033b5e8d367d9d8146f567ad14b763f064
Changeset: http://git.rtems.org/rtems-docs/commit/?id=698580033b5e8d367d9d8146f567ad14b763f064
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Feb 10 16:51:25 2021 +0100
c-user: Move deprecated/removed directives
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/clock/index.rst | 1 +
c-user/clock/removed-directives.rst | 81 ++++++++++
c-user/task/deprecated-directives.rst | 46 ++++++
c-user/task/index.rst | 2 +
c-user/task/removed-directives.rst | 283 ++++++++++++++++++++++++++++++++++
5 files changed, 413 insertions(+)
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.
More information about the vc
mailing list