Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) Real Time Clock (RTC) Drivers for Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) When Linux developers talk about a "Real Time Clock", they usually mean
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) something that tracks wall clock time and is battery backed so that it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) works even with system power off.  Such clocks will normally not track
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) the local time zone or daylight savings time -- unless they dual boot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) with MS-Windows -- but will instead be set to Coordinated Universal Time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) (UTC, formerly "Greenwich Mean Time").
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) The newest non-PC hardware tends to just count seconds, like the time(2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) system call reports, but RTCs also very commonly represent time using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) the Gregorian calendar and 24 hour time, as reported by gmtime(3).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) Linux has two largely-compatible userspace RTC API families you may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) need to know about:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19)     *	/dev/rtc ... is the RTC provided by PC compatible systems,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) 	so it's not very portable to non-x86 systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22)     *	/dev/rtc0, /dev/rtc1 ... are part of a framework that's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 	supported by a wide variety of RTC chips on all systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) Programmers need to understand that the PC/AT functionality is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) always available, and some systems can do much more.  That is, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) RTCs use the same API to make requests in both RTC frameworks (using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) different filenames of course), but the hardware may not offer the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) same functionality.  For example, not every RTC is hooked up to an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) IRQ, so they can't all issue alarms; and where standard PC RTCs can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) only issue an alarm up to 24 hours in the future, other hardware may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) be able to schedule one any time in the upcoming century.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) Old PC/AT-Compatible driver:  /dev/rtc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) All PCs (even Alpha machines) have a Real Time Clock built into them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) Usually they are built into the chipset of the computer, but some may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) actually have a Motorola MC146818 (or clone) on the board. This is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) clock that keeps the date and time while your computer is turned off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) ACPI has standardized that MC146818 functionality, and extended it in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) a few ways (enabling longer alarm periods, and wake-from-hibernate).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) That functionality is NOT exposed in the old driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) However it can also be used to generate signals from a slow 2Hz to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) relatively fast 8192Hz, in increments of powers of two. These signals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) are reported by interrupt number 8. (Oh! So *that* is what IRQ 8 is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) for...) It can also function as a 24hr alarm, raising IRQ 8 when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) alarm goes off. The alarm can also be programmed to only check any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) subset of the three programmable values, meaning that it could be set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) ring on the 30th second of the 30th minute of every hour, for example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) The clock can also be set to generate an interrupt upon every clock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) update, thus generating a 1Hz signal.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) The interrupts are reported via /dev/rtc (major 10, minor 135, read only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) character device) in the form of an unsigned long. The low byte contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) the type of interrupt (update-done, alarm-rang, or periodic) that was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) raised, and the remaining bytes contain the number of interrupts since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) the last read.  Status information is reported through the pseudo-file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) /proc/driver/rtc if the /proc filesystem was enabled.  The driver has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) built in locking so that only one process is allowed to have the /dev/rtc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) interface open at a time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) A user process can monitor these interrupts by doing a read(2) or a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) select(2) on /dev/rtc -- either will block/stop the user process until
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) the next interrupt is received. This is useful for things like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) reasonably high frequency data acquisition where one doesn't want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) burn up 100% CPU by polling gettimeofday etc. etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) At high frequencies, or under high loads, the user process should check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) the number of interrupts received since the last read to determine if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) there has been any interrupt "pileup" so to speak. Just for reference, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) typical 486-33 running a tight read loop on /dev/rtc will start to suffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) occasional interrupt pileup (i.e. > 1 IRQ event since last read) for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) frequencies above 1024Hz. So you really should check the high bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) of the value you read, especially at frequencies above that of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) normal timer interrupt, which is 100Hz.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) Programming and/or enabling interrupt frequencies greater than 64Hz is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) only allowed by root. This is perhaps a bit conservative, but we don't want
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) an evil user generating lots of IRQs on a slow 386sx-16, where it might have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) a negative impact on performance. This 64Hz limit can be changed by writing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) a different value to /proc/sys/dev/rtc/max-user-freq. Note that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) interrupt handler is only a few lines of code to minimize any possibility
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) of this effect.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) Also, if the kernel time is synchronized with an external source, the 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) kernel will write the time back to the CMOS clock every 11 minutes. In 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) the process of doing this, the kernel briefly turns off RTC periodic 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) interrupts, so be aware of this if you are doing serious work. If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) don't synchronize the kernel time with an external source (via ntp or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) whatever) then the kernel will keep its hands off the RTC, allowing you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) exclusive access to the device for your applications.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) The alarm and/or interrupt frequency are programmed into the RTC via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) various ioctl(2) calls as listed in ./include/linux/rtc.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) Rather than write 50 pages describing the ioctl() and so on, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) perhaps more useful to include a small test program that demonstrates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) how to use them, and demonstrates the features of the driver. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) probably a lot more useful to people interested in writing applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) that will be using this driver.  See the code at the end of this document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) (The original /dev/rtc driver was written by Paul Gortmaker.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) New portable "RTC Class" drivers:  /dev/rtcN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) --------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) Because Linux supports many non-ACPI and non-PC platforms, some of which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) have more than one RTC style clock, it needed a more portable solution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) than expecting a single battery-backed MC146818 clone on every system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Accordingly, a new "RTC Class" framework has been defined.  It offers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) three different userspace interfaces:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)     *	/dev/rtcN ... much the same as the older /dev/rtc interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)     *	/sys/class/rtc/rtcN ... sysfs attributes support readonly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) 	access to some RTC attributes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)     *	/proc/driver/rtc ... the system clock RTC may expose itself
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 	using a procfs interface. If there is no RTC for the system clock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) 	rtc0 is used by default. More information is (currently) shown
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 	here than through sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) The RTC Class framework supports a wide variety of RTCs, ranging from those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) integrated into embeddable system-on-chip (SOC) processors to discrete chips
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) using I2C, SPI, or some other bus to communicate with the host CPU.  There's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) even support for PC-style RTCs ... including the features exposed on newer PCs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) through ACPI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) The new framework also removes the "one RTC per system" restriction.  For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) example, maybe the low-power battery-backed RTC is a discrete I2C chip, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) a high functionality RTC is integrated into the SOC.  That system might read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) the system clock from the discrete RTC, but use the integrated one for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) other tasks, because of its greater functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) Check out tools/testing/selftests/rtc/rtctest.c for an example usage of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) ioctl interface.