《STM32MP157嵌入式Linux驱动开发指南》第四十三章 RTC芯片PCF8563

正点原子

1）实验平台：正点原子STM32MP157开发板
2)  章节摘自【正点原子】《STM32MP157嵌入式Linux驱动开发指南》
3）购买链接:https://item.taobao.com/item.htm?&id=629270721801
4）全套实验源码+手册+视频下载地址：http://www.openedv.com/docs/boards/arm-linux/zdyzmp157.html
5）正点原子官方B站：https://space.bilibili.com/394620890
6）正点原子STM32MP157技术交流群：691905614   

第四十三章 外置RTC芯片PCF8563实验

        上一章我们学习了STM32MP1内置RTC外设，了解了Linux系统下RTC驱动框架。一般的应用场合使用SOC内置的RTC就可以了，而且成本也低，但是在一些对于时间精度要求比较高的场合，SOC内置的RTC就不适用了。这个时候我们需要根据自己的应用要求选择合适的外置RTC芯片，正点原子STM32MP1开发板上板载了一个RTC芯片：PCF8563，这是一个IIC接口的外置RTC芯片，本章我们就来学习一下如何驱动外置RTC芯片。


43.1 PCF8563简介
43.1.1 PCF8563简介
        PCF8563是一个CMOS RTC芯片，支持时间和日历功能，支持可编程的时钟输出、中断输出以及低电压检测。PCF8563提供了两线IIC接口来传输时间信息，最大传输速度为400Kbit/S，在读写寄存器的时候地址自增，PCF8563相关特性如下：
        ①、提供年、月、日、星期，时、分、秒计时，使用外置32.768Khz晶振。
        ②、低后备电流：0.25uA ，VDD=3.0V，温度25℃。
        ③、IIC接口，速度最高400KHz。
        ④、可编程时钟输出，可以供其他设备使用，可输出的时钟频率有32.768kHz、1.024kHz、32Hz和1Hz。
        ⑤、支持闹钟和定时功能。
        ⑥、IIC读地址为0XA3，写地址为0XA2，也就是IIC器件地址为：0X51。
        ⑦，有一个开漏输出的中断引脚。
        PCF8563框图如图43.1.1.1所示：

图43.1.1.1 PCF8563框图

        简单分析一下图43.1.1.1中的框图：
        ①、这是PCF8563的32.768kHz晶振引脚，PCF8563必选要外接32.768kHz晶振。
        ②、这是PCF8563的IIC引脚，PCF8563通过IIC接口与主控进行通信，因此PCF8563本质是个IIC器件。
        ③、时钟输出引脚。
        ④、中断引脚。
        ⑤、前面说了，PCF8563是个IIC器件，因此内部就有很多寄存器来实现RTC功能，比如配置芯片，读取时间信息等。这部分就是PCF8563的内部寄存器，稍后我们会详细分析PCF8563内部寄存器。
43.1.2 PCF8563寄存器详解
        PCF8563有16个内部寄存器，这些寄存器都是8位的。前两个寄存器(0x00和0x01)为控制/状态寄存器。0X02~0X08为时间和日期寄存器，这些寄存器保存着秒、分、时、日、星期、月和年信息。0X09~0X0C为闹钟寄存器，保存闹钟信息。0X0D为时钟输出频率寄存器，0X0E和0X0F这两个寄存器时钟控制寄存器。注意、时分秒、年月日、闹钟等时间信息为BCD格式。
        接下来我们看一下这些寄存器如何使用：
        1、控制状态寄存器1(0X00)
        首先是状态寄存器，寄存器结构如图43.1.2.1所示：

图43.1.2.1 控制状态寄存器1

        图43.1.2.1是控制状态寄存器1，相应的位含义如下：
        TEST1(bit7)：0，正常模式；1，测试模式。
        N(bit6,bit4,bit2~0)：未使用。
        STOP(bit5)：0，RTC时钟运行；1，RTC时钟停止。
        TESTC(bit3)：0，正常模式，关闭POR覆写；1，使能POR覆写。
        2、控制状态寄存器2(0X01)
        接下来看一下控制状态寄存器2，寄存器结构如图43.1.2.2所示：

图43.1.2.2 控制状态寄存器2

        图43.1.2.2是控制状态寄存器2，相应的位含义如下：
        N(bit7~5)：未使用。
        TI_TP(bit4)：为0的时候INT引脚取决于TF位，为1的时候INT引脚输出指定频率的脉冲。
        AF(bit3)：闹钟标志位，为1的话表示闹钟发生，写0清除，写1无效。
        TF(bit2)：定时器标志位，为1的话表示定时发生，写0清除，写1无效。
        AIE(bit1)：闹钟中断使能位，0，关闭闹钟中断；1，使能闹钟中断。
        TIE(bit0)：定时器中断使能位，0，关闭定时器中断；1，使能定时器中断。
3、时间和日期寄存器(0X02~0X08)
        接下来看一下时间和日期相关寄存器，一共7个寄存器，结构如图43.1.2.3所示：

图43.1.2.3 时间和日期寄存器

        我们依次来看一下图43.1.2.3中的这些寄存器：
        0X02：此寄存器为秒钟寄存器，PCF8563是有低电压检测的，当VDD电压低于最小允许电压的时候VL(bit)位就会置1，表示时钟异常，如果电压正常的话就为0。 SECONDS(bit6~0)这7位表示具体的秒数，范围0~59，为BCD格式。
        0X03：此寄存器为分钟寄存器，MINUTES(bit6~0)这7位有效，表示具体的分钟数，范围0~59，为BCD格式。
       0X04：此寄存器为小时寄存器，HOURS(bit5~0)这6位有效，表示具体的小时数，范围0~23，为BCD格式。
        0X05：此寄存器为日期寄存器，DAYS(bit5~0)这6位有效，表示具体的小时数，范围1~31，为BCD格式。
        0X06：此寄存器为星期寄存器，WEEKDAYS(bit2~0)这3位有效，表示具体的星期，范围0~6，为BCD格式。
        0X06：此寄存器为星期寄存器，WEEKDAYS(bit2~0)这3位有效，表示具体的星期，范围0~6，为BCD格式。0为星期日，1为星期一，以此类推，6就是星期六。
        0X07：此寄存器为月份寄存器，其中C(bit7)为世纪标志位，如果为1的话表示20xx年，为0的话表示19xx年。MONTHS(bit4~0)这5位有效，表示具体的月份，范围1~12，分别为1~12月，为BCD格式。
        0X08：此寄存器为年寄存器，YEARS(bit7~0)这8位有效，表示具体的年份，范围0~99。
4、闹钟寄存器(0X09~0X0C)
接下来看一下闹钟相关寄存器，一共4个寄存器，结构如图43.1.2.4所示：

图43.1.2.4 闹钟寄存器

我们依次来看一下图43.1.2.4中的这些寄存器：
        0X09：此寄存器为闹钟分钟寄存器，AE_M(bit7)为分钟闹钟使能位，为0的话使能分钟闹钟，为1的话关闭。 MINUTE_ALARM(bit6~0)这7位表示具体的闹钟分钟，范围0~59，为BCD格式。
       0X0A：此寄存器为闹钟小时寄存器，含义和0X09寄存器类似。
        0X0B：此寄存器为闹钟日期寄存器，含义和0X09寄存器类似。
        0X0C：此寄存器为闹钟日期寄存器，含义和0X09寄存器类似。
另外还有时钟输出寄存(0X0D)以及定时器寄存器(0X0E和0X0F)，这里我们不用PFC8563的时钟输出和定时器功能，这里就不讲解了，感兴趣的可以参考PCF8563数据手册。
总体来说，PCF8563还是很简单的，这是一个IIC接口的RTC芯片，因此在Linux系统下就涉及到两类驱动：
①、IIC驱动，需要IIC驱动框架来读写PCF8563芯片。
②、RTC驱动，因为这是一个RTC芯片，因此要用到RTC驱动框架。
如果要用到中断功能的话，还需要用到Linux系统中的中断子系统，这些我们前面都有相应的实验讲解。所以PCF8563的Linux驱动并不复杂，而且重点是Linux系统默认就已经集成了PCF8563驱动，我们使用起来非常简单，直接修改设备树，添加PCF8563节点信息，然后使能内核的PCF8563驱动即可。
43.2 硬件原理图分析
        PCF8563原理图如图43.2.1所示：

图43.2.1 PCF8563原理图

        从图43.2.1可以看出，PCF8563连接到了STM32MP157的I2C4接口上，引脚为PZ5、PZ4。另外，PCF8563的INT引脚连接到了STM32MP157的PI3引脚上。
43.3 实验驱动编写
43.3.1 修改设备树
1、添加或者查找PCF8563所使用的IO的pinmux配置
        前面说了，PCF8563的IIC接口连接到了STM32MP157的I2C4上，对应的引脚为PZ4和PZ5。另外还有一个中断引脚PI3，我们首先需要在设备树中添加这3个引脚对应的配置信息。首先添加PZ4和PZ5，打开stm32mp15-pincrtl.dtsi文件，查找一下有没有I2C4的引脚配置信息，默认是有的，内容如下：
示例代码43.3.1.1 i2c4引脚节点

1. 1  i2c4_pins_a: i2c4-0 {
   
2. 2           pins {
   
3. 3                       pinmux = <STM32_PINMUX('Z', 4, AF6)>,                 /* I2C4_SCL         */
   
4. 4                              <STM32_PINMUX('Z', 5, AF6)>;         /* I2C4_SDA         */
   
5. 5                       bias-disable;
   
6. 6                       drive-open-drain;
   
7. 7                       slew-rate = <0>;
   
8. 8           };
   
9. 9  };
   
10. 10
    
11. 11 i2c4_pins_sleep_a: i2c4-1 {
    
12. 12          pins {
    
13. 13              pinmux = <STM32_PINMUX('Z', 4, ANALOG)>,         /* I2C4_SCL         */
    
14. 14                             <STM32_PINMUX('Z', 5, ANALOG)>;         /* I2C4_SDA         */
    
15. 15          };
    
16. 16 };

复制代码

        从第3、4行可以看出，I2C4默认引脚就是PZ4和PZ5，和我们本实验一样，所以I2C4的引脚不需要我们修改，直接使用i2c4_pins_a即可。接下来还需要定义中断引脚PI3的引脚信息，前面讲过了，如果一个引脚作为GPIO功能的话可以不用添加此引脚pinctrl信息。
2、在I2C4节点下添加pinmux并追加 pcf8563子节点
        前面说了linux内核内部已经集成了PCF8563驱动，所以肯定有文档描述如何使用这个驱动。打开Documentation/devicetree/bindings/rtc/pcf8563.txt，此文档描述了如何使用Linux内核自带的pcf8563驱动，也给出了参考设备节点，大家参考此文档即可。
在stm32mp157d-atk.dts文件，追加I2C4节点，追加如下所示内容：
示例代码43.3.1.3 追加pcf8563节点

1. 1  &i2c4 {
   
2. 2           pinctrl-names = "default", "sleep";
   
3. 3              pinctrl-0 = <&i2c4_pins_a>;
   
4. 4           pinctrl-1 = <&i2c4_pins_sleep_a>;      
   
5. 5           status = "okay";
   
6. 6  
   
7. 7               pcf8563@51{
   
8. 8                  compatible = "nxp,pcf8563";
   
9. 9                  irq_gpio = <&gpioi 3 IRQ_TYPE_EDGE_FALLING>;
   
10. 10                 reg = <0x51>;
    
11. 11          };
    
12. 12 };

复制代码

        第2~4行，设置IO要使用的pinmux配置。
第7~10行，pcf8563设备子节点，第8行设置compatible为“nxp,pcf8563”，这个是必须的，否则无法匹配linux内核自带的pcf8563驱动。从第9行设置pcf8563中断引脚为PI3，下降沿触发。pcf8563的I2C地址为0X51，因此reg为0X51。
43.3.2 PCF8563驱动使能
        1、关闭STM32MP157内置RTC驱动
        上一个实验我们使能了STM32MP157内部RTC，为了防止干扰，所以要先关闭内部RTC！配置路径为：

1. -> Device Drivers                                                                          
   
2. -> Real Time Clock
   
3.         -> STM32 RTC    //取消选中

复制代码

        如图43.3.2.1所示：

图43.3.2.1 关闭STM32MP157内部RTC

        2、使能Linux内核自带的PCF8563驱动
        接下来需要使能linux内核自带的PCF8563驱动，配置路径如下：

1. -> Device Drivers                                                                          
   
2. -> Real Time Clock
   
3.         -> <*> Philips PCF8563/Epson RTC8564      //选中PCF8563

复制代码

        如图43.3.2.2所示：

图43.3.2.2 使能PCF8563驱动

配置完成以后重新编译内核和设备树，得到新的uImage和stm32mp157d-atk.dtb。
43.4 运行测试
使用上面编译得到的内核和设备树启动开发板。当系统第一次启动，我们没有设置PCF8563时间的时候，启动过程会提示如图43.4.1所示信息：

图43.4.1 PCF8563启动过程

        从图43.4.1可以看出，系统已经识别出了PCF8563，说明驱动没问题。但是，这里提示检测到低电压，日期和时间无效。这是因为我们没有设置时间，等系统启动成功，然后参考上一章的方法设置RTC时间，比如我这里设置时间为2021年5月21号，下午15:52:00，输入如下命令：

1. date -s "2021-05-21 15:52:00"        //设置时间
   
2. hwclock -w                                        //保存

复制代码

        时间设置好以后重启系统，此时系统log信息如图43.4.2所示：

图43.4.2 PCF8563启动信息

        从图43.4.2可以看出，此时PCF8563再没有提示电压低的错误，而且正确的读出了时间信息，整个开发板掉电以后PCF8563也会继续计时，因为有一个纽扣电池供电。
43.5 PCF8563驱动分析
        上一小节我们已经测试了PCF8563，本小节我们来简单看一下PCF8563驱动源码，根据示例代码43.3.1.3中的第8行的compatible属性值可以找到对应到驱动文件，在linux源码中搜索字符串“nxp,pcf8563”即可找到对应的驱动文件，驱动文件为drivers/rtc/rtc-pcf8563.c。
        PCF8563是个I2C器件，因此基础驱动框架是I2C，在rtc-pcf8563.c文件中找到如下所示内容：
示例代码43.5.1 pcf8563 I2C驱动框架

1. 1  static const struct i2c_device_id pcf8563_id[] = {
   
2. 2           { "pcf8563", 0 },
   
3. 3           { "rtc8564", 0 },
   
4. 4           { }
   
5. 5  };
   
6. 6  MODULE_DEVICE_TABLE(i2c, pcf8563_id);
   
7. 7  
   
8. 8  #ifdef CONFIG_OF
   
9. 9  static const struct of_device_id pcf8563_of_match[] = {
   
10. 10          { .compatible = "nxp,pcf8563" },
    
11. 11          { .compatible = "epson,rtc8564" },
    
12. 12          { .compatible = "microcrystal,rv8564" },
    
13. 13                  {}
    
14. 14 };
    
15. 15 MODULE_DEVICE_TABLE(of, pcf8563_of_match);
    
16. 16 #endif
    
17. 17
    
18. 18 static struct i2c_driver pcf8563_driver = {
    
19. 19          .driver     = {
    
20. 20              .name   = "rtc-pcf8563",
    
21. 21              .of_match_table = of_match_ptr(pcf8563_of_match),
    
22. 22          },
    
23. 23          .probe      = pcf8563_probe,
    
24. 24          .id_table   = pcf8563_id,
    
25. 25 };
    
26. 26
    
27. 27 module_i2c_driver(pcf8563_driver);

复制代码

        上述示例代码就是个标准的I2C驱动框架，第9~14行的pcf8563_of_match结构体数组就是设备树匹配数组，第10行的compatible属性为“nxp,pcf8563”，和我们的设备树向匹配。匹配以后第23行的pcf8563_probe函数就会执行。
        接下来看一下pcf8563_probe函数，函数源码如下(有缩略)：
示例代码43.5.2 pcf8563_probe 函数

1. 1  static int pcf8563_probe(struct i2c_client *client,
   
2. 2               const struct i2c_device_id *id)
   
3. 3  {
   
4. 4   struct pcf8563 *pcf8563;
   
5. 5   int err;
   
6. 6   unsigned char buf;
   
7. ......
   
8. 13  pcf8563 = devm_kzalloc(&client->dev, sizeof(struct pcf8563),
   
9. 14              GFP_KERNEL);
   
10. 15  if (!pcf8563)
    
11. 16      return -ENOMEM;
    
12. 17
    
13. 18  i2c_set_clientdata(client, pcf8563);
    
14. 19  pcf8563->client = client;
    
15. 20  device_set_wakeup_capable(&client->dev, 1);
    
16. 21
    
17. 22  /* Set timer to lowest frequency to save power */
    
18. 23  buf = PCF8563_TMRC_1_60;
    
19. 24  err = pcf8563_write_block_data(client, PCF8563_REG_TMRC, 1, &buf);
    
20. 25  if (err < 0) {
    
21. 26      dev_err(&client->dev, "%s: write error\n", __func__);
    
22. 27      return err;
    
23. 28  }
    
24. 29
    
25. 30  /* Clear flags and disable interrupts */
    
26. 31  buf = 0;
    
27. 32  err = pcf8563_write_block_data(client, PCF8563_REG_ST2, 1, &buf);
    
28. 33  if (err < 0) {
    
29. 34      dev_err(&client->dev, "%s: write error\n", __func__);
    
30. 35      return err;
    
31. 36  }
    
32. 37
    
33. 38  pcf8563->rtc = devm_rtc_allocate_device(&client->dev);
    
34. 39  if (IS_ERR(pcf8563->rtc))
    
35. 40      return PTR_ERR(pcf8563->rtc);
    
36. 41
    
37. 42  pcf8563->rtc->ops = &pcf8563_rtc_ops;
    
38. 43  /* the pcf8563 alarm only supports a minute accuracy */
    
39. 44  pcf8563->rtc->uie_unsupported = 1;
    
40. 45  pcf8563->rtc->range_min = RTC_TIMESTAMP_BEGIN_2000;
    
41. 46  pcf8563->rtc->range_max = RTC_TIMESTAMP_END_2099;
    
42. 47  pcf8563->rtc->set_start_time = true;
    
43. 48
    
44. 49  if (client->irq > 0) {
    
45. 50      err = devm_request_threaded_irq(&client->dev, client->irq,
    
46. 51              NULL, pcf8563_irq,
    
47. 52              IRQF_SHARED | IRQF_ONESHOT | IRQF_TRIGGER_LOW,
    
48. 53              pcf8563_driver.driver.name, client);
    
49. 54      if (err) {
    
50. 55          dev_err(&client->dev, "unable to request IRQ %d\n",
    
51. 56                              client->irq);
    
52. 57          return err;
    
53. 58      }
    
54. 59  }
    
55. 60
    
56. 61  err = rtc_register_device(pcf8563->rtc);
    
57. 62  if (err)
    
58. 63      return err;
    
59. ......
    
60. 70  return 0;
    
61. 71 }

复制代码

        第13行，申请内存内存，rtc-pcf8563.c定义了一个pcf8563结构体来描述PCF8563芯片，所以这里就是申请一个pcf8563实例。
        第23~36行，初始化PCF8563。
        第38行，pcf8563结构体里面有个rtc成员变量，此成员变量是个rtc_device结构体指针。看到这里，大家应该很熟悉了，这个就是上一章讲解的RTC驱动框架最核心的rtc_device。这里需要对这个rtc指针分配内存。
        第588行，设置rtc_device的ops成员变量为pcf8563_rtc_ops，pcf8563_rtc_ops包含了PCF8563的具体操作，包括设置时间、读取时间、设置闹钟等。
        第590~593行，继续初始化rtc的其他成员变量。
        第595~605行，中断初始化，PCF8563有个中断引脚INT，因此可以使用中断功能。这里使用devm_request_threaded_irq函数完成中断申请已经初始化，中断函数为pcf8563_irq。
        第607行，调用rtc_register_device函数向系统注册rtc_device，也就是pcf8563。
        总结一下，pcf8563_probe函数的核心就是初始化PCF8563，然后使用上一章讲的RTC驱动框架来设置PCF8563，然后向内核注册。
接下来我们看一下PCF8563的核心：pcf8563_rtc_ops，内容如下：
示例代码43.5.3 pcf8563_rtc_ops

1. 1 static const struct rtc_class_ops pcf8563_rtc_ops = {
   
2. 2           .ioctl              = pcf8563_rtc_ioctl,
   
3. 3           .read_time          = pcf8563_rtc_read_time,
   
4. 4           .set_time           = pcf8563_rtc_set_time,
   
5. 5           .read_alarm         = pcf8563_rtc_read_alarm,
   
6. 6           .set_alarm          = pcf8563_rtc_set_alarm,
   
7. 7           .alarm_irq_enable = pcf8563_irq_enable,
   
8. 8 };

复制代码

        pcf8563_rtc_ops提供了PCF8563的时间以及闹钟读写操作函数，应用程序对PCF8563的所有操作最终都是通过这些函数来完成的。我们以读时间为例，当应用程序读取PCF8563当前时间的时候，.read_time就会执行，在这里就是pcf8563_rtc_read_time，函数源码如下(有省略)：
示例代码43.5.4 pcf8563_rtc_read_time函数

1. 1  static int pcf8563_rtc_read_time(struct device *dev,
   
2. struct rtc_time *tm)
   
3. 2  {
   
4. 3           struct i2c_client *client = to_i2c_client(dev);
   
5. 4           struct pcf8563 *pcf8563 = i2c_get_clientdata(client);
   
6. 5                   unsigned char buf[9];
   
7. 6           int err;
   
8. 7  
   
9. 8           err = pcf8563_read_block_data(client, PCF8563_REG_ST1, 9, buf);
   
10. 9           if (err)
    
11. 10                     return err;
    
12. 11
    
13. 12          if (buf[PCF8563_REG_SC] & PCF8563_SC_LV) {
    
14. 13              pcf8563->voltage_low = 1;
    
15. 14              dev_err(&client->dev,
    
16. 15                          "low voltage detected, date/time is not reliable.\n");
    
17. 16              return -EINVAL;
    
18. 17          }
    
19. ......
    
20. 28          tm->tm_sec = bcd2bin(buf[PCF8563_REG_SC] & 0x7F);
    
21. 29          tm->tm_min = bcd2bin(buf[PCF8563_REG_MN] & 0x7F);
    
22. 30          tm->tm_hour = bcd2bin(buf[PCF8563_REG_HR] & 0x3F);
    
23. 31          tm->tm_mday = bcd2bin(buf[PCF8563_REG_DM] & 0x3F);
    
24. 32          tm->tm_wday = buf[PCF8563_REG_DW] & 0x07;
    
25. 33          tm->tm_mon = bcd2bin(buf[PCF8563_REG_MO] & 0x1F) - 1; 、
    
26. 34          tm->tm_year = bcd2bin(buf[PCF8563_REG_YR]) + 100;
    
27. 35          /* detect the polarity heuristically. see note above. */
    
28. 36          pcf8563->c_polarity = (buf[PCF8563_REG_MO] & PCF8563_MO_C) ?
    
29. 37              (tm->tm_year >= 100) : (tm->tm_year < 100);
    
30. ......
    
31. 45          return 0;
    
32. 46 }

复制代码

        第8行，使用pcf8563_read_block_data函数从PCF8563_REG_ST1寄存器(地址为0X00)开始，连续读取9个寄存器的数据。这样就可以得到PCF8563的控制与状态寄存器1和2，以及事件与日期寄存器的值。
        第12行，判断PCF8563的0X02寄存器VL位是否为1，也就是检查PCF8563是否处于低电压模式，事件和日期是否有效。
        第226~232行，依次获取PCF8563中的时间和日期值，这里使用bcd2bin函数将原始的BCD值转换为时间值。将获取到的时间和日期打包到参数tm中，tm是个rtc_time结构体指针变量。
        第234行，判断0X07寄存器的C位(bit7)的值，此位为1的话表示20xx年，为0的话就是19xx年。
        可以看出pcf8563_rtc_read_time函数很简单，就是读取PCF8563内部的时间和日期值，然后将其打包进rtc_time里面。其他的函数大同小异，大家可以自行分析一下，这里就不讲解了。
        至此，PCF8563驱动就简单分析完成了，其他IIC接口的RTC芯片驱动基本都是类似的，大家可以在实际项目开发中选择合适的RTC芯片。