[PATCH] c-user: Clarify timer manager documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Feb 3 05:33:35 UTC 2021
Unify the wording across similar directives of other managers. Add
"CONSTRAINTS" section.
Update #3993.
---
c-user/timer/directives.rst | 198 ++++++++++++++++++++++++++--------
c-user/timer/index.rst | 2 +
c-user/timer/introduction.rst | 2 +-
3 files changed, 157 insertions(+), 45 deletions(-)
diff --git a/c-user/timer/directives.rst b/c-user/timer/directives.rst
index a4d1b64..31760d6 100644
--- a/c-user/timer/directives.rst
+++ b/c-user/timer/directives.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically
@@ -52,18 +52,19 @@ Creates a timer.
.. rubric:: PARAMETERS:
``name``
- This parameter is the name of the timer.
+ This parameter is the object name of the timer.
``id``
This parameter is the pointer to an object identifier variable. The
- identifier of the created timer object will be stored in this variable, in
- case of a successful operation.
+ identifier of the created timer will be stored in this variable, in case of
+ a successful operation.
.. rubric:: DESCRIPTION:
-This directive creates a timer. The assigned object identifier is returned in
-``id``. This identifier is used to access the timer with other timer related
-directives.
+This directive creates a timer which resides on the local node. The timer has
+the user-defined object name specified in ``name``. The assigned object
+identifier is returned in ``id``. This identifier is used to access the timer
+with other timer related directives.
.. rubric:: RETURN VALUES:
@@ -71,28 +72,42 @@ directives.
The requested operation was successful.
:c:macro:`RTEMS_INVALID_NAME`
- The timer name was invalid.
+ The ``name`` parameter was invalid.
:c:macro:`RTEMS_INVALID_ADDRESS`
The ``id`` parameter was `NULL
<https://en.cppreference.com/w/c/types/NULL>`_.
:c:macro:`RTEMS_TOO_MANY`
- There was no inactive object available to create a new timer. The number
- of timers available to the application is configured through the
- :ref:`CONFIGURE_MAXIMUM_TIMERS` configuration option.
+ There was no inactive object available to create a timer. The number of
+ timers available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_TIMERS` application configuration option.
.. rubric:: NOTES:
-This directive may cause the calling task to be preempted due to an obtain and
-release of the object allocator mutex.
+The processor used to maintain the timer is the processor of the calling task
+at some point during the timer creation.
For control and maintenance of the timer, RTEMS allocates a :term:`TMCB` from
the local TMCB free pool and initializes it.
-In SMP configurations, the processor of the currently executing thread
-determines the processor used for the created timer. During the life-time of
-the timer this processor is used to manage the timer internally.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The number of timers available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_TIMERS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
.. Generated from spec:/rtems/timer/if/ident
@@ -128,7 +143,7 @@ Identifies a timer by the object name.
.. rubric:: DESCRIPTION:
-This directive obtains the timer identifier associated with the timer name
+This directive obtains a timer identifier associated with the timer name
specified in ``name``.
.. rubric:: RETURN VALUES:
@@ -150,12 +165,22 @@ specified in ``name``.
If the timer name is not unique, then the timer identifier will match the first
timer with that name in the search order. However, this timer identifier is
-not guaranteed to correspond to the desired timer. The timer identifier is
-used with other timer related directives to access the timer.
+not guaranteed to correspond to the desired timer.
The objects are searched from lowest to the highest index. Only the local node
is searched.
+The timer identifier is used with other timer related directives to access the
+timer.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
.. Generated from spec:/rtems/timer/if/cancel
.. raw:: latex
@@ -185,8 +210,8 @@ Cancels the timer.
.. rubric:: DESCRIPTION:
-This directive cancels the timer specified in the ``id`` parameter. This timer
-will be reinitiated by the next invocation of :ref:`InterfaceRtemsTimerReset`,
+This directive cancels the timer specified by ``id``. This timer will be
+reinitiated by the next invocation of :ref:`InterfaceRtemsTimerReset`,
:ref:`InterfaceRtemsTimerFireAfter`, or :ref:`InterfaceRtemsTimerFireWhen` with
the same timer identifier.
@@ -198,9 +223,17 @@ the same timer identifier.
:c:macro:`RTEMS_INVALID_ID`
There was no timer associated with the identifier specified by ``id``.
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
-This directive will not cause the running task to be preempted.
+* The directive will not cause the calling task to be preempted.
.. Generated from spec:/rtems/timer/if/delete
@@ -231,8 +264,8 @@ Deletes the timer.
.. rubric:: DESCRIPTION:
-This directive deletes the timer specified by the ``id`` parameter. If the
-timer is running, it is automatically canceled.
+This directive deletes the timer specified by ``id``. If the timer is running,
+it is automatically canceled.
.. rubric:: RETURN VALUES:
@@ -244,12 +277,24 @@ timer is running, it is automatically canceled.
.. rubric:: NOTES:
-This directive may cause the calling task to be preempted due to an obtain and
-release of the object allocator mutex.
-
The :term:`TMCB` for the deleted timer is reclaimed by RTEMS.
-A timer can be deleted by a task other than the task which created the timer.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The calling task does not have to be the task that created the object. Any
+ local task that knows the object identifier can delete the object.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may free memory to the RTEMS Workspace.
.. Generated from spec:/rtems/timer/if/fire-after
@@ -316,9 +361,17 @@ invoked with the argument ``user_data`` in the context of the clock tick
:c:macro:`RTEMS_INVALID_ID`
There was no timer associated with the identifier specified by ``id``.
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
-This directive will not cause the running task to be preempted.
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
.. Generated from spec:/rtems/timer/if/fire-when
@@ -391,9 +444,17 @@ argument ``user_data`` in the context of the clock tick :term:`ISR`.
:c:macro:`RTEMS_INVALID_ID`
There was no timer associated with the identifier specified by ``id``.
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
-This directive will not cause the running task to be preempted.
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
.. Generated from spec:/rtems/timer/if/initiate-server
@@ -464,12 +525,27 @@ executing all timers initiated via the
.. rubric:: NOTES:
-This directive may cause the calling task to be preempted due to an obtain and
-release of the object allocator mutex.
-
The Timer Server task is created using the :ref:`InterfaceRtemsTaskCreate`
directive and must be accounted for when configuring the system.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may obtain and release the object allocator mutex. This may
+ cause the calling task to be preempted.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The number of timers available to the application is configured through the
+ :ref:`CONFIGURE_MAXIMUM_TIMERS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+ unlimited objects, the directive may allocate memory from the RTEMS
+ Workspace.
+
.. Generated from spec:/rtems/timer/if/server-fire-after
.. raw:: latex
@@ -538,9 +614,17 @@ task.
:c:macro:`RTEMS_INVALID_ID`
There was no timer associated with the identifier specified by ``id``.
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
-This directive will not cause the running task to be preempted.
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
.. Generated from spec:/rtems/timer/if/server-fire-when
@@ -616,9 +700,17 @@ argument ``user_data`` in the context of the Timer Server task.
:c:macro:`RTEMS_INVALID_ID`
There was no timer associated with the identifier specified by ``id``.
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
-This directive will not cause the running task to be preempted.
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
.. Generated from spec:/rtems/timer/if/reset
@@ -669,8 +761,6 @@ timer service routine which the original :ref:`InterfaceRtemsTimerFireAfter` or
.. rubric:: NOTES:
-This directive will not cause the running task to be preempted.
-
If the timer has not been used or the last usage of this timer was by a
:ref:`InterfaceRtemsTimerFireWhen` or :ref:`InterfaceRtemsTimerServerFireWhen`
directive, then the :c:macro:`RTEMS_NOT_DEFINED` error is returned.
@@ -678,6 +768,18 @@ directive, then the :c:macro:`RTEMS_NOT_DEFINED` error is returned.
Restarting a cancelled after timer results in the timer being reinitiated with
its previous timer service routine and interval.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
.. Generated from spec:/rtems/timer/if/get-information
.. raw:: latex
@@ -728,6 +830,14 @@ This directive returns information about the timer.
:c:macro:`RTEMS_INVALID_ID`
There was no timer associated with the identifier specified by ``id``.
-.. rubric:: NOTES:
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
-This directive will not cause the running task to be preempted.
+* The directive will not cause the calling task to be preempted.
diff --git a/c-user/timer/index.rst b/c-user/timer/index.rst
index 48e726e..6557668 100644
--- a/c-user/timer/index.rst
+++ b/c-user/timer/index.rst
@@ -4,6 +4,8 @@
.. index:: timers
+.. _RTEMSAPIClassicTimer:
+
Timer Manager
*************
diff --git a/c-user/timer/introduction.rst b/c-user/timer/introduction.rst
index 6806898..76db7ff 100644
--- a/c-user/timer/introduction.rst
+++ b/c-user/timer/introduction.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically
--
2.26.2
More information about the devel
mailing list