SSU_RTC使用参考

REVISION HISTORY

Revision No.
Description
 Date
1.0
  • Initial release
    		•  07/28/2018
    2.0
  • Driver version upgrade
    		•  11/03/2021
    3.0
  • Driver version upgrade
    		•  10/28/2022

    1. 概述

    本文讲述SigmaStar RTCPWC驱动的使用方法，RTC驱动采用标准的LINUX框架，能够使用统一的接口来操作RTC，同时在LINUX框架外添加符合SigmaStar IP功能的附加设置。

    2. RTC操作方法及规范

    2.1. 显示系统时间

    命令：date

    2.2. 设置系统时间

    命令: date MMDDhhmmYYYY.ss

    MM : month(01-12);

    DD : day(01-31);

    Hhmm : time(0000-2359);

    YYYY : year[optional];

    ss : seconds(00-59) [optional]

    2.3. Show RTC Clock

    命令：hwclock

    2.4. Set RTC Clock to System Clock

    命令：hwclock –w

    3. RTC应用编程操作方法

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

    3.1. 读取系统时间

    命令：./rtc_ut

    3.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秒

    3.3. 读取报警时间

    命令：./rtc_ut -a

    3.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时间为当前时间加上10秒

    4. 自定义用户空间接口

    4.1. 用户空间接口

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

    文件 描述
    alarm_timer 用于查看和设置报警时间，输出的值为倒计时，输入的值为增加倒计时时间
    wakeup_event 用于查看PWC的唤醒源，会在下一次下电/上电周期更新
    event_state 用于查看PWC Event的实时状态
    count_status 用于查看驱动错误计数的次数，该功能用于调试
    offset_count 用于调整频率补偿的计数值

    如需设置alarm时间为30秒后，可以使用以下命令：

    1. echo 30 > alarm_timer

    查看倒计时时间，可以使用以下命令：

    1. cat alarm_timer

    设置偏差补偿计数值为正100（计数值如何计算请查阅 频率补偿配置），可以使用以下命令：

    1. echo 100 > offset_count

    设置偏差补偿计数值为负100，可以使用以下命令：

    1. echo -100 > offset_count

    查看当前偏差补偿计数值，可以使用以下命令：

    1. cat offset_count

    5. 驱动配置

    5.1. 系统框架

    当前平台无PAD_RTC_IO2和PAD_RTC_IO3，与PAD_RTC_IO2和PAD_RTC_IO3相关的内容请忽略即可

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

    现有的唤醒源有：

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

    2. RTC的Alarm中断唤醒

    系统的框架图如下：

    1. rtcpwc {
2.     compatible = "sstar,rtcpwc";
3.     reg = <0x1F006800 0x200>;
4.     interrupts = <GIC_SPI INT_IRQ_DIG_TOP IRQ_TYPE_LEVEL_HIGH>;
5.     alarm-enable;
          /*
           * io4 control source selection
           * io0/io1/io2/io3 ctrl bit0
           * alarm ctrl           bit1
           * sw ctrl              bit2
           * support the combination of above ways
           */
6.     io4-enable = <3>;
          /*
           * io5 control source selection
           * io4 ctrl    bit0
           * alarm ctrl  bit1
           * sw ctrl     bit2
           * support the combination of above ways
           */
7.     io5-enable = <2>;
8.     status = "ok";
9. };

    dtsi中的io4-enable对应以上框架图的H0F[1:0]，例如当前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]。

    io5-enable属性对应以上框架图的H20[1:0]，例如当前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 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

    5.2. PAD_RTC_IO1配置

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

    5.3. PAD_RTC_IO0配置

    PAD_RTC_IO0支持配置成下拉模式和高阻态模式，默认为下拉模式：

    通过dtsi文件配置为高阻态模式：

    10. rtcpwc {
11.     compatible = "sstar,rtcpwc";
12.     reg = <0x1F006800 0x200>;
13.     interrupts = <GIC_SPI INT_IRQ_DIG_TOP IRQ_TYPE_LEVEL_HIGH>;
14.     alarm-enable;
15.     io0-hiz;
16.     io4-enable = <3>;
17.     io5-enable = <2>;
18.     status = "ok";
19. };

    5.4. PAD_RTC_IO2配置

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

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

    1. rtcpwc {
2.     compatible = "sstar,rtcpwc";
3.     reg = <0x1F006800 0x200>;
4.     interrupts = <GIC_SPI INT_IRQ_DIG_TOP IRQ_TYPE_LEVEL_HIGH>;
5.     alarm-enable;
6.     io2-wos = <2>;
7.     io2-wos-v = <0x2 0x3>;
8.     status = "ok";
9. };

    软件可以通过dtsi的io2-wos属性和io2-wos-v配置PAD_RTC_IO2比较器的类型和比较器的高低电压，io2-wos可选的值为：

    属性值 描述
    0 CMPHL - compare high and low
    1 CMPHL - compare high and low
    2 CMPL - compare low
    3 CMPH - compare high

    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。

    5.4.1. CMPHL

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

    5.4.2. CMPL

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

    5.4.3. CMPH

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

    5.5. PAD_RTC_IO3配置

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

    通过dtsi文件配置为上拉模式：

    1. rtcpwc {
2.     compatible = "sstar,rtcpwc";
3.     reg = <0x1F006800 0x200>;
4.     interrupts = <GIC_SPI INT_IRQ_DIG_TOP IRQ_TYPE_LEVEL_HIGH>;
5.     alarm-enable;
6.     io3-pu;
7.     io4-enable = <3>;
8.     io5-enable = <2>;
9.     status = "ok";
10. };

    上拉模式内部框图：

    5.6. 闹钟配置

    1. rtcpwc {
2.     compatible = "sstar,rtcpwc";
3.     reg = <0x1F006800 0x200>;
4.     interrupts = <GIC_SPI INT_IRQ_DIG_TOP IRQ_TYPE_LEVEL_HIGH>;
5.     alarm-enable;
6.     status = "ok";
7. };

    alarm-enable为alarm功能的总开关，如果不声明alarm-enable属性，alarm相关的功能将无法使用包括sys fs的节点，一般建议不要关闭alarm功能。

    5.7. 频率补偿配置

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

    RTC的频率偏移功能会在每32个1Hz时钟来临的时候进行补偿，补偿的时间计算公式为：

    Toffset = 1/f × count

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

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

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

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

    补偿计数值（count）为正数时，为时间延后计算出来的时间，计数补偿值（count）为负值时，为时间提前计算出来的时间值。

    其他配置为硬件相关设计决定的配置，禁止修改，否则将会导致RTCPWC模块无法正常工作。