Files
STM32F4-Base/App/util/ioboard_di.h
T
wandering1 2b466b85f0 feat(ui): add DI/DO status page showing 8 inputs and 4 outputs
New read-only content page under 实时数据 → 开入开出 showing the board's
8 opto inputs (DI_A..DI_H, 合/分) and 4 relay outputs (KO6/TRIP/ERT/CLZ,
吸合/释放) as a 12-row list, 8 rows per page, 2 pages.

Data path reuses the existing de-bounced input poll instead of adding a
second hardware reader:

  defaultTask (50 ms) → ioboard_di_snap_publish() → de-bounced snapshot
    → ioboard_di_snap_lookup()  [new registration channel]
    → ui_data_feed_tick() (uiTask, 200 ms)
    → ui_data_rt_t.dio_di_* / dio_do_*

No new critical sections, no new hardware access on the UI path. Outputs
come from the volatile shadow register (a memory read, no lock).

Semantic honesty, recorded in ui_page_di_do.c and README §6:
  · Output state is the software shadow register (ODR mirror), NOT a
    mechanical contact feedback — this platform has no auxiliary contact
    readback path. ioboard_do_read_level() also reads ODR, so comparing
    the two is tautological.
  · IOBOARD_DO_LEVEL_ACTIVE polarity has not been checked against the
    schematic.
  · Input bit order has not been verified by manual shorting. The
    2026-11-16 run read 0x00 eight times because the operator had no time
    to short each channel — the data path itself was fine.
  · Board-level inputs are deliberately kept out of the 33-point telemetry
    bitmap (IEC 104 point-table semantics); the two have no mapping.

Invalid snapshots render "--", never 合/分 or 吸合/释放: painting "no data"
as "all inputs released" would tell the field the inputs are open when we
simply failed to read them.

Board-verified 2026-11-16: page 1 shows 分 on all 8 inputs, page 2 shows
释放 on all 4 outputs, page footer and paging correct. Input bit order
still pending manual shorting.

Also: regenerate ui_font_cn_12 for 吸/释, add golden references for both
pages, align check_menu_rows.py L2 geometry with the now-4-item submenu,
and register the new source file in both the Keil project and CMake.

Reviewed independently; zero blocking findings.
2026-11-16 21:45:08 +08:00

237 lines
14 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 单测直接编译。
* 跨任务共享:快照对象归写者(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);仅 <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);
/* ======================== 注册式共享读口 ======================== */
/*
* 为什么要有这一对函数:快照对象是写者(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 */