mirror of
https://git.rtems.org/rtems-docs/
synced 2025-06-04 21:52:47 +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:
Sebastian Huber
parent
a1c5d680b9
commit
698580033b
@ -15,3 +15,4 @@ Clock Manager
|
||||
background
|
||||
operations
|
||||
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
|
||||
operations
|
||||
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