Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 347 insertions, 0 deletions

diff --git a/man/man4/rtc.4 b/man/man4/rtc.4
new file mode 100644
index 0000000..f720086
--- /dev/null
+++ b/man/man4/rtc.4
@@ -0,0 +1,347 @@
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+rtc \- real-time clock
+.SH SYNOPSIS
+.nf
+#include <linux/rtc.h>
+.P
+.BI "int ioctl(" fd ", RTC_" request ", " param ");"
+.fi
+.SH DESCRIPTION
+This is the interface to drivers for real-time clocks (RTCs).
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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
+.B RTC_ALM_READ
+.TQ
+.B 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
+.B RTC_IRQP_READ
+.TQ
+.B 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
+.B RTC_AIE_ON
+.TQ
+.B RTC_AIE_OFF
+Enable or disable the alarm interrupt, for RTCs that support alarms.
+The third
+.BR ioctl (2)
+argument is ignored.
+.TP
+.B RTC_UIE_ON
+.TQ
+.B 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
+.B RTC_PIE_ON
+.TQ
+.B 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
+.B RTC_EPOCH_READ
+.TQ
+.B 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
+.B RTC_WKALM_RD
+.TQ
+.B 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:
+.P
+.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
+.I /dev/rtc
+.TQ
+.I /dev/rtc0
+.TQ
+.I /dev/rtc1
+.TQ
+\&.\|.\|.
+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.
+.P
+An RTC's Epoch has nothing to do with the POSIX Epoch which is
+used only for the system clock.
+.P
+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.
+.P
+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.
+.P
+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)
+.P
+.I Documentation/rtc.txt
+in the Linux kernel source tree