Files
STM32F4-Base/test/host/ioboard/ioboard_test.c
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

783 lines
34 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.
/*
* 模块名称:开入去抖与快照(ioboard_di)主机侧单元测试
* 模块功能:在 PC 上离线验证 App/util/ioboard_di.c 的纯逻辑——通道去抖(窗口/边界/
* 回绕/抖动推迟)与双区快照(一致性、有效性、失败不写 0、饱和计数)。
*
* 被测对象:真实源文件 App/util/ioboard_di.c(#include 原样纳入)。
* 该单元只依赖 <stdint.h>,**无需任何桩**。
*
* 为什么值得单测(真机上这些判据要么测不出来、要么要等很久):
* 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 <stdint.h>
#include <stdio.h>
#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;
}