source: rtems/doc/user/clock.t @ 8e29715

4.9
Last change on this file since 8e29715 was 8e29715, checked in by Joel Sherrill <joel.sherrill@…>, on 01/11/10 at 16:17:44

2010-01-11 Marc Pignat <marc.pignat@…>

PR 1490/doc

  • user/clock.t: Fix typo. rtems_clock_get_ticks_per_second not rtems_clock_get_ticks_per_seconds.
  • Property mode set to 100644
File size: 22.2 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Clock Manager
10
11@cindex clock
12
13@section Introduction
14
15The clock manager provides support for time of day
16and other time related capabilities.  The directives provided by
17the clock manager are:
18
19@itemize @bullet
20@item @code{@value{DIRPREFIX}clock_set} - Set date and time
21@item @code{@value{DIRPREFIX}clock_get} - Get date and time information
22@item @code{@value{DIRPREFIX}clock_get_tod} - Get date and time in TOD format
23@item @code{@value{DIRPREFIX}clock_get_tod_timeval} - Get date and time in timeval format
24@item @code{@value{DIRPREFIX}clock_get_seconds_since_epoch} - Get seconds since epoch
25@item @code{@value{DIRPREFIX}clock_get_ticks_per_second} - Get ticks per second
26@item @code{@value{DIRPREFIX}clock_get_ticks_since_boot} - Get ticks since boot
27@item @code{@value{DIRPREFIX}clock_get_uptime} - Get time since boot
28@item @code{@value{DIRPREFIX}clock_set_nanoseconds_extension} - Install the nanoseconds since last tick handler
29@item @code{@value{DIRPREFIX}clock_tick} - Announce a clock tick
30@end itemize
31
32@section Background
33
34@subsection Required Support
35
36For the features provided by the clock manager to be
37utilized, periodic timer interrupts are required.  Therefore, a
38real-time clock or hardware timer is necessary to create the
39timer interrupts.  The @code{@value{DIRPREFIX}clock_tick}
40directive is normally called
41by the timer ISR to announce to RTEMS that a system clock tick
42has occurred.  Elapsed time is measured in ticks.  A tick is
43defined to be an integral number of microseconds which is
44specified by the user in the Configuration Table.
45
46@subsection Time and Date Data Structures
47
48The clock facilities of the clock manager operate
49upon calendar time.  These directives utilize the following date
50and time @value{STRUCTURE} for the native time and date format:
51
52
53@ifset is-C
54@findex rtems_time_of_day
55@example
56struct rtems_tod_control @{
57  uint32_t year;   /* greater than 1987 */
58  uint32_t month;  /* 1 - 12 */
59  uint32_t day;    /* 1 - 31 */
60  uint32_t hour;   /* 0 - 23 */
61  uint32_t minute; /* 0 - 59 */
62  uint32_t second; /* 0 - 59 */
63  uint32_t ticks;  /* elapsed between seconds */
64@};
65
66typedef struct rtems_tod_control rtems_time_of_day;
67@end example
68@end ifset
69
70@ifset is-Ada
71@example
72type Time_Of_Day is
73   record
74      Year    : RTEMS.Unsigned32; -- year, A.D.
75      Month   : RTEMS.Unsigned32; -- month, 1 .. 12
76      Day     : RTEMS.Unsigned32; -- day, 1 .. 31
77      Hour    : RTEMS.Unsigned32; -- hour, 0 .. 23
78      Minute  : RTEMS.Unsigned32; -- minute, 0 .. 59
79      Second  : RTEMS.Unsigned32; -- second, 0 .. 59
80      Ticks   : RTEMS.Unsigned32; -- elapsed ticks between seconds
81   end record;
82@end example
83@end ifset
84
85
86The native date and time format is the only format
87supported when setting the system date and time using the
88@code{@value{DIRPREFIX}clock_get} directive.  Some applications
89expect to operate on a "UNIX-style" date and time data structure.  The
90@code{@value{DIRPREFIX}clock_get} directive can optionally return
91the current date and time in the
92following @value{STRUCTURE}:
93
94@ifset is-C
95@example
96@group
97typedef struct @{
98  uint32_t seconds;       /* seconds since RTEMS epoch*/
99  uint32_t microseconds;  /* since last second        */
100@} rtems_clock_time_value;
101@end group
102@end example
103@end ifset
104
105@ifset is-Ada
106@example
107type Clock_Time_Value is
108   record
109      Seconds      : Unsigned32;
110      Microseconds : Unsigned32;
111   end record;
112@end example
113@end ifset
114
115The seconds field in this @value{STRUCTURE} is the number of seconds
116since the POSIX epoch of January 1, 1970 but will never be prior to
117the RTEMS epoch of January 1, 1988.
118
119@subsection Clock Tick and Timeslicing
120
121@cindex timeslicing
122
123Timeslicing is a task scheduling discipline in which
124tasks of equal priority are executed for a specific period of
125time before control of the CPU is passed to another task.  It is
126also sometimes referred to as the automatic round-robin
127scheduling algorithm.  The length of time allocated to each task
128is known as the quantum or timeslice.
129
130The system's timeslice is defined as an integral
131number of ticks, and is specified in the Configuration Table.
132The timeslice is defined for the entire system of tasks, but
133timeslicing is enabled and disabled on a per task basis.
134
135The @code{@value{DIRPREFIX}clock_tick}
136directive implements timeslicing by
137decrementing the running task's time-remaining counter when both
138timeslicing and preemption are enabled.  If the task's timeslice
139has expired, then that task will be preempted if there exists a
140ready task of equal priority.
141
142@subsection Delays
143
144@cindex delays
145
146A sleep timer allows a task to delay for a given
147interval or up until a given time, and then wake and continue
148execution.  This type of timer is created automatically by the
149@code{@value{DIRPREFIX}task_wake_after}
150and @code{@value{DIRPREFIX}task_wake_when} directives and, as a result,
151does not have an RTEMS ID.  Once activated, a sleep timer cannot
152be explicitly deleted.  Each task may activate one and only one
153sleep timer at a time.
154
155@subsection Timeouts
156
157@cindex timeouts
158
159Timeouts are a special type of timer automatically
160created when the timeout option is used on the
161@code{@value{DIRPREFIX}message_queue_receive},
162@code{@value{DIRPREFIX}event_receive},
163@code{@value{DIRPREFIX}semaphore_obtain} and
164@code{@value{DIRPREFIX}region_get_segment} directives. 
165Each task may have one and only one timeout active at a time. 
166When a timeout expires, it unblocks the task with a timeout status code.
167
168@section Operations
169
170@subsection Announcing a Tick
171
172RTEMS provides the @code{@value{DIRPREFIX}clock_tick} directive which is
173called from the user's real-time clock ISR to inform RTEMS that
174a tick has elapsed.  The tick frequency value, defined in
175microseconds, is a configuration parameter found in the
176Configuration Table.  RTEMS divides one million microseconds
177(one second) by the number of microseconds per tick to determine
178the number of calls to the
179@code{@value{DIRPREFIX}clock_tick} directive per second.  The
180frequency of @code{@value{DIRPREFIX}clock_tick}
181calls determines the resolution
182(granularity) for all time dependent RTEMS actions.  For
183example, calling @code{@value{DIRPREFIX}clock_tick}
184ten times per second yields a higher
185resolution than calling @code{@value{DIRPREFIX}clock_tick}
186two times per second.  The @code{@value{DIRPREFIX}clock_tick}
187directive is responsible for maintaining both
188calendar time and the dynamic set of timers.
189
190@subsection Setting the Time
191
192The @code{@value{DIRPREFIX}clock_set} directive allows a task or an ISR to
193set the date and time maintained by RTEMS.  If setting the date
194and time causes any outstanding timers to pass their deadline,
195then the expired timers will be fired during the invocation of
196the @code{@value{DIRPREFIX}clock_set} directive.
197
198@subsection Obtaining the Time
199
200The @code{@value{DIRPREFIX}clock_get} directive allows a task or an ISR to
201obtain the current date and time or date and time related
202information.  The current date and time can be returned in
203either native or UNIX-style format.  Additionally, the
204application can obtain date and time related information such as
205the number of seconds since the RTEMS epoch, the number of ticks
206since the executive was initialized, and the number of ticks per
207second.  The information returned by the
208@code{@value{DIRPREFIX}clock_get} directive is
209dependent on the option selected by the caller.  This
210is specified using one of the following constants
211associated with the enumerated type
212@code{@value{DIRPREFIX}clock_get_options}:
213
214@findex rtems_clock_get_options
215
216@itemize @bullet
217@item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time
218
219@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style
220date and time
221
222@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - obtain number of ticks
223since RTEMS was initialized
224
225@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number
226of seconds since RTEMS epoch
227
228@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock
229ticks per second
230
231@end itemize
232
233Calendar time operations will return an error code if
234invoked before the date and time have been set.
235
236@section Directives
237
238This section details the clock manager's directives.
239A subsection is dedicated to each of this manager's directives
240and describes the calling sequence, related constants, usage,
241and status codes.
242
243@c
244@c
245@c
246@page
247@subsection CLOCK_SET - Set date and time
248
249@subheading CALLING SEQUENCE:
250
251@cindex set the time of day
252
253@ifset is-C
254@findex rtems_clock_set
255@example
256rtems_status_code rtems_clock_set(
257  rtems_time_of_day *time_buffer
258);
259@end example
260@end ifset
261
262@ifset is-Ada
263@example
264procedure Clock_Set (
265   Time_Buffer : in     RTEMS.Time_Of_Day;
266   Result      :    out RTEMS.Status_Codes
267);
268@end example
269@end ifset
270
271@subheading DIRECTIVE STATUS CODES:
272@code{@value{RPREFIX}SUCCESSFUL} - date and time set successfully@*
273@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL@*
274@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day
275
276@subheading DESCRIPTION:
277
278This directive sets the system date and time.  The
279date, time, and ticks in the time_buffer @value{STRUCTURE} are all
280range-checked, and an error is returned if any one is out of its
281valid range.
282
283@subheading NOTES:
284
285Years before 1988 are invalid.
286
287The system date and time are based on the configured
288tick rate (number of microseconds in a tick).
289
290Setting the time forward may cause a higher priority
291task, blocked waiting on a specific time, to be made ready.  In
292this case, the calling task will be preempted after the next
293clock tick.
294
295Re-initializing RTEMS causes the system date and time
296to be reset to an uninitialized state.  Another call to
297@code{@value{DIRPREFIX}clock_set} is required to re-initialize
298the system date and time to application specific specifications.
299
300@c
301@c
302@c
303@page
304@subsection CLOCK_GET - Get date and time information
305
306@cindex obtain the time of day
307
308@subheading CALLING SEQUENCE:
309
310@ifset is-C
311@findex rtems_clock_get
312@example
313rtems_status_code rtems_clock_get(
314  rtems_clock_get_options  option,
315  void                    *time_buffer
316);
317@end example
318@end ifset
319
320@ifset is-Ada
321@example
322procedure Clock_Get (
323   Option      : in     RTEMS.Clock_Get_Options;
324   Time_Buffer : in     RTEMS.Address;
325   Result      :    out RTEMS.Status_Codes
326);
327@end example
328@end ifset
329
330@subheading DIRECTIVE STATUS CODES:
331@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
332@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
333@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
334
335@subheading DESCRIPTION:
336
337This directive obtains the system date and time.  If
338the caller is attempting to obtain the date and time (i.e.
339option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH},
340@code{@value{RPREFIX}CLOCK_GET_TOD}, or
341@code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time
342has not been set with a previous call to
343@code{@value{DIRPREFIX}clock_set}, then the
344@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
345The caller can always obtain the number of ticks per second (option is
346@code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of
347ticks since the executive was initialized option is
348@code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}).
349
350The @code{option} argument may taken on any value of the enumerated
351type @code{rtems_clock_get_options}.  The data type expected for
352@code{time_buffer} is based on the value of @code{option} as
353indicated below:
354
355@findex rtems_clock_get_options
356@ifset is-C
357@itemize @bullet
358@item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *)
359
360@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - (rtems_interval *)
361
362@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - (rtems_interval *)
363
364@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - (rtems_interval *)
365
366@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - (rtems_clock_time_value *)
367
368@end itemize
369@end ifset
370
371@ifset is-Ada
372@itemize @bullet
373@item @code{@value{RPREFIX}Clock_Get_TOD} - Address of an variable of
374type RTEMS.Time_Of_Day
375
376@item @code{@value{RPREFIX}Clock_Get_Seconds_Since_Epoch} - Address of an
377variable of type RTEMS.Interval
378
379@item @code{@value{RPREFIX}Clock_Get_Ticks_Since_Boot} - Address of an
380variable of type RTEMS.Interval
381
382@item @code{@value{RPREFIX}Clock_Get_Ticks_Per_Second} - Address of an
383variable of type RTEMS.Interval
384
385@item @code{@value{RPREFIX}Clock_Get_Time_Value} - Address of an variable of
386type RTEMS.Clock_Time_Value
387
388@end itemize
389@end ifset
390
391@subheading NOTES:
392
393This directive is callable from an ISR.
394
395This directive will not cause the running task to be
396preempted.  Re-initializing RTEMS causes the system date and
397time to be reset to an uninitialized state.  Another call to
398@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
399system date and time to application specific specifications.
400
401@c
402@c
403@c
404@page
405@subsection CLOCK_GET_TOD - Get date and time in TOD format
406
407@cindex obtain the time of day
408
409@subheading CALLING SEQUENCE:
410
411@ifset is-C
412@findex rtems_clock_get_tod
413@example
414rtems_status_code rtems_clock_get_tod(
415  rtems_time_of_day *time_buffer
416);
417@end example
418@end ifset
419
420@ifset is-Ada
421@example
422procedure Clock_Get_TOD (
423   Time_Buffer : in     RTEMS.Time_Of_Day;
424   Result      :    out RTEMS.Status_Codes
425);
426@end example
427@end ifset
428
429@subheading DIRECTIVE STATUS CODES:
430@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
431@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
432@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
433
434@subheading DESCRIPTION:
435
436This directive obtains the system date and time.  If the date and time
437has not been set with a previous call to
438@code{@value{DIRPREFIX}clock_set}, then the
439@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
440
441@subheading NOTES:
442
443This directive is callable from an ISR.
444
445This directive will not cause the running task to be
446preempted.  Re-initializing RTEMS causes the system date and
447time to be reset to an uninitialized state.  Another call to
448@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
449system date and time to application specific specifications.
450
451@c
452@c
453@c
454@page
455@subsection CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
456
457@cindex obtain the time of day
458
459@subheading CALLING SEQUENCE:
460
461@ifset is-C
462@findex rtems_clock_get_tod_timeval
463@example
464rtems_status_code rtems_clock_get_tod(
465  struct timeval  *time
466);
467@end example
468@end ifset
469
470@ifset is-Ada
471@example
472procedure Clock_Get_TOD_Timeval (
473   Time   : in     RTEMS.Timeval;
474   Result :    out RTEMS.Status_Codes
475);
476@end example
477@end ifset
478
479@subheading DIRECTIVE STATUS CODES:
480@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
481@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
482@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time} is NULL
483
484@subheading DESCRIPTION:
485
486This directive obtains the system date and time in POSIX
487@code{struct timeval} format.  If the date and time
488has not been set with a previous call to
489@code{@value{DIRPREFIX}clock_set}, then the
490@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
491
492@subheading NOTES:
493
494This directive is callable from an ISR.
495
496This directive will not cause the running task to be
497preempted.  Re-initializing RTEMS causes the system date and
498time to be reset to an uninitialized state.  Another call to
499@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
500system date and time to application specific specifications.
501
502@c
503@c
504@c
505@page
506@subsection CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
507
508@cindex obtain seconds since epoch
509
510@subheading CALLING SEQUENCE:
511
512@ifset is-C
513@findex rtems_clock_get_seconds_since_epoch
514@example
515rtems_status_code rtems_clock_get_seconds_since_epoch(
516  rtems_interval *the_interval
517);
518@end example
519@end ifset
520
521@ifset is-Ada
522@example
523procedure Clock_Get_Seconds_Since_Epoch(
524   The_Interval :    out RTEMS.Interval;
525   Result       :    out RTEMS.Status_Codes
526);
527@end example
528@end ifset
529
530@subheading DIRECTIVE STATUS CODES:
531@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
532@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
533@code{@value{RPREFIX}INVALID_ADDRESS} - @code{the_interval} is NULL
534
535@subheading DESCRIPTION:
536
537This directive returns the number of seconds since the RTEMS
538epoch and the current system date and time.  If the date and time
539has not been set with a previous call to
540@code{@value{DIRPREFIX}clock_set}, then the
541@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
542
543@subheading NOTES:
544
545This directive is callable from an ISR.
546
547This directive will not cause the running task to be
548preempted.  Re-initializing RTEMS causes the system date and
549time to be reset to an uninitialized state.  Another call to
550@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
551system date and time to application specific specifications.
552
553@c
554@c
555@c
556@page
557@subsection CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
558
559@cindex obtain seconds since epoch
560
561@subheading CALLING SEQUENCE:
562
563@ifset is-C
564@findex rtems_clock_get_ticks_per_second
565@example
566rtems_interval rtems_clock_get_ticks_per_second(void);
567@end example
568@end ifset
569
570@ifset is-Ada
571@example
572function Clock_Get_Ticks_Per_Seconds
573return RTEMS.Interval;
574@end example
575@end ifset
576
577@subheading DIRECTIVE STATUS CODES:
578NONE
579
580@subheading DESCRIPTION:
581
582This directive returns the number of clock ticks per second.  This
583is strictly based upon the microseconds per clock tick that the
584application has configured.
585
586@subheading NOTES:
587
588This directive is callable from an ISR.
589
590This directive will not cause the running task to be
591preempted.  Re-initializing RTEMS causes the system date and
592time to be reset to an uninitialized state.  Another call to
593@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
594system date and time to application specific specifications.
595
596@c
597@c
598@c
599@page
600@subsection CLOCK_GET_TICKS_SINCE_BOOT - Get ticks since boot
601
602@cindex obtain ticks since boot
603
604@subheading CALLING SEQUENCE:
605
606@ifset is-C
607@findex rtems_clock_get_ticks_since_boot
608@example
609rtems_interval rtems_clock_get_ticks_since_boot(void);
610@end example
611@end ifset
612
613@ifset is-Ada
614@example
615function Clock_Get_Ticks_Since_Boot
616return RTEMS.Interval;
617@end example
618@end ifset
619
620@subheading DIRECTIVE STATUS CODES:
621NONE
622
623@subheading DESCRIPTION:
624
625This directive returns the number of clock ticks that have elapsed
626since the system was booted.  This is the historical measure of uptime
627in an RTEMS system.  The newer service
628@code{@value{DIRPREFIX}clock_get_uptime} is another and potentially
629more accurate way of obtaining similar information.
630
631@subheading NOTES:
632
633This directive is callable from an ISR.
634
635This directive will not cause the running task to be
636preempted.  Re-initializing RTEMS causes the system date and
637time to be reset to an uninitialized state.  Another call to
638@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
639system date and time to application specific specifications.
640
641This directive simply returns the number of times the dirivective
642@code{@value{DIRPREFIX}clock_tick} has been invoked since the
643system was booted.
644
645@c
646@c
647@c
648@page
649@subsection CLOCK_GET_UPTIME - Get the time since boot
650
651@cindex clock get uptime
652@cindex uptime
653
654@subheading CALLING SEQUENCE:
655
656@ifset is-C
657@findex rtems_clock_get_uptime
658@example
659rtems_status_code rtems_clock_get_uptime(
660  struct timespec *uptime
661);
662@end example
663@end ifset
664
665@ifset is-Ada
666@example
667procedure Clock_Get_Uptime (
668   Uptime :    out RTEMS.Timespec;
669   Result :    out RTEMS.Status_Codes
670);
671@end example
672@end ifset
673
674@subheading DIRECTIVE STATUS CODES:
675@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
676@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
677
678@subheading DESCRIPTION:
679
680This directive returns the seconds and nanoseconds since the
681system was booted.  If the BSP supports nanosecond clock
682accuracy, the time reported will probably be different on every
683call.
684
685@subheading NOTES:
686
687This directive may be called from an ISR.
688
689
690@c
691@c
692@c
693@page
694@subsection CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
695
696@cindex clock set nanoseconds extension
697@cindex nanoseconds extension
698@cindex nanoseconds time accuracy
699
700@subheading CALLING SEQUENCE:
701
702@ifset is-C
703@findex rtems_clock_set_nanoseconds_extension
704@example
705rtems_status_code rtems_clock_set_nanoseconds_extension(
706  rtems_nanoseconds_extension_routine routine
707);
708@end example
709@end ifset
710
711@ifset is-Ada
712@example
713NOT SUPPORTED FROM Ada BINDING
714@end example
715@end ifset
716
717@subheading DIRECTIVE STATUS CODES:
718@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
719@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
720
721@subheading DESCRIPTION:
722
723This directive is used by the Clock device driver to install the
724@code{routine} which will be invoked by the internal RTEMS method used to
725obtain a highly accurate time of day.  It is usually called during
726the initialization of the driver.
727
728When the @code{routine} is invoked, it will determine the number of
729nanoseconds which have elapsed since the last invocation of
730the @code{@value{DIRPREFIX}clock_tick} directive.  It should do
731this as quickly as possible with as little impact as possible
732on the device used as a clock source.
733
734@subheading NOTES:
735
736This directive may be called from an ISR.
737
738This directive is called as part of every service to obtain the
739current date and time as well as timestamps.
740
741@c
742@c
743@c
744@page
745@subsection CLOCK_TICK - Announce a clock tick
746
747@cindex clock tick
748
749@subheading CALLING SEQUENCE:
750
751@ifset is-C
752@findex rtems_clock_tick
753@example
754rtems_status_code rtems_clock_tick( void );
755@end example
756@end ifset
757
758@ifset is-Ada
759@example
760procedure Clock_Tick (
761   Result :    out RTEMS.Status_Codes
762);
763@end example
764@end ifset
765
766@subheading DIRECTIVE STATUS CODES:
767@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully
768
769@subheading DESCRIPTION:
770
771This directive announces to RTEMS that a system clock
772tick has occurred.  The directive is usually called from the
773timer interrupt ISR of the local processor.  This directive
774maintains the system date and time, decrements timers for
775delayed tasks, timeouts, rate monotonic periods, and implements
776timeslicing.
777
778@subheading NOTES:
779
780This directive is typically called from an ISR.
781
782The @code{microseconds_per_tick} and @code{ticks_per_timeslice}
783parameters in the Configuration Table contain the number of
784microseconds per tick and number of ticks per timeslice,
785respectively.
786
Note: See TracBrowser for help on using the repository browser.