Changeset 5cd3258 in rtems


Ignore:
Timestamp:
Jan 17, 2002, 11:14:16 PM (19 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
5dd28ac7
Parents:
6449498
Message:

2001-01-17 Joel Sherrill <joel@…>

  • timer.t: Added task-based timer information including the new directives rtems_timer_initiate(), rtems_timer_server_fire_after(), and rtems_timer_server_fire_when().
Location:
doc/user
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/user/ChangeLog

    r6449498 r5cd3258  
     12001-01-17      Joel Sherrill <joel@OARcorp.com>
     2
     3        * timer.t: Added task-based timer information including the
     4        new directives rtems_timer_initiate(), rtems_timer_server_fire_after(),
     5        and rtems_timer_server_fire_when().
     6
    172000-08-10      Joel Sherrill <joel@OARcorp.com>
    28
  • doc/user/timer.t

    r6449498 r5cd3258  
    2323@item @code{@value{DIRPREFIX}timer_fire_after} - Fire timer after interval
    2424@item @code{@value{DIRPREFIX}timer_fire_when} - Fire timer when specified
     25@item @code{@value{DIRPREFIX}timer_initiate_server} - Initiate server for task-based timers
     26@item @code{@value{DIRPREFIX}timer_server_fire_after} - Fire task-based timer after interval
     27@item @code{@value{DIRPREFIX}timer_server_fire_when} - Fire task-based timer when specified
    2528@item @code{@value{DIRPREFIX}timer_reset} - Reset an interval timer
    2629@end itemize
     
    3841application to schedule operations to occur at specific times in
    3942the future.  User supplied timer service routines are invoked by
    40 the @code{@value{DIRPREFIX}clock_tick} directive
    41 when the timer fires.  Timer service routines may perform
    42 any operations or directives which normally
     43either the @code{@value{DIRPREFIX}clock_tick} directive or
     44a special Timer Server task when the timer fires.  Timer service
     45routines may perform any operations or directives which normally
    4346would be performed by the application code which invoked the
    4447@code{@value{DIRPREFIX}clock_tick} directive.
     
    5255has failed to reach a reset point.  This use of a timer is
    5356sometimes referred to as a "keep alive" or a "deadman" timer.
     57
     58@subsection Timer Server
     59
     60The Timer Server task is responsible for executing the timer
     61service routines associated with all task-based timers.
     62This task executes at a priority higher than any RTEMS application
     63task and thus can be viewed logically as the lowest priority interrupt.
     64
     65By providing a mechanism where timer service routines execute
     66in task rather than interrupt space, the application is
     67allowed a bit more flexibility in what operations a timer
     68service routine can perform.  For example, the Timer Server
     69can be configured to have a floating point context in which case
     70it would be save to perform floating point operations
     71from a task-based timer.  Most of the time, executing floating
     72point instructions from an interrupt service routine
     73is not considered safe.
     74
     75The Timer Server is designed to remain blocked until a
     76task-based timer fires.  This reduces the execution overhead
     77of the Timer Server.
    5478
    5579@subsection Timer Service Routines
     
    106130@subsection Initiating an Interval Timer
    107131
    108 The @code{@value{DIRPREFIX}timer_fire_after} directive initiates a timer to
    109 fire a user provided timer service routine after the specified
     132The @code{@value{DIRPREFIX}timer_fire_after}
     133and @code{@value{DIRPREFIX}timer_server_fire_after}
     134directives initiate a timer to fire a user provided
     135timer service routine after the specified
    110136number of clock ticks have elapsed.  When the interval has
    111137elapsed, the timer service routine will be invoked from the
    112 @code{@value{DIRPREFIX}clock_tick} directive.
     138@code{@value{DIRPREFIX}clock_tick} directive if it was initiated
     139by the @code{@value{DIRPREFIX}timer_fire_after} directive
     140and from the Timer Server task if initiated by the
     141@code{@value{DIRPREFIX}timer_server_fire_after} directive.
    113142
    114143@subsection Initiating a Time of Day Timer
    115144
    116 The @code{@value{DIRPREFIX}timer_fire_when} directive initiates a timer to
     145The @code{@value{DIRPREFIX}timer_fire_when}
     146and @code{@value{DIRPREFIX}timer_server_fire_when}
     147directive initiate a timer to
    117148fire a user provided timer service routine when the specified
    118149time of day has been reached.  When the interval has elapsed,
    119150the timer service routine will be invoked from the
    120 @code{@value{DIRPREFIX}clock_tick} directive.
     151@code{@value{DIRPREFIX}clock_tick} directive
     152by the @code{@value{DIRPREFIX}timer_fire_when} directive
     153and from the Timer Server task if initiated by the
     154@code{@value{DIRPREFIX}timer_server_fire_when} directive.
    121155
    122156@subsection Canceling a Timer
     
    133167The @code{@value{DIRPREFIX}timer_reset} directive is used to restore an
    134168interval timer initiated by a previous invocation of
    135 @code{@value{DIRPREFIX}timer_fire_after} to
     169@code{@value{DIRPREFIX}timer_fire_after} or
     170@code{@value{DIRPREFIX}timer_server_fire_after} to
    136171its original interval length.  If the
    137172timer has not been used or the last usage of this timer
    138 was by a @code{@value{DIRPREFIX}timer_fire_when} directive, then an error is
    139 returned.  The timer service routine is not changed or
    140 fired by this directive.
     173was by the @code{@value{DIRPREFIX}timer_fire_when}
     174or @code{@value{DIRPREFIX}timer_server_fire_when}
     175directive, then an error is returned.  The timer service routine
     176is not changed or fired by this directive.
     177
     178@subsection Initiating the Timer Server
     179
     180The @code{@value{DIRPREFIX}timer_initiate_server} directive is used to
     181allocate and start the execution of the Timer Server task.  The
     182application can specify both the stack size and attributes of the
     183Timer Server.  The Timer Server executes at a priority higher than
     184any application task and thus the user can expect to be preempted
     185as the result of executing the @code{@value{DIRPREFIX}timer_initiate_server}
     186directive.
    141187
    142188@subsection Deleting a Timer
     
    289335be reinitiated by the next invocation of @code{@value{DIRPREFIX}timer_reset},
    290336@code{@value{DIRPREFIX}timer_fire_after}, or
    291 @code{@value{DIRPREFIX}timer_fire_when} with id.
     337@code{@value{DIRPREFIX}timer_fire_when} with this id.
    292338
    293339@subheading NOTES:
     
    452498@c
    453499@page
     500@subsection TIMER_INITIATE_SERVER - Initiate server for task-based timers
     501
     502@cindex initiate the Timer Server
     503
     504@subheading CALLING SEQUENCE:
     505
     506@ifset is-C
     507@findex rtems_timer_initiate_server
     508@example
     509rtems_status_code rtems_timer_initiate_server(
     510  unsigned32           stack_size,
     511  rtems_attribute      attribute_set
     512)
     513);
     514@end example
     515@end ifset
     516
     517@ifset is-Ada
     518@example
     519procedure Timer_Initiate_Server (
     520   Stack_Size    : in     RTEMS.Unsigned32;
     521   Attribute_Set : in     RTEMS.Attribute;
     522   Result        :    out RTEMS.Status_Codes
     523);
     524@end example
     525@end ifset
     526
     527@subheading DIRECTIVE STATUS CODES:
     528@code{@value{RPREFIX}SUCCESSFUL} - Timer Server initiated successfully@*
     529@code{@value{RPREFIX}TOO_MANY} - too many tasks created
     530
     531@subheading DESCRIPTION:
     532
     533This directive initiates the Timer Server task.  This task
     534is responsible for executing all timers initiated via the
     535@code{@value{DIRPREFIX}timer_server_fire_after} or
     536@code{@value{DIRPREFIX}timer_server_fire_when} directives.
     537
     538@subheading NOTES:
     539
     540This directive could cause the calling task to be preempted.
     541
     542The Timer Server task is created using the
     543@code{@value{DIRPREFIX}task_create} service and must be accounted
     544for when configuring the system.
     545
     546Even through this directive invokes the @code{@value{DIRPREFIX}task_create}
     547and @code{@value{DIRPREFIX}task_start} directives, it should only fail
     548due to resource allocation problems.
     549
     550@c
     551@c
     552@c
     553@page
     554@subsection TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
     555
     556@cindex fire task-based a timer after an interval
     557
     558@subheading CALLING SEQUENCE:
     559
     560@ifset is-C
     561@findex rtems_timer_server_fire_after
     562@example
     563rtems_status_code rtems_timer_server_fire_after(
     564  rtems_id                           id,
     565  rtems_interval                     ticks,
     566  rtems_timer_service_routine_entry  routine,
     567  void                              *user_data
     568);
     569@end example
     570@end ifset
     571
     572@ifset is-Ada
     573@example
     574procedure Timer_Fire_Server_After (
     575   ID        : in     RTEMS.ID;
     576   Ticks     : in     RTEMS.Interval;
     577   Routine   : in     RTEMS.Timer_Service_Routine;
     578   User_Data : in     RTEMS.Address;
     579   Result    :    out RTEMS.Status_Codes
     580);
     581@end example
     582@end ifset
     583
     584@subheading DIRECTIVE STATUS CODES:
     585@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
     586@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
     587@code{@value{RPREFIX}INVALID_NUMBER} - invalid interval@*
     588@code{@value{RPREFIX}INCORRECT_STATE} - Timer Server not initiated
     589
     590@subheading DESCRIPTION:
     591
     592This directive initiates the timer specified by id and specifies
     593that when it fires it will be executed by the Timer Server.
     594
     595If the timer is running, it is automatically canceled before
     596being initiated.  The timer is scheduled to fire after an
     597interval ticks clock ticks has passed.  When the timer fires,
     598the timer service routine routine will be invoked with the
     599argument user_data.
     600
     601@subheading NOTES:
     602
     603This directive will not cause the running task to be
     604preempted.
     605
     606@c
     607@c
     608@c
     609@page
     610@subsection TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
     611
     612@cindex fire a task-based timer at wall time
     613
     614@subheading CALLING SEQUENCE:
     615
     616@ifset is-C
     617@findex rtems_timer_server_fire_when
     618@example
     619rtems_status_code rtems_timer_server_fire_when(
     620  rtems_id                           id,
     621  rtems_time_of_day                 *wall_time,
     622  rtems_timer_service_routine_entry  routine,
     623  void                              *user_data
     624);
     625@end example
     626@end ifset
     627
     628@ifset is-Ada
     629@example
     630procedure Timer_Fire_Server_When (
     631   ID        : in     RTEMS.ID;
     632   Wall_Time : in     RTEMS.Time_Of_Day;
     633   Routine   : in     RTEMS.Timer_Service_Routine;
     634   User_Data : in     RTEMS.Address;
     635   Result    :    out RTEMS.Status_Codes
     636);
     637@end example
     638@end ifset
     639
     640@subheading DIRECTIVE STATUS CODES:
     641@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
     642@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
     643@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
     644@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day@*
     645@code{@value{RPREFIX}INCORRECT_STATE} - Timer Server not initiated
     646
     647@subheading DESCRIPTION:
     648
     649This directive initiates the timer specified by id and specifies
     650that when it fires it will be executed by the Timer Server.
     651
     652If the timer is running, it is automatically canceled before
     653being initiated.  The timer is scheduled to fire at the time of
     654day specified by wall_time.  When the timer fires, the timer
     655service routine routine will be invoked with the argument
     656user_data.
     657
     658@subheading NOTES:
     659
     660This directive will not cause the running task to be
     661preempted.
     662
     663@c
     664@c
     665@c
     666@page
    454667@subsection TIMER_RESET - Reset an interval timer
    455668
     
    484697
    485698This directive resets the timer associated with id.
    486 This timer must have been previously initiated with a
    487 @code{@value{DIRPREFIX}timer_fire_after}
     699This timer must have been previously initiated with either the
     700@code{@value{DIRPREFIX}timer_fire_after} or
     701@code{@value{DIRPREFIX}timer_server_fire_after}
    488702directive.  If active the timer is canceled,
    489703after which the timer is reinitiated using the same interval and
    490704timer service routine which the original
    491705@code{@value{DIRPREFIX}timer_fire_after}
     706@code{@value{DIRPREFIX}timer_server_fire_after}
    492707directive used.
    493708
     
    495710
    496711If the timer has not been used or the last usage of this timer
    497 was by a @code{@value{DIRPREFIX}timer_fire_when}
     712was by a @code{@value{DIRPREFIX}timer_fire_when} or
     713@code{@value{DIRPREFIX}timer_server_fire_when}
    498714directive, then the @code{@value{RPREFIX}NOT_DEFINED} error is
    499715returned.
Note: See TracChangeset for help on using the changeset viewer.