Changes between Initial Version and Version 1 of RTC

Timestamp:

03/20/2018 05:18:10 PM (7 years ago)

Author:

Tim Harvey

Comment:

initial page

RTC

@@ +1 @@
+[[PageOutline]]
+
+[=#rtc]
+= Real Time Clock (RTC) =
+A Real Time Clock (RTC), also known as a 'Hardware Clock' is a time keeping device on a computer that is able to keep the time even when the device is powered off. This is typically done via a dedicated chip that is powered off a coin-cell battery.
+
+
+[=#rtc-class]
+== Linux RTC class (sysfs) ==
+The Linux kernel has a RTC class for RTC drivers which creates entries in {{{/sys/class/rtc}}}. Each RTC device detected and registered via supported drivers has a directory along with its cooresponding {{{/dev/rtc<n>}}} device node that can be used to interact with the RTC.
+
+Here are some examples of what you can do via this {{{sysfs}}} interface:
+ * Show the name of the rtc driver:
+{{{#!bash
+root@xenial-ventana:~# cat /sys/class/rtc/rtc0/name 
+rtc-ds1672
+}}}
+ * Show number of seconds since the [https://en.wikipedia.org/wiki/Unix_time Unix epoch]:
+{{{#!bash
+root@xenial-ventana:~# cat /sys/class/rtc/rtc0/since_epoch 
+143
+}}}
+ * Show Date and Time from the RTC's perspective:
+{{{#!bash
+root@xenial-ventana:~# cat /sys/class/rtc/rtc0/date        
+1970-01-01
+root@xenial-ventana:~# cat /sys/class/rtc/rtc0/time
+00:02:29
+}}}
+
+
+[=#hwclock]
+== hwclock Application ==
+The {{{hwclock}}} application is a userspace app that uses the Linux kernel RTC API to interace with available RTC's on the system in order to:
+ - get the time from the RTC
+ - set the time from the RTC to the Linux system time
+ - set the Linux system time to the RTC
+
+Examples:
+* Update the Linux System Time via NTP, then store the Linux System Time in the RTC:
+{{{#!bash
+ntpdate -s time.nist.gov
+hwclock --systohc
+}}}
+* Set the system time from the RTC:
+{{{#!bash
+hwclock --hctosys # set the system time from the RTC
+}}}
+  - In Ubuntu for example, this is done for you via {{{/etc/init.d/hwclock.sh}}} from the {{{util-linux}}} package.
+
+Note that if you happen to have more than one RTC in the system you can add the {{{-f <device>}}} parameter to refer to the one you want to work with. If you do have more than one RTC and one of them is not useful (such as the snvs RTC from an iMX6 processor on a Ventana board) you can disable or [#modules blacklist the kernel module] to keep it from loading.
+
+
+[=#hctosys]
+== hctosys Kernel option (RTC_HCTOSYS / RTC_HTOSYS_DEVICE) ==
+A kernel option is available at compile time that can set the Linux system time from the value stored in an RTC provided the RTC driver is built static in the kernel. Note that this is not always the case and many RTC drivers these days are built as kernel modules. To enable this you need to build your kernel with the following:
+- RTC_HCTOSYS=y
+- RTC_HCTOSYS_DEVICE=rtc0 (or whichever static RTC you want to use if you have multiple)
+- RTC_DRV_DS1672=y (for the GSC RTC for example)
+
+Note that Gateworks boards have an RTC implemented in the [wiki:gsc Gateworks System Controller (GSC)] that emulates a DS1672 RTC.
+
+If you are using for example an Ubuntu kernel this option is enabled but won't do you any good because the RTC on Gateworks boards are built as a kernel module. In order to set the system time from an RTC built as a module see [#hwclock hwclock above]
+
+
+[=#gsc-rtc]
+== Gateworks Boards and GSC RTC ==
+Gateworks boards have a [wiki:gsc Gateworks System Controller (GSC)] which emulates a DS1672 RTC.
+
+Note that Ventana boards based on the i.MX6 SoC may also have an additional RTC that is detected but not used. On these boards you should disable or blacklist the snvs RTC driver as it has no value because the i.MX6 RTC does not have a battery source.
+
+
+[=#modules]
+== working with RTC kernel modules
+=== blacklisting un-usable RTCs
+Some SoC's have RTC's built in that are un-usable because they don't have a battery powering them. An example of this is the i.MX6 RTC (rtc_snvs kernel driver) on Ventana boards. These boards use the DS1672 RTC emulated by the Gateworks GSC RTC instead.
+
+To get rid of a kernel driver like the i.MX6 RTC driver (rtc_snvs) you can:
+- build your own kernel with it disabled
+- remove the kernel module which depends on the OS your using:
+  * for Ubuntu it would be in /lib/modules/.../rtc_snvs.ko
+- blacklist the kernel module from the init scripts that load modules which depends on the OS your using
+
+Module blacklist examples:
+ * for Ubuntu you can add it to a file in /etc/modprobe.d or create your own such as:
+{{{#!bash
+echo "blacklist rtc_snvs" > /etc/modprobe.d/blacklist-rtc.conf
+}}}
+
+=== syncing the system time with the RTC ===
+If using an RTC that is built in the kernel as a static driver you can use the [#hctosys hctosys] driver option. However if your using a kernel module you need to sync the time manually after the kernel boots. You can do this using the [#hwclock hwclock] application.
+
+
+[=#ntp]
+== Network Time Protocol (NTP) ==
+The Network Time Protocol can be used to update the Linux system clock. While this is completely independent from an RTC it is often useful to update the Linux system time using NTP prior to setting the RTC:
+{{{#!bash
+ntpdate -s time.nist.gov
+hwclock --systohc
+}}}