[PATCH v2 14/16] c-user: Split up timer manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:01:08 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/index.rst | 2 +-
c-user/timer/background.rst | 71 +++++++
.../directives.rst} | 180 ------------------
c-user/timer/index.rst | 15 ++
c-user/timer/introduction.rst | 29 +++
c-user/timer/operations.rst | 84 ++++++++
6 files changed, 200 insertions(+), 181 deletions(-)
create mode 100644 c-user/timer/background.rst
rename c-user/{timer_manager.rst => timer/directives.rst} (64%)
create mode 100644 c-user/timer/index.rst
create mode 100644 c-user/timer/introduction.rst
create mode 100644 c-user/timer/operations.rst
diff --git a/c-user/index.rst b/c-user/index.rst
index 344b791..3507947 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -33,7 +33,7 @@ RTEMS Classic API Guide (|version|).
task/index
interrupt/index
clock/index
- timer_manager
+ timer/index
rate-monotonic/index
semaphore/index
barrier/index
diff --git a/c-user/timer/background.rst b/c-user/timer/background.rst
new file mode 100644
index 0000000..20cf202
--- /dev/null
+++ b/c-user/timer/background.rst
@@ -0,0 +1,71 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Background
+==========
+
+Required Support
+----------------
+
+A clock tick is required to support the functionality provided by this manager.
+
+Timers
+------
+
+A timer is an RTEMS object which allows the application to schedule operations
+to occur at specific times in the future. User supplied timer service routines
+are invoked by either a clock tick directive or a special Timer
+Server task when the timer fires. Timer service routines may perform any
+operations or directives which normally would be performed by the application
+code which invoked a clock tick directive.
+
+The timer can be used to implement watchdog routines which only fire to denote
+that an application error has occurred. The timer is reset at specific points
+in the application to ensure that the watchdog does not fire. Thus, if the
+application does not reset the watchdog timer, then the timer service routine
+will fire to indicate that the application has failed to reach a reset point.
+This use of a timer is sometimes referred to as a "keep alive" or a "deadman"
+timer.
+
+Timer Server
+------------
+
+The Timer Server task is responsible for executing the timer service routines
+associated with all task-based timers. This task executes at a priority
+specified by :ref:`rtems_timer_initiate_server() <rtems_timer_initiate_server>`
+and it may have a priority of zero (the highest priority). In uniprocessor
+configurations, it is created non-preemptible.
+
+By providing a mechanism where timer service routines execute in task rather
+than interrupt space, the application is allowed a bit more flexibility in what
+operations a timer service routine can perform. For example, the Timer Server
+can be configured to have a floating point context in which case it would be
+safe to perform floating point operations from a task-based timer. Most of the
+time, executing floating point instructions from an interrupt service routine
+is not considered safe. The timer service routines invoked by the Timer Server
+may block, however, since this blocks the Timer Server itself, other timer
+service routines that are already pending do not run until the blocked timer
+service routine finished its work.
+
+The Timer Server is designed to remain blocked until a task-based timer fires.
+This reduces the execution overhead of the Timer Server.
+
+.. index:: rtems_timer_service_routine
+
+Timer Service Routines
+----------------------
+
+The timer service routine should adhere to C calling conventions and have a
+prototype similar to the following:
+
+.. code-block:: c
+
+ rtems_timer_service_routine user_routine(
+ rtems_id timer_id,
+ void *user_data
+ );
+
+Where the timer_id parameter is the RTEMS object ID of the timer which is being
+fired and user_data is a pointer to user-defined information which may be
+utilized by the timer service routine. The argument user_data may be NULL.
diff --git a/c-user/timer_manager.rst b/c-user/timer/directives.rst
similarity index 64%
rename from c-user/timer_manager.rst
rename to c-user/timer/directives.rst
index fc5f79c..d9b9877 100644
--- a/c-user/timer_manager.rst
+++ b/c-user/timer/directives.rst
@@ -2,186 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: timers
-
-Timer Manager
-*************
-
-Introduction
-============
-
-The timer manager provides support for timer
-facilities. The directives provided by the timer manager are:
-
-- rtems_timer_create_ - Create a timer
-
-- rtems_timer_ident_ - Get ID of a timer
-
-- rtems_timer_cancel_ - Cancel a timer
-
-- rtems_timer_delete_ - Delete a timer
-
-- rtems_timer_fire_after_ - Fire timer after interval
-
-- rtems_timer_fire_when_ - Fire timer when specified
-
-- rtems_timer_initiate_server_ - Initiate server for task-based timers
-
-- rtems_timer_server_fire_after_ - Fire task-based timer after interval
-
-- rtems_timer_server_fire_when_ - Fire task-based timer when specified
-
-- rtems_timer_reset_ - Reset an interval timer
-
-Background
-==========
-
-Required Support
-----------------
-
-A clock tick is required to support the functionality provided by this manager.
-
-Timers
-------
-
-A timer is an RTEMS object which allows the application to schedule operations
-to occur at specific times in the future. User supplied timer service routines
-are invoked by either a clock tick directive or a special Timer
-Server task when the timer fires. Timer service routines may perform any
-operations or directives which normally would be performed by the application
-code which invoked a clock tick directive.
-
-The timer can be used to implement watchdog routines which only fire to denote
-that an application error has occurred. The timer is reset at specific points
-in the application to ensure that the watchdog does not fire. Thus, if the
-application does not reset the watchdog timer, then the timer service routine
-will fire to indicate that the application has failed to reach a reset point.
-This use of a timer is sometimes referred to as a "keep alive" or a "deadman"
-timer.
-
-Timer Server
-------------
-
-The Timer Server task is responsible for executing the timer service routines
-associated with all task-based timers. This task executes at a priority
-specified by :ref:`rtems_timer_initiate_server() <rtems_timer_initiate_server>`
-and it may have a priority of zero (the highest priority). In uniprocessor
-configurations, it is created non-preemptible.
-
-By providing a mechanism where timer service routines execute in task rather
-than interrupt space, the application is allowed a bit more flexibility in what
-operations a timer service routine can perform. For example, the Timer Server
-can be configured to have a floating point context in which case it would be
-safe to perform floating point operations from a task-based timer. Most of the
-time, executing floating point instructions from an interrupt service routine
-is not considered safe. The timer service routines invoked by the Timer Server
-may block, however, since this blocks the Timer Server itself, other timer
-service routines that are already pending do not run until the blocked timer
-service routine finished its work.
-
-The Timer Server is designed to remain blocked until a task-based timer fires.
-This reduces the execution overhead of the Timer Server.
-
-.. index:: rtems_timer_service_routine
-
-Timer Service Routines
-----------------------
-
-The timer service routine should adhere to C calling conventions and have a
-prototype similar to the following:
-
-.. code-block:: c
-
- rtems_timer_service_routine user_routine(
- rtems_id timer_id,
- void *user_data
- );
-
-Where the timer_id parameter is the RTEMS object ID of the timer which is being
-fired and user_data is a pointer to user-defined information which may be
-utilized by the timer service routine. The argument user_data may be NULL.
-
-Operations
-==========
-
-Creating a Timer
-----------------
-
-The ``rtems_timer_create`` directive creates a timer by allocating a Timer
-Control Block (TMCB), assigning the timer a user-specified name, and assigning
-it a timer ID. Newly created timers do not have a timer service routine
-associated with them and are not active.
-
-Obtaining Timer IDs
--------------------
-
-When a timer is created, RTEMS generates a unique timer ID and assigns it to
-the created timer until it is deleted. The timer ID may be obtained by either
-of two methods. First, as the result of an invocation of the
-``rtems_timer_create`` directive, the timer ID is stored in a user provided
-location. Second, the timer ID may be obtained later using the
-``rtems_timer_ident`` directive. The timer ID is used by other directives to
-manipulate this timer.
-
-Initiating an Interval Timer
-----------------------------
-
-The ``rtems_timer_fire_after`` and ``rtems_timer_server_fire_after`` directives
-initiate a timer to fire a user provided timer service routine after the
-specified number of clock ticks have elapsed. When the interval has elapsed,
-the timer service routine will be invoked from a clock tick
-directive if it was initiated by the ``rtems_timer_fire_after`` directive and
-from the Timer Server task if initiated by the
-``rtems_timer_server_fire_after`` directive.
-
-Initiating a Time of Day Timer
-------------------------------
-
-The ``rtems_timer_fire_when`` and ``rtems_timer_server_fire_when`` directive
-initiate a timer to fire a user provided timer service routine when the
-specified time of day has been reached. When the interval has elapsed, the
-timer service routine will be invoked from a clock tick directive
-by the ``rtems_timer_fire_when`` directive and from the Timer Server task if
-initiated by the ``rtems_timer_server_fire_when`` directive.
-
-Canceling a Timer
------------------
-
-The ``rtems_timer_cancel`` directive is used to halt the specified timer. Once
-canceled, the timer service routine will not fire unless the timer is
-reinitiated. The timer can be reinitiated using the ``rtems_timer_reset``,
-``rtems_timer_fire_after``, and ``rtems_timer_fire_when`` directives.
-
-Resetting a Timer
------------------
-
-The ``rtems_timer_reset`` directive is used to restore an interval timer
-initiated by a previous invocation of ``rtems_timer_fire_after`` or
-``rtems_timer_server_fire_after`` to its original interval length. If the
-timer has not been used or the last usage of this timer was by the
-``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then
-an error is returned. The timer service routine is not changed or fired by
-this directive.
-
-Initiating the Timer Server
----------------------------
-
-The ``rtems_timer_initiate_server`` directive is used to allocate and start the
-execution of the Timer Server task. The application can specify both the stack
-size and attributes of the Timer Server. The Timer Server executes at a
-priority higher than any application task and thus the user can expect to be
-preempted as the result of executing the ``rtems_timer_initiate_server``
-directive.
-
-Deleting a Timer
-----------------
-
-The ``rtems_timer_delete`` directive is used to delete a timer. If the timer
-is running and has not expired, the timer is automatically canceled. The
-timer's control block is returned to the TMCB free list when it is deleted. A
-timer can be deleted by a task other than the task which created the timer.
-Any subsequent references to the timer's name and ID are invalid.
-
Directives
==========
diff --git a/c-user/timer/index.rst b/c-user/timer/index.rst
new file mode 100644
index 0000000..48e726e
--- /dev/null
+++ b/c-user/timer/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: timers
+
+Timer Manager
+*************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/timer/introduction.rst b/c-user/timer/introduction.rst
new file mode 100644
index 0000000..48a36ba
--- /dev/null
+++ b/c-user/timer/introduction.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The timer manager provides support for timer
+facilities. The directives provided by the timer manager are:
+
+- :ref:`rtems_timer_create`
+
+- :ref:`rtems_timer_ident`
+
+- :ref:`rtems_timer_cancel`
+
+- :ref:`rtems_timer_delete`
+
+- :ref:`rtems_timer_fire_after`
+
+- :ref:`rtems_timer_fire_when`
+
+- :ref:`rtems_timer_initiate_server`
+
+- :ref:`rtems_timer_server_fire_after`
+
+- :ref:`rtems_timer_server_fire_when`
+
+- :ref:`rtems_timer_reset`
diff --git a/c-user/timer/operations.rst b/c-user/timer/operations.rst
new file mode 100644
index 0000000..8a6404f
--- /dev/null
+++ b/c-user/timer/operations.rst
@@ -0,0 +1,84 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Creating a Timer
+----------------
+
+The ``rtems_timer_create`` directive creates a timer by allocating a Timer
+Control Block (TMCB), assigning the timer a user-specified name, and assigning
+it a timer ID. Newly created timers do not have a timer service routine
+associated with them and are not active.
+
+Obtaining Timer IDs
+-------------------
+
+When a timer is created, RTEMS generates a unique timer ID and assigns it to
+the created timer until it is deleted. The timer ID may be obtained by either
+of two methods. First, as the result of an invocation of the
+``rtems_timer_create`` directive, the timer ID is stored in a user provided
+location. Second, the timer ID may be obtained later using the
+``rtems_timer_ident`` directive. The timer ID is used by other directives to
+manipulate this timer.
+
+Initiating an Interval Timer
+----------------------------
+
+The ``rtems_timer_fire_after`` and ``rtems_timer_server_fire_after`` directives
+initiate a timer to fire a user provided timer service routine after the
+specified number of clock ticks have elapsed. When the interval has elapsed,
+the timer service routine will be invoked from a clock tick
+directive if it was initiated by the ``rtems_timer_fire_after`` directive and
+from the Timer Server task if initiated by the
+``rtems_timer_server_fire_after`` directive.
+
+Initiating a Time of Day Timer
+------------------------------
+
+The ``rtems_timer_fire_when`` and ``rtems_timer_server_fire_when`` directive
+initiate a timer to fire a user provided timer service routine when the
+specified time of day has been reached. When the interval has elapsed, the
+timer service routine will be invoked from a clock tick directive
+by the ``rtems_timer_fire_when`` directive and from the Timer Server task if
+initiated by the ``rtems_timer_server_fire_when`` directive.
+
+Canceling a Timer
+-----------------
+
+The ``rtems_timer_cancel`` directive is used to halt the specified timer. Once
+canceled, the timer service routine will not fire unless the timer is
+reinitiated. The timer can be reinitiated using the ``rtems_timer_reset``,
+``rtems_timer_fire_after``, and ``rtems_timer_fire_when`` directives.
+
+Resetting a Timer
+-----------------
+
+The ``rtems_timer_reset`` directive is used to restore an interval timer
+initiated by a previous invocation of ``rtems_timer_fire_after`` or
+``rtems_timer_server_fire_after`` to its original interval length. If the
+timer has not been used or the last usage of this timer was by the
+``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then
+an error is returned. The timer service routine is not changed or fired by
+this directive.
+
+Initiating the Timer Server
+---------------------------
+
+The ``rtems_timer_initiate_server`` directive is used to allocate and start the
+execution of the Timer Server task. The application can specify both the stack
+size and attributes of the Timer Server. The Timer Server executes at a
+priority higher than any application task and thus the user can expect to be
+preempted as the result of executing the ``rtems_timer_initiate_server``
+directive.
+
+Deleting a Timer
+----------------
+
+The ``rtems_timer_delete`` directive is used to delete a timer. If the timer
+is running and has not expired, the timer is automatically canceled. The
+timer's control block is returned to the TMCB free list when it is deleted. A
+timer can be deleted by a task other than the task which created the timer.
+Any subsequent references to the timer's name and ID are invalid.
--
2.26.2
More information about the devel
mailing list