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 状态改为 🟡 主体已落地。
This commit is contained in:
@@ -0,0 +1,139 @@
|
||||
/*
|
||||
* 模块名称：BSP 统一错误与等待约定
|
||||
* 模块功能：给 Drivers/BSP 下的所有驱动一个共用的返回码语义与等待时长语义，
|
||||
* 使「这次失败能不能重试」成为跨模块可判定的信息，而不是每个模块各自猜。
|
||||
* 适用平台：STM32F4 系列（ARMCC v5）；本头文件不依赖 HAL，模拟器/主机侧同样可编译。
|
||||
* 作者：王建锋
|
||||
* 创建日期：2026-10-23
|
||||
* 修改记录：
|
||||
* 2026-10-23 王建锋 创建：错误码 + 可重试判定 + 等待值契约（首个试点 RS485；同日挂 bsp-err 钩子）
|
||||
*/
|
||||
|
||||
#ifndef BSP_ERR_H
|
||||
#define BSP_ERR_H
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#include <stdint.h>
|
||||
|
||||
/* ============================================================================
|
||||
* 一、错误码：0 = 成功，负值 = 失败
|
||||
* ==========================================================================*/
|
||||
|
||||
/*
|
||||
* 为什么 0 必须是成功：本仓现存调用点绝大多数已经写成 != 0 / == 0（实测跨模块调用
|
||||
* 点约 798 处），反向约定要把每个判据都改一遍，纯赔本。
|
||||
*
|
||||
* ⚠ **一个数量与一个错误码不许挤在同一个返回值里**（面向新 API 的原则）。
|
||||
* 现存两族，都**有意保留**、都已核对：
|
||||
* · net_*（返回字节数，0=对端关闭，-1=错误，-2=超时无数据）——刻意的 BSD 形状，
|
||||
* 已裁定不纳入（见文末边界纪律 3）；
|
||||
* · tpafe5160_snapshot() / adc_input_poll()（1=取到新帧，0=无新帧，BSP_ERR_PARAM=参数错）
|
||||
* ——**0 不是错误**，是"这一拍没有新数据"，套成败码会把慢消费者的正常路径变成失败。
|
||||
* 反例订正：gd5f2gq5ue_read/write/erase 核过实现与头注释是"0=成功、其它=错误码"，
|
||||
* **不是**字节数返回，别再拿它当反面例子（本头文件初稿错过这个错）。
|
||||
* 新 API 要报"做了多少"就走出参：bsp_err_t xxx(..., size_t *p_done)。
|
||||
* 为什么值得写死这条：三态返回（>0 / 0 / <0）要求调用方把三种形态都判到，而实测调用点
|
||||
* 大多是"先赋值再判 != 0"——第三种形态就是这么被吞掉的。
|
||||
*/
|
||||
typedef int bsp_err_t;
|
||||
|
||||
#define BSP_OK ((bsp_err_t)0) /* 成功 */
|
||||
#define BSP_ERR_PARAM ((bsp_err_t)-1) /* 参数非法：指针空、长度越界 */
|
||||
#define BSP_ERR_STATE ((bsp_err_t)-2) /* 调用时机不对：未初始化、状态机不允许 */
|
||||
#define BSP_ERR_TIMEOUT ((bsp_err_t)-3) /* 超时 —— 可重试 */
|
||||
#define BSP_ERR_IO ((bsp_err_t)-4) /* 总线/介质读写失败 */
|
||||
#define BSP_ERR_NO_DEVICE ((bsp_err_t)-5) /* 芯片不在位、无响应（上电时序或硬件） */
|
||||
#define BSP_ERR_BUSY ((bsp_err_t)-6) /* 对端或本侧忙 —— 可重试 */
|
||||
#define BSP_ERR_CRC ((bsp_err_t)-7) /* 校验失败：ECC / CRC / 和校验 */
|
||||
#define BSP_ERR_NO_SPACE ((bsp_err_t)-8) /* 容量或块池耗尽 */
|
||||
#define BSP_ERR_DENIED ((bsp_err_t)-9) /* 被策略拒绝：写保护、鉴权、门未开 */
|
||||
#define BSP_ERR_PARTIAL ((bsp_err_t)-10) /* 部分完成，配合 *p_done 判断做到哪一步 */
|
||||
|
||||
/*
|
||||
* 函数功能：判断一个失败码是否「重试可能成功」
|
||||
* 入口参数：e - 待判定的 bsp_err_t
|
||||
* 返回值：非 0 = 可重试；0 = 重试也没用（参数、状态、策略、无器件这类确定性失败）
|
||||
* 限定条件：只用于已确认失败的码（传 BSP_OK 得 0，不算错）
|
||||
* 函数说明：这才是本头文件真正值钱的一条。现状是把「可重试」写在注释里——
|
||||
* gd5f2gq5ue.c 的返回值注释就写着「GD5F_BUSY_TIMEOUT(-2) - 超时（可重试）」，
|
||||
* 语义在，但跨模块不可判定：上层想统一退避，就得为每个驱动各写一遍 if。有了这条，
|
||||
* 「超时/忙退避、确定性失败立刻放弃」可以只写在一处。不要据此无上限重试：
|
||||
* 上限、退避节奏、喂看门狗都由调用方负责（见文末约定）。
|
||||
*/
|
||||
#define BSP_ERR_CAN_RETRY(e) (((e) == BSP_ERR_TIMEOUT) || ((e) == BSP_ERR_BUSY))
|
||||
|
||||
/* ============================================================================
|
||||
* 二、等待时长契约：把「这个数到底是多久」写死
|
||||
* ==========================================================================*/
|
||||
|
||||
/*
|
||||
* 实测现状（同形不同义，这就是本契约存在的全部理由）：
|
||||
* · SD2506_I2C_TIMEOUT_MS 100、CH395F_SPI_BYTE_TIMEOUT_MS 100U
|
||||
* 真的毫秒：喂 HAL 的 tick 域，本仓 HAL 时基 1ms。
|
||||
* · osWaitForever 与 HAL_MAX_DELAY 同为 0xFFFFFFFFU
|
||||
* 值相同、域不同：一个进 CMSIS-RTOS2、一个进 HAL。于是「把上层拿到的超时值直接
|
||||
* 转手传给另一层」这种代码既不报错也不变慢，直到某天真等死。
|
||||
* · GD5F_SPI_TIMEOUT 100
|
||||
* 不是时间，是自旋圈数（DMA 等待循环）。改 SPI 分频或换主频，实际时长跟着变，
|
||||
* 而且没有任何地方报警。
|
||||
* · GD5F_BUSY_TIMEOUT、TPAFE5160_BUSY_TIMEOUT = -2（**2026-10-23 已消**：前者改名
|
||||
* GD5F_WAIT_EXPIRED（值不变），后者收编成 BSP_ERR_TIMEOUT；留此记录是因为
|
||||
* "时长宏与返回码共用一个名字形状"这类坑只写规则不会自己消失，得留个实证锚点）
|
||||
*
|
||||
* 因此约定：
|
||||
* 一、公开 API 的超时参数一律 uint32_t 毫秒；
|
||||
* 二、要无限等就显式传 BSP_WAIT_FOREVER，不许写 0xFFFFFFFFU、-1 或 0（0 是不等）；
|
||||
* 三、自旋圈数型超时不许叫 *_TIMEOUT_MS，命名须含 LOOP/COUNT 且注释写明非时间量；
|
||||
* 返回码一律不许叫 *_TIMEOUT，改返回 BSP_ERR_TIMEOUT。
|
||||
*
|
||||
* ⚠ 两条硬纪律（AGENTS 铁律，这里只复述到最近的使用点）：
|
||||
* · 内核启动前不得传 BSP_WAIT_FOREVER：osKernelInitialize 之前任何阻塞调用都会挂；
|
||||
* · 长等待与重试循环必须在循环内喂看门狗（本仓 IWDG 有 required_mask 机制）。
|
||||
*/
|
||||
#define BSP_WAIT_NONE ((uint32_t)0U) /* 不等待，立即返回 */
|
||||
#define BSP_WAIT_FOREVER ((uint32_t)0xFFFFFFFFU) /* 无限等待，仅限任务上下文 */
|
||||
|
||||
/*
|
||||
* 函数功能：把毫秒表达成超时入参（本仓 tick = 1ms，故等价）
|
||||
* 入口参数：ms - 毫秒数
|
||||
* 返回值：可直接传给等待类 API 的 uint32_t
|
||||
* 限定条件：仅当 configTICK_RATE_HZ = 1000 时与 tick 数等价
|
||||
* 函数说明：留着它的理由是换算点必须只有一处——哪天 tick 改了只改这里，而不是去
|
||||
* 各驱动里翻 0xFFFFFFFF 和裸数字。
|
||||
*/
|
||||
#define BSP_WAIT_MS(ms) ((uint32_t)(ms))
|
||||
|
||||
/* ============================================================================
|
||||
* 三、边界纪律（写在这里是为了说清什么算「不该改」）
|
||||
* ==========================================================================*/
|
||||
|
||||
/*
|
||||
* 1. 第三方的码不改、不吞、就地映射：HAL_StatusTypeDef、dhara_error_t、FRESULT、
|
||||
* CH395F_ERR_*（芯片寄存器原生码）、FTP 的 226/425/450/550 协议码，全部保留原样，
|
||||
* 只在跨越我们模块边界那一行映射成 bsp_err_t。它们是外部契约或协议本身，改名等于
|
||||
* 伪造语义。映射函数由各驱动自己写一个 static——本头文件刻意不 include HAL，
|
||||
* 以保持主机侧可编译。
|
||||
* 2. 公开 API 面不得返回 HAL_StatusTypeDef 或 bool 表示成败：bool 把「为什么失败」整条
|
||||
* 丢掉，HAL 枚举把 HAL 焊进调用方的 include 链。
|
||||
* 3. net_* 的 BSD 兼容层保持 BSD 形状（返回字节数 + 每任务 errno 槽），**不进本约定**
|
||||
* （用户确认 2026-10-22）：它的调用方要的就是那个形状，模拟器的 Winsock 后端也照同一
|
||||
* 形状实现；归一只到芯片层 ch395f_*。要收口的是"芯片码到 bsp_err_t"这一层，不是把
|
||||
* BSD 形状改成另一套——那只会让 net_* 的调用方在每个判据上多绕一道。
|
||||
* 4. **丢弃返回值必须写 (void)**。为什么不能靠编译器：实测 ARMCC v5 对
|
||||
* __attribute__((warn_unused_result)) 完全不生效——2026-10-23 凌晨在 rs485_transmit 上做过
|
||||
* 实验，属性在位、调用点裸调不接返回值，构建仍然 0 错 0 警告。所以这条只能靠门禁脚本
|
||||
* （scripts/check_bsp_err.py）与"写 (void) 表示故意丢弃"的书写约定来兜；也意味着
|
||||
* 评审时看见没有 (void) 也没接返回值的调用，就是漏判嫌疑。
|
||||
* 5. 重试由调用方决定：必须有上限、必须喂看门狗、不得跨越就绪屏障盲目等。本头文件
|
||||
* 不提供 retry helper——一个通用 while 重试包装太容易被拿去包住无限等待；每个日志
|
||||
* 调用点内联约 216 B 栈的教训在前，栈预算不欢迎「顺手加一层」。
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* BSP_ERR_H */
|
||||
Reference in New Issue
Block a user