mirror of
https://git.rtems.org/rtems-docs/
synced 2025-07-25 07:13:14 +08:00
c-user: Move deprecated/removed directives
This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993.
This commit is contained in:
parent
a1c5d680b9
commit
698580033b
@ -15,3 +15,4 @@ Clock Manager
|
|||||||
background
|
background
|
||||||
operations
|
operations
|
||||||
directives
|
directives
|
||||||
|
removed-directives
|
||||||
|
81
c-user/clock/removed-directives.rst
Normal file
81
c-user/clock/removed-directives.rst
Normal file
@ -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.
|
46
c-user/task/deprecated-directives.rst
Normal file
46
c-user/task/deprecated-directives.rst
Normal file
@ -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.
|
@ -15,3 +15,5 @@ Task Manager
|
|||||||
background
|
background
|
||||||
operations
|
operations
|
||||||
directives
|
directives
|
||||||
|
deprecated-directives
|
||||||
|
removed-directives
|
||||||
|
283
c-user/task/removed-directives.rst
Normal file
283
c-user/task/removed-directives.rst
Normal file
@ -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.
|
Loading…
x
Reference in New Issue
Block a user