c-user: Split up timer manager

This makes it easier to automatically generate parts of the manager
documentation in the future.

Update #3993.

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

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.

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
 ==========
 

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

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`

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.