RTC使用参考¶
REVISION HISTORY¶
| Revision No. | Description |
Date |
|---|---|---|
| 1.0 | 01/31/2024 |
1. 概述¶
Real Time Clock（实时时钟），简称RTC，主要是用于计时和闹钟设置。RTC驱动采用标准的LINUX框架，能够使用统一的接口来操作RTC，同时在LINUX框架外添加符合Sgs 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的基本功能包括支持硬件时间的读取和设置，支持闹钟时间的读取和设置。计时和定时常见的单位是1s，有些芯片会有毫秒级定时的功能，例如jaguar1硬件支持最小31.25ms的定时。
-
PWC支持通过控制PAD_RTC_IO4和PAD_RTC_IO5引脚的高低电平，继而控制相关电源域，常用的唤醒源包括：RTC Alarm，PAD_RTC_IO0，PAD_RTC_IO1，PAD_RTC_IO2，PAD_RTC_IO3。
-
PWC的RTC_IO0、1一般是要在RTC_IO4、5拉低之后拉动才能触发RTC_IO4、5的上电，有些芯片（例如jaguar1）支持在RTC_IO4、5还未掉电时就记录下IO0、1有被拉动过，进而在下次RTC_IO4、5下电时立即再给它们上电。
-
不同chip下RTC/PWC的支持情况如下表，当前的文档请参考 iford 这一行。
chipname RTC PWC ALARM HRALARM IO0 IO1 IO2 IO3 EVENT_RECORD iford Y Y Y / Y Y / / / ifado Y / Y / / / / / / pcupid Y Y Y / / Y / Y / ibopper Y / Y / / / / / / ifackel Y / Y / / / / / / jaguar1 Y Y Y Y Y Y / / Y
4. 硬件连接介绍¶
4.1. RTC晶振频率¶
RTC目前使用32.768kHz频率的晶振
4.2. PWC的系统框架¶
PWC可以通过唤醒源触发从而控制PAD_RTC_IO4和PAD_RTC_IO5引脚的高低电平，PAD_RTC_IO4和PAD_RTC_IO5控制外部的电源芯片从而控制整板电源。
RTC部分可控的唤醒源有：
-
PAD_RTC_IO0 - PAD_RTC_IO3 组成的按键/波形唤醒
-
RTC的Alarm中断唤醒
-
sw ctrl（software control）
系统的框架图如下：
注：图2-2中的power_on_st与图2-3的pwr_en在硬件上是处于相连状态
结合图2-2和图2-3可以看到，PAD_RTC_IO0 - PAD_RTC_IO3的事件触发和RTC Alarm的事件触发都可以使power_on_st输出高电平，沿着power_on_st->pwr_en进而拉高PAD_RTC_IO4的电平，同时sw ctrl事件的触发也可以控制PAD_RTC_IO4电平。 从图2-3可以看到PAD_RTC_IO4的电平、RTC Alarm的事件触发和sw ctrl事件的触发都会影响到PAD_RTC_IO5的电平，因此可以灵活利用这些触发事件以及PAD_RTC_IO4和PAD_RTC_IO5的互相作用来实现电源控制，软件上的配置方法详见后文的Kernel用法介绍章节。
4.3. PAD_RTC_IO0配置¶
PAD_RTC_IO0支持配置成下拉模式和高阻态模式，默认为下拉模式，软件上的配置方法详见后文的Kernel用法介绍章节。
4.4. PAD_RTC_IO1配置¶
PAD_RTC_IO1 只有下拉（PD）的配置，不支持软件更改。内部框图为：
4.5. PAD_RTC_IO2配置¶
PAD_RTC_IO2可以支持配置内部高压/低压比较器的阈值，此外PAD_RTC_IO2还可以选择连接到内置的施密特触发器上以实现对不同信号捕捉。PAD_RTC_IO2的内部框图为：
施密特触发器可以通过比较器实现相同的逻辑，目前的驱动没有实现将PAD_RTC_IO2切换为施密特触发器的功能。PAD_RTC_IO2可以支持配置的类型为：CMPHL（compare high and low）、CMPH（compare low）、CMPL（compare high）
4.5.1. CMPHL¶
PAD_RTC_IO2与寄存器Offset 0x12和PAD_RTC_IO⅘的关系：
4.5.2. CMPL¶
PAD_RTC_IO2与寄存器Offset 0x12和PAD_RTC_IO⅘的关系：
4.5.3. CMPH¶
PAD_RTC_IO2与寄存器Offset 0x12和PAD_RTC_IO⅘的关系：
4.6. PAD_RTC_IO3配置¶
PAD_RTC_IO3支持配置成下拉模式和上拉模式，默认为下拉模式：
上拉模式内部框图：
5. Uboot用法介绍¶
RTC无Uboot下的驱动
6. Kernel用法介绍¶
6.1. Kernel Config配置¶
Device Drivers --->
<*> Sstar RTC Driver --->
[*] Sstar RTC With PWC
Sstar PWC IO Mode (Interrupt Mode) --->
[*] Sstar RTC With Alarm
[*] Sstar RTC With Offset
6.2. Dts配置¶
rtcpwc: rtcpwc {
compatible = "sgs,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' use for wakeup pm51
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 = <&sgs_pm_gpi_intc>;
interrupts = <INT_PM_GPI_FIQ_PAD_RTC_IO1>;
#endif /* CONFIG_SSTAR_PWC_IO_INTERRUPT */
};
};
| 属性 | 描述 | 备注 |
|---|---|---|
| compatible | 用于匹配驱动进行驱动注册 | 禁止修改 |
| reg | 寄存器映射的物理地址 | 禁止修改 |
| interrupts | 中断号及属性 | 禁止修改 |
| alarm-enable | alarm功能的总开关 | 建议开启 |
| alarm-init-on | 驱动初始化的时候进行闹钟触发 | 根据需要配置 |
| 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 | 配置频率偏移的方向为提前补偿 | 根据需要配置，不配置是延后补偿 |
| io4-enable | 用于配置PAD_RTC_IO4的触发模式 | 详细备注请见注释3 |
| io5-enable | 用于配置PAD_RTC_IO5的触发模式 | 详细备注请见注释3 |
| status | 驱动开关 | 根据需要配置，ok/disabled |
| poll-interval | polling的时间间隔 | 根据需要配置，单位为ms |
| num | 键值个数 | 根据需要配置 |
| keycode | 键值 | 根据需要配置 |
| 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）为正数时，为时间延后计算出来的时间，计数补偿值（offset-count）为负值时，为时间提前计算出来的时间值。
注释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 | ||
6.3. Padmux配置¶
RTC无需进行Padmux配置
6.4. RTC模块使用介绍¶
6.4.1. 显示系统时间¶
命令：date
6.4.2. 设置系统时间¶
命令: date MMDDhhmmYYYY.ss
MM : month(01-12);
DD : day(01-31);
Hhmm : time(0000-2359);
YYYY : year[optional];
ss : seconds(00-59) [optional]
6.4.3. Show RTC Clock¶
命令：hwclock
6.4.4. Set RTC Clock to System Clock¶
命令：hwclock –w
6.5. RTC应用编程操作方法¶
应用程序可以通过ioctl操作 /dev/rtc0 文件读取设定RTC时间及Alarm时间，代码具体实现可以参考driver/sgs/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时间为当前时间加上10秒
6.6. 自定义用户空间接口¶
6.6.1. 用户空间接口¶
由于内核的RTC框架并未完全涵盖Sgs 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（计数值如何计算请查阅[2.3 Dts配置参数说明]章节注释3），可以使用以下命令：
1. echo 100 > offset_count
设置偏差补偿计数值为负100，可以使用以下命令：
1. echo -100 > offset_count
查看当前偏差补偿计数值，可以使用以下命令：
1. cat offset_count
查看当前xtal状态，可以使用以下命令：
1. cat xtal_state
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/sgs/rtcpwc/alarm_time
2.cat /proc/interrupts
3.等待Alarm触发，确认Alarm中断触发次数是否有增加
Q3：电源控制场景出现异常
1.示波器测量出现问题前后的RTC_IO4&5的波形
2.确认波形的行为是否符合预期的上下电操作