diff options
Diffstat (limited to 'c_user/timer_manager.rst')
-rw-r--r-- | c_user/timer_manager.rst | 575 |
1 files changed, 312 insertions, 263 deletions
diff --git a/c_user/timer_manager.rst b/c_user/timer_manager.rst index 2d83bf9..2e43770 100644 --- a/c_user/timer_manager.rst +++ b/c_user/timer_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Timer Manager ############# @@ -9,25 +13,25 @@ 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_create_ - Create a timer -- ``rtems_timer_ident`` - Get ID of a timer +- rtems_timer_ident_ - Get ID of a timer -- ``rtems_timer_cancel`` - Cancel a timer +- rtems_timer_cancel_ - Cancel a timer -- ``rtems_timer_delete`` - Delete a timer +- rtems_timer_delete_ - Delete a timer -- ``rtems_timer_fire_after`` - Fire timer after interval +- rtems_timer_fire_after_ - Fire timer after interval -- ``rtems_timer_fire_when`` - Fire timer when specified +- rtems_timer_fire_when_ - Fire timer when specified -- ``rtems_timer_initiate_server`` - Initiate server for task-based timers +- 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_after_ - Fire task-based timer after interval -- ``rtems_timer_server_fire_when`` - Fire task-based timer when specified +- rtems_timer_server_fire_when_ - Fire task-based timer when specified -- ``rtems_timer_reset`` - Reset an interval timer +- rtems_timer_reset_ - Reset an interval timer Background ========== @@ -40,65 +44,60 @@ 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. +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. +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 +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 + 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. +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 ========== @@ -106,95 +105,89 @@ 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. +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. +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. +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. +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. +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. +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`` +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. +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. +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. + +.. _rtems_timer_create: TIMER_CREATE - Create a timer ----------------------------- @@ -207,29 +200,36 @@ TIMER_CREATE - Create a timer .. code:: c rtems_status_code rtems_timer_create( - rtems_name name, - rtems_id \*id + 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 +``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. +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. +This directive will not cause the calling task to be preempted. + +.. _rtems_timer_ident: TIMER_IDENT - Get ID of a timer ------------------------------- @@ -242,29 +242,34 @@ TIMER_IDENT - Get ID of a timer .. code:: c rtems_status_code rtems_timer_ident( - rtems_name name, - rtems_id \*id + 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 +``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 +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. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_cancel: TIMER_CANCEL - Cancel a timer ----------------------------- @@ -277,23 +282,29 @@ TIMER_CANCEL - Cancel a timer .. code:: c rtems_status_code rtems_timer_cancel( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer canceled successfully -``RTEMS_INVALID_ID`` - invalid timer id +``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. +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. +.. _rtems_timer_delete: + TIMER_DELETE - Delete a timer ----------------------------- .. index:: delete a timer @@ -305,27 +316,30 @@ TIMER_DELETE - Delete a timer .. code:: c rtems_status_code rtems_timer_delete( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer deleted successfully -``RTEMS_INVALID_ID`` - invalid timer id +``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. +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. +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. -A timer can be deleted by a task other than the task -which created the timer. +.. _rtems_timer_fire_after: TIMER_FIRE_AFTER - Fire timer after interval -------------------------------------------- @@ -338,32 +352,38 @@ TIMER_FIRE_AFTER - Fire timer after interval .. code:: c rtems_status_code rtems_timer_fire_after( - rtems_id id, - rtems_interval ticks, - rtems_timer_service_routine_entry routine, - void \*user_data + 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_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. +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. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_fire_when: TIMER_FIRE_WHEN - Fire timer when specified ------------------------------------------- @@ -376,34 +396,44 @@ TIMER_FIRE_WHEN - Fire timer when specified .. 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 + 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_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. +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. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_initiate_server: TIMER_INITIATE_SERVER - Initiate server for task-based timers ------------------------------------------------------------- @@ -416,32 +446,38 @@ TIMER_INITIATE_SERVER - Initiate server for task-based timers .. code:: c rtems_status_code rtems_timer_initiate_server( - uint32_t priority, - uint32_t stack_size, - rtems_attribute attribute_set + 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 +``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. +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. +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. -Even through this directive invokes the ``rtems_task_create`` -and ``rtems_task_start`` directives, it should only fail -due to resource allocation problems. +.. _rtems_timer_server_fire_after: TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval -------------------------------------------------------------- @@ -454,35 +490,44 @@ TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval .. 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 + 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 +``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. +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. +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. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_server_fire_when: TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified ------------------------------------------------------------- @@ -495,37 +540,50 @@ TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified .. 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 + 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 +``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. +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. +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. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_reset: TIMER_RESET - Reset an interval timer ------------------------------------- @@ -538,45 +596,36 @@ TIMER_RESET - Reset an interval timer .. code:: c rtems_status_code rtems_timer_reset( - rtems_id id + 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 +``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. +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`` or +``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. +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. +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 - |