Applications - Real-time Clock (RTC)

Introduction

This page shows how the internal Real-time Clock (RTC) of the SAMA5D2 Series ARM® Cortex®-A5 Microprocessor Unit (MPU) 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 which is dedicated for 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.png

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 "Create Project with Default Configuration" page, where you will use the default configuration file: atmel_sama5d27_som1_ek_mmc_dev_defconfig.


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/.

1

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.


Kernel

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

1

From the Buildroot directory, run the Linux kernel menuconfig:

$ make linux-menuconfig

The top-level menu will be displayed:

linux-config-top-level.png

Device Driver

2

Select Device Drivers —->

linux-config-device-drivers.png

Real-time Clock

3

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-config-set-rtc.png

4

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.

set-the-RTC-time.png

5

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.

sys-class.png

6

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.

dev-rtcN.png

7

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

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

linux-config-rtc-at91.png

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.

Hands-On

Access with /dev/rtc0

hwclock is a Linux command for accessing RTC via /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

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:

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

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


Time Zone

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

1

From the Buildroot directory, run the Buildroot menuconfig:

$ make menuconfig

The top-level menu will be displayed:

buildroot-system-config.png

2

Select System configuration ——>

buildroot-install-timezone-info.png

3

Select [*] Install timezone info

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

4

Save the configuration and build Buildroot.

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


Summary

In 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.

© 2019 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.