This application note explains how to use the external I2C-based Real Time Clock (RTC) on the i.MX 8M SOM Starter Kit.

The Starter Kit provides both external (DS1339) and on-chip (SNVS) RTC, as well as a battery holder for a coin battery providing back-up power. The external (DS1339) RTC should be enabled in the Linux .dts file. To do this, change the status of the ds1339 device node from disabled to okay in meta-emcraft/recipes-kernel/linux/linux-imx/imx8m-som.dts:

ds1339: rtc@68 {
                ...
                status = "okay";
};

Both RTC devices will be available in Linux as /dev/rtc0 and /dev/rtc1 correspondingly. The external RTC will be used by default and available as /dev/rtc (a symlink to /dev/rtc0).

Step through the following procedure:

1. Boot Linux to the shell interface and validate that the RTC devices have been detected and initialized by the Linux kernel successfully:

root@imx8m-som:~# dmesg | grep rtc
[    1.048209] rtc-ds1307 0-0068: rtc core: registered ds1339 as rtc0
[    1.050166] snvs_rtc 30370000.snvs:snvs-rtc-lp: rtc core: registered 
30370000.snvs:snvs- as rtc1
...
root@imx8m-som:~#

2. The software installed on the i.MX 8M SOM Starter Kit has the systemd-timesyncd daemon enabled by default. It implements an SNTP client and is synchronizing the system clock across the network in background, assuming that the Starter Kit has access to the Internet. Temporarily stop this daemon:

root@imx8m-som:~# systemctl stop systemd-timesyncd

3. The system time and date can be set to the right values manually, using the date command:

root@imx8m-som:~# date -s "2018-05-05 05:05:05"
Sat May  5 05:05:05 UTC 2018
root@imx8m-som:~#

4. It is important to understand that the system time is reset on each power / reset cycle. It is therefore important to write the system time into the RTC. This is done as follows:

root@imx8m-som:~# hwclock -w
root@imx8m-som:~#

5. Now the RTC has the right time and date so even if we disconnect the main power from the Starter Kit, we will still maintain the time in the RTC, as long as the RTC is powered from a battery. To test that, disconnect the main power from the i.MX 8M SOM Starter Kit for several minutes and then power the Starter Kit up again.
6. As Linux boots up, the RTC device driver copies the up-to-date time and date in the RTC to the system time. This is reflected in the kernel boot messages. Boot Linux to the shell interface and check the the kernel messages:

root@imx8m-som:~# dmesg | grep rtc
...
[    2.054756] rtc-ds1307 0-0068: setting system clock to 2018-05-05 
05:06:26 UTC (1525496786)
root@imx8m-som:~#

7. The RTC also has an alarm feature that can be used to schedule various events, including wake-up from the low-power mode. The hardware interrupt is triggered at the specified moment in the future. To demonstrate this, first check the number of interrupts triggered by the RTC since the system start (zero in this example - see the second column):

root@imx8m-som:~# grep ds1339 /proc/interrupts
198:          0          0          0          0  gpio-mxc  29 Edge  ds1339
root@imx8m-som:~#

8. Schedule an RTC alarm to happen in two seconds from now:

root@imx8m-som:~# echo +2 > /sys/class/rtc/rtc0/wakealarm
root@imx8m-som:~#

9. In two seconds, validate that the RTC interrupt count has increased by one:

root@imx8m-som:~# grep ds1339 /proc/interrupts
198:          1          0          0          0  gpio-mxc  29 Edge  ds1339
root@imx8m-som:~#