source: rtems/doc/user/clock.t @ 4fa4ea65

4.104.114.84.95
Last change on this file since 4fa4ea65 was 4fa4ea65, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 27, 1998 at 1:24:21 PM

Added Hitachi SH

  • Property mode set to 100644
File size: 14.4 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@ifinfo
10@node Clock Manager, Clock Manager Introduction, INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress, Top
11@end ifinfo
12@chapter Clock Manager
13@ifinfo
14@menu
15* Clock Manager Introduction::
16* Clock Manager Background::
17* Clock Manager Operations::
18* Clock Manager Directives::
19@end menu
20@end ifinfo
21
22@ifinfo
23@node Clock Manager Introduction, Clock Manager Background, Clock Manager, Clock Manager
24@end ifinfo
25@section Introduction
26
27The clock manager provides support for time of day
28and other time related capabilities.  The directives provided by
29the clock manager are:
30
31@itemize @bullet
32@item @code{@value{DIRPREFIX}clock_set} - Set system date and time
33@item @code{@value{DIRPREFIX}clock_get} - Get system date and time information
34@item @code{@value{DIRPREFIX}clock_tick} - Announce a clock tick
35@end itemize
36
37@ifinfo
38@node Clock Manager Background, Required Support, Clock Manager Introduction, Clock Manager
39@end ifinfo
40@section Background
41@ifinfo
42@menu
43* Required Support::
44* Time and Date Data Structures::
45* Clock Tick and Timeslicing::
46* Delays::
47* Timeouts::
48@end menu
49@end ifinfo
50
51@ifinfo
52@node Required Support, Time and Date Data Structures, Clock Manager Background, Clock Manager Background
53@end ifinfo
54@subsection Required Support
55
56For the features provided by the clock manager to be
57utilized, periodic timer interrupts are required.  Therefore, a
58real-time clock or hardware timer is necessary to create the
59timer interrupts.  The clock_tick directive is normally called
60by the timer ISR to announce to RTEMS that a system clock tick
61has occurred.  Elapsed time is measured in ticks.  A tick is
62defined to be an integral number of microseconds which is
63specified by the user in the Configuration Table.
64
65@ifinfo
66@node Time and Date Data Structures, Clock Tick and Timeslicing, Required Support, Clock Manager Background
67@end ifinfo
68@subsection Time and Date Data Structures
69
70The clock facilities of the clock manager operate
71upon calendar time.  These directives utilize the following date
72and time @value{STRUCTURE} for the native time and date format:
73
74@ifset is-C
75@example
76struct rtems_tod_control @{
77  rtems_unsigned32 year;   /* greater than 1987 */
78  rtems_unsigned32 month;  /* 1 - 12 */
79  rtems_unsigned32 day;    /* 1 - 31 */
80  rtems_unsigned32 hour;   /* 0 - 23 */
81  rtems_unsigned32 minute; /* 0 - 59 */
82  rtems_unsigned32 second; /* 0 - 59 */
83  rtems_unsigned32 ticks;  /* elapsed between seconds */
84@};
85
86typedef struct rtems_tod_control rtems_time_of_day;
87@end example
88@end ifset
89
90@ifset is-Ada
91@example
92type Time_Of_Day is
93   record
94      Year    : RTEMS.Unsigned32; -- year, A.D.
95      Month   : RTEMS.Unsigned32; -- month, 1 .. 12
96      Day     : RTEMS.Unsigned32; -- day, 1 .. 31
97      Hour    : RTEMS.Unsigned32; -- hour, 0 .. 23
98      Minute  : RTEMS.Unsigned32; -- minute, 0 .. 59
99      Second  : RTEMS.Unsigned32; -- second, 0 .. 59
100      Ticks   : RTEMS.Unsigned32; -- elapsed ticks between seconds
101   end record;
102@end example
103@end ifset
104
105
106The native date and time format is the only format
107supported when setting the system date and time using the
108clock_get directive.  Some applications expect to operate on a
109"UNIX-style" date and time data structure.  The clock_get
110directive can optionally return the current date and time in the
111following @value{STRUCTURE}:
112
113@ifset is-C
114@example
115@group
116typedef struct @{
117  rtems_unsigned32 seconds;       /* seconds since RTEMS epoch*/
118  rtems_unsigned32 microseconds;  /* since last second        */
119@} rtems_clock_time_value;
120@end group
121@end example
122@end ifset
123
124@ifset is-Ada
125@example
126type Clock_Time_Value is
127   record
128      Seconds      : Unsigned32;
129      Microseconds : Unsigned32;
130   end record;
131@end example
132@end ifset
133
134The seconds field in this @value{STRUCTURE} is the number of
135seconds since the RTEMS epoch of January 1, 1988.
136
137@ifinfo
138@node Clock Tick and Timeslicing, Delays, Time and Date Data Structures, Clock Manager Background
139@end ifinfo
140@subsection Clock Tick and Timeslicing
141
142Timeslicing is a task scheduling discipline in which
143tasks of equal priority are executed for a specific period of
144time before control of the CPU is passed to another task.  It is
145also sometimes referred to as the automatic round-robin
146scheduling algorithm.  The length of time allocated to each task
147is known as the quantum or timeslice.
148
149The system's timeslice is defined as an integral
150number of ticks, and is specified in the Configuration Table.
151The timeslice is defined for the entire system of tasks, but
152timeslicing is enabled and disabled on a per task basis.
153
154The clock_tick directive implements timeslicing by
155decrementing the running task's time-remaining counter when both
156timeslicing and preemption are enabled.  If the task's timeslice
157has expired, then that task will be preempted if there exists a
158ready task of equal priority.
159
160@ifinfo
161@node Delays, Timeouts, Clock Tick and Timeslicing, Clock Manager Background
162@end ifinfo
163@subsection Delays
164
165A sleep timer allows a task to delay for a given
166interval or up until a given time, and then wake and continue
167execution.  This type of timer is created automatically by the
168task_wake_after and task_wake_when directives and, as a result,
169does not have an RTEMS ID.  Once activated, a sleep timer cannot
170be explicitly deleted.  Each task may activate one and only one
171sleep timer at a time.
172
173@ifinfo
174@node Timeouts, Clock Manager Operations, Delays, Clock Manager Background
175@end ifinfo
176@subsection Timeouts
177
178Timeouts are a special type of timer automatically
179created when the timeout option is used on the
180message_queue_receive, event_receive, semaphore_obtain and
181region_get_segment directives.  Each task may have one and only
182one timeout active at a time.  When a timeout expires, it
183unblocks the task with a timeout status code.
184
185@ifinfo
186@node Clock Manager Operations, Announcing a Tick, Timeouts, Clock Manager
187@end ifinfo
188@section Operations
189@ifinfo
190@menu
191* Announcing a Tick::
192* Setting the Time::
193* Obtaining the Time::
194@end menu
195@end ifinfo
196
197@ifinfo
198@node Announcing a Tick, Setting the Time, Clock Manager Operations, Clock Manager Operations
199@end ifinfo
200@subsection Announcing a Tick
201
202RTEMS provides the clock_tick directive which is
203called from the user's real-time clock ISR to inform RTEMS that
204a tick has elapsed.  The tick frequency value, defined in
205microseconds, is a configuration parameter found in the
206Configuration Table.  RTEMS divides one million microseconds
207(one second) by the number of microseconds per tick to determine
208the number of calls to the clock_tick directive per second.  The
209frequency of clock_tick calls determines the resolution
210(granularity) for all time dependent RTEMS actions.  For
211example, calling clock_tick ten times per second yields a higher
212resolution than calling clock_tick two times per second.  The
213clock_tick directive is responsible for maintaining both
214calendar time and the dynamic set of timers.
215
216@ifinfo
217@node Setting the Time, Obtaining the Time, Announcing a Tick, Clock Manager Operations
218@end ifinfo
219@subsection Setting the Time
220
221The clock_set directive allows a task or an ISR to
222set the date and time maintained by RTEMS.  If setting the date
223and time causes any outstanding timers to pass their deadline,
224then the expired timers will be fired during the invocation of
225the clock_set directive.
226
227@ifinfo
228@node Obtaining the Time, Clock Manager Directives, Setting the Time, Clock Manager Operations
229@end ifinfo
230@subsection Obtaining the Time
231
232The clock_get directive allows a task or an ISR to
233obtain the current date and time or date and time related
234information.  The current date and time can be returned in
235either native or UNIX-style format.  Additionally, the
236application can obtain date and time related information such as
237the number of seconds since the RTEMS epoch, the number of ticks
238since the executive was initialized, and the number of ticks per
239second.  The information returned by the clock_get directive is
240dependent on the option selected by the caller.  The following
241options are available:
242
243@itemize @bullet
244@item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time
245
246@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style date and time
247
248@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - obtain number of ticks
249since RTEMS was initialized
250
251@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number of seconds
252since RTEMS epoch
253
254@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock ticks
255per second
256
257@end itemize
258
259Calendar time operations will return an error code if
260invoked before the date and time have been set.
261
262@ifinfo
263@node Clock Manager Directives, CLOCK_SET - Set system date and time, Obtaining the Time, Clock Manager
264@end ifinfo
265@section Directives
266@ifinfo
267@menu
268* CLOCK_SET - Set system date and time::
269* CLOCK_GET - Get system date and time information::
270* CLOCK_TICK - Announce a clock tick::
271@end menu
272@end ifinfo
273
274This section details the clock manager's directives.
275A subsection is dedicated to each of this manager's directives
276and describes the calling sequence, related constants, usage,
277and status codes.
278
279@page
280@ifinfo
281@node CLOCK_SET - Set system date and time, CLOCK_GET - Get system date and time information, Clock Manager Directives, Clock Manager Directives
282@end ifinfo
283@subsection CLOCK_SET - Set system date and time
284
285@subheading CALLING SEQUENCE:
286
287@ifset is-C
288@example
289rtems_status_code rtems_clock_set(
290  rtems_time_of_day *time_buffer
291);
292@end example
293@end ifset
294
295@ifset is-Ada
296@example
297procedure Clock_Set (
298   Time_Buffer : in     RTEMS.Time_Of_Day;
299   Result      :    out RTEMS.Status_Codes
300);
301@end example
302@end ifset
303
304@subheading DIRECTIVE STATUS CODES:
305@code{@value{RPREFIX}SUCCESSFUL} - date and time set successfully@*
306@code{INVALID_TIME_OF_DAY} - invalid time of day
307
308@subheading DESCRIPTION:
309
310This directive sets the system date and time.  The
311date, time, and ticks in the time_buffer @value{STRUCTURE} are all
312range-checked, and an error is returned if any one is out of its
313valid range.
314
315@subheading NOTES:
316
317Years before 1988 are invalid.
318
319The system date and time are based on the configured
320tick rate (number of microseconds in a tick).
321
322Setting the time forward may cause a higher priority
323task, blocked waiting on a specific time, to be made ready.  In
324this case, the calling task will be preempted after the next
325clock tick.
326
327Re-initializing RTEMS causes the system date and time
328to be reset to an uninitialized state.  Another call to
329clock_set is required to re-initialize the system date and time
330to application specific specifications.
331
332@page
333@ifinfo
334@node CLOCK_GET - Get system date and time information, CLOCK_TICK - Announce a clock tick, CLOCK_SET - Set system date and time, Clock Manager Directives
335@end ifinfo
336@subsection CLOCK_GET - Get system date and time information
337
338@subheading CALLING SEQUENCE:
339
340@ifset is-C
341@example
342rtems_status_code rtems_clock_get(
343  rtems_clock_get_options  option,
344  void                    *time_buffer
345);
346@end example
347@end ifset
348
349@ifset is-Ada
350@example
351procedure Clock_Get (
352   Option      : in     RTEMS.Clock_Get_Options;
353   Time_Buffer : in     RTEMS.Address;
354   Result      :    out RTEMS.Status_Codes
355);
356@end example
357@end ifset
358
359@subheading DIRECTIVE STATUS CODES:
360@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
361@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set
362
363@subheading DESCRIPTION:
364
365This directive obtains the system date and time.  If
366the caller is attempting to obtain the date and time (i.e.
367option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH},
368@code{@value{RPREFIX}CLOCK_GET_TOD}, or @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time
369has not been set with a previous call to clock_set, then the
370@code{@value{RPREFIX}NOT_DEFINED} status code is returned.  The caller can always
371obtain the number of ticks per second (option is
372@code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of ticks since the
373executive was initialized option is @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}).
374
375The data type expected for time_buffer is indicated below:
376
377@ifset is-C
378@itemize @bullet
379@item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *)
380
381@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - (rtems_clock_time_value *)
382
383@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - (rtems_interval *)
384
385@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - (rtems_interval *)
386
387@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - (rtems_interval *)
388
389@end itemize
390@end ifset
391
392@ifset is-Ada
393@itemize @bullet
394@item @code{@value{RPREFIX}CLOCK_GET_TOD} - Address of an variable of type RTEMS.Time_Of_Day
395
396@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - Address of an variable of
397type RTEMS.Clock_Time_Value
398
399@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - Address of an variable of
400type RTEMS.Interval
401
402@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - Address of an variable of
403type RTEMS.Interval
404
405@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - Address of an variable of
406type RTEMS.Interval
407
408@end itemize
409@end ifset
410
411@subheading NOTES:
412
413This directive is callable from an ISR.
414
415This directive will not cause the running task to be
416preempted.  Re-initializing RTEMS causes the system date and
417time to be reset to an uninitialized state.  Another call to
418clock_set is required to re-initialize the system date and time
419to application specific specifications.
420
421@page
422@ifinfo
423@node CLOCK_TICK - Announce a clock tick, Timer Manager, CLOCK_GET - Get system date and time information, Clock Manager Directives
424@end ifinfo
425@subsection CLOCK_TICK - Announce a clock tick
426
427@subheading CALLING SEQUENCE:
428
429@ifset is-C
430@example
431rtems_status_code rtems_clock_tick( void );
432@end example
433@end ifset
434
435@ifset is-Ada
436@example
437procedure Clock_Tick (
438   Result :    out RTEMS.Status_Codes
439);
440@end example
441@end ifset
442
443@subheading DIRECTIVE STATUS CODES:
444@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully
445
446@subheading DESCRIPTION:
447
448This directive announces to RTEMS that a system clock
449tick has occurred.  The directive is usually called from the
450timer interrupt ISR of the local processor.  This directive
451maintains the system date and time, decrements timers for
452delayed tasks, timeouts, rate monotonic periods, and implements
453timeslicing.
454
455@subheading NOTES:
456
457This directive is typically called from an ISR.
458
459The microseconds_per_tick and ticks_per_timeslice
460parameters in the Configuration Table contain the number of
461microseconds per tick and number of ticks per timeslice,
462respectively.
463
Note: See TracBrowser for help on using the repository browser.