rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-01 23:52:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

c-user: Split up timer manager

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

Update #3993.
This commit is contained in:
Sebastian Huber 2020-08-20 10:16:21 +02:00
parent ccb384b623
commit a99bbaec5f
6 changed files with 200 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
c-user/index.rst
View File

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

71
c-user/timer/background.rst Normal file
View File

@ -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.

180
c-user/timer_manager.rst → c-user/timer/directives.rst
View File

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

15
c-user/timer/index.rst Normal file
View File

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

29
c-user/timer/introduction.rst Normal file
View File

@ -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`

84
c-user/timer/operations.rst Normal file
View File

@ -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.