Applications - Real-time Clock (RTC)

Last modified by Microchip on 2024/06/20 12:43

This page shows how the internal Real-time Clock (RTC) of the SAMA5D2 Series is enabled in the Linux® kernel and how to access the RTC in user space.

First, a couple of concepts to explain before moving on:

  • Wall clock: This is the Linux system clock. It was coded to run starting from January 1, 1970, and is driven by the system tick. The Wall clock starts running after the system powers on and stops running when the system powers down, so it can't be used to store the real time. Normally, the Wall clock will be updated according to the time of the RTC when the system is booting.
  • RTC: This is an external or on-chip device that is dedicated to storing the real time.

Prerequisites

This application is developed for the ATSAMA5D27-SOM1-EK1 development platform:

This application is developed using the Buildroot build system.

Hardware

The SAMA5D2 Series Arm® Cortex®-A5 MPU contains an integrated RTC with the following features:

  • Full Asynchronous Design for Ultra-Low Power Consumption
  • Gregorian, Coordinated Universal Time (UTC), and Persian Modes Supported
  • Programmable Periodic Interrupt
  • Safety/security Features:
    • Valid Time and Date Programming Check
    • On-The-Fly Time and Date Validity Check
  • Counters Calibration Circuitry to Compensate for Crystal Oscillator Variations
  • Waveform Generation for Trigger Event
  • Tamper Timestamping Registers
  • Register Write Protection

Real-time Clock Block Diagram

RTC Block Diagram

Back to Top


Buildroot Configuration

Objective: Using Buildroot, build a bootable image and Flash onto an SD Memory Card for the ATSAMA5D27-SOM1-EK1 development board.

Follow the steps for building the image in the "Buildroot - Create Project with Default Configuration" page, where you will use the default configuration file: atmel_sama5d27_som1_ek_mmc_dev_defconfig.

Back to Top


Device Tree

Objective: Observe how the RTC device is configured in the device tree. No changes are required.

Once Buildroot has completed its build, the RTC definitions for the ATSAMA5D27-SOM1-EK1 are configured by a device tree. The device tree source include (*.dtsi) file is located in the Buildroot output directory, /output/build/linux-linux4sam_6.0/arch/arm/boot/dts/.

Examine the sama5d2.dtsi file and observe the RTC device assignments:

1304  clk32k: sckc@f8048050 {
1305      compatible = "atmel,sama5d4-sckc";
1306      reg = <0xf8048050 0x4>;
1307
1308      clocks = <&slow_xtal>;
1309      #clock-cells = <0>;
1310  };
1311
1312  rtc@f80480b0 {
1313      compatible = "atmel,at91rm9200-rtc";
1314      reg = <0xf80480b0 0x30>;
1315      interrupts = <74 IRQ_TYPE_LEVEL_HIGH 7>;
1316      clocks = <&clk32k>;
1317  };

Line 1305 specifies which driver will be used for the slow clock device.

Line 1306 the slow clock controller base address is 0xf8048050, the size of the register block is 0x4.

Line 1308 there are two clock sources for slow clock controller: (1) external 32.768 kHz crystal oscillator, or (2) internal 64 kHz RC oscillator. Here, the external 32.768 kHz crystal oscillator is configured.

Line 1313 specifies which driver will be used for the RTC device.

Line 1314 the RTC base address is 0xf80480b0, the size of the register block is 0x30.

Line 1315 the PID of the RTC is 74; IRQ high level triggered; priority 7.

Line 1316 the slow clock (configured above) is used by the RTC.

Back to Top


Kernel

Objective: Observe how RTC functionality was configured in the Linux kernel. No changes are required.

From the Buildroot directory, run the Linux kernel menuconfig:

$ make linux-menuconfig

The top-level menu will be displayed:

Linux menuconfig top menu

Back to Top


Device Driver

Select Device Drivers ---->.

Linux menuconfig device drivers

Back to Top


Real-time Clock

Observe [*] Set system time from RTC on startup and resume has been selected.

With this feature selected, the system time (Wall clock) will be set to use the value, reading from a specified RTC device.

Linux menuconfig Real Time Clock

Back to Top


Observe [*] Set the RTC time based on NTP synchronization has been selected.

With this feature selected, the system time (Wall clock) will be stored in the RTC specified by RTC_SYSTOHC_DEVICE approximately every 11 minutes if the user-space reports synchronized NTP status.

Linux menuconfig set the RTC time

Back to Top


Observe [*] /sys/class/rtc/rtcN (sysfs) has been selected.

With this feature selected, the RTC driver can be accessed from the command line via sysfs.

Linux menuconfig sysfs

Back to Top


Observe [*] /dev/rtcN (character devices) has been selected.

With this feature selected, the RTC driver can be accessed using standard C language Application Programming Interface (API) via the device node of RTC.

Linux menuconfig rtcN

Back to Top


Scroll down and observe <*> AT91RM9200 or some AT91SAM9 RTC has been selected.

With the default setting, the RTC driver has been selected.

Linux menuconfig RTC driver

Back to Top

Rootfs

Three methods (file nodes) can be used to access RTC driver:

/dev/rtc0
The device (dev) node interface can only be accessed by the C language program, as most of the operations must be done by ioctl().

/sys/class/rtc

The sysfs interface is more friendly for accessing, because all needed operations could be done by read() and write(). Normally this interface will be used with scripting programming or in the command line.

/proc/driver/rtc

This proc interface is used to check the status of the RTC device.

Back to Top

Hands-On

Access With /dev/rtc0

The Linux command, hwclock, is for accessing RTC via the /dev/rtcX device node:

# hwclock --help
BusyBox v1.27.2 (2019-04-26 11:28:56 CST) multi-call binary.

Usage: hwclock [-r|--show] [-s|--hctosys] [-w|--systohc] [-t|--systz] [-l|--localtime] [-u|--utc] [-f|--rtc FILE]

Query and set hardware clock (RTC)

-r Show hardware clock time
-s Set system time from hardware clock
-w Set hardware clock from system time
-t Set in-kernel timezone, correct system time if hardware clock is in local time
-u Assume hardware clock is kept in UTC
-l Assume hardware clock is kept in local time
-f FILE Use specified device (e.g. /dev/rtc2)

Read RTC time:

# hwclock
Wed Jul 24 13:47:14 2019 0.000000 seconds

Read the time of Wall clock:

# date
Wed Jul 24 13:47:54 UTC 2019

Set system time from hardware clock:

# hwclock -s

Set hardware clock from system time:

# hwclock -w

Back to Top

Access With /sys/class/rtc

Read RTC time and date:

# cat /sys/class/rtc/rtc0/time
14:55:22
# cat /sys/class/rtc/rtc0/date
2019-07-24

Use RTC Alarm to Wake Up System:

The alarm signal will be asserted after 20 seconds:

# echo +20 > /sys/class/rtc/rtc0/wakealarm

Check current time:

# date
Wed Jul 24 23:01:21 CST 2019 

 Set the system to standby:

# echo standby > /sys/power/state
PM: suspend entry (shallow)
PM: Syncing filesystems … done.
Freezing user space processes … (elapsed 0.001 seconds) done.
OOM killer disabled.
Freezing remaining freezable tasks … (elapsed 0.001 seconds) done.
Suspending console(s) (use no_console_suspend to debug)
atmel_usart_serial atmel_usart_serial.0.auto: using dma0chan5 for rx DMA transfers
atmel_usart_serial atmel_usart_serial.0.auto: using dma0chan6 for tx DMA transfers
OOM killer enabled.
Restarting tasks … done.
PM: suspend exit

Check wake-up time:

# date
Wed Jul 24 23:01:42 CST 2019

Back to Top

Access With /proc/driver/rtc

Check the status of the RTC driver:

$ cat /proc/driver/rtc
rtc_time : 07:08:08
rtc_date : 2019-07-24
alrm_time : 06:24:45
alrm_date : 2019-07-10
alarm_IRQ : no
alrm_pending : no
update IRQ enabled : no
periodic IRQ enabled : no
periodic IRQ frequency : 1024
max user IRQ frequency : 64
24hr : yes
periodic_IRQ : no
update_IRQ : no
HPET_emulated : yes
BCD : yes
DST_enable : no
periodic_freq : 1024
batt_status : okay

Back to Top

Time Zone

The timezone feature is supported by Buildroot. To install timezone info, perform the following steps:

From the Buildroot directory, run the Buildroot menuconfig:

$ make menuconfig

The top-level menu will be displayed:

Buildroot Top Menu: System configuration

Back to Top


Select System configuration ---->

Buildroot: Install timezone info

Back to Top


Select [*] Install timezone info

You will see two submenus appear when selected: (default) timezone list and (Etc/UTC) default local time.

Back to Top


Save the configuration and build Buildroot.

Back to Top

Accessing Time Zone

To check the timezone information on the target board, UTC was used with the default setting:

# ls -l /etc/TZ
lrwxrwxrwx 1 root root 32 Jul 23 18:17 /etc/TZ -> ../usr/share/zoneinfo/uclibc/UTC

The following log will show how many areas the timezone has been predefined on the target:

# ls /usr/share/zoneinfo/uclibc/
Africa Chile GB-Eire Israel Navajo US
America Cuba GMT Jamaica PRC UTC
Antarctica EET GMT+0 Japan PST8PDT Universal
Arctic EST GMT-0 Kwajalein Pacific W-SU
Asia EST5EDT GMT0 Libya Poland WET
Atlantic Egypt Greenwich MET Portugal Zulu
Australia Eire HST MST ROC
Brazil Etc Hongkong MST7MDT ROK
CET Europe Iceland Mexico Singapore
CST6CDT Factory Indian NZ Turkey
Canada GB Iran NZ-CHAT UCT 

For example, to change the timezone to Asia/Shanghai:

# ln -s -f /usr/share/zoneinfo/uclibc/Asia/Shanghai /etc/TZ
# ls -l /etc/TZ
lrwxrwxrwx 1 root root 40 Jul 24 21:53 /etc/TZ -> /usr/share/zoneinfo/uclibc/Asia/Shanghai
# date
Wed Jul 24 21:53:46 CST 2019 ##

Back to Top

Summary

On this page, you used Buildroot to build an image with RTC support for the ATSAMA5D2 Series MPU. You accessed the RTC via three different methods: access with /dev/rtcX, /sys/class/rtc, and /proc/driver/rtc. You also selected an alternate timezone. You walked through the device tree and kernel to observe how the embedded Linux system configures the source code for building.

Back to Top