简介：面向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.5V，3.3V和5V逻辑电平都能跑，这个兼容性相当友好。
要注意的是模块上的CR2032电池座，很多廉价模块的电池座是贴片式，虚焊率很高。上电后先量一下电池座正极有没有3V电压，没有就先补焊。另外DS1302内置的涓流充电电路默认是关闭的，也就是说电池不会被系统充电，别指望它像手机电池一样自己回血。如果你的模块标注了"带充电功能"，那需要在寄存器0x90写入涓流充电配置，默认情况下不建议开启，容易把电池充鼓包。
2.2 GPIO编号怎么选、怎么确认
DS1302只需要三个GPIO，但选线有点讲究。我用的板子是RK3568，GPIO编号经过多次映射（SoC内部GPIO号到内核gpiochip号再到libgpiod的line offset），直接看原理图上的GPIO3_A2这种命名很容易搞混。
我的做法是：先跑gpiodetect看看系统里有几个gpiochip，再用gpioinfo查看每个chip对应的GPIO号范围。然后选三个彼此相邻但不冲突的GPIO，优先挑板上没有复用的引脚。以我用的RK3568为例，最后选的是GPIO0_B5（CE）、GPIO0_B6（SCLK）、GPIO0_B7（IO），分别是libgpiod编号下的13、14、15号。
连接方式很简单：模块的VCC接3.3V，GND接GND，CE、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固定为1，bit6是写保护控制，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] Description=Sync system time from DS1302 RTC After=systemd-modules-load.service [Service] Type=oneshot ExecStart=/usr/local/bin/ds1302tool read | xargs date -s [Install] WantedBy=multi-user.target启用：
systemctl enable ds1302-sync.service systemctl start ds1302-sync.service如果你的系统里还有板载RTC，hwclock -w -f /dev/rtc1指定的是第二个RT/dev/rtc0被板载RTC占用。我的建议是干脆禁用板载RTC直接让DS1302独占/dev/rtc0，避免两个RTC打架。在内核启动参数里加rtc-cmos.use_hctosys=0，或者把板载RTC的驱动在设备树里禁用掉。
5.4 关机自动写回
光有开机同步还不够，极端情况下（比如NTP不可用）系统时间会慢，关机前把系统时间写回DS1302能减少漂移积累。systemd的shutdown服务写法稍微特殊一点：
# /etc/systemd/system/ds1302-sync-shutdown.service [Unit] Description=Save system time to DS1302 before shutdown DefaultDependencies=no Before=shutdown.target reboot.target halt.target [Service] Type=oneshot RemainAfterExit=yes ExecStart=/bin/true ExecStop=/usr/local/bin/ds1302tool write "$(date '+%Y-%m-%d %H:%M:%S')" [Install] WantedBy=multi-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检查，如果和预期差了几秒以上就顺手校准一下芯片。这个习惯帮我排除过好几次因为模块接触不良导致的假故障。这套方案稳定跑了几个月，每次断电重启时间都准得出奇，基本值回票价了。
本文还有配套的精品资源，点击获取
