文档结构调整

docs/问题记录/SD2506_Trap_Records.md

@@ -0,0 +1,41 @@
+# SD2506API-G 陷阱记录 (Trap Records)
+
+## 陷阱 1：KEIL/ARMCC 下十六进制字面量 `H` 后缀被编译为 0（严重）
+
+### 现象
+SD2506 RTC 时间写不进去：`sd2506_set_time()` 返回 OK，但回读 / 示波器 / 重启后时间不更新。
+诊断时读 `SD2506_REG_CTR1`(0x0F) 得到的值像是秒寄存器内容（PMF / BLF / RTCF / WRTC 位全是反的），
+曾据此误判为「芯片处于 VBAT 模式、写保护硬禁止、需要抬高 VDD 电压」——**全部是假象**。
+
+### 根因
+在 `Drivers/BSP/SD2506/sd2506.h` 中，控制寄存器 1 曾写成：
+
+```c
+#define SD2506_REG_CTR1 0x0FH  /* 控制寄存器1 */
+```
+
+KEIL/ARMCC (armcc v5) **不识别 `H` 整数后缀**。遇到 `0x0FH` 会报语法错并把它当作 **0** 处理，
+于是 `SD2506_REG_CTR1` 实际等于 `0`（即秒寄存器 00H），而不是 `0x0F`。
+
+后果链：
+1. `sd2506_write_enable()` 把 WRTC 位写到了 **00H（秒寄存器）**，而非真正的 CTR1(0x0F)；
+2. 真正的 CTR1 里 WRTC 永远是 0 → 写保护永不解除；
+3. 任何对 00H~79H 的「时间写」都被芯片静默忽略；
+4. 所有通过 `SD2506_REG_CTR1` 读取的诊断都实际读到秒寄存器，于是 PMF / BLF / RTCF / WRTC 解码全错。
+
+### 修复
+把整数后缀统一改成 `U`（或纯 `0xNN`，绝不能带 `H`）：
+
+```c
+#define SD2506_REG_CTR1 0x0FU  /* 控制寄存器1 */
+```
+
+### 排查要点（铁律）
+- KEIL 工程里 **所有** 十六进制寄存器 / 常量宏都必须用 `0xNNU` / `0xNNUL` / `0xNN`，**禁止 `0xNNH`**。
+- 全工程已扫描确认仅此一处 `0x0FH` 非法字面量（`.c/.h` 非注释行）；凡是出现
+  「寄存器读出来位全反 / WRTC 置位无效 / 时间写不进」，**先排查寄存器宏后缀**，再怀疑硬件。
+- 改代码只用 Edit 工具，绝不用 PowerShell `Get/Set-Content` 重写含中文文件（会 UTF-8/GBK 互转乱码）。
+
+### 验证
+修复后 `TEST_SUITE_RTC` Phase 1：6/6 PASS，`set==readback` PASS，CTR1 真实读出 `PMF=0`（VDD 模式）。
+VDD 3.2V 完全正常，无需抬高电压；之前的「VBAT / 电压不够」推断作废。