From 698580033b5e8d367d9d8146f567ad14b763f064 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 10 Feb 2021 16:51:25 +0100 Subject: 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(+) create mode 100644 c-user/clock/removed-directives.rst create mode 100644 c-user/task/deprecated-directives.rst create mode 100644 c-user/task/removed-directives.rst (limited to 'c-user') 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. -- cgit v1.2.3