Files
STM32F4-Base/App/util/ioboard_di.h
T
wandering1 fd767d1dcd feat(ioboard): 开入开出板驱动、去抖快照与主机侧单测接入
74HC165 开入 + 光耦继电器开出的完整硬件抽象层,接进 defaultTask
的 50ms 节拍。开入 8 路(第二块 165 数据线板上未接,故只有 8 位),
开出 4 路(高电平吸合)。

驱动 BSP drivers:
- IOBOARD/ioboard.c 装载与移位时序,每步注明数据手册依据;
  SH/LD 拉高前先拉低 CLK,否则装载瞬间多移一位;
  单次读取上界 26us(延时按最慢列 VCC 2V 全温区取值)。
- IOBOARD/ioboard_bits.c 位序组装纯函数,只依赖 stdint.h,
  主机侧可直接 include 做单测:读 8 次为 H,G,F,E,D,C,B,A,
  A 放 bit0(bit(7-i) = reads[i])。
- 极性集中在 IOBOARD_DO_LEVEL_ACTIVE 一处,接口语义统一为
  mask 的 1 = 吸合。

业务接线:
- App/util/ioboard_di.c 通道去抖与双区快照,纯逻辑;
  刻意不 include ioboard.h(其引脚宏会牵入 main.h),
  两处路数常量由测试的编译期静态断言钉住。
- default_task.c 的 default_task_di_poll():读失败不喂去抖、
  不写发布值,只把上一有效值加 valid=0 发布出去,
  避免"全 0"被现场读成开入全部复归。
- 去抖实际粒度 50ms(每个轮询周期喂一拍),最坏上报约 100ms;
  想要真 20ms 需另建定时器,本次不做。
- Src/main.c 在 app_main_init 之前调 ioboard_init(),
  上电即把 4 路出口钉在全释放并确认 165 静止态。

测试:
- test/host/ioboard/ 100 条断言。位序主判据为单比特两端
  (只有 A 得 0x01、只有 H 得 0x80)加八点双射穷举;
  混合图样降级为辅助,因该图样曾先后被算成 0xA5、0x5A、0xAA。
- 去抖覆盖 20ms 边界、抖动不翻、跨 49.7 天回绕。
- 失败语义覆盖"失败保留上次有效值"与"失败窗口内的真实变位不丢"。

文档:
- 新增 docs/硬件平台/开入开出实施说明.md。
- 硬件规格与能力边界 §5 的能力边界现状改写:出口继电器与
  开入回路已具备、业务层未接入;4 路开出只可台架验证,
  不得用于真实跳闸。
- 修正 docs/文档规范.md §3.1:原文要求所有互链用仓库根相对,
  与 check_doc_links.py 的实际解析基准矛盾(markdown 链接按
  当前文档目录解析,反引号路径才按仓库根)。改为区分两类,
  并补 §3.1b 写明对应校验器。
- 清理 docs/任务规划/登记簿.md 改名为硬件改版登记.md 后
  遗留的 9 处旧名引用。

门禁: keil-build 0 Error 0 Warning;主机侧单测 ioboard 100/100、
sb_proto 45/45;pre-commit 48 根钩子全通过。
2026-11-16 18:30:31 +08:00

181 lines
9.5 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.
/*
* 模块名称:开入(DI)去抖与快照——纯逻辑层
* 模块功能:把「每拍读一次 8 路开入」拆成两个与硬件无关的部件——
* ① 通道去抖:每个通道独立计时,电平连续稳定满 DI_DEBOUNCE_WINDOW_MS 才翻转;
* ② 双区快照:消费者拿到的 mask 与 seq 永远来自同一份已稳定的副本。
* 读引脚在 App/util/ioboard_di.c 的 .c 部分(本 .c 就是那一半,属于同一模块的
* 可测部分);本头文件**不 include** HAL / FreeRTOS / ioboard.h / main.h,
* 可被主机侧 MSVC 单测直接编译。
*
* 为什么去抖不放进 ioboard.c:BSP 只回答"让硬件动起来并如实汇报",去抖与
* 失败语义是上报层的事;而且 ioboard.c 依赖 HAL/FreeRTOS,主机侧编不过。
* 为什么不做成通用 di_debounce 工具:去抖的具体语义(20 ms、8 路、失败拍
* 推时间戳)是开入业务的一部分,抽成泛化工具会造出第二个真相源。
* 适用平台:任何 C99(ARMCC v5 / MSVC / GCC);仅 <stdint.h>。
* 作者:王建锋
* 创建日期: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 <stdint.h>
#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);
/*
* 函数功能:读"有效 → 失效 下降沿"累计次数与"连续失败拍数"
* 入口参数: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 */