Files
STM32F4-Base/App/util/ioboard_di.c
T
wandering1 a90de6b75e 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 不变,符合纯注释改动)。
2026-11-19 11:44:14 +08:00

304 lines
10 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)去抖与快照——纯逻辑实现(本模块可主机侧测试的那一半)
* 模块功能:ioboard_di.h 全部纯函数(另含一张单指针登记表,供写者与读者跨任务
* 共享同一份快照——表本身不涉及 HAL/FreeRTOS,仍是纯逻辑)。
* 零 HAL、零 FreeRTOS;唯一的全局状态是登记表,只由写者登记一次、之后只读。
* MCU(ARMCC C99)与主机侧 MSVC 编译**同一份源码**。
* 适用平台:任何 C99
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建
*/
#include "ioboard_di.h"
/*
* 函数功能:判断传入指针是否为空(空指针统一按 "0" 处理)
* 入口参数:p - 待判定的指针(const void *;取值任意,含 NULL)
* 返回值:1 = 空指针;0 = 非空指针
* 限定条件:任意上下文;无副作用
* 函数说明:本层是纯逻辑,不为防御性检查引入错误码;调用方(defaultTask)传的都是
* 静态对象地址,NULL 只可能出现在测试里。
*/
static uint8_t di_is_null(const void *p)
{
return (p == 0) ? 1U : 0U;
}
/* ======================== 通道去抖 ======================== */
/*
* 函数功能:把一组通道复位成"下一拍即整组确立"
* 入口参数: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;
if (di_is_null(ch) != 0U) {
return;
}
for (i = 0U; i < n; i++) {
ch[i].t_ms = now_ms;
ch[i].raw = 0U;
ch[i].stable = 0U;
ch[i].started = 0U;
}
}
uint8_t ioboard_di_ch_feed(ioboard_di_ch_t *c, uint8_t level, uint32_t now_ms,
uint32_t window_ms)
{
uint8_t lvl;
if (di_is_null(c) != 0U) {
return 0U;
}
lvl = (level != 0U) ? 1U : 0U;
/* 一、首个样本直接确立:上电后不必空等一个窗口才有开入值 */
if (c->started == 0U) {
c->started = 1U;
c->raw = lvl;
c->stable = lvl;
c->t_ms = now_ms;
return 0U; /* 首拍不算"稳定电平翻转":此前没有稳定值可翻 */
}
/* 二、原始电平变了:重新开始计时。抖动只会不断推迟翻转,这就是去抖 */
if (lvl != c->raw) {
c->raw = lvl;
c->t_ms = now_ms;
return 0U;
}
/* 三、原始电平持续满窗口 → 稳定电平跟随。
* 用无符号减法而不是 now >= t + window:tick 在 49.7 天处回绕时前者依然正确,
* 后者会在回绕附近出现一次长达 49 天的"永不翻转"(或者反过来瞬间误翻)。
* 边界取 >=:恰好满 20 ms 就应翻转。 */
if ((c->stable != lvl) && ((uint32_t)(now_ms - c->t_ms) >= window_ms)) {
c->stable = lvl;
return 1U;
}
return 0U;
}
/* ======================== 双区快照 ======================== */
uint8_t ioboard_di_snap_publish(ioboard_di_snapshot_t *s, uint8_t mask, uint8_t valid,
uint8_t is_fail)
{
uint8_t changed;
uint8_t was_valid;
if (di_is_null(s) != 0U) {
return 0U;
}
/* 先递增成奇数 = "正在写";数据写完再递增成偶数 = "可读" */
s->seq++;
was_valid = s->valid;
changed = 0U;
if (s->change_seq == 0U) {
/* 第一次发布:视为一次变化(让上位机区分"还没有值"与"已建立基线") */
changed = 1U;
} else if (s->mask != mask) {
changed = 1U;
}
/* 读失败**不自行写 0**:mask 就是调用方传进来的值(失败拍传的是上一有效值) */
s->mask = mask;
s->valid = (valid != 0U) ? 1U : 0U;
if (is_fail == 0U) {
if (s->fail_count < (int32_t)IOBOARD_DI_FAIL_COUNT_CAP) {
s->fail_count++;
}
} else {
/* 任何一次成功读都说明"当前这一拍读到了":计数从 0 重新累计,
* 表示**连续**失败拍数。不归零的话,一次偶发失败会让计数永久停在上界,
* 之后真正的断线再也看不出来(饱和计数只拦"长时间连续断线")。 */
s->fail_count = 0;
}
/* 有效 → 失效 的下降沿记一次故障次数(恢复沿不改 fail_edges,靠 valid 回落体现) */
if ((was_valid != 0U) && (s->valid == 0U)) {
s->fail_edges++;
}
if (changed != 0U) {
s->change_seq++;
}
s->seq++;
return changed;
}
uint8_t ioboard_di_snap_read(const ioboard_di_snapshot_t *s, uint8_t *out_mask,
uint32_t *out_seq)
{
uint32_t s1;
uint32_t s2;
uint8_t n;
if (di_is_null(s) != 0U) {
if (out_mask != 0) {
*out_mask = 0U;
}
if (out_seq != 0) {
*out_seq = 0U;
}
return 0U;
}
/* 一次读取两遍并校验序号:读期间若被写者打断,序号会变化或为奇数 → 作废重来 */
for (n = 0U; n < (uint8_t)IOBOARD_DI_SNAP_RETRY; n++) {
s1 = s->seq;
if ((s1 & 1U) != 0U) {
continue; /* 写者正在写 */
}
if (out_mask != 0) {
*out_mask = s->mask;
}
if (out_seq != 0) {
*out_seq = s->change_seq;
}
s2 = s->seq;
if ((s1 == s2) && ((s2 & 1U) == 0U)) {
return (s->valid != 0U) ? 1U : 0U;
}
}
/* 连续被打断 20 次:本次不给值(调用方按"无新数据"处理,绝不拿半新半旧的东西) */
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) {
return;
}
s->seq = 0U;
s->mask = 0U;
s->valid = 0U;
s->fail_count = 0;
s->fail_edges = 0U;
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)) {
return;
}
out->seq = s->seq;
out->mask = s->mask;
out->valid = s->valid;
out->fail_count = s->fail_count;
out->fail_edges = s->fail_edges;
out->change_seq = s->change_seq;
}
void ioboard_di_snap_faults(const ioboard_di_snapshot_t *s, uint32_t *out_edges,
int32_t *out_fails)
{
if (di_is_null(s) != 0U) {
if (out_edges != 0) {
*out_edges = 0U;
}
if (out_fails != 0) {
*out_fails = 0;
}
return;
}
if (out_edges != 0) {
*out_edges = s->fail_edges;
}
if (out_fails != 0) {
*out_fails = s->fail_count;
}
}
/* ======================== 注册式共享读口 ======================== */
/*
* 已登记的快照对象;NULL = 尚未登记。编译期零初始化,**没有初始化函数**——
* 于是不存在"谁必须先跑"的启动顺序依赖(见头文件函数说明三)。
* volatile 的理由见头文件函数说明四:跨任务传地址,读者侧不得被编译器缓存。
* 占用后永不改变(register 只允许同一指针重复登记),所以读者读它不需要任何保护:
* 要么读到 NULL(无写者),要么读到一个此后终身有效的地址。
*/
static const ioboard_di_snapshot_t *volatile s_di_snap_registered = 0;
/*
* 函数功能:写者登记它的快照对象(只存指针,不复制、不改写内容)
* 入口参数:s - 由本登记者独占写入的快照对象(s == 0 = 参数非法)
* 返回值:0 = 登记成功 / 重复登记同一指针(幂等);-1 = 参数非法或已被另一指针占用
* 限定条件:单写者;先登记再发布(语义全文见 ioboard_di.h 的同名声明)
* 函数说明:占用后不可变——首个指针即唯一真相源,第二个不同指针一律拒绝并保留首个。
*/
int ioboard_di_snap_register(const ioboard_di_snapshot_t *s)
{
if (di_is_null(s) != 0U) {
return -1;
}
/* 首个登记=占用。重复登记必须是**同一个**指针(幂等),否则拒绝并保留首个:
* 两个快照对象并存就是两份真相,读者拿到哪一份取决于调度顺序,不可接受。 */
if (s_di_snap_registered == 0) {
s_di_snap_registered = s;
return 0;
}
if (s_di_snap_registered == s) {
return 0;
}
return -1;
}
/*
* 函数功能:读者取已登记的快照对象
* 入口参数:无
* 返回值:已登记的快照指针;未登记 = NULL(消费者按"无数据源"处理,不是全 0)
* 限定条件:任意上下文、无锁、不阻塞、不关中断
* 函数说明:拿到指针后必须再走 ioboard_di_snap_read() 取一致值,不要直接读字段。
*/
const ioboard_di_snapshot_t *ioboard_di_snap_lookup(void)
{
return s_di_snap_registered;
}