RTC

1 RTC Real-Time Clock Overview

RTC (Real Time Clock) is a hardware device dedicated to recording time. It is an important component in a computer system. The main function of the RTC is to maintain time counting even when the system is powered off or shut down, ensuring that the system can obtain accurate time information after restarting.

1.1 HYM8563 RTC Chip Specifications

Basic Parameters

Chip Model: HYM8563
Interface Type: I2C bus interface
Operating Voltage: 1.0V ~ 5.5V
Backup Voltage: 1.0V ~ 5.5V
I2C Address: 0x51 (7-bit address)
I2C Rate: Supports standard mode (100kHz) and fast mode (400kHz)

Clock Accuracy

Crystal Frequency: 32.768kHz
Clock Accuracy: ±20ppm (25°C)
Temperature Range: -40°C ~ +85°C
Clock Error: Approximately ±1 minute/month (25°C)

1.2 RTC System Architecture

Hardware Connection

RK3568J SoC
    ├── I2C2 接口
    │   ├── SDA (数据线)
    │   ├── SCL (时钟线)
    │   └── INT (中断线)
    └── HYM8563 RTC芯片
        ├── 32.768kHz 晶振
        └── 电源管理电路

Software Architecture

应用层
    ├── date, hwclock 命令
    ├── timedatectl 工具
    └── 用户应用程序
        │
内核层
    ├── RTC 子系统
    ├── HYM8563 驱动
    ├── I2C 子系统
    └── 设备树配置
        │
硬件层
    ├── I2C 控制器
    └── HYM8563 芯片

1.3 Why RTC Is Needed

Linux's system time (wall time) can only be used while the system is running; when the system is powered off, the time is lost. The RTC can continue working after the system shuts down, relying on an external battery or other power source, and preserve the time. This is particularly important for the following scenarios:

No Network Environment: Offline devices that cannot synchronize time via NTP
Data Integrity: Data recording systems that require accurate timestamps
Scheduled Tasks: Systems that need to start automatically at specific times
Regulatory Requirements: Some industries have strict requirements for time accuracy

2 RTC Usage

1) RTC User-Space Interface Calls

Linux provides three userspace call interfaces. The corresponding paths on the board are:

SYSFS interface: /sys/class/rtc/rtc0/
PROCFS interface: /proc/driver/rtc
IOCTL interface: /dev/rtc0

2) SYSFS Interface

cat proc/driver/rtc
rtc_time        : 02:01:53
rtc_date        : 2025-02-21
alrm_time       : 00:00:00
alrm_date       : 1970-01-01
alarm_IRQ       : no
alrm_pending    : no
update IRQ enabled      : no
periodic IRQ enabled    : no
periodic IRQ frequency  : 1
max user IRQ frequency  : 64
24hr            : yes

3) PROCFS Interface

cat /proc/driver/rtc
rtc_time        : 09:50:05
rtc_date        : 2024-10-21
alrm_time       : 00:00:00
alrm_date       : 1970-01-01
alarm_IRQ       : no
alrm_pending    : no
update IRQ enabled      : no
periodic IRQ enabled    : no
periodic IRQ frequency  : 1
max user IRQ frequency  : 64
24hr            : yes

4) IOCTL Interface

You can refer to the kernel documentation as an example: kernel/tools/testing/selftests/timers/rtcpie.c

3 Common Commands

date          // 修改系统时钟，具体命令使用可以 man 下
hwclock -s    // 将硬件时间同步到系统时间
hwclock -w    // 将系统时间同步到硬件时间
timedatectl   // 显示系统时间等

# 以下手动设置时间或者网络同步时间后，-w 将系统时间写入到硬件 rtc，-s 再将 rtc 时间写回系统，这样每次重启板卡都会进行 rtc 时间同步到系统时间。
sudo date -s "2025-02-14 08:00:00"  // 手动设置时间
sudo  hwclock -w  // 系统时间同步到硬件 rtc
sudo  hwclock -s  // 硬件 rtc 同步到系统

3.1 NTP Time Synchronization

# 安装 NTP 客户端
sudo apt-get install ntp ntpdate

# 手动同步时间
sudo ntpdate -s time.nist.gov

# 配置 NTP 服务器
sudo nano /etc/ntp.conf

# 添加 NTP 服务器
server 0.pool.ntp.org iburst
server 1.pool.ntp.org iburst
server 2.pool.ntp.org iburst
server 3.pool.ntp.org iburst

# 启动 NTP 服务
sudo systemctl enable ntp
sudo systemctl start ntp

# 同步到硬件 RTC
sudo hwclock -w

3.2 Managing Time with timedatectl

# 查看时间状态
timedatectl status

# 设置时区
sudo timedatectl set-timezone Asia/Shanghai

# 启用 NTP 同步
sudo timedatectl set-ntp true

# 手动设置时间
sudo timedatectl set-time "2025-02-14 08:00:00"

# 同步到硬件 RTC
sudo hwclock -w

4 Troubleshooting

4.1 RTC Device Cannot Be Recognized

Inspection Steps:

# 检查 I2C 设备
i2cdetect -y 2

# 检查设备树配置
cat /proc/device-tree/i2c@*/rtc@*/compatible

# 检查内核日志
dmesg | grep -i rtc
dmesg | grep -i hym8563

# 检查驱动加载
lsmod | grep rtc

Solutions:

# 手动加载 RTC 驱动
sudo modprobe rtc-hym8563

# 检查 I2C 总线配置
sudo i2cget -y 2 0x51 0x00

4.2 Inaccurate Time or Drift

Diagnostic Methods:

# 比较系统时间和 RTC 时间
date
hwclock -r

# 检查时钟源
cat /sys/devices/system/clocksource/clocksource0/current_clocksource

# 监控时钟漂移
ntpq -p

Solutions:

# 校准 RTC 时间
sudo ntpdate -s time.nist.gov
sudo hwclock -w

# 调整系统时钟
sudo adjtimex -t

4.3 Alarm Function Abnormalities

Inspection Points:

# 检查中断配置
cat /proc/interrupts | grep rtc

# 检查唤醒源
cat /sys/power/wakeup_count

# 测试闹钟功能
echo +10 > /sys/class/rtc/rtc0/wakealarm
cat /sys/class/rtc/rtc0/wakealarm