]>
Commit | Line | Data |
---|---|---|
9c2360f8 MK |
1 | .\" rtc.4 |
2 | .\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) | |
3 | .\" | |
4 | .\" This is free documentation; you can redistribute it and/or | |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
8 | .\" | |
9 | .\" The GNU General Public License's references to "object code" | |
10 | .\" and "executables" are to be interpreted as the output of any | |
11 | .\" document formatting or typesetting system, including | |
12 | .\" intermediate and printed output. | |
13 | .\" | |
14 | .\" This manual is distributed in the hope that it will be useful, | |
15 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | .\" GNU General Public License for more details. | |
18 | .\" | |
19 | .\" You should have received a copy of the GNU General Public | |
20 | .\" License along with this manual; if not, write to the Free | |
21 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
22 | .\" USA. | |
23 | .\" | |
24 | .\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $ | |
25 | .\" | |
26 | .\" 2006-02-08 Various additions by mtk | |
92aebf8f | 27 | .\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell |
9c2360f8 | 28 | .\" |
3d5a3539 | 29 | .TH RTC 4 2006-11-26 "Linux" "Linux Programmer's Manual" |
9c2360f8 MK |
30 | .SH NAME |
31 | rtc \- real-time clock | |
32 | .SH SYNOPSIS | |
33 | #include <linux/rtc.h> | |
92aebf8f MK |
34 | .sp |
35 | .BI "int ioctl(" fd ", RTC_" request ", " param ");" | |
9c2360f8 | 36 | .SH DESCRIPTION |
92aebf8f | 37 | This is the interface to drivers for real-time clocks (RTCs). |
9c2360f8 | 38 | |
92aebf8f MK |
39 | Most computers have one or more hardware clocks which record the |
40 | current "wall clock" time. | |
41 | These are called "Real Time Clocks" (RTCs). | |
42 | One of these usually has battery backup power so that it tracks the time | |
43 | even while the computer is turned off. | |
44 | RTCs often provide alarms and other interrupts. | |
9c2360f8 | 45 | |
92aebf8f MK |
46 | All x86 PCs, and ACPI based systems, have an RTC that is compatible with |
47 | the Motorola MC146818 chip on the original PC/AT. | |
48 | Today such an RTC is usually integrated into the mainboard's chipset | |
49 | (south bridge), and uses a replaceable coin-sized backup battery. | |
9c2360f8 | 50 | |
92aebf8f MK |
51 | Non-PC systems, such as embedded systems built around system-on-chip |
52 | processors, use other implementations. | |
53 | They usually won't offer the same functionality as the RTC from a PC/AT. | |
54 | .SS RTC vs System Clock | |
55 | RTCs should not be confused with the system clock, which is | |
56 | a software clock maintained by the kernel and used to implement | |
57 | .BR gettimeofday (2) | |
58 | and | |
9c2360f8 | 59 | .BR time (2), |
92aebf8f MK |
60 | as well as setting timestamps on files, etc. |
61 | The system clock reports seconds and microseconds since a start point, | |
62 | defined to be the POSIX Epoch: Jan 1, 1970, 0:00 UTC. | |
63 | (One common implementation counts timer interrupts, once | |
64 | per "jiffy", at a frequency of 100, 250, or 1000 Hz.) | |
3758f6da | 65 | That is, it is supposed to report wall clock time, which RTCs also do. |
9c2360f8 | 66 | |
92aebf8f MK |
67 | A key difference between an RTC and the system clock is that RTCs |
68 | run even when the system is in a low power state (including "off"), | |
69 | and the system clock can't. | |
3758f6da | 70 | Until it is initialized, the system clock can only report time since |
92aebf8f MK |
71 | system boot ... not since the POSIX Epoch. |
72 | So at boot time, and after resuming from a system low power state, the | |
73 | system clock will often be set to the current wall clock time using an RTC. | |
74 | Systems without an RTC need to set the system clock using another clock, | |
75 | maybe across the network or by entering that data manually. | |
76 | .SS RTC functionality | |
77 | RTCs can be read and written with | |
78 | .BR hwclock (8), | |
79 | or directly with the ioctl requests listed below. | |
80 | ||
81 | Besides tracking the date and time, many RTCs can also generate | |
9c2360f8 MK |
82 | interrupts |
83 | .IP * | |
75b94dc3 | 84 | on every clock update (i.e., once per second); |
9c2360f8 MK |
85 | .IP * |
86 | at periodic intervals with a frequency that can be set to | |
87 | any power-of-2 multiple in the range 2 Hz to 8192 Hz; | |
88 | .IP * | |
89 | on reaching a previously specified alarm time. | |
90 | .PP | |
92aebf8f MK |
91 | Each of those interrupt sources can be enabled or disabled separately. |
92 | On many systems, the alarm interrupt can be configured as a system wakeup | |
93 | event, which can resume the system from a low power state such as | |
94 | Suspend-to-RAM (STR, called S3 in ACPI systems), | |
95 | Hibernation (called S4 in ACPI systems), | |
96 | or even "off" (called S5 in ACPI systems). | |
97 | On some systems, the battery backed RTC can't issue | |
98 | interrupts, but another one can. | |
9c2360f8 MK |
99 | |
100 | The | |
101 | .B /dev/rtc | |
92aebf8f | 102 | (or |
4df883b9 MK |
103 | .BR /dev/rtc0 , |
104 | .BR /dev/rtc1 , | |
92aebf8f MK |
105 | etc) |
106 | device can be opened only once (until it is closed) and it is read-only. | |
107 | On | |
9c2360f8 MK |
108 | .BR read (2) |
109 | and | |
110 | .BR select (2) | |
92aebf8f | 111 | the calling process is blocked until the next interrupt from that RTC |
9c2360f8 MK |
112 | is received. |
113 | Following the interrupt, the process can read a long integer, of which | |
92aebf8f MK |
114 | the least significant byte contains a bit mask encoding |
115 | the types of interrupt that occurred, | |
9c2360f8 MK |
116 | while the remaining 3 bytes contain the number of interrupts since the |
117 | last | |
118 | .BR read (2). | |
5e21af3a | 119 | .SS ioctl(2) interface |
c13182ef | 120 | The following |
9c2360f8 | 121 | .BR ioctl (2) |
92aebf8f | 122 | requests are defined on file descriptors connected to RTC devices: |
9c2360f8 MK |
123 | .TP |
124 | .B RTC_RD_TIME | |
92aebf8f | 125 | Returns this RTC's time in the following structure: |
9c2360f8 MK |
126 | .PP |
127 | .RS | |
128 | .in +0.5i | |
129 | .nf | |
130 | struct rtc_time { | |
131 | int tm_sec; | |
132 | int tm_min; | |
133 | int tm_hour; | |
134 | int tm_mday; | |
135 | int tm_mon; | |
136 | int tm_year; | |
137 | int tm_wday; /* unused */ | |
138 | int tm_yday; /* unused */ | |
139 | int tm_isdst; /* unused */ | |
140 | }; | |
141 | .fi | |
142 | .in -0.5i | |
143 | .RE | |
144 | .IP | |
145 | The fields in this structure have the same meaning and ranges as for the | |
146 | .I tm | |
147 | structure described in | |
148 | .BR gmtime (3). | |
149 | A pointer to this structure should be passed as the third | |
5e21af3a | 150 | .BR ioctl (2) |
9c2360f8 MK |
151 | argument. |
152 | .TP | |
153 | .B RTC_SET_TIME | |
c13182ef | 154 | Sets this RTC's time to the time specified by the |
9c2360f8 | 155 | .I rtc_time |
c13182ef | 156 | structure pointed to by the third |
5e21af3a | 157 | .BR ioctl (2) |
9c2360f8 MK |
158 | argument. |
159 | To set the | |
92aebf8f | 160 | RTC's time the process must be privileged (i.e., have the |
9c2360f8 MK |
161 | .B CAP_SYS_TIME |
162 | capability). | |
163 | .TP | |
164 | .BR RTC_ALM_READ ", " RTC_ALM_SET | |
92aebf8f MK |
165 | Read and set the alarm time, for RTCs that support alarms. |
166 | The alarm interrupt must be separately enabled or disabled using the | |
167 | .BR RTC_AIE_ON ", " RTC_AIE_OFF | |
168 | requests. | |
60a90ecd MK |
169 | The third |
170 | .BR ioctl (2) | |
171 | argument is a pointer to an | |
c13182ef MK |
172 | .I rtc_time |
173 | structure. | |
174 | Only the | |
9c2360f8 MK |
175 | .IR tm_sec , |
176 | .IR tm_min , | |
177 | and | |
178 | .IR tm_hour | |
179 | fields of this structure are used. | |
180 | .TP | |
181 | .BR RTC_IRQP_READ ", " RTC_IRQP_SET | |
92aebf8f MK |
182 | Read and set the frequency for periodic interrupts, |
183 | for RTCs that support periodic interrupts. | |
184 | The periodic interrupt must be separately enabled or disabled using the | |
185 | .BR RTC_PIE_ON ", " RTC_PIE_OFF | |
186 | requests. | |
60a90ecd MK |
187 | The third |
188 | .BR ioctl (2) | |
189 | argument is a | |
92aebf8f | 190 | .I "unsigned long\ *" |
c13182ef MK |
191 | or a |
192 | .IR "unsigned long" , | |
9c2360f8 | 193 | respectively. |
c13182ef MK |
194 | The value is the frequency in interrupts per second. |
195 | The set of allowable frequencies is the multiples of two | |
9c2360f8 MK |
196 | in the range 2 to 8192. |
197 | Only a privileged process (i.e., one having the | |
198 | .B CAP_SYS_RESOURCE | |
199 | capability) can set frequencies above the value specified in | |
200 | .IR /proc/sys/dev/rtc/max-user-freq . | |
201 | (This file contains the value 64 by default.) | |
202 | .TP | |
203 | .BR RTC_AIE_ON ", " RTC_AIE_OFF | |
92aebf8f | 204 | Enable or disable the alarm interrupt, for RTCs that support alarms. |
60a90ecd MK |
205 | The third |
206 | .BR ioctl (2) | |
207 | argument is ignored. | |
9c2360f8 MK |
208 | .TP |
209 | .BR RTC_UIE_ON ", " RTC_UIE_OFF | |
92aebf8f MK |
210 | Enable or disable the interrupt on every clock update, |
211 | for RTCs that support this once-per-second interrupt. | |
60a90ecd MK |
212 | The third |
213 | .BR ioctl (2) | |
214 | argument is ignored. | |
9c2360f8 MK |
215 | .TP |
216 | .BR RTC_PIE_ON ", " RTC_PIE_OFF | |
92aebf8f MK |
217 | Enable or disable the periodic interrupt, |
218 | for RTCs that support these periodic interrupts. | |
60a90ecd MK |
219 | The third |
220 | .BR ioctl (2) | |
221 | argument is ignored. | |
9c2360f8 MK |
222 | Only a privileged process (i.e., one having the |
223 | .B CAP_SYS_RESOURCE | |
c13182ef | 224 | capability) can enable the periodic interrupt if the frequency is |
9c2360f8 MK |
225 | currently set above the value specified in |
226 | .IR /proc/sys/dev/rtc/max-user-freq . | |
227 | .TP | |
228 | .BR RTC_EPOCH_READ ", " RTC_EPOCH_SET | |
92aebf8f | 229 | Many RTCs encode the year in an 8-bit register which is either |
c13182ef | 230 | interpreted as an 8-bit binary number or as a BCD number. |
9c2360f8 | 231 | In both cases, |
c13182ef | 232 | the number is interpreted relative to this RTC's Epoch. |
92aebf8f MK |
233 | The RTC's Epoch is |
234 | initialized to 1900 on most systems but on Alpha and MIPS it might | |
9c2360f8 | 235 | also be initialized to 1952, 1980, or 2000, depending on the value of |
c13182ef | 236 | an RTC register for the year. |
92aebf8f MK |
237 | With some RTCs, |
238 | these operations can be used to read or to set the RTC's Epoch, | |
239 | respectively. | |
60a90ecd MK |
240 | The third |
241 | .BR ioctl (2) | |
242 | argument is a | |
92aebf8f | 243 | .I "unsigned long\ *" |
c13182ef MK |
244 | or a |
245 | .IR "unsigned long" , | |
92aebf8f MK |
246 | respectively, and the value returned (or assigned) is the epoch. |
247 | To set the RTC's Epoch the process must be privileged (i.e., have the | |
9c2360f8 MK |
248 | .B CAP_SYS_TIME |
249 | capability). | |
92aebf8f MK |
250 | .TP |
251 | .BR RTC_WKALM_RD ", " RTC_WKALM_SET | |
252 | Some RTCs support a more powerful alarm interface, using these ioctls | |
253 | to read or write the RTC's alarm time (respectively) with this structure: | |
254 | .PP | |
255 | .RS | |
256 | .in +0.5i | |
257 | .nf | |
258 | struct rtc_wkalrm { | |
259 | unsigned char enabled; | |
260 | unsigned char pending; | |
261 | struct rtc_time time; | |
262 | }; | |
263 | .fi | |
264 | .in -0.5i | |
265 | .RE | |
266 | .IP | |
267 | The | |
268 | .I enabled | |
269 | flag is used to enable or disable the alarm interrupt, | |
270 | or to read its current status; when using these calls, | |
271 | .BR RTC_AIE_ON " and " RTC_AIE_OFF | |
c13182ef MK |
272 | are not used. |
273 | The | |
92aebf8f MK |
274 | .I pending |
275 | flag is used by RTC_WKALM_RD to report a pending interrupt | |
276 | (so it's mostly useless on Linux, except when talking | |
277 | to the RTC managed by EFI firmware). | |
278 | The | |
279 | .I time | |
280 | field is as used with | |
281 | .B RTC_ALM_READ | |
282 | and | |
283 | .B RTC_ALM_SET | |
284 | except that the | |
285 | .IR tm_mday , | |
286 | .IR tm_mon , | |
287 | and | |
288 | .IR tm_year | |
289 | fields are also valid. | |
290 | A pointer to this structure should be passed as the third | |
5e21af3a | 291 | .BR ioctl (2) |
92aebf8f | 292 | argument. |
9c2360f8 | 293 | .SH FILES |
92aebf8f MK |
294 | .IR /dev/rtc ", " |
295 | .IR /dev/rtc0 ", " | |
296 | .IR /dev/rtc1 ", " | |
297 | etc: RTC special character device files. | |
9c2360f8 | 298 | |
92aebf8f MK |
299 | .IR /proc/driver/rtc : |
300 | status of the (first) RTC. | |
9c2360f8 MK |
301 | .SH NOTES |
302 | When the kernel's system time is synchronized with an external | |
303 | reference using | |
304 | .BR adjtimex (2) | |
c13182ef | 305 | it will update a designated RTC periodically every 11 minutes. |
92aebf8f MK |
306 | To do so, the kernel has to briefly turn off periodic interrupts; |
307 | this might affect programs using that RTC. | |
9c2360f8 | 308 | |
92aebf8f | 309 | An RTC's Epoch has nothing to do with the POSIX Epoch which is only |
9c2360f8 MK |
310 | used for the system clock. |
311 | ||
92aebf8f | 312 | If the year according to the RTC's Epoch and the year register is |
75b94dc3 | 313 | less than 1970 it is assumed to be 100 years later, that is, between 2000 |
9c2360f8 | 314 | and 2069. |
92aebf8f MK |
315 | |
316 | Some RTCs support "wildcard" values in alarm fields, to support | |
317 | scenarios like periodic alarms at fifteen minutes after every hour, | |
c13182ef MK |
318 | or on the first day of each month. |
319 | Such usage is non portable; | |
92aebf8f MK |
320 | portable user space code only expects a single alarm interrupt, and |
321 | will either disable or reinitialize the alarm after receiving it. | |
322 | ||
323 | Some RTCs support periodic interrupts with periods that are multiples | |
324 | of a second rather than fractions of a second; | |
325 | multiple alarms; | |
326 | programmable output clock signals; | |
327 | non-volatile memory; | |
328 | and other hardware | |
329 | capabilities that are not currently exposed by this API. | |
9c2360f8 MK |
330 | .SH "SEE ALSO" |
331 | .BR hwclock (8), | |
332 | .BR date (1), | |
333 | .BR time (2), | |
334 | .BR stime (2), | |
335 | .BR gettimeofday (2), | |
336 | .BR settimeofday (2), | |
337 | .BR adjtimex (2), | |
338 | .BR gmtime (3), | |
eafd5ce1 | 339 | .BR time (7), |
9c2360f8 | 340 | /usr/src/linux/Documentation/rtc.txt |