/* * 模块名称:开入(DI)去抖与快照——纯逻辑层 * 模块功能:把「每拍读一次 8 路开入」拆成两个与硬件无关的部件—— * ① 通道去抖:每个通道独立计时,电平连续稳定满 DI_DEBOUNCE_WINDOW_MS 才翻转; * ② 双区快照:消费者拿到的 mask 与 seq 永远来自同一份已稳定的副本。 * 读引脚在 App/util/ioboard_di.c 的 .c 部分(本 .c 就是那一半,属于同一模块的 * 可测部分);本头文件**不 include** HAL / FreeRTOS / ioboard.h / main.h, * 可被主机侧 MSVC 单测直接编译。 * 跨任务共享:快照对象归写者(defaultTask)私有,读者经下方的 * ioboard_di_snap_register / ioboard_di_snap_lookup 拿指针,仍用同一套 * 序号协议(ioboard_di_snap_read)读——不引入第二份副本、不引入锁。 * * 为什么去抖不放进 ioboard.c:BSP 只回答"让硬件动起来并如实汇报",去抖与 * 失败语义是上报层的事;而且 ioboard.c 依赖 HAL/FreeRTOS,主机侧编不过。 * 为什么不做成通用 di_debounce 工具:去抖的具体语义(20 ms、8 路、失败拍 * 推时间戳)是开入业务的一部分,抽成泛化工具会造出第二个真相源。 * 适用平台:任何 C99(ARMCC v5 / MSVC / GCC);仅 。 * 作者:王建锋 * 创建日期:2026-11-16 * 修改记录: * 2026-11-16 王建锋 创建 * * 失败语义(本模块最重要的一条,单测与调用方都依赖它): * 本项目铁律是「读失败不得把开入当全 0 上报」。本模块的落点有三处: * · 快照 mask **只**由成功读更新:失败拍喂进去的是"上一有效值",绝不自行产生 0; * · 但失败拍**照样推进**去抖计时并更新候选值——否则一次跨过整段失败窗口的真实 * 变位会被永久吞掉,104/UI 上看到的仍是旧值且无痕迹; * · 有效性下降沿 / 恢复沿各记一次(fail_edges / valid),由调用方决定是否留痕; * 本模块本身不碰文件系统、不依赖 CMSIS,所以能在 PC 上跑。 */ #ifndef IOBOARD_DI_H #define IOBOARD_DI_H #include #ifdef __cplusplus extern "C" { #endif /* ======================== 常量 ======================== */ /* 去抖窗口(ms):某通道电平须连续稳定这么久,快照才允许翻转。 * 取 20 ms:现场开关与继电器辅助触点抖动在 5~10 ms 量级,20 ms 是常见两倍余量; * 且 20 ms < defaultTask 的 50 ms 基准拍(最快两拍后翻转)、 * 远小于 100 ms 喂狗判定,不影响任何既有节拍。 */ #define IOBOARD_DI_DEBOUNCE_MS 20u /* 开入路数。**刻意不复用 IOBOARD_DI_COUNT**:IOBOARD 头里的 HC165 引脚宏会展开成 * main.h 的符号,一旦被 .c 真正使用就把 MCU 头拉进本纯逻辑单元,主机侧编不过。 * 两者的一致性由主机侧测试在编译期静态断言(test/host/ioboard/ioboard_test.c)。 */ #define IOBOARD_DI_CH_NUM 8u /* 读失败累计上界:到顶后不再增加,防止长时间断线把 int32 计数绕成负数, * 让"一直失败"看起来像"从未失败" */ #define IOBOARD_DI_FAIL_COUNT_CAP 0x7FFFFFFFL /* 读侧重试上限:写者一次发布是十几条指令,正常第二遍必一致; * 20 次仍不一致 = 被持续抢占,返回 0 让调用方本次不用这个值 */ #define IOBOARD_DI_SNAP_RETRY 20u /* ======================== 通道去抖 ======================== */ /* * 单通道去抖状态。结构体公开是为了让调用方放进静态存储(本仓禁用 C 库堆分配)。 * 字段语义(一律走下面的函数读改写,别直接写): * t_ms - raw 最近一次变化的时刻 * raw - 最近一拍读到的电平(0/1) * stable - 已确认稳定的电平(就是快照里那一位) * started - 是否已收到第一拍(0 = 尚未确立) */ typedef struct { uint32_t t_ms; uint8_t raw; uint8_t stable; uint8_t started; } ioboard_di_ch_t; /* * 函数功能:把一组通道复位成"下一拍即整组确立" * 入口参数:ch - 通道数组 * n - 数组长度(可小于 IOBOARD_DI_CH_NUM,便于单测只用一个通道) * now_ms - 复位时刻(沿用调用方时间基准,通常是 HAL_GetTick) * 返回值:无 * 限定条件:任意上下文;纯内存写,不加锁 * 函数说明:复位后**第一拍**无论读到什么都整组确立——这是 run 期"重新武装"语义: * 调用方先让快照失效、再复位,下一拍重新建立基准,不必区分设备是上电起来 * 还是从故障恢复起来。 */ void ioboard_di_ch_reset(ioboard_di_ch_t *ch, uint8_t n, uint32_t now_ms); /* * 函数功能:喂一拍采样给单个通道 * 入口参数:c - 通道状态(已复位或已初始化) * level - 本拍电平(非 0 即 1;传更宽的值也安全) * now_ms - 本拍时刻(ms,任意起点、允许 32 位回绕) * window_ms - 去抖窗口(ms;0 = 不滤波,下一拍立即跟随) * 返回值:1 = 稳定电平在本拍翻转;0 = 未翻转 * 限定条件:相邻两拍间隔须 < 2^32 ms(49 天)——本项目 50 ms 节拍天然满足 * 函数说明: * 一、首个样本直接确立(否则上电后要空等一个窗口才有开入值)。 * 二、raw 变化 → 记新 raw 与时刻、计时重开始(抖动不断推迟翻转,这就是去抖)。 * 三、raw 未变、已稳定、且 (now - t_ms) **>=** window → stable 跟随 raw。 * 用无符号减法而不是 `now >= t + window`:后者在 tick 回绕附近会错误地 * "永久成立"或"永久不成立"(单测"回绕"一条扫这个窗口)。边界取 >=:满 20 ms 即翻。 */ uint8_t ioboard_di_ch_feed(ioboard_di_ch_t *c, uint8_t level, uint32_t now_ms, uint32_t window_ms); /* ======================== 双区快照 ======================== */ /* * 快照。**单写者**(run 期 = defaultTask;同一时刻只有一个写者),**多读者** * (任意上下文、无锁)。读者按"序号偶数且前后一致"取一致值;写者按"奇-写-偶"发布。 */ typedef struct { volatile uint32_t seq; /* 偶数 = 稳定;奇数 = 正在写 */ volatile uint8_t mask; /* 去抖后的 8 路开入(bit0 = A … bit7 = H) */ volatile uint8_t valid; /* 1 = 至少成功读过一次、且当前不在失败态 */ volatile int32_t fail_count; /* **连续**读失败拍数(成功一拍即归零;饱和于 CAP) */ volatile uint32_t fail_edges; /* 有效 → 失效 的下降沿次数(= 故障次数) */ volatile uint32_t change_seq; /* 去抖后 mask 翻转次数 */ } ioboard_di_snapshot_t; /* * 函数功能:写者发布一拍 * 入口参数:s - 快照对象 * mask - 本拍去抖结果(读失败时**必须**传上一有效值) * valid - 本拍之后是否有效(0/1) * is_fail - 本拍是否读失败(0 = 失败;非 0 = 成功) * 返回值:去抖后 mask 相对上一拍是否翻转(1 = 翻转,change_seq 已加一) * 限定条件:单写者;不加锁;可在临界区内调用 * 函数说明:第一次发布(change_seq == 0)也返回 1,让上位机区分"还没有任何值"与 * "已建立基线"。本函数**从不自行生成 0**:mask 就是调用方传进来的值, * 失败拍传的是上一有效值——这就是"失败不当全 0"的落点。 */ uint8_t ioboard_di_snap_publish(ioboard_di_snapshot_t *s, uint8_t mask, uint8_t valid, uint8_t is_fail); /* * 函数功能:读者取一致的一组值 * 入口参数:s - 快照对象 * out_mask - 输出,去抖后开入(可为 NULL) * out_seq - 输出,change_seq(可为 NULL) * 返回值:1 = 读到一致且有效的快照;0 = 快照尚无效 / 读取期间持续被打断 * 限定条件:任意上下文、无锁、不阻塞 * 函数说明:返回 0 时 out_mask 仍被写为"最近一次发布值",但**不得**当新数据用—— * 消费者按"本次无新数据"处理(保留自己上一次保存的值)。 */ uint8_t ioboard_di_snap_read(const ioboard_di_snapshot_t *s, uint8_t *out_mask, uint32_t *out_seq); /* * 函数功能:把快照清成"从未成功读过"的初始态 * 入口参数:s - 快照对象 * 返回值:无 * 限定条件:单写者(初始化期 / 尚无读者) * 函数说明:全字段清零。**mask = 0 此时不表示"开入全 0"**——消费者必须看 valid 与 * change_seq。 */ void ioboard_di_snap_reset(ioboard_di_snapshot_t *s); /* 诊断副本:不保证一致性,仅供自检/串口打印 */ void ioboard_di_snap_copy(const ioboard_di_snapshot_t *s, ioboard_di_snapshot_t *out); /* ======================== 注册式共享读口 ======================== */ /* * 为什么要有这一对函数:快照对象是写者(defaultTask)的文件作用域静态变量, * 作用域外拿不到地址。让读者自己 include 写者的私有状态 = 打开第二个写者入口; * 让读者 copy 一份 = 造出第二份随时间漂移的真相。所以中间只放"登记一个地址", * 读者拿走指针后**仍走 ioboard_di_snap_read() 的同一套序号协议**(不是第二个读者实现)。 * 在此之前 ioboard_di_snap_read() 在本仓没有任何调用方(它只被主机侧单测覆盖), * 本对函数就是它"跨任务可用"的接线:读者 = App/app/ui_data_feed.c(uiTask 上下文), * 写者 = defaultTask(登记点 = default_task_di_publish_register)。 * 为什么注册表放在本纯逻辑层:它就是一个指针 + 单写者判据,零 HAL / 零 FreeRTOS; * 放进来才能在主机侧单测里直接验证"拒绝第二个写者",而不必上板。 */ /* * 函数功能:写者登记它的快照对象(产品里 = defaultTask 的 s_di_snap) * 入口参数:s - 由本登记者独占写入的快照对象(s == 0 = 参数非法) * 返回值:0 - 成功(首次登记成功,或重复登记的**正是同一个**指针:幂等) * -1 - 参数非法(s == 0),或已被**另一个**指针占用(保留首个,拒绝后来的) * 限定条件:写在登记成功之后**才开始**发布,不得先发布再登记(见函数说明第二段) * 函数说明: * 一、只存指针:不复制、不初始化、不改写快照内容——快照的初始态由写者自己 * (ioboard_di_snap_reset 或静态零初始化)负责,本函数不代劳。否则登记时刻 * 就是一个"把写者正在发布的快照清零"的竞态点。 * 二、单写者:占用后第一个指针就是唯一真相源。第二个不同指针 = 返回 -1 并保留首个; * 重复登记同一指针 = 幂等返回 0。为什么换写者也不行:指针一变,读者拿到的 * 旧指针生命周期无法保证,且两个快照对象同时存在正是本函数要禁掉的局面 * (换写者需要先下线旧写者,本平台没有这种用法,故不提供注销)。 * 三、登记表本身是编译期零初始化的文件作用域静态,**没有"初始化"步骤**: * 于是不存在"谁必须先跑一遍初始化"的启动顺序依赖,本函数也是幂等的。 * 是否可用在任务启动之前:可以(注册表零初始化、本就用于 app_main_init 阶段的 * 提前登记),但届时还没有读者——本仓的登记点在写者自己的任务启动段: * default_task_func 里调 default_task_di_publish_register(),先于首次 * default_task_di_poll() 发布。 * 四、注册表置 volatile:读者(uiTask / 任意上下文)与写者(defaultTask)跨任务 * 通过它传地址,编译器不得把"看起来没变"的读缓存起来。指针本身的赋值在 M4 上 * 是单条 32 位存储,读者不会看到半个地址;"读到非 0 之后指针不再变化"由上面 * 的不可变约束保证,所以读者侧既不用关中断也不用再校验一次。 */ int ioboard_di_snap_register(const ioboard_di_snapshot_t *s); /* * 函数功能:读者取已登记的快照对象 * 入口参数:无 * 返回值:已登记的快照指针;未登记(或登记被拒绝且从未成功过)= NULL * 限定条件:任意上下文(任务 / 中断 / 启动段)、无锁、不阻塞、不关中断 * 函数说明:拿到指针后必须自己调 ioboard_di_snap_read() 取一致值,**不要**直接读 * s->mask —— 直接读会不带序号校验,拿到写者写到一半的字段。 * 返回 NULL 表示"本构建没有开入发布者"(如 TEST_SUITE_STORAGE), * 消费者应把它当作"无数据源",不是"开入全 0"。 */ const ioboard_di_snapshot_t *ioboard_di_snap_lookup(void); /* * 函数功能:读"有效 → 失效 下降沿"累计次数与"连续失败拍数" * 入口参数:s - 快照对象 * out_edges - 输出,fail_edges(可为 NULL) * out_fails - 输出,fail_count(可为 NULL) * 返回值:无 * 限定条件:任意上下文;单字读,值可能来自相邻两拍(诊断用途够用) * 函数说明:调用方(defaultTask)用它把"开入读失败"这一事实经 syslog 留痕—— * 本模块自己不碰文件系统,留痕点只有调用方知道该写哪个日志、写多频。 */ void ioboard_di_snap_faults(const ioboard_di_snapshot_t *s, uint32_t *out_edges, int32_t *out_fails); #ifdef __cplusplus } #endif #endif /* IOBOARD_DI_H */