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