From a90de6b75eed0502b8b87e6ea7368762f8475e76 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Thu, 19 Nov 2026 11:44:14 +0800 Subject: [PATCH] =?UTF-8?q?fix(util):=20=E8=A1=A5=20ioboard=5Fdi=20?= =?UTF-8?q?=E5=9B=9B=E4=B8=AA=E7=A7=81=E6=9C=89/=E5=AF=BC=E5=87=BA?= =?UTF-8?q?=E5=87=BD=E6=95=B0=E7=9A=84=E6=B3=A8=E9=87=8A=E5=A4=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit coding-standard 钩子在 App/util/ioboard_di.c 报 4 处 CODE-RULE-09(5.3 函数注释 缺「函数功能」):di_is_null、ioboard_di_ch_reset、ioboard_di_snap_reset、 ioboard_di_snap_copy。该文件自 fd767d1d 引入起就缺这几段,与本次合并无关。 只补注释、零行为改动(+38/-2,全部为注释行):函数签名、函数体、空行结构未动。 事实来源全部取现有代码与 ioboard_di.h 的同名声明,没有新增说法。 顺带给 ioboard_di_snap_copy 写清它与 snap_read 的差别:本函数不做双侧 seq 校验, 可能拷到写者写一半的状态,只供诊断场景用;要一致值必须走 snap_read。 此前头文件只有一句「不保证一致性」,实现里没有任何说明。 实测:check_coding_standard.py 单文件 0 违规、全仓 0 违规; test/host/ioboard 131/131 PASSED;Keil 0 Error(s) 0 Warning(s), Program Size Code=365924 与改前逐项相同(Code 不变,符合纯注释改动)。 --- App/util/ioboard_di.c | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/App/util/ioboard_di.c b/App/util/ioboard_di.c index 93def5ab..b69387b2 100644 --- a/App/util/ioboard_di.c +++ b/App/util/ioboard_di.c @@ -13,8 +13,14 @@ #include "ioboard_di.h" -/* 空指针统一按 "0" 处理:本层是纯逻辑,不为防御性检查引入错误码; - * 调用方(defaultTask)传的都是静态对象地址,NULL 只可能出现在测试里 */ +/* + * 函数功能:判断传入指针是否为空(空指针统一按 "0" 处理) + * 入口参数:p - 待判定的指针(const void *;取值任意,含 NULL) + * 返回值:1 = 空指针;0 = 非空指针 + * 限定条件:任意上下文;无副作用 + * 函数说明:本层是纯逻辑,不为防御性检查引入错误码;调用方(defaultTask)传的都是 + * 静态对象地址,NULL 只可能出现在测试里。 + */ static uint8_t di_is_null(const void *p) { return (p == 0) ? 1U : 0U; @@ -22,6 +28,17 @@ static uint8_t di_is_null(const void *p) /* ======================== 通道去抖 ======================== */ +/* + * 函数功能:把一组通道复位成"下一拍即整组确立" + * 入口参数:ch - 通道数组(ioboard_di_ch_t *) + * 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) { uint8_t i; @@ -169,6 +186,14 @@ uint8_t ioboard_di_snap_read(const ioboard_di_snapshot_t *s, uint8_t *out_mask, return 0U; } +/* + * 函数功能:把快照清成"从未成功读过"的初始态 + * 入口参数:s - 快照对象(ioboard_di_snapshot_t *;NULL 直接返回,不做任何写) + * 返回值:无 + * 限定条件:单写者(初始化期 / 尚无读者) + * 函数说明:全字段清零。**mask = 0 此时不表示"开入全 0"**——消费者必须看 valid 与 + * change_seq。fail_count 是 int、其余字段无符号,清零时两者都写 0。 + */ void ioboard_di_snap_reset(ioboard_di_snapshot_t *s) { if (di_is_null(s) != 0U) { @@ -183,6 +208,17 @@ void ioboard_di_snap_reset(ioboard_di_snapshot_t *s) s->change_seq = 0U; } +/* + * 函数功能:把快照逐字段拷一份诊断副本(诊断用,不保证一致性) + * 入口参数:s - 源快照对象(ioboard_di_snapshot_t *) + * out - 目标副本对象(调用方提供存储;任一指针为 NULL 时直接返回,不写 out) + * 返回值:无 + * 限定条件:任意上下文;无锁、不阻塞 + * 函数说明:**不保证一致性**——本函数不做双侧 seq 校验,可能拷到写者写一半的状态, + * 只在没有并发一致性要求的诊断场景(自检/串口打印)用;要一致值请走 + * ioboard_di_snap_read()。拷贝的是 seq / mask / valid / fail_count / + * fail_edges / change_seq 六个字段。 + */ void ioboard_di_snap_copy(const ioboard_di_snapshot_t *s, ioboard_di_snapshot_t *out) { if ((di_is_null(s) != 0U) || (di_is_null(out) != 0U)) {