wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
8cbc7bc6b66fcf82a6e06b87195e8e97b0a4b44d
STM32F4-Base/Drivers/BSP/SD2506/sd2506.h
T
wandering1 78248a1cdf feat(S-5): 收编 SD2506/TPAFE 并给 dhara 失败分类，门禁基线 19→17 
前一笔立契约与门禁（`Drivers/BSP/bsp_err.h` + `bsp-err` 钩子 + RS485 试点）；这一笔按用户
指定顺序 C3 → C1 → C2 把三个模块真正收编，并让存储失败第一次变得可读、可分类。

**C3 · SD2506 整模块（11 个公共 API + 6 个内部 helper）**：三枚私有宏 `SD2506_OK`/
`SD2506_ERROR`/`SD2506_I2C_ERROR` **删除而不是留别名**——留别名等于新代码还能用旧形状，
把迁移洗掉；编译器替我们找全所有调用点。新增 `sd2506_err_from_hal()`，**把 I2C 超时从
"和没人应答共用一个 −2"里拆出来归成 `BSP_ERR_TIMEOUT`（可重试）**——SD2506 是启动链第一站、
I2C1 上电时序敏感，这是本波唯一真正的语义改善，不是改名。`sd2506_init` 的 charge 寄存器
**回读校验不符**原返参数类错误，改归 `BSP_ERR_IO`（那不是调用方的错）。

**C1 · 同形两义**：`GD5F_BUSY_TIMEOUT` → `GD5F_WAIT_EXPIRED`（**值 −2 不变**，纯消"名字叫
TIMEOUT 其实是返回码"）。**GD5F 私有码集整体收编刻意没做**：169 处引用里 48 处在板级套件、
还要动 Trap 记录用词，属另一波带真机+套件回归的工作，不夹带。TPAFE5160 收编 23 处：
`BUSY_TIMEOUT → BSP_ERR_TIMEOUT`、`ERROR → BSP_ERR_PARAM`（**同值 −1，行为零变化**）、
`FRSTDATA_ERR → BSP_ERR_NO_DEVICE`（E-44 的本义就是"芯片没驱动 DB 总线"，归到器件无响应比
私有 −3 有用，且避开与 `BSP_ERR_TIMEOUT` 撞值）。实测 `tpafe5160.o`/`gd5f2gq5ue.o` 的 Code
增量为 **0**——改名不产生一条指令。

⚠ **`tpafe5160_snapshot()` 刻意不套成败码**：它是 1=有新帧 / 0=无新帧 / −1=参数错 的三态
**状态**返回，0 不是错误而是"这一拍没有新数据"，强行收编会把慢消费者的正常路径变成失败。
顺带订正我上一版在 `bsp_err.h` 的断言——"本层只有 `net_*` 把数量与错误挤同一返回值"是错的，
`snapshot`/`adc_input_poll` 就是第二族；两族现都已写明并各注保留理由。

**C2 · FTL 坍缩点分类**：`ftl_flush_cache`/`ftl_read_page` 不再把 dhara 失败压成
  `GD5F_ERROR`，
按**处置差异**分三类，并在最早同时知道 LPN 与原始码的位置就地打印：`ECC`/`TOO_BAD` →
`BSP_ERR_CRC`（页级，重试或换页，不代表卷坏）；`JOURNAL_FULL`/`MAP_FULL` →
`BSP_ERR_NO_SPACE`（介质健康但块池/日志见底，此时重格式化只是把问题推回去）；
`BAD_BLOCK`/`RECOVER`/`CORRUPT_MAP`/越界 → `BSP_ERR_IO`（完整性故障，保卷 + 上报，不许自愈
重格式化）。这与 **E-31** 是同一条纪律的两端。可读名用自建短表：**本仓 dhara 没有编
`error.c`，用 `dhara_strerror()` 会直接链接失败**。`disk_read`/`disk_write` 仍回
  `RES_ERROR`
（FatFs 契约）；要让 defaultTask 卷健康探针按类分支还差跨调用存活的快照 → C4 待还。

**两次靠核实拦住的自我错误**：① 我一度认定 `DBG_ERROR("... err=%d", err)` 是把结构体塞进
varargs 的格式 bug——核 `Lib/dhara/error.h` 后确认 `dhara_error_t` 是 `enum`（标量），那行日志
本来合法，改了反而是引入错误；② `bsp-err` 一次 `replace_all` 越界把 8 处 **GD5F 码空间**的
判据改成 `!= BSP_OK`（数值同为 0、无行为变化），但那正是"把两个码空间混起来"，已逐一还原。
`cppcheck` 亦抓到 `cls` 声明作用域过宽，已收进失败分支。

**验证**：`@build` 0 错 0 警告（`Code` 213,648、RO 18,860、`ER_IROM1` 232,508 B /
  22.2%、
`ROM 合计` 233,696；**RAM 三项零增量**）；`@test` PASS（692 ms，烧入戳 `Oct 23 01:35:32`）
且逐条读到被改模块的锚点：`SD2506 init: OK (ret=0)` 与 ID/时间/温度/电池四条读回正常、
`ADC init: OK`、`NAND init: OK`、`Map resumed: 14094/97504`、`adc=` 帧计数持续递增（证明
snapshot 三态未被改坏）、`[ERR]`/Fault/FAIL 0 条。主机单测：系统时钟 100/100、dhara NAND
移植层 149/149（两者都因本次改动需补 `Drivers/BSP` include 路径，补后在钩子内实跑 Passed）。
`pre-commit run` 全量 RC=0（20 个实跑钩子 Passed）；`bsp-err` 基线 **19 → 17**（还掉两个
`*_BUSY_TIMEOUT = -2`）、`--prune` 干净；`doc-links --all --sections-strict` 147 篇
  0 问题；
`id-check --strict`、`layer-deps`、`mem-numbers`、`mem-budget`、`ui-golden` 全过；33
  个文件
字节卫生 0 异常（无 CR / 无 U+FFFD / 无行尾空格 / 均有尾换行）。

**口径与数字联动**：新增 `docs/架构设计/STM32F4-Base存储架构说明.md` §10.4（三类码与处置
理由）；`pre-commit使用说明.md` §2.27 与 `AGENTS.md` 基线计数 19 → 17；TPAFE README、
GD5F 测试指南与 Trap 记录均**保留旧名留痕**以便对旧日志；配图桶按 .map 对象级增量重算
（`dhara/FTL` 10,931 → 11,222，+291 全部落在 `nand_ftl.o`；应用代码/UI +36 落在
`app_main.o`；其余散量入"其他"7,557；桶和 = Code+RO 断言通过、文本溢出 0）；
`ram_baseline --update/--write`、`ram_report_20261023.md` 快照、报告 §1.3/§5.1/§5.4
  与
部署文档 §3.3 数字全部同步；报告 §0.4/§9 的 S-5 状态改为 🟡 主体已落地。
2026-10-23 07:42:02 +08:00

316 lines
13 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* 模块名称：SD2506API-G RTC 实时时钟驱动
* 模块功能：SD2506API-G 高精度温补实时时钟模块 I2C 驱动，提供时间读写、
* 温度读取、电池电压检测、ID 读取等功能
* 适用平台：STM32F407ZGT6，I2C1 接口 (PB6-SCL, PB7-SDA)
* 作者：王建锋
* 创建日期：2026-07-17
* 修改记录：
* 2026-07-17 王建锋 创建初始版本，参考 SD2506API-G Ver2.0 手册
*/
#ifndef SD2506_H
#define SD2506_H
#ifdef __cplusplus
extern "C" {
#endif
#include "main.h"
/* ======================== I2C 地址 ======================== */
/*
* SD2506API-G 7位器件地址: 0x32
* HAL库使用8位地址: 写 0x64, 读 0x65
*/
#define SD2506_I2C_ADDR 0x32U
#define SD2506_I2C_ADDR_WRITE 0x64U
#define SD2506_I2C_ADDR_READ 0x65U
/* ======================== 寄存器地址定义 ======================== */
/* 实时时钟寄存器 (00H~06H) */
#define SD2506_REG_SEC 0x00U /* 秒 00~59 BCD */
#define SD2506_REG_MIN 0x01U /* 分 00~59 BCD */
#define SD2506_REG_HOUR 0x02U /* 时 00~23 BCD, bit7=12/24 */
#define SD2506_REG_WEEK 0x03U /* 星期 00~06 BCD */
#define SD2506_REG_DAY 0x04U /* 日 01~31 BCD */
#define SD2506_REG_MON 0x05U /* 月 01~12 BCD */
#define SD2506_REG_YEAR 0x06U /* 年 00~99 BCD */
/* 报警寄存器 (07H~0EH) */
#define SD2506_REG_AL_SEC 0x07U /* 秒报警 */
#define SD2506_REG_AL_MIN 0x08U /* 分报警 */
#define SD2506_REG_AL_HOUR 0x09U /* 时报警 */
#define SD2506_REG_AL_WEEK 0x0AU /* 星期报警 */
#define SD2506_REG_AL_DAY 0x0BU /* 日报警 */
#define SD2506_REG_AL_MON 0x0CU /* 月报警 */
#define SD2506_REG_AL_YEAR 0x0DU /* 年报警 */
#define SD2506_REG_AL_EN 0x0EU /* 报警允许寄存器 */
/* 控制寄存器 */
#define SD2506_REG_CTR1 0x0FU /* 控制寄存器1 */
#define SD2506_REG_CTR2 0x10U /* 控制寄存器2 */
#define SD2506_REG_CTR3 0x11U /* 控制寄存器3 */
/* 倒计时寄存器 (13H~15H) */
#define SD2506_REG_CNT0 0x13U /* 倒计时字节0 (LSB) */
#define SD2506_REG_CNT1 0x14U /* 倒计时字节1 */
#define SD2506_REG_CNT2 0x15U /* 倒计时字节2 (MSB) */
/* 温度寄存器 */
#define SD2506_REG_TEMP 0x16U /* 温度值 (bit7=符号位) */
#define SD2506_REG_AGTC 0x17U /* IIC控制寄存器 AGTC */
#define SD2506_REG_CHARGE 0x18U /* 充电选择寄存器 */
#define SD2506_REG_CTR4 0x19U /* 扩展控制寄存器 CTR4 */
#define SD2506_REG_CTR5 0x1AU /* 控制寄存器 CTR5 */
#define SD2506_REG_BAT_VAL 0x1BU /* 电池电压低8位 */
/* 温度报警及历史 */
#define SD2506_REG_TEMP_AL 0x1CU /* 低温报警温度值 */
#define SD2506_REG_TEMP_AH 0x1DU /* 高温报警温度值 */
#define SD2506_REG_TEMP_HIS_L 0x1EU /* 历史低温 */
#define SD2506_REG_TEMP_HIS_H 0x1FU /* 历史高温 */
/* 用户 SRAM (2CH~71H) */
#define SD2506_REG_SRAM_START 0x2CU
#define SD2506_REG_SRAM_END 0x71U
#define SD2506_SRAM_SIZE 70U /* 70字节 */
/* ID 码 (72H~79H) */
#define SD2506_REG_ID_START 0x72U
#define SD2506_REG_ID_END 0x79U
#define SD2506_ID_SIZE 8U /* 8字节 */
/* ======================== 控制位定义 ======================== */
/* 控制寄存器 1 (0FH)：bit7=WRTC3 bit6=OSF bit5=INTAF bit4=INTDF bit3=BLF
* bit2=WRTC2 bit1=PMF bit0=RTCF（手册寄存器总表） */
#define SD2506_CTR1_INTAF (1U << 5) /* 报警中断标志 */
#define SD2506_CTR1_INTDF (1U << 4) /* 倒计时中断标志 */
#define SD2506_CTR1_BLF (1U << 3) /* 电池欠压标志 */
/* 控制寄存器 3 (11H) */
#define SD2506_CTR3_ARST (1U << 7) /* 自动复位使能（ARST=1 时读 CTR1 自动清 INTAF/INTDF/BLF） */
/* 控制寄存器 2 (10H) */
#define SD2506_CTR2_INTAE (1U << 5) /* 报警中断允许 */
#define SD2506_CTR2_INTFE (1U << 4) /* 频率中断允许 */
#define SD2506_CTR2_INTDE (1U << 3) /* 倒计时中断允许 */
#define SD2506_CTR2_IM (1U << 2) /* 中断模式: 0=单事件, 1=周期 */
#define SD2506_CTR2_INTS1 (1U << 1) /* INT输出选择 bit1 */
#define SD2506_CTR2_INTS0 (1U << 0) /* INT输出选择 bit0 */
/* 报警允许寄存器 (0EH) */
#define SD2506_AL_EN_EAY (1U << 6) /* 年报警允许 */
#define SD2506_AL_EN_EAMO (1U << 5) /* 月报警允许 */
#define SD2506_AL_EN_EAD (1U << 4) /* 日报警允许 */
#define SD2506_AL_EN_EAW (1U << 3) /* 星期报警允许 */
#define SD2506_AL_EN_EAH (1U << 2) /* 时报警允许 */
#define SD2506_AL_EN_EAMN (1U << 1) /* 分报警允许 */
#define SD2506_AL_EN_EAS (1U << 0) /* 秒报警允许 */
/* 24/12小时制位 */
#define SD2506_HOUR_24 (1U << 7) /* bit7=1 表示24小时制 */
/* ======================== 充电配置 ======================== */
/* 充电寄存器 (18H) 位定义（手册 §4.8）：
* Bit7=EN_Charge（充电允许，复位 0=禁止）；
* Bit1=Charge1、Bit0=Charge0：00=2K / 01=10K / 10=5K / 11=断开（复位态） */
#define SD2506_CHARGE_EN (1U << 7) /* EN_Charge: 充电允许 (Bit7) */
#define SD2506_CHARGE_2K (0U) /* 2K 电阻: Charge1=0, Charge0=0 */
#define SD2506_CHARGE_10K (1U << 0) /* 10K 电阻: Charge1=0, Charge0=1 */
#define SD2506_CHARGE_5K (1U << 1) /* 5K 电阻: Charge1=1, Charge0=0 */
#define SD2506_CHARGE_DISCON (0x03U) /* 断开: Charge1=1, Charge0=1（复位态） */
#define SD2506_CHARGE_INIT_VALUE (0x82U) /* 上电目标值: EN_Charge|5K = 出厂 82H */
/* ======================== 写保护配置 ======================== */
/* 写允许窗口内写 0FH 的建议值: 0xFF（手册 L396：WRTC 位只能保持 1，
* 0FH 其余位均为标志位） */
#define SD2506_CTR1_WRITE_ON 0xFFU
/* 写禁止过渡时 0FH 的建议值: 0x7B（WRTC2/WRTC3=0、标志位 1；WRTC1 在
* CTR2 需另行清除；ARST 在 CTR3 与本寄存器无关） */
#define SD2506_CTR1_WRITE_OFF 0x7BU
/* ======================== 返回值定义 ========================
* 本模块**不再自带错误码**（2026-10-23，S-5）：统一走 Drivers/BSP/bsp_err.h。
* 旧码映射 —— SD2506_OK → BSP_OK；SD2506_ERROR（参数类）→ BSP_ERR_PARAM；
* SD2506_I2C_ERROR → BSP_ERR_IO，其中 I2C 超时刻意单独归成 **BSP_ERR_TIMEOUT
* （可重试）**：旧码把"总线上没人应答"和"超时"混成一个 -2，调用方没法规避。
* 三处旧宏已**删除而不是留别名**——留着就还能被新代码继续用，等于把迁移洗掉。
*/
#include "bsp_err.h"
/* ======================== 超时时间 ======================== */
#define SD2506_I2C_TIMEOUT_MS 100
/* ======================== 数据结构 ======================== */
/*
* RTC 时间日期结构体
* year: 2000~2099
* month: 1~12
* day: 1~31
* hour: 0~23 (24小时制)
* minute: 0~59
* second: 0~59
* week: 0~6 (0=星期天, 1=星期一, ..., 6=星期六)
*/
typedef struct {
uint16_t year;
uint8_t month;
uint8_t day;
uint8_t hour;
uint8_t minute;
uint8_t second;
uint8_t week;
} sd2506_time_t;
/* ======================== 函数声明 ======================== */
/*
* 函数功能：初始化 SD2506API-G RTC
* 入口参数：无
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 失败或回读校验不符；BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：CubeMX 已完成 I2C1 初始化
* 函数说明：1. 读取芯片 ID 验证通信
* 2. 充电寄存器 18H 回读校验（出厂 82H 非易失），值漂移时经写允许
* 窗口重置并回读验证
* 3. 上电即写禁止态（WRTC 全 0），无需再写 0FH
*/
bsp_err_t sd2506_init(void);
/*
* 函数功能：设置 RTC 时间日期
* 入口参数：time - 时间结构体指针，包含要设置的时间
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 通信失败；BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：1. 先开写保护
* 2. 一次性写入 7 字节时间数据 (00H~06H)
* 3. 关闭写保护
* 注意：不可单独写某一个时间寄存器
*/
bsp_err_t sd2506_set_time(const sd2506_time_t *p_time);
/*
* 函数功能：读取 RTC 时间日期
* 入口参数：time - 时间结构体指针，用于存储读取结果
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 通信失败；BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：1. 一次读取 7 字节时间数据 (00H~06H)
* 2. BCD 转十进制
* 3. 屏蔽小时 bit7 (12/24标志位)
*/
bsp_err_t sd2506_get_time(sd2506_time_t *p_time);
/*
* 函数功能：读取芯片内部温度
* 入口参数：temp - 温度输出指针 (整数部分, 有符号)
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 通信失败；BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：读取 16H 寄存器，bit7 为符号位，范围 -40~+85
*/
bsp_err_t sd2506_get_temperature(int8_t *p_temp);
/*
* 函数功能：读取电池电压 (毫伏)
* 入口参数：voltage - 电压输出指针 (单位: mV)
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 通信失败；BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：1. 读取 1AH bit7 (BAT8_VAL) 和 1BH (BAT_VL)
* 2. 组合 9 位数据得到电压值 (如 0x135 = 309 = 3.09V)
*/
bsp_err_t sd2506_get_battery_voltage(uint16_t *p_voltage);
/*
* 函数功能：读取芯片 8 字节 ID
* 入口参数：id - 8 字节输出缓冲区
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 通信失败；BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：读取 72H~79H 共 8 字节唯一 ID
*/
bsp_err_t sd2506_get_id(uint8_t p_id[8]);
/*
* 函数功能：读取用户 SRAM 数据
* 入口参数：addr - SRAM 起始地址 (0~69)
* buf - 数据输出缓冲区
* len - 读取长度 (1~70)
* 返回值：BSP_OK - 成功；BSP_ERR_PARAM - 参数错误；BSP_ERR_IO - I2C 通信失败；
* BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：SRAM 地址范围 0~69，对应寄存器 2CH~71H
*/
bsp_err_t sd2506_read_sram(uint8_t addr, uint8_t *p_buf, uint8_t len);
/*
* 函数功能：写入用户 SRAM 数据
* 入口参数：addr - SRAM 起始地址 (0~69)
* buf - 数据输入缓冲区
* len - 写入长度 (1~70)
* 返回值：BSP_OK - 成功；BSP_ERR_PARAM - 参数错误；BSP_ERR_IO - I2C 通信失败；
* BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：SRAM 地址范围 0~69，对应寄存器 2CH~71H
* SRAM 无需开写保护即可写入
*/
bsp_err_t sd2506_write_sram(uint8_t addr, const uint8_t *p_buf, uint8_t len);
/*
* 函数功能：设置报警中断
* 入口参数：time - 报警时间结构体
* mask - 报警匹配掩码 (SD2506_AL_EN_xxx 位或组合)
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 通信失败；BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：1. 开写保护
* 2. 写入报警寄存器 (07H~0EH)
* 3. 使能报警中断 INTAE
* 4. 关写保护
*/
bsp_err_t sd2506_set_alarm(const sd2506_time_t *p_time, uint8_t mask);
/*
* 函数功能：清除报警中断标志 INTAF
* 入口参数：无
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 通信失败；BSP_ERR_TIMEOUT - I2C 超时（可重试）
* 限定条件：sd2506_init() 已调用
* 函数说明：ARST(CTR3 bit7) 未启用，读 CTR1 不清 INTAF；本函数经写允许窗口
* 手动写 CTR1 将 INTAF 置 0
*/
bsp_err_t sd2506_clear_alarm(void);
/*
* 函数功能：读取当前 0FH 控制寄存器1 状态
* 入口参数：val - 输出值指针
* 返回值：BSP_OK - 成功；BSP_ERR_IO - I2C 通信失败；BSP_ERR_TIMEOUT - I2C 超时（可重试）
*/
bsp_err_t sd2506_read_ctr1(uint8_t *p_val);
/*
* 函数功能：BCD 码转十进制
* 入口参数：bcd - BCD 码值
* 返回值：十进制值
* 函数说明：内部辅助函数
*/
uint8_t sd2506_bcd_to_dec(uint8_t bcd);
/*
* 函数功能：十进制转 BCD 码
* 入口参数：dec - 十进制值
* 返回值：BCD 码值
* 函数说明：内部辅助函数
*/
uint8_t sd2506_dec_to_bcd(uint8_t dec);
#ifdef __cplusplus
}
#endif
#endif /* SD2506_H */
Reference in New Issue View Git Blame Copy Permalink