简介面向Linux驱动开发者资源提供DS1302实时时钟芯片的完整驱动源码与测试程序。驱动覆盖设备树配置、I2C/SPI接口适配、BCD时间格式转换、内核timekeeper同步、掉电保护处理以及用户空间/dev/rtc*设备节点访问等关键环节配套的app程序可直接读写时间适合嵌入式系统时钟管理、驱动移植学习也可作为RTC子系统课程设计的起点。压缩包共22个文件总大小34KB内含3个.c源文件、2个.o中间目标文件、1个.ko内核模块、1个app-ds1302可执行测试程序、Makefile构建脚本以及cmd编译记录、txt说明、modules.order与symvers等模块依赖辅助文件既有完整源码也有编译产物与依赖关系便于对照Makefile理解Linux内核模块的编译流程。已有386人学习/下载无论用于学习还是工程参考对掌握Linux字符设备驱动框架、RTC驱动注册与回调函数编写、I2C/SPI底层通信以及常见调试手段都具有直接参考价值。 最近手上一块RK3568的板子要离线跑采集系统断电几次之后时间直接回到1970年。板载的RTC电池座虚焊换了几次电池都不行只能外挂方案。翻了一圈DS1302是市面上最便宜、最容易买到的实时时钟芯片模块几块钱一个三线接口随便找三个GPIO就能驱动。本来以为Linux下应该很顺利结果发现事情没这么简单——内核没有现成的DS1302驱动网上资料又全是单片机和树莓派的真正在Linux用户空间把这块芯片跑起来的完整案例少得可怜。这篇文章我就把整个折腾过程完整写下来从芯片通信协议、GPIO规划、用户空间C驱动实现到hwclock对接系统时间、常见故障排查全部一次说清楚。照着我这个流程走你只需要一块DS1302模块和一块能跑Linux的开发板就能在半小时内把硬件RTC跑起来重启不丢时间。1. DS1302为什么在Linux里没驱动——芯片与内核的现实差距1.1 三线协议和SPI/I2C的本质区别DS1302用的是Dallas自定的三线协议CE片选、SCLK时钟、IO数据。很多资料说它类似SPI这个说法害人不浅。标准SPI有MISO和MOSI两条独立数据线收发可以同时进行DS1302只有一根IO线读和写必须分时切换方向。更关键的是它的命令字节是LSB先发寄存器地址也不是连续排布读操作还要求在SCLK下降沿输出数据——这套时序跟标准SPI相去甚远。我最早也想偷懒把DS1302挂到spi-gpio模拟的SPI总线上用内核里那个rtc-ds1302驱动。折腾了一天不是片选信号对不上就是半双工切换出问题读出来的数据全是乱的。后来想明白了这种非标芯片内核没有原生支持强行靠SPI框架去套纯属给自己挖坑。1.2 三种可行方案对比在Linux下驱动DS1302实际可行的路径有三条写内核驱动挂到RTC子系统rtc-hym8563那种模式通过dev/rtc设备文件访问用设备树加platform驱动仍然是内核态方案用户空间直接操作GPIO模拟时序读写寄存器内核驱动方案看着最正经但代价是你要维护驱动代码和板级设备树换内核版本后还得跟着适配。而且DS1302这类芯片本身数据量极小不涉及中断、DMA等需要内核介入的场景用户空间完全能胜任。我的选择是用户空间方案用libgpiod操作GPIO按数据手册的时序图逐位收发。这个方案有三个好处代码逻辑和DS1302数据手册一一对应出了问题直接对着时序图排查不依赖内核版本换板子只要改GPIO编号调试方便printf就能看到每一字节的收发结果。2. 硬件接线与GPIO规划——决定后续调试进度的关键步骤2.1 模块选择和供电细节市面上的DS1302模块有两种一种是裸芯片加晶振加电池座另一种还带一块掉电保存的EEPROM。我建议选前者功能越少越不容易出问题。模块供电支持2.0V到5.5V3.3V和5V逻辑电平都能跑这个兼容性相当友好。要注意的是模块上的CR2032电池座很多廉价模块的电池座是贴片式虚焊率很高。上电后先量一下电池座正极有没有3V电压没有就先补焊。另外DS1302内置的涓流充电电路默认是关闭的也就是说电池不会被系统充电别指望它像手机电池一样自己回血。如果你的模块标注了带充电功能那需要在寄存器0x90写入涓流充电配置默认情况下不建议开启容易把电池充鼓包。2.2 GPIO编号怎么选、怎么确认DS1302只需要三个GPIO但选线有点讲究。我用的板子是RK3568GPIO编号经过多次映射SoC内部GPIO号到内核gpiochip号再到libgpiod的line offset直接看原理图上的GPIO3_A2这种命名很容易搞混。我的做法是先跑gpiodetect看看系统里有几个gpiochip再用gpioinfo查看每个chip对应的GPIO号范围。然后选三个彼此相邻但不冲突的GPIO优先挑板上没有复用的引脚。以我用的RK3568为例最后选的是GPIO0_B5CE、GPIO0_B6SCLK、GPIO0_B7IO分别是libgpiod编号下的13、14、15号。连接方式很简单模块的VCC接3.3VGND接GNDCE、SCLK、IO分别接三个GPIO。如果你用的是树莓派注意它有两种编号体系board编号和BCM编号用libgpiod的话以gpioinfo显示为准。2.3 晶振不起振这个隐藏雷区DS1302的时基来自外部32.768kHz晶振。很多模块出厂时晶振就不焊接或者虚焊现象是芯片能读写但秒寄存器永远不变。判断方法初始化后连续读两次秒寄存器间隔一秒以上如果数值没变十有八九是晶振没起振。处理办法是补焊晶振两端注意不要用热风枪吹太久DS1302是塑料封装过热容易内部损坏。补焊后用示波器量晶振引脚正常能看到32.768kHz的正弦波。没有示波器也没关系读秒寄存器会跳变就说明起振了。3. 用户空间C驱动实现——核心时序函数与完整代码3.1 libgpiod环境准备libgpiod是Linux内核GPIO子系统的新一代用户空间接口替代老的sysfs。安装很简单# Debian/Ubuntu apt install libgpiod-dev gpiod # 确定GPIO编号 gpiodetect gpioinfo gpiochip0写代码的头文件是gpiod.h链接时加-lgpiod。如果你的板子没有libgpiod那就只能退回sysfs方式/sys/class/gpio操作但代码会啰嗦很多我们这里全部用libgpiod写。3.2 核心时序写字节和读字节DS1302的所有操作都建立在写一个字节和读一个字节之上。先看时序图再说代码——写字节时CE拉高后每个SCLK上升沿主机把IO线电平锁存进芯片读字节时命令字节发完后每个SCLK下降沿芯片把数据输出到IO线主机要在SCLK低电平期间采样。#include gpiod.h #include stdio.h #include stdlib.h #include unistd.h #include time.h #define CE_LINE 13 #define SCLK_LINE 14 #define IO_LINE 15 struct gpiod_chip *chip; struct gpiod_line *ce_line, *sclk_line, *io_line; static void delay_us(int us) { struct timespec ts; ts.tv_sec 0; ts.tv_nsec us * 1000; nanosleep(ts, NULL); } static void init_gpio(void) { chip gpiod_chip_open_by_name(gpiochip0); if (!chip) { perror(gpiod_chip_open_by_name); exit(1); } ce_line gpiod_chip_get_line(chip, CE_LINE); sclk_line gpiod_chip_get_line(chip, SCLK_LINE); io_line gpiod_chip_get_line(chip, IO_LINE); gpiod_line_request_output(ce_line, ds1302, 0); gpiod_line_request_output(sclk_line, ds1302, 0); gpiod_line_request_output(io_line, ds1302, 0); } static void ds1302_write_byte(unsigned char dat) { int i; gpiod_line_set_value(io_line, 0); for (i 0; i 8; i) { gpiod_line_set_value(io_line, (dat i) 0x01); delay_us(2); gpiod_line_set_value(sclk_line, 1); delay_us(2); gpiod_line_set_value(sclk_line, 0); delay_us(2); } } static unsigned char ds1302_read_byte(void) { int i; unsigned char dat 0; gpiod_line_request_input(io_line, ds1302); for (i 0; i 8; i) { gpiod_line_set_value(sclk_line, 0); delay_us(2); if (gpiod_line_get_value(io_line)) dat | (1 i); gpiod_line_set_value(sclk_line, 1); delay_us(2); } gpiod_line_request_output(io_line, ds1302, 0); return dat; }写字节时先把IO设置为输出然后在SCLK拉高之前把数据放上IO线让上升沿稳稳锁存。读字节时把IO切换为输入SCLK拉低后芯片已经把数据输出到IO线上了这时候gpiod_line_get_value采样最稳然后再拉高SCLK进入下一位。3.3 读写任意寄存器命令字节的构造规则DS1302的命令字节是8位格式是bit7固定为1bit6是写保护控制bit5是时钟暂停控制bit4到bit1是寄存器地址bit0是读写方向1读0写。它还有一个巧妙的设计——每个寄存器有独立的读地址和写地址比如秒寄存器的写地址是0x80读地址是0x81分寄存器的写地址是0x82读地址是0x83依此类推。static unsigned char ds1302_read_reg(unsigned char addr) { unsigned char dat; gpiod_line_set_value(ce_line, 1); delay_us(2); ds1302_write_byte(addr | 0x01); /* 读命令 */ dat ds1302_read_byte(); gpiod_line_set_value(ce_line, 0); delay_us(2); return dat; } static void ds1302_write_reg(unsigned char addr, unsigned char dat) { gpiod_line_set_value(ce_line, 1); delay_us(2); ds1302_write_byte(addr 0xFE); /* 写命令 */ ds1302_write_byte(dat); gpiod_line_set_value(ce_line, 0); delay_us(2); }每次读写前CE都要拉高结束后CE拉低。这是一个容易忽略的细节——CE不拉低的话芯片一直处于活跃状态下次操作时可能还在处理上一次的残余数据。3.4 BCD码转换最容易写错的地方DS1302内部寄存器存的是BCD码不是十进制。比如秒寄存器读到0x59表示的是59秒而不是十进制的59。第一次接触的人十有八九在这里翻车。static unsigned char bcd2bin(unsigned char bcd) { return (bcd 4) * 10 (bcd 0x0F); } static unsigned char bin2bcd(unsigned char bin) { return ((bin / 10) 4) (bin % 10); }读时间时把每个寄存器都过一遍bcd2bin写时间时全部过一遍bin2bcd。有个坑BCD转换函数本身不校验输入范围比如分钟寄存器写0x75这种非法BCD值芯片也不报错只是时间会乱跳。所以写时间前最好先检查范围分钟和秒在0到59小时在0到23。3.5 完整读写时间流程有了上面的基础函数读时间就是逐个寄存器取数写时间就是先关写保护、逐个寄存器写入、再开写保护。struct ds1302_time { int year; /* 2000-2099 */ int month; /* 1-12 */ int day; /* 1-31 */ int hour; /* 0-23 */ int minute; /* 0-59 */ int second; /* 0-59 */ int week; /* 1-7 */ }; static void ds1302_get_time(struct ds1302_time *t) { t-second bcd2bin(ds1302_read_reg(0x81)); t-minute bcd2bin(ds1302_read_reg(0x83)); t-hour bcd2bin(ds1302_read_reg(0x85)); t-day bcd2bin(ds1302_read_reg(0x87)); t-month bcd2bin(ds1302_read_reg(0x89)); t-week bcd2bin(ds1302_read_reg(0x8B)); t-year bcd2bin(ds1302_read_reg(0x8D)) 2000; } static void ds1302_set_time(const struct ds1302_time *t) { ds1302_write_reg(0x8E, 0x00); /* 关闭写保护 */ ds1302_write_reg(0x80, bin2bcd(t-second)); ds1302_write_reg(0x82, bin2bcd(t-minute)); ds1302_write_reg(0x84, bin2bcd(t-hour)); ds1302_write_reg(0x86, bin2bcd(t-day)); ds1302_write_reg(0x88, bin2bcd(t-month)); ds1302_write_reg(0x8A, bin2bcd(t-week)); ds1302_write_reg(0x8C, bin2bcd(t-year - 2000)); ds1302_write_reg(0x8E, 0x80); /* 打开写保护 */ }写时间时有个顺序上的细节写保护寄存器0x8E最后再设回0x80如果先开保护再写其他寄存器操作会被芯片拒绝表现是写入后读回来全是原值。秒寄存器0x80的最高位是CH位时钟暂停位为1时芯片内部时钟停止振荡。初始化时如果你写0就是让时钟跑起来。我见过有人在设置时间时不小心把CH位带上去了结果时间永远不走。稳妥做法是写入的秒值直接清掉最高位bin2bcd(t-second) 0x7F。4. 实测最容易踩的坑——从读回0xFF到时间不走的完整排查链路4.1 读回0xFF或0x00先别怀疑芯片第一次跑通代码后我读秒寄存器返回值是0xFF再读分寄存器还是0xFF。直觉告诉我芯片坏了检查了接线、供电、晶振全都没问题。后来把SCLK和IO两路都加上拉电阻问题消失。DS1302的空闲状态下IO应该是高阻或者由外部上拉保持稳定电平。模块上如果没带上拉电阻读操作时IO方向刚切到输入电平还没稳定就被采样读回来的全是1。解决办法是在IO和SCLK上各加一个10kΩ上拉到VCC。注意CE不需要上拉它平时必须保持低电平。如果你读回来的是0x00大概率是IO方向切换后GPIO内部下拉把电平拉低了而不是芯片输出低。这时候检查一下gpiod_line_request_input之后有没有加延时等电平稳定再采样。4.2 时间不走晶振问题和CH位两重原因时间不走有两个典型原因我都遇到过。第一个是晶振没起振前面已经说了判断方法。第二个是秒寄存器最高位CH被写成了1。排查CH位时不要只看设置时间的代码很多模块出厂时EEPROM里残留的寄存器值就是乱码。初始化时要么把CH位清零要么在写时间时用掩码强制清零。我的习惯是每次上电初始化都先读秒寄存器然后把CH位清零再写回去unsigned char sec_reg ds1302_read_reg(0x81); ds1302_write_reg(0x80, sec_reg 0x7F);4.3 SCLK初始电平导致的偶发错乱DS1302对SCLK在CE拉高前的状态很敏感。如果SCLK默认输出高电平CE一拉高芯片可能把第一个上升沿当作命令字节的开始导致后续错位。所以初始化时有一个顺序先确保SCLK输出低电平再拉高CE开始传输。上面的init_gpio已经把三个线都初始化为0输出这块就不会有问题。有些代码库为了省事初始化GPIO时SCLK直接是默认状态运气不好就会复现偶发读写错误。4.4 GPIO编号错乱一种极其隐蔽的故障libgpiod的line编号和芯片手册的GPIO编号不是一回事。比如RK3568的GPIO0_B5在内核gpiochip里可能排到了第13号但在另一个体系里可能又是另一个号。排查方法写一个测试程序给某个line循环输出高低电平用万用表量对应引脚有没有翻转。如果量不到把gpioinfo的输出和原理图逐一对一遍八成是编号选错了。千万别想当然用GPIO3_A2那种命名直接算不同板子的BSP差异很大。5. 让DS1302接管Linux系统时间——hwclock同步与开机自启5.1 Linux的双时钟机制Linux系统里其实有两个时间系统时钟由内核维护断电丢失和硬件时钟RTC芯片维护由电池供电。正常情况下开机时内核从RTC读取时间设置系统时钟关机时把系统时钟写回RTC。但我们的DS1302不在内核RTC子系统里内核压根不知道它的存在。所以需要手动用hwclock命令完成同步。hwclock默认操作的是/dev/rtc0也就是系统里第一个硬件RTC。如果板载RTC和DS1302共存要指定设备文件。5.2 时间同步命令先把系统时间设置好用date命令或NTP同步然后写入DS1302# 准备一个读取DS1302并输出标准时间字符串的程序 # 假设编译好的程序叫ds1302tool # 从DS1302读取时间并设置为系统时间 date -s $(ds1302tool read) hwclock -w -f /dev/rtc1 # 把系统时间写入DS1302 ds1302tool write $(date %Y-%m-%d %H:%M:%S)我实际的做法是写两个小脚本ds1302_sync_from.sh负责开机时从芯片读时间、用date设置系统时间ds1302_sync_to.sh负责关机前用当前系统时间更新芯片。5.3 systemd开机自启在systemd的框架下可以通过一个oneshot服务实现开机自动同步# /etc/systemd/system/ds1302-sync.service [Unit] DescriptionSync system time from DS1302 RTC Aftersystemd-modules-load.service [Service] Typeoneshot ExecStart/usr/local/bin/ds1302tool read | xargs date -s [Install] WantedBymulti-user.target启用systemctl enable ds1302-sync.service systemctl start ds1302-sync.service如果你的系统里还有板载RTChwclock -w -f /dev/rtc1指定的是第二个RT/dev/rtc0被板载RTC占用。我的建议是干脆禁用板载RTC直接让DS1302独占/dev/rtc0避免两个RTC打架。在内核启动参数里加rtc-cmos.use_hctosys0或者把板载RTC的驱动在设备树里禁用掉。5.4 关机自动写回光有开机同步还不够极端情况下比如NTP不可用系统时间会慢关机前把系统时间写回DS1302能减少漂移积累。systemd的shutdown服务写法稍微特殊一点# /etc/systemd/system/ds1302-sync-shutdown.service [Unit] DescriptionSave system time to DS1302 before shutdown DefaultDependenciesno Beforeshutdown.target reboot.target halt.target [Service] Typeoneshot RemainAfterExityes ExecStart/bin/true ExecStop/usr/local/bin/ds1302tool write $(date %Y-%m-%d %H:%M:%S) [Install] WantedBymulti-user.target这个写法利用了ExecStop在服务停止时执行的机制systemd在关机时会按依赖顺序停止所有服务这样就能在系统完全断电前把时间写回。实测下来配合一个正常的DS1302模块断电几个月时间误差基本在几十秒以内完全够用。6. 一些零散但很实用的经验补充6.1 同一块板子上同时跑用户空间驱动和内核RTC如果板子上已经有其他RTC芯片你想让DS1302作为辅助RTC需要注意date命令和hwclock命令的配合。date -s设置的是系统时钟它并不会自动通知内核去写RTC。很多教程让人直接date -s然后以为完事了其实关机再开时间又没了。6.2 编译时的优化选项用gcc编译上面的C代码建议加上-O2。有些优化等级会改变代码执行节奏间接影响GPIO翻转的时序。实测-O0编译的程序读DS1302一切正常-O3反而偶尔出错原因可能是编译器重排了gpiod_line_set_value和delay_us的调用顺序。如果遇到这种玄学问题把和时序相关的函数加上__attribute__((optimize(O0)))禁用优化。6.3 加一个CRC或者校验位DS1302没有内置任何校验机制数据线受干扰时读回的时间可能直接错乱。我的做法是在时间寄存器之外额外往芯片的充电寄存器0x90或者用户RAM区域写一个魔数每次读时间前先校验魔数不对就判定为数据异常。#define DS1302_MAGIC 0xA5 static int ds1302_verify_magic(void) { return ds1302_read_reg(0x91) DS1302_MAGIC; } static void ds1302_set_magic(void) { ds1302_write_reg(0x90, DS1302_MAGIC); }0x90到0x91是DS1302的涓流充电和RAM区域不初始化的话是随机值。写入魔数后每次读时间前校验一次就能有效避免读到垃圾数据后把系统时间设成乱码。6.4 关于模块的精度期望最后说句实在话DS1302的精度在RTC芯片里属于中等水平常温下典型温漂在±2ppm到±5ppm之间也就是每天几秒的误差量级。如果要求更高的精度可以外部接一个温补晶振或者换DS3231这种带温度补偿的芯片。但对于绝大多数离线设备、数据记录仪、工控主机来说DS1302的精度已经完全够用了——系统运行期间有NTP校时断电期间有备用电池维持误差根本不会累积到影响业务的程度。我个人的习惯是每次断电重启之后等系统第一个服务同步完DS1302时间再执行一次date检查如果和预期差了几秒以上就顺手校准一下芯片。这个习惯帮我排除过好几次因为模块接触不良导致的假故障。这套方案稳定跑了几个月每次断电重启时间都准得出奇基本值回票价了。本文还有配套的精品资源点击获取