]>
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 | |
34ccb744 | 46 | All i386 PCs, and ACPI based systems, have an RTC that is compatible with |
92aebf8f MK |
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 | 82 | interrupts |
a6e2f128 | 83 | .IP * 3 |
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 | |
83b78642 | 101 | .I /dev/rtc |
92aebf8f | 102 | (or |
83b78642 MK |
103 | .IR /dev/rtc0 , |
104 | .IR /dev/rtc1 , | |
0967c11f | 105 | etc.) |
92aebf8f MK |
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: |
a6e2f128 | 126 | .IP |
088a639b | 127 | .in +4n |
9c2360f8 MK |
128 | .nf |
129 | struct rtc_time { | |
130 | int tm_sec; | |
131 | int tm_min; | |
132 | int tm_hour; | |
133 | int tm_mday; | |
134 | int tm_mon; | |
135 | int tm_year; | |
136 | int tm_wday; /* unused */ | |
137 | int tm_yday; /* unused */ | |
138 | int tm_isdst; /* unused */ | |
139 | }; | |
140 | .fi | |
a08ea57c | 141 | .in |
9c2360f8 MK |
142 | .IP |
143 | The fields in this structure have the same meaning and ranges as for the | |
144 | .I tm | |
145 | structure described in | |
146 | .BR gmtime (3). | |
147 | A pointer to this structure should be passed as the third | |
5e21af3a | 148 | .BR ioctl (2) |
9c2360f8 MK |
149 | argument. |
150 | .TP | |
151 | .B RTC_SET_TIME | |
c13182ef | 152 | Sets this RTC's time to the time specified by the |
9c2360f8 | 153 | .I rtc_time |
c13182ef | 154 | structure pointed to by the third |
5e21af3a | 155 | .BR ioctl (2) |
9c2360f8 MK |
156 | argument. |
157 | To set the | |
92aebf8f | 158 | RTC's time the process must be privileged (i.e., have the |
9c2360f8 MK |
159 | .B CAP_SYS_TIME |
160 | capability). | |
161 | .TP | |
162 | .BR RTC_ALM_READ ", " RTC_ALM_SET | |
92aebf8f MK |
163 | Read and set the alarm time, for RTCs that support alarms. |
164 | The alarm interrupt must be separately enabled or disabled using the | |
165 | .BR RTC_AIE_ON ", " RTC_AIE_OFF | |
166 | requests. | |
60a90ecd MK |
167 | The third |
168 | .BR ioctl (2) | |
169 | argument is a pointer to an | |
c13182ef MK |
170 | .I rtc_time |
171 | structure. | |
172 | Only the | |
9c2360f8 MK |
173 | .IR tm_sec , |
174 | .IR tm_min , | |
175 | and | |
0daa9e92 | 176 | .I tm_hour |
9c2360f8 MK |
177 | fields of this structure are used. |
178 | .TP | |
179 | .BR RTC_IRQP_READ ", " RTC_IRQP_SET | |
92aebf8f MK |
180 | Read and set the frequency for periodic interrupts, |
181 | for RTCs that support periodic interrupts. | |
182 | The periodic interrupt must be separately enabled or disabled using the | |
183 | .BR RTC_PIE_ON ", " RTC_PIE_OFF | |
184 | requests. | |
60a90ecd MK |
185 | The third |
186 | .BR ioctl (2) | |
3c5e62b6 | 187 | argument is an |
92aebf8f | 188 | .I "unsigned long\ *" |
3c5e62b6 | 189 | or an |
c13182ef | 190 | .IR "unsigned long" , |
9c2360f8 | 191 | respectively. |
c13182ef MK |
192 | The value is the frequency in interrupts per second. |
193 | The set of allowable frequencies is the multiples of two | |
9c2360f8 MK |
194 | in the range 2 to 8192. |
195 | Only a privileged process (i.e., one having the | |
196 | .B CAP_SYS_RESOURCE | |
197 | capability) can set frequencies above the value specified in | |
198 | .IR /proc/sys/dev/rtc/max-user-freq . | |
199 | (This file contains the value 64 by default.) | |
200 | .TP | |
201 | .BR RTC_AIE_ON ", " RTC_AIE_OFF | |
92aebf8f | 202 | Enable or disable the alarm interrupt, for RTCs that support alarms. |
60a90ecd MK |
203 | The third |
204 | .BR ioctl (2) | |
205 | argument is ignored. | |
9c2360f8 MK |
206 | .TP |
207 | .BR RTC_UIE_ON ", " RTC_UIE_OFF | |
92aebf8f MK |
208 | Enable or disable the interrupt on every clock update, |
209 | for RTCs that support this once-per-second interrupt. | |
60a90ecd MK |
210 | The third |
211 | .BR ioctl (2) | |
212 | argument is ignored. | |
9c2360f8 MK |
213 | .TP |
214 | .BR RTC_PIE_ON ", " RTC_PIE_OFF | |
92aebf8f MK |
215 | Enable or disable the periodic interrupt, |
216 | for RTCs that support these periodic interrupts. | |
60a90ecd MK |
217 | The third |
218 | .BR ioctl (2) | |
219 | argument is ignored. | |
9c2360f8 MK |
220 | Only a privileged process (i.e., one having the |
221 | .B CAP_SYS_RESOURCE | |
c13182ef | 222 | capability) can enable the periodic interrupt if the frequency is |
9c2360f8 MK |
223 | currently set above the value specified in |
224 | .IR /proc/sys/dev/rtc/max-user-freq . | |
225 | .TP | |
226 | .BR RTC_EPOCH_READ ", " RTC_EPOCH_SET | |
92aebf8f | 227 | Many RTCs encode the year in an 8-bit register which is either |
c13182ef | 228 | interpreted as an 8-bit binary number or as a BCD number. |
9c2360f8 | 229 | In both cases, |
c13182ef | 230 | the number is interpreted relative to this RTC's Epoch. |
92aebf8f MK |
231 | The RTC's Epoch is |
232 | initialized to 1900 on most systems but on Alpha and MIPS it might | |
9c2360f8 | 233 | also be initialized to 1952, 1980, or 2000, depending on the value of |
c13182ef | 234 | an RTC register for the year. |
92aebf8f MK |
235 | With some RTCs, |
236 | these operations can be used to read or to set the RTC's Epoch, | |
237 | respectively. | |
60a90ecd MK |
238 | The third |
239 | .BR ioctl (2) | |
240 | argument is a | |
92aebf8f | 241 | .I "unsigned long\ *" |
c13182ef MK |
242 | or a |
243 | .IR "unsigned long" , | |
be9634cf | 244 | respectively, and the value returned (or assigned) is the Epoch. |
92aebf8f | 245 | To set the RTC's Epoch the process must be privileged (i.e., have the |
9c2360f8 MK |
246 | .B CAP_SYS_TIME |
247 | capability). | |
92aebf8f MK |
248 | .TP |
249 | .BR RTC_WKALM_RD ", " RTC_WKALM_SET | |
250 | Some RTCs support a more powerful alarm interface, using these ioctls | |
251 | to read or write the RTC's alarm time (respectively) with this structure: | |
252 | .PP | |
253 | .RS | |
088a639b | 254 | .in +4n |
92aebf8f MK |
255 | .nf |
256 | struct rtc_wkalrm { | |
257 | unsigned char enabled; | |
258 | unsigned char pending; | |
259 | struct rtc_time time; | |
260 | }; | |
261 | .fi | |
a08ea57c | 262 | .in |
92aebf8f MK |
263 | .RE |
264 | .IP | |
265 | The | |
266 | .I enabled | |
267 | flag is used to enable or disable the alarm interrupt, | |
268 | or to read its current status; when using these calls, | |
269 | .BR RTC_AIE_ON " and " RTC_AIE_OFF | |
c13182ef MK |
270 | are not used. |
271 | The | |
92aebf8f | 272 | .I pending |
231846a6 MK |
273 | flag is used by |
274 | .B RTC_WKALM_RD | |
275 | to report a pending interrupt | |
92aebf8f MK |
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 | |
0daa9e92 | 288 | .I tm_year |
92aebf8f MK |
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 | 318 | or on the first day of each month. |
c382a365 | 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 | 330 | .SH "SEE ALSO" |
9c2360f8 | 331 | .BR date (1), |
f0c34053 | 332 | .BR adjtimex (2), |
9c2360f8 MK |
333 | .BR gettimeofday (2), |
334 | .BR settimeofday (2), | |
f0c34053 MK |
335 | .BR stime (2), |
336 | .BR time (2), | |
9c2360f8 | 337 | .BR gmtime (3), |
eafd5ce1 | 338 | .BR time (7), |
f0c34053 | 339 | .BR hwclock (8), |
9c2360f8 | 340 | /usr/src/linux/Documentation/rtc.txt |