From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/timer_manager.rst | 582 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 582 insertions(+) create mode 100644 c_user/timer_manager.rst (limited to 'c_user/timer_manager.rst') diff --git a/c_user/timer_manager.rst b/c_user/timer_manager.rst new file mode 100644 index 0000000..828cfe2 --- /dev/null +++ b/c_user/timer_manager.rst @@ -0,0 +1,582 @@ +Timer Manager +############# + +.. index:: timers + +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 the ``rtems_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 the``rtems_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 higher than any RTEMS application +task, and is created non-preemptible, and thus can be viewed logically as +the lowest priority interrupt. + +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. However, since the Timer Server task +is non-preemptible, only directives allowed from an ISR can be +called in the timer service routine. + +The Timer Server is designed to remain blocked until a +task-based timer fires. This reduces the execution overhead +of the Timer Server. + +Timer Service Routines +---------------------- + +The timer service routine should adhere to C calling +conventions and have a prototype similar to the following:.. index:: rtems_timer_service_routine + +.. code:: 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 the``rtems_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 the``rtems_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 +========== + +This section details the timer manager’s directives. +A subsection is dedicated to each of this manager’s directives +and describes the calling sequence, related constants, usage, +and status codes. + +TIMER_CREATE - Create a timer +----------------------------- +.. index:: create a timer + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_create + +.. code:: c + + rtems_status_code rtems_timer_create( + rtems_name name, + rtems_id \*id + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer created successfully +``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL +``RTEMS_INVALID_NAME`` - invalid timer name +``RTEMS_TOO_MANY`` - too many timers created + +**DESCRIPTION:** + +This directive creates a timer. The assigned timer +id is returned in id. This id is used to access the timer with +other timer manager directives. For control and maintenance of +the timer, RTEMS allocates a TMCB from the local TMCB free pool +and initializes it. + +**NOTES:** + +This directive will not cause the calling task to be +preempted. + +TIMER_IDENT - Get ID of a timer +------------------------------- +.. index:: obtain the ID of a timer + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_ident + +.. code:: c + + rtems_status_code rtems_timer_ident( + rtems_name name, + rtems_id \*id + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer identified successfully +``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL +``RTEMS_INVALID_NAME`` - timer name not found + +**DESCRIPTION:** + +This directive obtains the timer id associated with +the timer name to be acquired. If the timer name is not unique, +then the timer id will match one of the timers with that name. +However, this timer id is not guaranteed to correspond to the +desired timer. The timer id is used to access this timer in +other timer related directives. + +**NOTES:** + +This directive will not cause the running task to be +preempted. + +TIMER_CANCEL - Cancel a timer +----------------------------- +.. index:: cancel a timer + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_cancel + +.. code:: c + + rtems_status_code rtems_timer_cancel( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer canceled successfully +``RTEMS_INVALID_ID`` - invalid timer id + +**DESCRIPTION:** + +This directive cancels the timer id. This timer will +be reinitiated by the next invocation of ``rtems_timer_reset``,``rtems_timer_fire_after``, or``rtems_timer_fire_when`` with this id. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +TIMER_DELETE - Delete a timer +----------------------------- +.. index:: delete a timer + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_delete + +.. code:: c + + rtems_status_code rtems_timer_delete( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer deleted successfully +``RTEMS_INVALID_ID`` - invalid timer id + +**DESCRIPTION:** + +This directive deletes the timer specified by id. If +the timer is running, it is automatically canceled. The TMCB +for the deleted timer is reclaimed by RTEMS. + +**NOTES:** + +This directive will not cause the running task to be +preempted. + +A timer can be deleted by a task other than the task +which created the timer. + +TIMER_FIRE_AFTER - Fire timer after interval +-------------------------------------------- +.. index:: fire a timer after an interval + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_fire_after + +.. code:: c + + rtems_status_code rtems_timer_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void \*user_data + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer initiated successfully +``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL +``RTEMS_INVALID_ID`` - invalid timer id +``RTEMS_INVALID_NUMBER`` - invalid interval + +**DESCRIPTION:** + +This directive initiates the timer specified by id. +If the timer is running, it is automatically canceled before +being initiated. The timer is scheduled to fire after an +interval ticks clock ticks has passed. When the timer fires, +the timer service routine routine will be invoked with the +argument user_data. + +**NOTES:** + +This directive will not cause the running task to be +preempted. + +TIMER_FIRE_WHEN - Fire timer when specified +------------------------------------------- +.. index:: fire a timer at wall time + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_fire_when + +.. code:: c + + rtems_status_code rtems_timer_fire_when( + rtems_id id, + rtems_time_of_day \*wall_time, + rtems_timer_service_routine_entry routine, + void \*user_data + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer initiated successfully +``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL +``RTEMS_INVALID_ADDRESS`` - ``wall_time`` is NULL +``RTEMS_INVALID_ID`` - invalid timer id +``RTEMS_NOT_DEFINED`` - system date and time is not set +``RTEMS_INVALID_CLOCK`` - invalid time of day + +**DESCRIPTION:** + +This directive initiates the timer specified by id. +If the timer is running, it is automatically canceled before +being initiated. The timer is scheduled to fire at the time of +day specified by wall_time. When the timer fires, the timer +service routine routine will be invoked with the argument +user_data. + +**NOTES:** + +This directive will not cause the running task to be +preempted. + +TIMER_INITIATE_SERVER - Initiate server for task-based timers +------------------------------------------------------------- +.. index:: initiate the Timer Server + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_initiate_server + +.. code:: c + + rtems_status_code rtems_timer_initiate_server( + uint32_t priority, + uint32_t stack_size, + rtems_attribute attribute_set + ) + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - Timer Server initiated successfully +``RTEMS_TOO_MANY`` - too many tasks created + +**DESCRIPTION:** + +This directive initiates the Timer Server task. This task +is responsible for executing all timers initiated via the``rtems_timer_server_fire_after`` or``rtems_timer_server_fire_when`` directives. + +**NOTES:** + +This directive could cause the calling task to be preempted. + +The Timer Server task is created using the``rtems_task_create`` service and must be accounted +for when configuring the system. + +Even through this directive invokes the ``rtems_task_create`` +and ``rtems_task_start`` directives, it should only fail +due to resource allocation problems. + +TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval +-------------------------------------------------------------- +.. index:: fire task-based a timer after an interval + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_server_fire_after + +.. code:: c + + rtems_status_code rtems_timer_server_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void \*user_data + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer initiated successfully +``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL +``RTEMS_INVALID_ID`` - invalid timer id +``RTEMS_INVALID_NUMBER`` - invalid interval +``RTEMS_INCORRECT_STATE`` - Timer Server not initiated + +**DESCRIPTION:** + +This directive initiates the timer specified by id and specifies +that when it fires it will be executed by the Timer Server. + +If the timer is running, it is automatically canceled before +being initiated. The timer is scheduled to fire after an +interval ticks clock ticks has passed. When the timer fires, +the timer service routine routine will be invoked with the +argument user_data. + +**NOTES:** + +This directive will not cause the running task to be +preempted. + +TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified +------------------------------------------------------------- +.. index:: fire a task-based timer at wall time + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_server_fire_when + +.. code:: c + + rtems_status_code rtems_timer_server_fire_when( + rtems_id id, + rtems_time_of_day \*wall_time, + rtems_timer_service_routine_entry routine, + void \*user_data + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer initiated successfully +``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL +``RTEMS_INVALID_ADDRESS`` - ``wall_time`` is NULL +``RTEMS_INVALID_ID`` - invalid timer id +``RTEMS_NOT_DEFINED`` - system date and time is not set +``RTEMS_INVALID_CLOCK`` - invalid time of day +``RTEMS_INCORRECT_STATE`` - Timer Server not initiated + +**DESCRIPTION:** + +This directive initiates the timer specified by id and specifies +that when it fires it will be executed by the Timer Server. + +If the timer is running, it is automatically canceled before +being initiated. The timer is scheduled to fire at the time of +day specified by wall_time. When the timer fires, the timer +service routine routine will be invoked with the argument +user_data. + +**NOTES:** + +This directive will not cause the running task to be +preempted. + +TIMER_RESET - Reset an interval timer +------------------------------------- +.. index:: reset a timer + +**CALLING SEQUENCE:** + +.. index:: rtems_timer_reset + +.. code:: c + + rtems_status_code rtems_timer_reset( + rtems_id id + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - timer reset successfully +``RTEMS_INVALID_ID`` - invalid timer id +``RTEMS_NOT_DEFINED`` - attempted to reset a when or newly created timer + +**DESCRIPTION:** + +This directive resets the timer associated with id. +This timer must have been previously initiated with either the``rtems_timer_fire_after`` or``rtems_timer_server_fire_after`` +directive. If active the timer is canceled, +after which the timer is reinitiated using the same interval and +timer service routine which the original``rtems_timer_fire_after````rtems_timer_server_fire_after`` +directive used. + +**NOTES:** + +If the timer has not been used or the last usage of this timer +was by a ``rtems_timer_fire_when`` or``rtems_timer_server_fire_when`` +directive, then the ``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. + +This directive will not cause the running task to be preempted. + +.. COMMENT: COPYRIGHT (c) 1988-2013. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + +.. COMMENT: Open Issues + +.. COMMENT: - nicen up the tables + +.. COMMENT: - use math mode to print formulas + -- cgit v1.2.3