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 | @chapter Real-Time Clock Driver |
---|
10 | |
---|
11 | @section Introduction |
---|
12 | |
---|
13 | The Real-Time Clock (@b{RTC}) driver is responsible for providing an |
---|
14 | interface to an @b{RTC} device. [NOTE: In this chapter, the abbreviation |
---|
15 | @b{TOD} is used for @b{Time of Day}.] The capabilities provided by this |
---|
16 | driver are: |
---|
17 | |
---|
18 | @itemize @bullet |
---|
19 | @item Set the RTC TOD to RTEMS TOD |
---|
20 | @item Set the RTEMS TOD to the RTC TOD |
---|
21 | @item Get the RTC TOD |
---|
22 | @item Set the RTC TOD to the Specified TOD |
---|
23 | @item Get the Difference Between the RTEMS and RTC TOD |
---|
24 | @end itemize |
---|
25 | |
---|
26 | The reference implementation for a real-time clock driver can |
---|
27 | be found in @code{c/src/lib/libbsp/shared/tod.c}. This driver |
---|
28 | is based on the libchip concept and can be easily configured |
---|
29 | to work with any of the RTC chips supported by the RTC |
---|
30 | chip drivers in the directory @code{c/src/lib/lib/libchip/rtc}. |
---|
31 | There is a README file in this directory for each supported |
---|
32 | RTC chip. Each of these README explains how to configure the |
---|
33 | shared libchip implementation of the RTC driver for that particular |
---|
34 | RTC chip. |
---|
35 | |
---|
36 | The DY-4 DMV177 BSP uses the shared libchip implementation of the RTC |
---|
37 | driver. Its @code{RTC_Table} configuration table can be found in |
---|
38 | @code{c/src/lib/libbsp/powerpc/dmv177/tod/config.c}. |
---|
39 | |
---|
40 | @section Initialization |
---|
41 | |
---|
42 | The @code{rtc_initialize} routine is responsible for initializing the |
---|
43 | RTC chip so it can be used. The shared libchip implementation of this |
---|
44 | driver supports multiple RTCs and bases its initialization order on |
---|
45 | the order the chips are defined in the @code{RTC_Table}. Each chip |
---|
46 | defined in the table may or may not be present on this particular board. |
---|
47 | It is the responsibility of the @code{deviceProbe} to indicate the |
---|
48 | presence of a particular RTC chip. The first RTC found to be present |
---|
49 | is considered the preferred RTC. |
---|
50 | |
---|
51 | In the shared libchip based implementation |
---|
52 | of the driver, the following actions are performed: |
---|
53 | |
---|
54 | @example |
---|
55 | @group |
---|
56 | rtems_device_driver rtc_initialize( |
---|
57 | rtems_device_major_number major, |
---|
58 | rtems_device_minor_number minor_arg, |
---|
59 | void *arg |
---|
60 | ) |
---|
61 | @{ |
---|
62 | for each RTC configured in RTC_Table |
---|
63 | if the deviceProbe for this RTC indicates it is present |
---|
64 | set RTC_Minor to this device |
---|
65 | set RTC_Present to TRUE |
---|
66 | break out of this loop |
---|
67 | |
---|
68 | if RTC_Present is not TRUE |
---|
69 | return RTEMS_INVALID_NUMBER to indicate that no RTC is present |
---|
70 | |
---|
71 | register this minor number as the "/dev/rtc" |
---|
72 | |
---|
73 | perform the deviceInitialize routine for the preferred RTC chip |
---|
74 | |
---|
75 | for RTCs past this one in the RTC_Table |
---|
76 | if the deviceProbe for this RTC indicates it is present |
---|
77 | perform the deviceInitialize routine for this RTC chip |
---|
78 | register the configured name for this RTC |
---|
79 | @} |
---|
80 | @end group |
---|
81 | @end example |
---|
82 | |
---|
83 | The @code{deviceProbe} routine returns TRUE if the device |
---|
84 | configured by this entry in the @code{RTC_Table} is present. |
---|
85 | This configuration scheme allows one to support multiple versions |
---|
86 | of the same board with a single BSP. For example, if the first |
---|
87 | generation of a board had Vendor A's RTC chip and the second |
---|
88 | generation had Vendor B's RTC chip, RTC_Table could contain |
---|
89 | information for both. The @code{deviceProbe} configured |
---|
90 | for Vendor A's RTC chip would need to return TRUE if the |
---|
91 | board was a first generation one. The @code{deviceProbe} |
---|
92 | routines are very board dependent. |
---|
93 | |
---|
94 | @section setRealTimeToRTEMS |
---|
95 | |
---|
96 | The @code{setRealTimeToRTEMS} routine sets the current RTEMS TOD to that |
---|
97 | of the preferred RTC. |
---|
98 | |
---|
99 | @example |
---|
100 | @group |
---|
101 | void setRealTimeToRTEMS(void) |
---|
102 | @{ |
---|
103 | if no RTCs are present |
---|
104 | return |
---|
105 | |
---|
106 | invoke the deviceGetTime routine for the preferred RTC |
---|
107 | set the RTEMS TOD using rtems_clock_set |
---|
108 | @} |
---|
109 | @end group |
---|
110 | @end example |
---|
111 | |
---|
112 | @section setRealTimeFromRTEMS |
---|
113 | |
---|
114 | The @code{setRealTimeFromRTEMS} routine sets the preferred RTC TOD to the |
---|
115 | current RTEMS TOD. |
---|
116 | |
---|
117 | @example |
---|
118 | @group |
---|
119 | void setRealTimeFromRTEMS(void) |
---|
120 | @{ |
---|
121 | if no RTCs are present |
---|
122 | return |
---|
123 | |
---|
124 | obtain the RTEMS TOD using rtems_clock_get |
---|
125 | invoke the deviceSetTime routine for the preferred RTC |
---|
126 | @} |
---|
127 | @end group |
---|
128 | @end example |
---|
129 | |
---|
130 | @section getRealTime |
---|
131 | |
---|
132 | The @code{getRealTime} returns the preferred RTC TOD to the |
---|
133 | caller. |
---|
134 | |
---|
135 | @example |
---|
136 | @group |
---|
137 | void getRealTime( rtems_time_of_day *tod ) |
---|
138 | @{ |
---|
139 | if no RTCs are present |
---|
140 | return |
---|
141 | |
---|
142 | invoke the deviceGetTime routine for the preferred RTC |
---|
143 | @} |
---|
144 | @end group |
---|
145 | @end example |
---|
146 | |
---|
147 | @section setRealTime |
---|
148 | |
---|
149 | The @code{setRealTime} routine sets the preferred RTC TOD to the |
---|
150 | TOD specified by the caller. |
---|
151 | |
---|
152 | @example |
---|
153 | @group |
---|
154 | void setRealTime( rtems_time_of_day *tod ) |
---|
155 | @{ |
---|
156 | if no RTCs are present |
---|
157 | return |
---|
158 | |
---|
159 | invoke the deviceSetTime routine for the preferred RTC |
---|
160 | @} |
---|
161 | @end group |
---|
162 | @end example |
---|
163 | |
---|
164 | @section checkRealTime |
---|
165 | |
---|
166 | The @code{checkRealTime} routine returns the number of seconds |
---|
167 | difference between the RTC TOD and the current RTEMS TOD. |
---|
168 | |
---|
169 | @example |
---|
170 | @group |
---|
171 | int checkRealTime( void ) |
---|
172 | @{ |
---|
173 | if no RTCs are present |
---|
174 | return -1 |
---|
175 | |
---|
176 | |
---|
177 | obtain the RTEMS TOD using rtems_clock_get |
---|
178 | get the TOD from the preferred RTC using the deviceGetTime routine |
---|
179 | |
---|
180 | convert the RTEMS TOD to seconds |
---|
181 | convert the RTC TOD to seconds |
---|
182 | |
---|
183 | return the RTEMS TOD in seconds - RTC TOD in seconds |
---|
184 | @} |
---|
185 | @end group |
---|
186 | @end example |
---|
187 | |
---|