diff options
Diffstat (limited to 'man4/rtc.4')
| -rw-r--r-- | man4/rtc.4 | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/man4/rtc.4 b/man4/rtc.4 new file mode 100644 index 0000000..aae4fc2 --- /dev/null +++ b/man4/rtc.4 @@ -0,0 +1,327 @@ +.\" rtc.4 +.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $ +.\" +.\" 2006-02-08 Various additions by mtk +.\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell +.\" +.TH rtc 4 2023-02-05 "Linux man-pages 6.05.01" +.SH NAME +rtc \- real-time clock +.SH SYNOPSIS +.nf +#include <linux/rtc.h> +.PP +.BI "int ioctl(" fd ", RTC_" request ", " param ");" +.fi +.SH DESCRIPTION +This is the interface to drivers for real-time clocks (RTCs). +.PP +Most computers have one or more hardware clocks which record the +current "wall clock" time. +These are called "Real Time Clocks" (RTCs). +One of these usually has battery backup power so that it tracks the time +even while the computer is turned off. +RTCs often provide alarms and other interrupts. +.PP +All i386 PCs, and ACPI-based systems, have an RTC that is compatible with +the Motorola MC146818 chip on the original PC/AT. +Today such an RTC is usually integrated into the mainboard's chipset +(south bridge), and uses a replaceable coin-sized backup battery. +.PP +Non-PC systems, such as embedded systems built around system-on-chip +processors, use other implementations. +They usually won't offer the same functionality as the RTC from a PC/AT. +.SS RTC vs system clock +RTCs should not be confused with the system clock, which is +a software clock maintained by the kernel and used to implement +.BR gettimeofday (2) +and +.BR time (2), +as well as setting timestamps on files, and so on. +The system clock reports seconds and microseconds since a start point, +defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC). +(One common implementation counts timer interrupts, once +per "jiffy", at a frequency of 100, 250, or 1000 Hz.) +That is, it is supposed to report wall clock time, which RTCs also do. +.PP +A key difference between an RTC and the system clock is that RTCs +run even when the system is in a low power state (including "off"), +and the system clock can't. +Until it is initialized, the system clock can only report time since +system boot ... not since the POSIX Epoch. +So at boot time, and after resuming from a system low power state, the +system clock will often be set to the current wall clock time using an RTC. +Systems without an RTC need to set the system clock using another clock, +maybe across the network or by entering that data manually. +.SS RTC functionality +RTCs can be read and written with +.BR hwclock (8), +or directly with the +.BR ioctl (2) +requests listed below. +.PP +Besides tracking the date and time, many RTCs can also generate +interrupts +.IP \[bu] 3 +on every clock update (i.e., once per second); +.IP \[bu] +at periodic intervals with a frequency that can be set to +any power-of-2 multiple in the range 2 Hz to 8192 Hz; +.IP \[bu] +on reaching a previously specified alarm time. +.PP +Each of those interrupt sources can be enabled or disabled separately. +On many systems, the alarm interrupt can be configured as a system wakeup +event, which can resume the system from a low power state such as +Suspend-to-RAM (STR, called S3 in ACPI systems), +Hibernation (called S4 in ACPI systems), +or even "off" (called S5 in ACPI systems). +On some systems, the battery backed RTC can't issue +interrupts, but another one can. +.PP +The +.I /dev/rtc +(or +.IR /dev/rtc0 , +.IR /dev/rtc1 , +etc.) +device can be opened only once (until it is closed) and it is read-only. +On +.BR read (2) +and +.BR select (2) +the calling process is blocked until the next interrupt from that RTC +is received. +Following the interrupt, the process can read a long integer, of which +the least significant byte contains a bit mask encoding +the types of interrupt that occurred, +while the remaining 3 bytes contain the number of interrupts since the +last +.BR read (2). +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to RTC devices: +.TP +.B RTC_RD_TIME +Returns this RTC's time in the following structure: +.IP +.in +4n +.EX +struct rtc_time { + int tm_sec; + int tm_min; + int tm_hour; + int tm_mday; + int tm_mon; + int tm_year; + int tm_wday; /* unused */ + int tm_yday; /* unused */ + int tm_isdst; /* unused */ +}; +.EE +.in +.IP +The fields in this structure have the same meaning and ranges as for the +.I tm +structure described in +.BR gmtime (3). +A pointer to this structure should be passed as the third +.BR ioctl (2) +argument. +.TP +.B RTC_SET_TIME +Sets this RTC's time to the time specified by the +.I rtc_time +structure pointed to by the third +.BR ioctl (2) +argument. +To set the +RTC's time the process must be privileged (i.e., have the +.B CAP_SYS_TIME +capability). +.TP +.BR RTC_ALM_READ ", " RTC_ALM_SET +Read and set the alarm time, for RTCs that support alarms. +The alarm interrupt must be separately enabled or disabled using the +.BR RTC_AIE_ON ", " RTC_AIE_OFF +requests. +The third +.BR ioctl (2) +argument is a pointer to an +.I rtc_time +structure. +Only the +.IR tm_sec , +.IR tm_min , +and +.I tm_hour +fields of this structure are used. +.TP +.BR RTC_IRQP_READ ", " RTC_IRQP_SET +Read and set the frequency for periodic interrupts, +for RTCs that support periodic interrupts. +The periodic interrupt must be separately enabled or disabled using the +.BR RTC_PIE_ON ", " RTC_PIE_OFF +requests. +The third +.BR ioctl (2) +argument is an +.I "unsigned long\ *" +or an +.IR "unsigned long" , +respectively. +The value is the frequency in interrupts per second. +The set of allowable frequencies is the multiples of two +in the range 2 to 8192. +Only a privileged process (i.e., one having the +.B CAP_SYS_RESOURCE +capability) can set frequencies above the value specified in +.IR /proc/sys/dev/rtc/max\-user\-freq . +(This file contains the value 64 by default.) +.TP +.BR RTC_AIE_ON ", " RTC_AIE_OFF +Enable or disable the alarm interrupt, for RTCs that support alarms. +The third +.BR ioctl (2) +argument is ignored. +.TP +.BR RTC_UIE_ON ", " RTC_UIE_OFF +Enable or disable the interrupt on every clock update, +for RTCs that support this once-per-second interrupt. +The third +.BR ioctl (2) +argument is ignored. +.TP +.BR RTC_PIE_ON ", " RTC_PIE_OFF +Enable or disable the periodic interrupt, +for RTCs that support these periodic interrupts. +The third +.BR ioctl (2) +argument is ignored. +Only a privileged process (i.e., one having the +.B CAP_SYS_RESOURCE +capability) can enable the periodic interrupt if the frequency is +currently set above the value specified in +.IR /proc/sys/dev/rtc/max\-user\-freq . +.TP +.BR RTC_EPOCH_READ ", " RTC_EPOCH_SET +Many RTCs encode the year in an 8-bit register which is either +interpreted as an 8-bit binary number or as a BCD number. +In both cases, +the number is interpreted relative to this RTC's Epoch. +The RTC's Epoch is +initialized to 1900 on most systems but on Alpha and MIPS it might +also be initialized to 1952, 1980, or 2000, depending on the value of +an RTC register for the year. +With some RTCs, +these operations can be used to read or to set the RTC's Epoch, +respectively. +The third +.BR ioctl (2) +argument is an +.I "unsigned long\ *" +or an +.IR "unsigned long" , +respectively, and the value returned (or assigned) is the Epoch. +To set the RTC's Epoch the process must be privileged (i.e., have the +.B CAP_SYS_TIME +capability). +.TP +.BR RTC_WKALM_RD ", " RTC_WKALM_SET +Some RTCs support a more powerful alarm interface, using these ioctls +to read or write the RTC's alarm time (respectively) with this structure: +.PP +.RS +.in +4n +.EX +struct rtc_wkalrm { + unsigned char enabled; + unsigned char pending; + struct rtc_time time; +}; +.EE +.in +.RE +.IP +The +.I enabled +flag is used to enable or disable the alarm interrupt, +or to read its current status; when using these calls, +.BR RTC_AIE_ON " and " RTC_AIE_OFF +are not used. +The +.I pending +flag is used by +.B RTC_WKALM_RD +to report a pending interrupt +(so it's mostly useless on Linux, except when talking +to the RTC managed by EFI firmware). +The +.I time +field is as used with +.B RTC_ALM_READ +and +.B RTC_ALM_SET +except that the +.IR tm_mday , +.IR tm_mon , +and +.I tm_year +fields are also valid. +A pointer to this structure should be passed as the third +.BR ioctl (2) +argument. +.SH FILES +.TP +.IR /dev/rtc ", " /dev/rtc0 ", " /dev/rtc1 ", etc." +RTC special character device files. +.TP +.I /proc/driver/rtc +status of the (first) RTC. +.SH NOTES +When the kernel's system time is synchronized with an external +reference using +.BR adjtimex (2) +it will update a designated RTC periodically every 11 minutes. +To do so, the kernel has to briefly turn off periodic interrupts; +this might affect programs using that RTC. +.PP +An RTC's Epoch has nothing to do with the POSIX Epoch which is +used only for the system clock. +.PP +If the year according to the RTC's Epoch and the year register is +less than 1970 it is assumed to be 100 years later, that is, between 2000 +and 2069. +.PP +Some RTCs support "wildcard" values in alarm fields, to support +scenarios like periodic alarms at fifteen minutes after every hour, +or on the first day of each month. +Such usage is nonportable; +portable user-space code expects only a single alarm interrupt, and +will either disable or reinitialize the alarm after receiving it. +.PP +Some RTCs support periodic interrupts with periods that are multiples +of a second rather than fractions of a second; +multiple alarms; +programmable output clock signals; +nonvolatile memory; +and other hardware +capabilities that are not currently exposed by this API. +.SH SEE ALSO +.BR date (1), +.BR adjtimex (2), +.BR gettimeofday (2), +.BR settimeofday (2), +.BR stime (2), +.BR time (2), +.BR gmtime (3), +.BR time (7), +.BR hwclock (8) +.PP +.I Documentation/rtc.txt +in the Linux kernel source tree |