fix(util): 补 ioboard_di 四个私有/导出函数的注释头

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 不变,符合纯注释改动)。
This commit is contained in:
2026-11-19 11:44:14 +08:00
parent 9c8c342f27
commit a90de6b75e
+38 -2
View File
@@ -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)) {