source: rtems/doc/user/clock.t @ bfddb047

4.11
Last change on this file since bfddb047 was bfddb047, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 16, 2012 at 1:02:12 PM

rtems: Add rtems_clock_get_uptime_timeval()

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