RTC使用参考

REVISION HISTORY

Revision No.
Description
 Date
1.0
  • Initial release
    		•  04/17/2025

    1. 概述

    Real Time Clock（实时时钟），简称RTC，主要是用于计时和闹钟设置。RTC驱动采用标准的LINUX框架，能够使用统一的接口来操作RTC，同时在LINUX框架外添加符合SigmaStar IP功能的PWC（Power Controller）功能。

    PWC（Power Controller）的功能是通过检测到唤醒源触发时控制PAD_RTC_IO4和PAD_RTC_IO5引脚的高低电平，PAD_RTC_IO4和PAD_RTC_IO5控制外部的电源芯片从而控制整板电源。

    2. 关键字说明

    • Alarm

      RTC支持预先设置一个硬件时间，当RTC走到该时间，会触发RTC的Alarm（闹钟）事件。

    • Offset

      RTC支持频率偏移的功能，能够在每32个1Hz时钟来临的时候进行时间正向/反向补偿。

    • REG

      本文的REG写法采用Haa[b]的格式，表示offset:0xaa的BITb，REG一律是在bank：0x34上的说明。

    3. 功能描述

    • RTC目前使用32.768kHz频率的晶振，建议外接32K晶振。无外接晶振的时候，RTC的clk来自内部晶振，其更容易受温度，电压等外部因素的干扰，影响到RTC的精度。

    • RTC的基本功能包括支持硬件时间的读取和设置，支持闹钟时间的读取和设置。

    • PWC支持通过控制PAD_RTC_IO4和PAD_RTC_IO5引脚的高低电平，继而控制相关电源域，常用的唤醒源包括：RTC Alarm，PAD_RTC_IO0，PAD_RTC_IO1，PAD_RTC_IO2，PAD_RTC_IO3。

    • 不同chip下RTC/PWC的支持情况如下表

      chipname RTC PWC ALARM IO0 IO1 IO2 IO3
      iford Y Y Y Y Y / /
      ifado Y / Y / / / /
      pcupid Y Y Y / Y / Y
      ibopper Y / Y / / / /
      ifackel Y / Y / / / /

    4. 硬件连接介绍

    4.1. PWC的系统框架

    图2-1 PWC电路硬件图

    PWC可以通过唤醒源触发从而控制PAD_RTC_IO4和PAD_RTC_IO5引脚的高低电平，PAD_RTC_IO4和PAD_RTC_IO5控制外部的电源芯片从而控制整板电源。

    RTC部分可控的唤醒源有：

    1. PAD_RTC_IO0 - PAD_RTC_IO3 组成的按键/波形唤醒

    2. RTC的Alarm中断唤醒

    3. sw ctrl（software control）

    系统的框架图如下：

    图2-2 PAD_RTC_IO4控制源电路图

    图2-3 PAD_RTC_IO4和PAD_RTC_IO5的控制源电路图

    注：图2-2中的power_on_st与图2-3的pwr_en在硬件上是处于相连状态

    结合图2-2和图2-3可以看到，PAD_RTC_IO0 - PAD_RTC_IO3的事件触发和RTC Alarm的事件触发都可以使rtc内部的power_on状态机输出高电平，沿着power_on状态机到pwr_en进而拉高PAD_RTC_IO4的电平，同时sw ctrl事件的触发（写1到sw_ctrl_bit寄存器）也可以控制PAD_RTC_IO4电平。 从图2-3可以看到PAD_RTC_IO4的电平、RTC Alarm的事件触发和sw ctrl事件的触发都会影响到PAD_RTC_IO5的电平，因此可以灵活利用这些触发事件以及PAD_RTC_IO4和PAD_RTC_IO5的互相作用来实现电源控制，软件上的配置方法详见后文的Kernel用法介绍章节。

    4.2. PAD_RTC_IO0配置

    PAD_RTC_IO0支持配置成下拉模式和高阻态模式，默认为下拉模式，软件上的配置方法详见后文的Kernel用法介绍章节。

    图2-4 PAD_RTC_IO0内部框图

    4.3. PAD_RTC_IO1配置

    PAD_RTC_IO1 只有下拉（PD）的配置，不支持软件更改。内部框图为：

    图2-5 PAD_RTC_IO1内部框图

    4.4. PAD_RTC_IO2配置

    PAD_RTC_IO2可以支持配置内部高压/低压比较器的阈值，此外PAD_RTC_IO2还可以选择连接到内置的施密特触发器上以实现对不同信号捕捉。PAD_RTC_IO2的内部框图为：

    图2-6 PAD_RTC_IO2内部框图

    施密特触发器可以通过比较器实现相同的逻辑，目前的驱动没有实现将PAD_RTC_IO2切换为施密特触发器的功能。PAD_RTC_IO2可以支持配置的类型为：CMPHL（compare high and low）、CMPH（compare low）、CMPL（compare high）

    4.4.1. CMPHL

    PAD_RTC_IO2与寄存器Offset 0x12和PAD_RTC_IO⅘的关系：

    图2-7 CMPHL下PAD_RTC_IO2与PAD_RTC_IO⅘的关系1图

    图2-8 CMPHL下PAD_RTC_IO2与PAD_RTC_IO⅘的关系2图

    4.4.2. CMPL

    PAD_RTC_IO2与寄存器Offset 0x12和PAD_RTC_IO⅘的关系：

    图2-9 CMPL下PAD_RTC_IO2与PAD_RTC_IO⅘的关系1图

    图2-10 CMPL下PAD_RTC_IO2与PAD_RTC_IO⅘的关系2图

    4.4.3. CMPH

    PAD_RTC_IO2与寄存器Offset 0x12和PAD_RTC_IO⅘的关系：

    图2-11 CMPH下PAD_RTC_IO2与PAD_RTC_IO⅘的关系1图

    图2-12 CMPH下PAD_RTC_IO2与PAD_RTC_IO⅘的关系2图

    4.5. PAD_RTC_IO3配置

    PAD_RTC_IO3支持配置成下拉模式和上拉模式，默认为下拉模式：

    图2-13 PAD_RTC_IO3下拉模式电路图

    上拉模式内部框图：

    图2-14 PAD_RTC_IO3上拉模式电路图

    5. Uboot用法介绍

    RTC无Uboot下的驱动

    6. Kernel用法介绍

    6.1. Kernel Config配置

    • RTC相关模块

      • interrupt

      • input

    在编译kernel时需要选择的配置如下:

    Device Drivers --->

    <*> Sstar RTC Driver --->
    [*]     Sstar RTC With PWC                         // 使能PWC功能
              Sstar PWC IO Mode (Polling Mode)  --->   // 切换RTC_IO的Interrupts mode和Polling mode
    [*]     Sstar RTC With Alarm                       // 使能RTC Alarm功能
    [*]     Sstar RTC With Offset                      // 使能RTC时间补偿功能

    6.2. Dts配置

            rtcpwc: rtcpwc {
            compatible = "sstar,rtcpwc";
            reg = <0x1F006800 0x200>;
            interrupts=<GIC_SPI INT_IRQ_FLAG_POC IRQ_TYPE_LEVEL_HIGH>;
            // io0-hiz;
            // io2-wos = <1>;           //0:CMPHL 1:CMPHL 2:CMPL 3:CMPH
            // io2-wos-v = <0x2 0x3>;   //<vl vh> 0<vl<8 0<vh<8
            // io3-pu;
            // offset-count = <100>;
            // offset-nagative;
            // iso-auto-regen;
            /*
             * io4 control source selection
             * io0/io1/io2/io3 ctrl bit0
             * alarm ctrl           bit1
             * sw ctrl              bit2
             * support the combination of above ways
             */
            io4-enable = <7>;
            /*
             * io5 control source selection
             * io4 ctrl    bit0
             * alarm ctrl  bit1
             * sw ctrl     bit2
             * support the combination of above ways
             */
            io5-enable = <7>;   // for demo board,use 3,default hight
            // io5-no-poweroff;    // io5 keep when excute 'poweroff'
            // auto-down-disable; // IO4/5 will not automatically pull down when PM power is off
            status = "ok";

#ifdef CONFIG_SSTAR_PWC_IO_POLLING
            poll-interval = <10>;
#endif /* CONFIG_SSTAR_PWC_IO_POLLING */
            io1 {
                num = <1>;
                keycode = <KEY_WAKEUP>;
#ifdef CONFIG_SSTAR_PWC_IO_POLLING
                debounce-interval = <10>;
#endif /* CONFIG_SSTAR_PWC_IO_POLLING */
#ifdef CONFIG_SSTAR_PWC_IO_INTERRUPT
                interrupt-parent = <&sstar_pm_gpi_intc>;
                interrupts = <INT_PM_GPI_FIQ_PAD_RTC_IO1>;
#endif /* CONFIG_SSTAR_PWC_IO_INTERRUPT */
            };
        };
    属性 描述 备注
    compatible 用于匹配驱动进行驱动注册 禁止修改
    reg 寄存器映射的物理地址 禁止修改
    interrupts 中断号及属性 禁止修改
    io0-hiz 配置PAD_RTC_IO0为高阻态模式 根据需要配置，不配置默认是下拉模式
    io2-wos 配置PAD_RTC_IO2比较器的类型 0:CMPHL 1:CMPHL 2:CMPL 3:CMPH，详细说明可见硬件介绍章节
    io2-wos-v 配置PAD_RTC_IO2比较器的电压 详细备注请见注释1
    io3-pu 配置PAD_RTC_IO3为上拉模式 根据需要配置，不配置默认是下拉模式
    offset-count 配置频率偏移的补偿值 详细备注请见注释2
    offset-nagative 配置频率偏移的方向为提前补偿 根据需要配置，不配置是延后补偿
    iso-auto-regen 常开RTC寄存器的重触发机制：寄存器设置出现问题的时候重新触发 默认不需要配置，出现问题的时候代码里面会自动打开，恢复正常之后再关闭
    io4-enable 用于配置PAD_RTC_IO4的触发模式 详细备注请见注释3
    io5-enable 用于配置PAD_RTC_IO5的触发模式 详细备注请见注释3
    auto-down-disable 关闭“IO⅘随着pm domain下电而自动拉低”的功能 根据需要配置，详细备注请见注释5
    status 驱动开关 根据需要配置，ok/disabled
    poll-interval polling的时间间隔 根据需要配置，单位为ms
    num RTC_IO的index 根据具体情况配置，详细备注请见注释4
    keycode 键值 根据需要配置，详细备注请见注释4
    debounce-interval polling的滤波 根据需要配置，单位为ms
    interrupt-parent RTCIO的中断parent 禁止修改
    interrupts 中断号 禁止修改

    注释1：io2-wos-v属性第一个值代表VL，第二个值代表VH，VL和VH可选的值为：

    属性值 VL VL电压值 VH VH电压值
    0 1/16 AVDD 0.206 15/16 AVDD 3.094
    1 2/16 AVDD 0.413 14/16 AVDD 2.888
    2 3/16 AVDD 0.619 13/16 AVDD 2.681
    3 4/16 AVDD 0.825 12/16 AVDD 2.475
    4 5/16 AVDD 1.031 11/16 AVDD 2.269
    5 6/16 AVDD 1.238 10/16 AVDD 2.063
    6 7/16 AVDD 1.444 9/16 AVDD 1.856
    7 8/16 AVDD 1.650 8/16 AVDD 1.650

    表中VL/VH电压值为AVDD取3.3V时的电压值

    硬件默认值为3，如果dtsi里指定了io2-wos属性没有指定io2-wos-v属性，则io2-wos-v的值将被设置为0。

    注释2：RTC计数功能可能会由于晶振容差、PCB容差等因素造成频率偏差，从而导致RTC计时出现偏差。为了补偿此类制造工艺造成的偏差，RTC增加了频率偏移的功能。频率偏移补偿误差可以在产品生产初期选取样品使用用户空间接口进行调试标定，然后通过DTS配置到驱动中，就能在最终产品中达到一定的矫正效果。 RTC的频率偏移功能会在每32个1Hz时钟来临的时候进行补偿，补偿的时间计算公式为：

    T = 1/f × count

    以目前使用的32.768kHz频率的晶振，补偿计数值（offset-count）为1计算，每32秒会纠正的时间为：

    T = 1/32768 × 1 × 1000000000 ≈ 30518ns

    其中补偿计数值（offset-count）的最大值为255，所以24小时下最大的补偿时间为：

    T = 30518ns × 255 × (24 × 60 × 60 ÷ 32) ≈ 21.0s

    补偿计数值（offset-count）为正数时，每32个1Hz时钟来临的时候，都会减去一部分时间，可以理解为使RTC硬件时间走得慢些；计数补偿值（offset-count）为负值时，则每32个1Hz时钟来临的时候，都会加上一部分时间，可以理解为使RTC硬件时间走得快些。

    注释3：dtsi中的io4-enable对应硬件介绍章节图2-2和图2-3的H10[3:0]、H0f[1]、H49[12]，例如当前io4-enable设置为3，则H0F[0]为1且H0F[1]也为1，代表此时PAD_RTC_IO4可以同时由PAD_RTC_IO0-3和RTC Alarm共同控制。PAD_RTC_IO4除了以上两种控制源，还可以通过SW Ctrl的方式，即io4-enable配置为'7'，对应H49[12]，代表此时PAD_RTC_IO4可以同时由PAD_RTC_IO0-3、RTC Alarm和SW Ctrl共同控制。

    io5-enable属性对应硬件介绍章节图2-3的H20[0]、H20[1]、H49[10]，例如当前io5-enable设置为2，则H20[0]为0且H20[1]为1，代表PAD_RTC_IO5不受PAD_RTC_IO4控制，PAD_RTC_IO5的状态仅受RTC Alarm的控制。与PAD_RTC_IO4相同的是，PAD_RTC_IO5也可以通过SW Ctrl的方式控制，将io5-enable配置为‘7’即可实现，对应H49[10]，则代表此时PAD_RTC_IO5可以同时由PAD_RTC_IO4、RTC Alarm和SW Ctrl共同控制 。

    按键唤醒的真值表如下：

    PAD Event Power On Remark PAD_RTC_IO4 PAD_RTC_IO5
    PAD_RTC_IO0 PD rise >VIH default rise rise
    HIZ rise >VIH   rise rise
    PAD_RTC_IO1 PD rise >VIH default rise rise
    PAD_RTC_IO2 CMPH rise >VIH   rise rise
    CMPL fall <VIL   rise rise
    CMPHL rise >VIH default rise rise
    schmitt rise >VIH   rise rise
    PAD_RTC_IO3 PD rise >VIH default rise rise
    PU fall <VIL   rise rise

    注释4：节点中的io1子节点是用于监测RTC_IO1的中断触发状态，可以通过cat /proc/interrutps查看中断触发次数，并且对接了输入子系统，可以在按键按下和抬起时刻上报键值，支持应用层进行键值的接收。 num属性为RTC_IO的index：0, 1, 2, 3…… keycode属性为所需要处理的键值，可在include/uapi/linux/input-event-codes.h中选择

    dtsi中默认配置了一只RTC_IO，如需多只可参考下方修改：

            rtcpwc: rtcpwc {
            ......
            io1 {
                num = <1>;
                keycode = <KEY_WAKEUP>;
#ifdef CONFIG_SSTAR_PWC_IO_POLLING
                debounce-interval = <10>;
#endif /* CONFIG_SSTAR_PWC_IO_POLLING */
#ifdef CONFIG_SSTAR_PWC_IO_INTERRUPT
                interrupt-parent = <&sstar_pm_gpi_intc>;
                interrupts = <INT_PM_GPI_FIQ_PAD_RTC_IO1>;
#endif /* CONFIG_SSTAR_PWC_IO_INTERRUPT */
            };
            io3 {
                num = <3>;
                keycode = <KEY_SLEEP>;
#ifdef CONFIG_SSTAR_PWC_IO_POLLING
                debounce-interval = <10>;
#endif /* CONFIG_SSTAR_PWC_IO_POLLING */
#ifdef CONFIG_SSTAR_PWC_IO_INTERRUPT
                interrupt-parent = <&sstar_pm_gpi_intc>;
                interrupts = <INT_PM_GPI_FIQ_PAD_RTC_IO3>;
#endif /* CONFIG_SSTAR_PWC_IO_INTERRUPT */
            };
        };

    注释5：auto-down-disable的配置与“IO⅘随着pm domain下电而自动拉低”的这个功能相对应，如果希望关闭这个功能，请配置该属性，如果希望打开这个功能，则注释掉该属性。

    举例说明：

    1. IO4控制pm-domain与nonpm-domain，IO5控制DDR。STR的时候希望拉低pm-domain和nonpm-domain，DDR保持高电平。那么此时就需要关闭该功能，dtsi中配置上auto-down-disable这个属性，才不会发生pm-domain拉低的时候把IO5拉低，继而拉低DDR。

    2. pm-domain下电的时候，希望IO⅘也能够一起拉低的场景，就注释掉该属性。

    6.3. Padmux配置

    RTC无需进行Padmux配置

    6.4. 模块使用介绍

    6.4.1. SYSFS 使用方法

    1. sys/class/rtc/rtc0

      目录下的节点提供了对硬件实时时钟的访问和控制接口，主要节点及其功能：

      节点 功能 示例值
      name RTC 设备的名称（驱动名称） sstar,rtcpwc 1f006800.rtcpwc
      date 当前 RTC 日期（YYYY-MM-DD） 2024-03-15
      time 当前 RTC 时间（HH:MM:SS） 14:30:45
      since_epoch 自 Unix 纪元（1970-01-01）以来的秒数 1710500000
      hctosys 是否在启动时从 RTC 同步时间到系统时钟 1（已同步），0（未同步）
      wakealarm 设置 RTC 唤醒时间（用于唤醒休眠的系统） 写入 +60 表示 60 秒后唤醒

    2. sys/class/sstar/rtcpwc

      由于内核的RTC框架并未完全涵盖SigmaStar RTCPWC硬件设计的编码要求，因此RTC驱动在sys文件系统中自定义了一些文件用于扩充功能。文件的位置为：/sys/class/sstar/rtcpwc/

      节点 功能 示例值
      alarm_timer 用于查看和设置报警时间，输出的值为倒计时，输入的值为增加倒计时时间 echo 30 > alarm_timer， cat alarm_timer
      wakeup_event 用于查看PWC的唤醒源，会在下一次下电/上电周期更新 cat wakeup_event
      event_state 用于查看PWC Event的实时状态 cat event_state
      count_status 用于查看驱动错误计数的次数，该功能用于调试 cat count_status
      offset_count 用于调整频率补偿的计数值 echo 100 > offset_count（正向补偿），echo -100 > offset_count（反向补偿）, cat offset_count

    6.4.2. ioctl使用方法

    头文件<rtc.h>位于/driver/uapi/linux目录下

    • RTC_RD_TIME：读取RTC当前时间

    • RTC_SET_TIME：设置RTC时间

    • RTC_ALM_READ：读取闹钟时间

    • RTC_ALM_SET：设置闹钟时间

    • RTC_AIE_ON：使能 RTC 闹钟中断

    6.4.3. RTC命令使用方法

    1. 显示系统时间

      命令：date

    2. 设置系统时间

      命令: date MMDDhhmmYYYY.ss

      MM : month(01-12);

      DD : day(01-31);

      Hhmm : time(0000-2359);

      YYYY : year[optional];

      ss : seconds(00-59) [optional]

    3. Show RTC Clock

      命令：hwclock

    4. Set RTC Clock to System Clock

      命令：hwclock –s

    6.5. Sample code

    应用程序可以通过ioctl操作 /dev/rtc0 文件读取设定RTC时间及Alarm时间，代码具体实现可以参考driver/sstar/rtc/ut/rtc_ut.c。接下来演示如何通过rtc_ut操作RTC。

    6.5.1. 读取硬件时间

    命令：./rtc_ut

    6.5.2. 设置硬件时间

    命令：./rtc_ut -w -s "2021-11-3 20:10:30"

    ​描述：设置RTC时间为2021年11月3日 20:10:30

    命令：./rtc_ut -w -o 10

    描述：设置RTC时间为当前时间加上10秒

    6.5.3. 读取报警时间

    命令：./rtc_ut -a

    6.5.4. 设置报警时间

    命令：./rtc_ut -a -w -s "2021-11-3 20:20:30"

    描述：设置RTC报警时间为2021年11月3日 20:20:30

    程序会sleep到alarm触发

    命令：./rtc_ut -w -a -o 10

    描述：设置RTC报警时间为当前RTC时间加上10秒，并于10秒后触发

    7. API参考

    RTC无对外开放使用的API。

    8. FAQ

    Q1：硬件时钟停止工作

    1.多次敲击命令hwclock确认时钟是否有在跳动，有跳动为正常，否则执行下一步

    2.多次读取RTC的寄存器，判断bank：0x34的0x9&0xA 是否有在跳动，截图保存寄存器信息

    3.检查RTC的外挂晶振工作状态和RTC供电是否都正常

    Q2：Alarm停止工作

    1.echo [time] > /sys/class/sstar/rtcpwc/alarm_time

    2.cat /proc/interrupts

    3.等待Alarm触发，确认Alarm中断触发次数是否有增加

    Q3：电源控制场景出现异常

    1.示波器测量出现问题前后的RTC_IO4&5的波形

    2.确认波形的行为是否符合预期的上下电操作