/* * 模块名称:开入去抖与快照(ioboard_di)主机侧单元测试 * 模块功能:在 PC 上离线验证 App/util/ioboard_di.c 的纯逻辑——通道去抖(窗口/边界/ * 回绕/抖动推迟)与双区快照(一致性、有效性、失败不写 0、饱和计数)。 * * 被测对象:真实源文件 App/util/ioboard_di.c(#include 原样纳入)。 * 该单元只依赖 ,**无需任何桩**。 * * 为什么值得单测(真机上这些判据要么测不出来、要么要等很久): * 1. 去抖窗口的边界:板端只表现为"有时候多报一次变位 / 有时候少报一次", * 靠现场遥信根本不知道是哪一拍差了 1 ms。这里有"19 ms 不翻、20 ms 翻"两条, * 以及"持续抖动在抖动结束后才开始计时"(否则抖动会被当成一次真变位上报成 SOE)。 * 2. tick 回绕:板端要跑满 49.7 天才遇到一次;若写成 now >= t + window 的绝对比较, * 回绕前后会静默冻结。这里用 0xFFFFFFF0 起的 32 拍扫过回绕点。 * 3. 失败语义(本项目 BSP 失败可观测性铁律):读失败**不得**把开入当全 0。 * 板端表现为"线松了十几秒、104 上开入全灭",与人眼看到的现场相反; * 这里逐拍喂失败拍,断言 mask 保持上一有效值、valid 掉落、fail_count 递增。 * 4. 失败窗口内的真实变位不能丢:失败拍只丢"值"不丢"时间戳"——若不推进计时, * 一次跨过整段失败窗口的变位会被永久吞掉,而没有任何迹象。 * * 命名约定:docs/文档规范.md §7.1 —— 用例号 2026-10-27 起停发,用语义化函数名。 * 创建日期:2026-11-16 */ #include #include #include "ioboard_di.h" #include "ioboard_bits.h" /* 只为编译期静态断言"路数一致",不使用任何函数 */ #include "bsp_err.h" #include "ioboard.h" /* 开出极性/语义位的宏契约(纯宏,主机侧可编译) */ /* 被测生产源(include_dirs 里有 Drivers/BSP/IOBOARD 与 App/util) */ #include "ioboard_bits.c" /* 74HC165 位序组装(纯函数,零依赖) */ #include "ioboard_di.c" /* 去抖 + 快照(纯逻辑,零依赖) */ static int s_pass; static int s_fail; #define CHECK(cond, name) \ do { \ if (cond) { \ s_pass++; \ } else { \ s_fail++; \ printf("FAIL: %s (line %d)\n", (name), __LINE__); \ } \ } while (0) /* 编译期一致性:本模块自己的路数与 BSP 的路数必须是同一个数。 * 主机侧没有 MCU 的 static_assert,用"负数组长度"这条经典技巧(MSVC/ARMCC 都编译期报错)。 */ typedef char ioboard_di_ch_num_must_match_bsp[(IOBOARD_DI_CH_NUM == IOBOARD_DI_COUNT) ? 1 : -1]; #define WIN IOBOARD_DI_DEBOUNCE_MS /* --------------------------------------------------------------------------- * 一、74HC165 位序组装(ioboard_bits.c) * -------------------------------------------------------------------------*/ /* * 全零基线:8 拍全读到低电平 → mask 必须是 0。 * 为什么值得测:基线错(例如按取反存储)会让"全安静"误报成有开入变位—— * 台架上一片安静跟着报警,没人会怀疑到位序函数。 */ static void di_assemble_all_zero(void) { static const uint8_t bits[IOBOARD_DI_COUNT] = { 0U, 0U, 0U, 0U, 0U, 0U, 0U, 0U }; CHECK(ioboard_di_assemble(bits) == 0x00U, "all-zero reads assemble to mask 0x00"); } /* * 全一 → 0xFF。为何值得测:防止逐位赋值被改成别的写法时漏掉一位—— * 漏掉的那一路现场表现为"某一路开入永远不来信号",最容易被当成外部接线问题。 */ static void di_assemble_all_one(void) { static const uint8_t bits[IOBOARD_DI_COUNT] = { 1U, 1U, 1U, 1U, 1U, 1U, 1U, 1U }; CHECK(ioboard_di_assemble(bits) == 0xFFU, "all-one reads assemble to mask 0xFF"); } /* * A 位(手册的 A 输入,接口约定 bit0):只有第 8 个时钟沿之前读到的比特为 1。 * 为何值得测:位序核心判据。A 是最后被移出的一位,若实现直接 `mask |= bit << i` * (不反序),A 会落在 bit7——台架上看不出,与"线接错一位"完全同形。 */ static void di_assemble_a_channel_is_bit0(void) { static const uint8_t bits[IOBOARD_DI_COUNT] = { 0U, 0U, 0U, 0U, 0U, 0U, 0U, 1U }; CHECK(ioboard_di_assemble(bits) == 0x01U, "only the 8th read (A channel) assembles to bit0 (0x01)"); } /* * H 位(手册的 H 输入,接口约定 bit7):只有第 1 个时钟沿之前读到的比特为 1。 * 为何值得测:与 A 位成对。单测 A 位仍可能被"整体反序后再取反"之类等价变形骗过, * A/H 两端同时钉住才能把"反序"这个动作本身锁死。 */ static void di_assemble_h_channel_is_bit7(void) { static const uint8_t bits[IOBOARD_DI_COUNT] = { 1U, 0U, 0U, 0U, 0U, 0U, 0U, 0U }; CHECK(ioboard_di_assemble(bits) == 0x80U, "only the 1st read (H channel) assembles to bit7 (0x80)"); } /* * 混合 1,0,1,0,1,0,1,0 → **0xAA**(H/F/D/B 为 1,落在 bit7/5/3/1)。 * * ⚠ 这是**辅助**用例,位序主判据是上面的单比特两端用例(只 A → 0x01、只 H → 0x80)。 * 来历(2026-11-16):同一组输入先后被三个人算出 0xA5、0x5A、0xAA 三个值, * 说明该图样对人类不友好——人要把"第几拍"与"第几位"在脑子里同时倒着数。 * 保留它只为覆盖"多位同时有效"的组合形态,且把三个候选值都摆出来当路标: * 0xAA = 正确实现(bit(7-i)) ← 本条断言的目标 * 0x55 = 不反序(mask |= bit << i) ← 这一类错误由 0x55 的反向用例与单比特用例拦住 * 0xA5 / 0x5A = 前两轮人工误算,不是任何实现的输出,引用前请先手推。 * 注意:本图样是回文的,正序/反序给出的是**互补**值而非同值,所以它确实能抓方向; * 它能抓方向并不改变"位序主判据用单比特两端"这条安排。 */ static void di_assemble_alternating_mixed(void) { static const uint8_t bits[IOBOARD_DI_COUNT] = { 1U, 0U, 1U, 0U, 1U, 0U, 1U, 0U }; CHECK(ioboard_di_assemble(bits) == 0xAAU, "alternating reads: H,F,D,B high -> bits 7/5/3/1 (0xAA)"); } /* * 反向交替 0,1,0,1,0,1,0,1 → 0x55(G/E/C/A 为 1,落在 bit6/4/2/0)。 * 为何值得测:与上一条成对——两条的期望值互补(0xAA / 0x55),任一条与实现同向错时 * 另一条必红;单比特两端用例已锁死映射,这两条只是"多位组合"的补充证据。 */ static void di_assemble_alternating_reverse_mixed(void) { static const uint8_t bits[IOBOARD_DI_COUNT] = { 0U, 1U, 0U, 1U, 0U, 1U, 0U, 1U }; CHECK(ioboard_di_assemble(bits) == 0x55U, "reverse alternating reads: G,E,C,A high -> bits 6/4/2/0 (0x55)"); } /* * README 同款算例:只有 A 与 H 两路有信号 → reads = [1,0,0,0,0,0,0,1] → 0x81。 * 为何值得测:这是文档与实现之间的人工核对锚点;两边不一致说明已有一个人先错。 */ static void di_assemble_a_and_h_is_0x81(void) { static const uint8_t bits[IOBOARD_DI_COUNT] = { 1U, 0U, 0U, 0U, 0U, 0U, 0U, 1U }; CHECK(ioboard_di_assemble(bits) == 0x81U, "worked example: only A and H high assembles to 0x81"); } /* * 非 0 即高(接口契约:任何非 0 值视为高电平)。 * 为何值得测:将来若把读到的原始电平扩展成更宽的值(如带计数)直接灌进来, * 断言 `bits[i] == 1` 的实现会把 0x03 当低——整路开入静默丢失。 */ static void di_assemble_nonzero_means_high(void) { static const uint8_t bits[IOBOARD_DI_COUNT] = { 0xFFU, 0x02U, 0x80U, 0x00U, 0x00U, 0x01U, 0x00U, 0x02U }; const uint8_t expect = (uint8_t)(0x80U | 0x40U | 0x20U | 0x04U | 0x01U); CHECK(ioboard_di_assemble(bits) == expect, "any non-zero read counts as high"); } /* * 逐位置穷举:8 个位置各放一个 1,mask 必须恰好是互异的一位,且覆盖 bit0..bit7 全部。 * 为何值得测:这是"位序映射"这条契约在全部 8 个输入上的**完整定义域**; * 写反、写漏、i 与 7-i 混用都会被它抓出(单靠 A/H 两端抓不到中间位的合流)。 */ static void di_assemble_each_position_is_bijective(void) { uint8_t seen_bit[IOBOARD_DI_COUNT]; uint8_t hit_count[IOBOARD_DI_COUNT]; uint8_t bijective = 1U; uint8_t reach_top = 0U; uint8_t i; for (i = 0U; i < (uint8_t)IOBOARD_DI_COUNT; i++) { seen_bit[i] = 0U; hit_count[i] = 0U; } for (i = 0U; i < (uint8_t)IOBOARD_DI_COUNT; i++) { uint8_t bits[IOBOARD_DI_COUNT]; uint8_t mask; uint8_t j; for (j = 0U; j < (uint8_t)IOBOARD_DI_COUNT; j++) { bits[j] = 0U; } bits[i] = 1U; mask = ioboard_di_assemble(bits); CHECK(mask == (uint8_t)(1U << ((uint8_t)(IOBOARD_DI_COUNT - 1U) - i)), "single high at read i lands exactly on bit(7-i)"); for (j = 0U; j < (uint8_t)IOBOARD_DI_COUNT; j++) { if ((mask & (uint8_t)(1U << j)) != 0U) { seen_bit[j]++; hit_count[i] = (uint8_t)(j + 1U); /* 1 基位号,0 = 没有任何位置命中 */ } } } for (i = 0U; i < (uint8_t)IOBOARD_DI_COUNT; i++) { if ((seen_bit[i] != 1U) || (hit_count[i] == 0U)) { bijective = 0U; } if (hit_count[i] == (uint8_t)IOBOARD_DI_COUNT) { reach_top = 1U; } } CHECK(bijective == 1U, "read index -> mask bit is a one-to-one map over all 8 reads"); CHECK(reach_top == 1U, "the mapping reaches bit7 (nothing collapsed into the low half)"); } /* --------------------------------------------------------------------------- * 二、开出极性与语义位(ioboard.h 的宏契约) * * 说明:ioboard.h 没有独立的"mask -> GPIO 电平"转换函数(极性只由 * IOBOARD_DO_LEVEL_ACTIVE 一个宏决定,是唯一可改点),真实电平须上板用万用表验。 * 主机侧能替台架钉住的只有宏契约本身。 * -------------------------------------------------------------------------*/ /* * 极性两档必须互补:ACTIVE 与 RELEASE 恰好一个是 1、一个是 0。 * 为何值得测:出口继电器误动是现场代价最高的一类缺陷。两个宏若被只改一个, * "上电全释放"会变成"上电全吸合"——一条互补断言就拦住。 */ static void do_polarity_macros_are_complementary(void) { const unsigned active = (unsigned)(IOBOARD_DO_LEVEL_ACTIVE); const unsigned release = (unsigned)(IOBOARD_DO_LEVEL_RELEASE); CHECK((active == 0U) || (active == 1U), "IOBOARD_DO_LEVEL_ACTIVE is a strict 1-bit level"); CHECK(active != release, "active and release levels are complementary"); CHECK((active + release) == 1U, "active + release == 1 (no third value can sneak in)"); } /* * 文档口径:当前硬件口径是"高电平 = 吸合"(用户 2026-11-16)。改成 0 本条即红—— * 这是有意的:改极性是**硬件事实变更**,必须同时改 README 与本条,不能悄悄翻过来。 */ static void do_active_level_matches_documented_high(void) { CHECK(IOBOARD_DO_LEVEL_ACTIVE == 1U, "active-high documented polarity still in force (change README together)"); } /* * 语义位:KO6=bit0、TRIP=bit1、ERT=bit2、CLZ=bit3,四位互异且恰好铺满 bit0..bit3。 * 为何值得测:这四个位就是出口通道号。互换两位 = 跳闸与告警出口对调, * 台架上继电器照样"动",只有知道端子接线的人才会发现。 */ static void do_semantic_bits_are_distinct_and_dense(void) { const uint8_t all = (uint8_t)(IOBOARD_DO_KO6 | IOBOARD_DO_TRIP | IOBOARD_DO_ERT | IOBOARD_DO_CLZ); CHECK(IOBOARD_DO_KO6 == 0x01U, "KO6 is bit0 (PC14)"); CHECK(IOBOARD_DO_TRIP == 0x02U, "TRIP is bit1 (PF0)"); CHECK(IOBOARD_DO_ERT == 0x04U, "ERT is bit2 (PF1)"); CHECK(IOBOARD_DO_CLZ == 0x08U, "CLZ is bit3 (PF6)"); CHECK(all == IOBOARD_DO_MASK_ALL, "the four channel bits exactly fill IOBOARD_DO_MASK_ALL"); CHECK(IOBOARD_DO_MASK_ALL == 0x0FU, "IOBOARD_DO_MASK_ALL is 0x0F (bit4..7 have no hardware)"); } /* * 路数常量:一片 74HC165 = 8 位。为何值得测:组装函数的移位用 IOBOARD_DI_COUNT 推导, * 若有人为"将来两块级联 16 路"把它改成 16,返回值仍是 uint8_t,移位会溢出为未定义行为。 */ static void counts_match_one_74hc165(void) { CHECK(IOBOARD_DI_COUNT == 8, "IOBOARD_DI_COUNT is 8 (one 74HC165)"); CHECK(IOBOARD_DI_MASK_ALL == 0xFFU, "IOBOARD_DI_MASK_ALL covers all 8 DI bits"); CHECK(IOBOARD_DO_COUNT == 4, "IOBOARD_DO_COUNT is 4 relay outputs"); } /* --------------------------------------------------------------------------- * 三、通道去抖(ioboard_di.c) * -------------------------------------------------------------------------*/ /* * 首拍直接确立:复位后第一拍读到 1,stable 立即为 1(不返回翻转)。 * 为何值得测:不这样做的话上电后要空等一个 20 ms 窗口,而 defaultTask 第一拍 * 恰好是 bring-up 完成之后——开入会在开机后短暂"不存在"。 */ static void deb_first_sample_establishes_immediately(void) { ioboard_di_ch_t c; ioboard_di_ch_reset(&c, 1U, 1000U); CHECK(c.started == 0U, "reset leaves the channel unestablished"); CHECK(ioboard_di_ch_feed(&c, 1U, 1000U, WIN) == 0U, "first sample does not count as a flip"); CHECK(c.stable == 1U, "first sample sets the stable level immediately"); CHECK(c.started == 1U, "first sample marks the channel established"); } /* * 窗口内不翻:1 -> 0 后的第 19 ms 仍为稳定 1。 * 为何值得测:窗口差 1 ms 在板端只表现为"偶尔多报一次变位",现场遥信根本看不出。 */ static void deb_flip_waits_full_window(void) { ioboard_di_ch_t c; ioboard_di_ch_reset(&c, 1U, 0U); (void)ioboard_di_ch_feed(&c, 1U, 0U, WIN); (void)ioboard_di_ch_feed(&c, 0U, 100U, WIN); /* raw 变 0,计时从 100 开始 */ CHECK(ioboard_di_ch_feed(&c, 0U, 100U + WIN - 1U, WIN) == 0U, "one ms short of the window: stable level does not flip"); CHECK(c.stable == 1U, "stable level still high at 19 ms"); } /* * 边界正好 20 ms:恰好满窗口即翻(>= 而不是 >)。 * 为何值得测:off-by-one 的另一种写法(>)会让每个窗口多等一拍; * 在 50 ms 轮询下方向相同,但在更快节拍下会变成"永远差一拍"。 */ static void deb_boundary_exactly_20ms_flips(void) { ioboard_di_ch_t c; ioboard_di_ch_reset(&c, 1U, 0U); (void)ioboard_di_ch_feed(&c, 1U, 0U, WIN); (void)ioboard_di_ch_feed(&c, 0U, 500U, WIN); CHECK(ioboard_di_ch_feed(&c, 0U, 500U + WIN, WIN) == 1U, "exactly 20 ms of stable low: stable level flips (boundary is >=)"); CHECK(c.stable == 0U, "stable level is low after the boundary flip"); } /* * 抖动只推迟、不丢:在窗口内反复 1/0/1/0,每次变化都重置计时,稳定电平一次都不翻。 * 为何值得测:去抖失效的最坏后果不是"延迟",而是**把抖动当成真变位**上报—— * IEC 104 会因此刷出一串假 SOE,运维会去现场查根本不存在的动作。 */ static void deb_chatter_does_not_flip(void) { ioboard_di_ch_t c; uint32_t t; uint8_t flips = 0U; ioboard_di_ch_reset(&c, 1U, 0U); (void)ioboard_di_ch_feed(&c, 1U, 0U, WIN); /* 10 个周期、每 5 ms 翻一次(< 20 ms 窗口),共 50 ms */ for (t = 5U; t <= 50U; t += 5U) { const uint8_t lvl = (((t / 5U) % 2U) == 0U) ? 1U : 0U; flips = (uint8_t)(flips + ioboard_di_ch_feed(&c, lvl, t, WIN)); } CHECK(flips == 0U, "chatter inside the window never flips the stable level"); CHECK(c.stable == 1U, "stable level still the original high after 50 ms of chatter"); } /* * 抖动结束后重新计时:最后一次抖动在 t=50,则 t=69 不翻、t=70 翻。 * 为何值得测:若实现用"第一次变化的时刻"而不是"最近一次变化的时刻"计时, * 抖动结束后会**立刻**翻转,等于只在开始处滤了一次——现场表现为"每次开关都报两次"。 */ static void deb_chatter_restarts_timer(void) { ioboard_di_ch_t c; ioboard_di_ch_reset(&c, 1U, 0U); (void)ioboard_di_ch_feed(&c, 1U, 0U, WIN); (void)ioboard_di_ch_feed(&c, 0U, 10U, WIN); (void)ioboard_di_ch_feed(&c, 1U, 20U, WIN); (void)ioboard_di_ch_feed(&c, 0U, 50U, WIN); /* 最后一次抖动:计时从 50 起 */ CHECK(ioboard_di_ch_feed(&c, 0U, 50U + WIN - 1U, WIN) == 0U, "timer restarts at the last edge (19 ms after it: no flip)"); CHECK(ioboard_di_ch_feed(&c, 0U, 50U + WIN, WIN) == 1U, "timer restarts at the last edge (20 ms after it: flip)"); } /* * 窗口 0 = 不滤波:下一拍立即跟随。为何值得测:上层若要临时关掉滤波(例如标定时 * 要看到原始抖动),window=0 必须是真的"立即",而不是被实现悄悄当成默认 20。 */ static void deb_zero_window_follows_next_sample(void) { ioboard_di_ch_t c; ioboard_di_ch_reset(&c, 1U, 0U); (void)ioboard_di_ch_feed(&c, 0U, 0U, 0U); (void)ioboard_di_ch_feed(&c, 1U, 1U, 0U); /* raw 变 1,计时从 1 起 */ CHECK(ioboard_di_ch_feed(&c, 1U, 1U, 0U) == 1U, "window 0 flips on the very next sample"); CHECK(c.stable == 1U, "window 0: stable follows the raw level immediately"); } /* * tick 回绕:raw 在 0xFFFFFFF0 由 1 变 0,窗口 20 ms → 翻在 0x00000004。 * 为何值得测:板端要跑满 49.7 天才遇到一次;若写成 `now >= t + window` 的绝对比较, * 回绕后 t + window 会溢出成小数,比较立刻为真 → 抖动被当成真变位。 * 这里先断言"回绕前差 1 ms 不翻"(若实现有溢出 bug,这一条会红)。 */ static void deb_flip_across_tick_wraparound(void) { ioboard_di_ch_t c; const uint32_t t0 = 0xFFFFFFF0U; ioboard_di_ch_reset(&c, 1U, 0U); (void)ioboard_di_ch_feed(&c, 1U, 0U, WIN); (void)ioboard_di_ch_feed(&c, 0U, t0, WIN); /* 计时起点:距回绕 16 ms */ CHECK(ioboard_di_ch_feed(&c, 0U, 0x00000003U, WIN) == 0U, "across wraparound: 19 ms after the edge does not flip"); CHECK(ioboard_di_ch_feed(&c, 0U, 0x00000004U, WIN) == 1U, "across wraparound: exactly 20 ms after the edge flips"); } /* * 1 ms 步进扫过回绕点:翻转只发生一次,且发生在距边沿恰好 20 ms 的那一拍。 * 为何值得测:上一条只测两个点;这里把 15 拍的整段扫一遍,任何"提前翻 / 漏翻 / * 连翻两次"都会被计数抓出(去抖是每个通道一次翻,多一次就是多一条假 SOE)。 */ static void deb_wraparound_sweep_flips_once(void) { ioboard_di_ch_t c; uint32_t t; uint8_t flips = 0U; uint32_t at_tick = 0U; const uint32_t t0 = 0xFFFFFFF0U; ioboard_di_ch_reset(&c, 1U, 0U); (void)ioboard_di_ch_feed(&c, 1U, 0U, WIN); (void)ioboard_di_ch_feed(&c, 0U, t0, WIN); for (t = 0x00000001U; t <= 0x00000010U; t++) { if (ioboard_di_ch_feed(&c, 0U, t, WIN) != 0U) { flips++; at_tick = t; } } CHECK(flips == 1U, "sweep across wraparound: exactly one flip"); CHECK(at_tick == 0x00000004U, "sweep across wraparound: the flip lands at t0+20 ms"); } /* * 通道相互独立:8 个通道里只让第 3 路变,其它 7 路必须原地不动。 * 为何值得测:若实现把"计时起点"存成模块级静态而不是每通道一份, * 任何一路抖动都会重置全组——现场表现为"动一路,旁边几路跟着报变位"。 */ static void deb_channels_are_independent(void) { ioboard_di_ch_t ch[IOBOARD_DI_CH_NUM]; uint8_t i; uint8_t flips_for_3 = 0U; uint8_t flips_other = 0U; ioboard_di_ch_reset(ch, (uint8_t)IOBOARD_DI_CH_NUM, 0U); for (i = 0U; i < (uint8_t)IOBOARD_DI_CH_NUM; i++) { (void)ioboard_di_ch_feed(&ch[i], 1U, 0U, WIN); /* 全是高 */ } for (i = 0U; i < (uint8_t)IOBOARD_DI_CH_NUM; i++) { const uint8_t lvl = (i == 3U) ? 0U : 1U; uint8_t f = ioboard_di_ch_feed(&ch[i], lvl, 10U, WIN); f = (uint8_t)(f + ioboard_di_ch_feed(&ch[i], lvl, 30U, WIN)); if (i == 3U) { flips_for_3 = (uint8_t)(flips_for_3 + f); } else { flips_other = (uint8_t)(flips_other + f); } } CHECK(flips_for_3 == 1U, "the channel that really changed flips exactly once"); CHECK(flips_other == 0U, "the other 7 channels never flip"); CHECK(ch[3].stable == 0U, "channel 3 is low after its window"); CHECK(ch[0].stable == 1U, "channel 0 untouched"); } /* --------------------------------------------------------------------------- * 四、双区快照(ioboard_di.c) * -------------------------------------------------------------------------*/ /* * 复位后快照"无效且无值":valid=0、change_seq=0,读出的值是 0 但返回 0。 * 为何值得测:消费者必须能区分"还没有任何开入值"与"开入全 0"; * 若复位后 valid 就是 1、change_seq 也是 0,104 会报一个从未发生过的"全 0 遥信"。 */ static void snap_reset_is_invalid_and_empty(void) { ioboard_di_snapshot_t s; uint8_t m = 0xEEU; uint32_t q = 0xEEU; ioboard_di_snap_reset(&s); CHECK(s.valid == 0U, "after reset the snapshot is invalid"); CHECK(s.change_seq == 0U, "after reset change_seq is 0 (no baseline yet)"); CHECK(ioboard_di_snap_read(&s, &m, &q) == 0U, "reading an invalid snapshot returns 0"); CHECK(m == 0U, "an invalid snapshot carries mask 0 (must not be used as data)"); CHECK(q == 0U, "an invalid snapshot carries change_seq 0"); } /* * 首次发布即建立基线:返回 1、change_seq = 1、读得到一致值。 * 为何值得测:上位机用 change_seq 从 0 到 1 的日子判断"基线已建立"; * 若首次发布不算变化,收到全 0 开入(合法)时也无法与"没有数据"区分。 */ static void snap_first_publish_establishes_baseline(void) { ioboard_di_snapshot_t s; uint8_t m = 0U; uint32_t q = 0U; ioboard_di_snap_reset(&s); CHECK(ioboard_di_snap_publish(&s, 0x00U, 1U, 1U) == 1U, "first publish counts as a change (0 -> 1 baseline)"); CHECK(s.change_seq == 1U, "change_seq is 1 after the first publish"); CHECK(ioboard_di_snap_read(&s, &m, &q) == 1U, "a published snapshot reads back valid"); CHECK(m == 0x00U, "reads back the published mask"); CHECK(q == 1U, "reads back the published change_seq"); } /* * 值不变不算变化:连续发布同一 mask,change_seq 不涨。 * 为何值得测:change_seq 是 104 的变位判据;若每拍都涨,COV 上送会变成"每 50 ms 一帧", * 把通道打通的是 104 链路带宽而不是真实变位。 */ static void snap_same_mask_does_not_bump_change_seq(void) { ioboard_di_snapshot_t s; ioboard_di_snap_reset(&s); (void)ioboard_di_snap_publish(&s, 0x12U, 1U, 1U); CHECK(ioboard_di_snap_publish(&s, 0x12U, 1U, 1U) == 0U, "same mask: not a change"); CHECK(s.change_seq == 1U, "same mask: change_seq unchanged"); CHECK(ioboard_di_snap_publish(&s, 0x13U, 1U, 1U) == 1U, "different mask: a change"); CHECK(s.change_seq == 2U, "different mask: change_seq incremented once"); } /* * 失败拍不把 mask 写成 0(本项目的铁律,核心断言): * 先发布 0xA5,接下来连续 5 拍"读失败",mask 必须仍是 0xA5,valid 掉到 0, * fail_count 涨到 5、fail_edges == 1(只记一次下降沿)。 * 为何值得测:板端表现为"线松了十几秒、104 上开入全灭",与人眼看到的现场相反; * 运维会以为现场真断电。这是本项目 BSP 失败可观测性铁律的主机侧落点。 */ static void snap_failure_keeps_last_valid_mask(void) { ioboard_di_snapshot_t s; uint8_t m = 0U; uint32_t q = 0U; uint8_t i; ioboard_di_snap_reset(&s); (void)ioboard_di_snap_publish(&s, 0xA5U, 1U, 1U); /* 一次成功读 */ for (i = 0U; i < 5U; i++) { (void)ioboard_di_snap_publish(&s, 0xA5U, 0U, 0U); /* 失败拍:传上一有效值 */ } CHECK(s.mask == 0xA5U, "failure frames never rewrite mask to 0 (keep the last valid value)"); CHECK(s.valid == 0U, "failure frames mark the snapshot invalid"); CHECK(s.fail_count == 5, "fail_count counts every failed frame"); CHECK(s.fail_edges == 1U, "fail_edges counts one falling edge for a contiguous failure window"); CHECK(s.change_seq == 1U, "failure frames do not create a phantom change"); CHECK(ioboard_di_snap_read(&s, &m, &q) == 0U, "reader sees the snapshot as invalid during failure"); CHECK(m == 0xA5U, "reader still costs the last valid mask (but must not use it as new data)"); } /* * 恢复:失败窗口之后成功读一次,valid 回到 1,fail_edges 不再涨。 * 为何值得测:fail_edges 只在下降沿计数;若实现把恢复也当边沿,故障次数会被重复上报。 */ static void snap_recovery_restores_valid(void) { ioboard_di_snapshot_t s; ioboard_di_snap_reset(&s); (void)ioboard_di_snap_publish(&s, 0x01U, 1U, 1U); (void)ioboard_di_snap_publish(&s, 0x01U, 0U, 0U); CHECK(ioboard_di_snap_publish(&s, 0x01U, 1U, 1U) == 0U, "recovery with the same mask is not a change"); CHECK(s.valid == 1U, "recovery restores valid"); CHECK(s.fail_edges == 1U, "recovery does not count as another falling edge"); CHECK(s.fail_count == 0, "recovery resets the consecutive-failure counter"); } /* * 失败期间的真实变位不丢:先成功读到 0x00,失败窗口里第 3 拍"实际变 0x01"(调用方 * 仍按上一有效值发布 0x00),恢复后第一拍发布 0x01 → change_seq 涨到 2。 * 为何值得测:这就是"失败拍只丢值、不丢时间戳与候选值"的意义(见 ioboard_di.h 的 * 失败语义说明)。若去抖/候选值在失败期间停摆,恢复后要重新走一个 20 ms 窗口, * 一次短故障(< 20 ms)里的真实变位会被永久吞掉,且没有任何迹象。 */ static void snap_real_change_across_failure_window_is_not_lost(void) { ioboard_di_snapshot_t s; ioboard_di_snap_reset(&s); (void)ioboard_di_snap_publish(&s, 0x00U, 1U, 1U); (void)ioboard_di_snap_publish(&s, 0x00U, 1U, 1U); CHECK(s.change_seq == 1U, "baseline established with change_seq 1"); (void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); /* 失败第 1 拍 */ (void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); /* 失败第 2 拍 */ (void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); /* 失败第 3 拍(实际已变) */ CHECK(ioboard_di_snap_publish(&s, 0x01U, 1U, 1U) == 1U, "the change that happened during the failure window surfaces on recovery"); CHECK(s.change_seq == 2U, "change_seq counts that change exactly once"); } /* * 失败计数:连续失败上不封顶地累加、到 CAP 饱和不绕负;**任何一次成功读即归零**。 * 为何值得测:一次断线跑满 24 天(2 147 483 647 ms)在长期服役的装置上是可能的; * 若 int32 绕回负数,自检里"读失败帧数为负"意味着"一直失败"看起来像"从未失败"。 * 反过来,若成功读不归零,一次偶发失败会让计数永久停在上界,之后真正的断线 * 再也看不出来——"连续"二字的两个方向都要钉住。 */ static void snap_fail_count_saturates_and_resets(void) { ioboard_di_snapshot_t s; ioboard_di_snap_reset(&s); (void)ioboard_di_snap_publish(&s, 0x00U, 1U, 1U); (void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); /* 进入失败态:一记下降沿 */ s.fail_count = (int32_t)IOBOARD_DI_FAIL_COUNT_CAP - 2; /* 抬到接近上界 */ (void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); (void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); CHECK(s.fail_count == (int32_t)IOBOARD_DI_FAIL_COUNT_CAP, "fail_count reaches CAP exactly"); (void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); (void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); CHECK(s.fail_count == (int32_t)IOBOARD_DI_FAIL_COUNT_CAP, "fail_count saturates at CAP instead of wrapping negative"); CHECK(s.fail_edges == 1U, "a long failure window is still one edge"); (void)ioboard_di_snap_publish(&s, 0x00U, 1U, 1U); /* 一次成功读 */ CHECK(s.fail_count == 0, "one successful read resets fail_count (it counts CONSECUTIVE failures)"); } /* * 阅读一致性协议的边界:写者正在写(seq 为奇数)时读者不得出结论。 * 为何值得测:真并发在主机侧无法复现,但"奇数序号 = 写者正在写"这一条是可构造的—— * 把 seq 手动设成奇数,读者必须返回 0 而不是把半新半旧的 mask 当结果。 */ static void snap_reader_rejects_odd_seq(void) { ioboard_di_snapshot_t s; uint8_t m = 0xAAU; uint32_t q = 0xAAU; ioboard_di_snap_reset(&s); (void)ioboard_di_snap_publish(&s, 0x3CU, 1U, 1U); s.seq = 5U; /* 模拟"写者停在两次递增之间" */ s.mask = 0x00U; /* 半新半旧的值 */ CHECK(ioboard_di_snap_read(&s, &m, &q) == 0U, "reader returns 0 while the writer holds an odd sequence"); CHECK(m == 0xAAU, "reader leaves out_mask untouched when it cannot get a consistent value"); s.mask = 0x3CU; s.seq = 6U; /* 写者恢复 */ CHECK(ioboard_di_snap_read(&s, &m, &q) == 1U, "reader succeeds once the sequence is even again"); CHECK(q == 1U, "reader returns change_seq, not the raw sequence"); } /* * 发布后序号恒为偶数:每拍发布一次,seq 必须保持偶数(写者协议的对外承诺)。 * 为何值得测:若实现漏掉最后那次递增,读者永远读不到——开入从某个时刻起静默冻结。 */ static void snap_seq_stays_even_after_publish(void) { ioboard_di_snapshot_t s; uint32_t i; ioboard_di_snap_reset(&s); for (i = 0U; i < 10U; i++) { (void)ioboard_di_snap_publish(&s, (uint8_t)i, 1U, 1U); } CHECK((s.seq & 1U) == 0U, "seq is even after every publish"); CHECK(s.seq == 20U, "each publish advances seq by 2 (odd then even)"); } /* * NULL 契约:所有 NULL 入参安全返回(不崩、不写)。 * 为何值得测:本层在 defaultTask 主循环里常驻调用,任何一次崩溃就是 IWDG 复位; * 防御性 NULL 分支也要被走一遍,否则它就是"写了但从未执行过"的代码。 */ static void di_null_inputs_are_safe(void) { ioboard_di_snapshot_t s; uint8_t m = 0x5AU; uint32_t q = 0x5AU; ioboard_di_snap_reset(&s); (void)ioboard_di_snap_publish(&s, 0x3CU, 1U, 1U); /* s 变成"有效且有值" */ ioboard_di_ch_reset(NULL, 1U, 0U); CHECK(ioboard_di_ch_feed(NULL, 1U, 0U, WIN) == 0U, "feed with a NULL channel returns 0"); ioboard_di_snap_reset(NULL); CHECK(ioboard_di_snap_publish(NULL, 0U, 1U, 1U) == 0U, "publish on a NULL snapshot returns 0"); CHECK(ioboard_di_snap_read(NULL, &m, &q) == 0U, "read on a NULL snapshot returns 0"); CHECK((m == 0U) && (q == 0U), "read on a NULL snapshot zeroes its outputs"); ioboard_di_snap_copy(NULL, &s); ioboard_di_snap_copy(&s, NULL); ioboard_di_snap_copy(NULL, NULL); CHECK(s.valid == 1U, "copy with a NULL source leaves the destination untouched"); CHECK(ioboard_di_snap_read(&s, NULL, NULL) == 1U, "reader tolerates NULL outputs (valid snapshot, values discarded)"); } /* * 诊断接口合同:snap_faults 取出的两个数与快照字段一致;NULL 源给 0。 * 为何值得测:defaultTask 用它在故障下降沿写 syslog;这里若读错字段, * 日志会写成"失败帧数 = 故障次数"这类倒挂值,排查时被反着理解。 */ static void snap_faults_accessor_matches_fields(void) { ioboard_di_snapshot_t s; uint32_t edges = 0U; int32_t fails = 0; ioboard_di_snap_reset(&s); (void)ioboard_di_snap_publish(&s, 0x01U, 1U, 1U); (void)ioboard_di_snap_publish(&s, 0x01U, 0U, 0U); (void)ioboard_di_snap_publish(&s, 0x01U, 0U, 0U); ioboard_di_snap_faults(&s, &edges, &fails); CHECK(edges == 1U, "faults accessor returns fail_edges"); CHECK(fails == 2, "faults accessor returns consecutive fail_count"); ioboard_di_snap_faults(&s, NULL, NULL); /* 两个输出都可省略 */ ioboard_di_snap_faults(NULL, &edges, &fails); CHECK((edges == 0U) && (fails == 0), "faults accessor on a NULL snapshot yields zeros"); } int main(void) { printf("-- ioboard unit tests --\n"); /* 一、74HC165 位序 */ di_assemble_all_zero(); di_assemble_all_one(); di_assemble_a_channel_is_bit0(); di_assemble_h_channel_is_bit7(); di_assemble_alternating_mixed(); di_assemble_alternating_reverse_mixed(); di_assemble_a_and_h_is_0x81(); di_assemble_nonzero_means_high(); di_assemble_each_position_is_bijective(); /* 二、开出极性 / 语义位 / 路数 */ do_polarity_macros_are_complementary(); do_active_level_matches_documented_high(); do_semantic_bits_are_distinct_and_dense(); counts_match_one_74hc165(); /* 三、通道去抖 */ deb_first_sample_establishes_immediately(); deb_flip_waits_full_window(); deb_boundary_exactly_20ms_flips(); deb_chatter_does_not_flip(); deb_chatter_restarts_timer(); deb_zero_window_follows_next_sample(); deb_flip_across_tick_wraparound(); deb_wraparound_sweep_flips_once(); deb_channels_are_independent(); /* 四、双区快照 */ snap_reset_is_invalid_and_empty(); snap_first_publish_establishes_baseline(); snap_same_mask_does_not_bump_change_seq(); snap_failure_keeps_last_valid_mask(); snap_recovery_restores_valid(); snap_real_change_across_failure_window_is_not_lost(); snap_fail_count_saturates_and_resets(); snap_reader_rejects_odd_seq(); snap_seq_stays_even_after_publish(); di_null_inputs_are_safe(); snap_faults_accessor_matches_fields(); printf("=== IO Board Tests: %d/%d PASSED ===\n", s_pass, s_pass + s_fail); return (s_fail == 0) ? 0 : 1; }