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
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.
.
Device Driver
Real-time Clock
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:
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.