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 根钩子全通过。
This commit is contained in:
2026-11-16 18:30:31 +08:00
parent d9f8dbfd90
commit fd767d1dcd
35 changed files with 3646 additions and 249 deletions
+132
View File
@@ -69,6 +69,8 @@
#include "wave_ring.h" /* 录波环消费侧:sealed/sealed_meta/read_cb/write_done(task-2) */
#include "wave_store.h" /* 段打包游标 + 段号轮转纯函数(落盘道本体,task-2) */
#include "task_handles.h" /* 任务句柄与属性块的引用契约(定义处仍是 Src/freertos.c) */
#include "ioboard.h" /* 开入开出板 BSP(硬件动起来并如实汇报) */
#include "ioboard_di.h" /* 开入去抖 + 双区快照(纯逻辑,主机侧同一份源码被单测覆盖) */
/* Private defines -----------------------------------------------------------*/
/* 栈水位观测节奏:首次报告须晚于 bring-up 深链(mount/mkfs/探针/cfg/syslog),
@@ -119,6 +121,29 @@ static const stack_probe_task_t s_stack_probe[] = {
static void stack_probe_poll(void);
#if !defined(TEST_SUITE_STORAGE)
static void default_task_net_cfg_save_notify(void);
static uint8_t default_task_di_poll(void);
/* 周期性发布者的编译期开关:两个测试套件构建都禁用本任务的发布(见 poll 函数的说明四) */
#if defined(TEST_SUITE_CH395F) || defined(TEST_SUITE_GDRAM)
#define DEFAULT_TASK_DI_PUBLISH_EN 0
#else
#define DEFAULT_TASK_DI_PUBLISH_EN 1
#endif
/*
* 开入(DI)采集状态,**文件作用域静态零初始化**(不占任务栈、不走堆):
* s_di_ch - 8 个通道的去抖状态机(App/util/ioboard_di.c)
* s_di_snap - 双区快照(消费者无锁读,见 ioboard_di.h)
* s_di_pub_mask - 最近一次**成功**读到的去抖后 mask;读失败时原样再发布,
* 这就是"失败不得当全 0 上报"在本任务侧的落点
* s_di_fail_edges_seen - 已写入日志的故障下降沿计数("每个 episode 只记一条")
* 为什么是文件作用域而不是任务内 static:poll 函数在任务函数之外定义,
* C99 里函数内 static 无法被别处看见;放文件作用域还让"唯一写者"更显眼。
*/
static ioboard_di_ch_t s_di_ch[IOBOARD_DI_CH_NUM];
static ioboard_di_snapshot_t s_di_snap;
static uint8_t s_di_pub_mask;
static uint32_t s_di_fail_edges_seen;
static FRESULT storage_bring_up(FATFS *fs);
static void wave_store_drain(void);
#endif
@@ -189,6 +214,16 @@ void default_task_func(void *argument) {
uint32_t cfg_poll_cnt = 0u;
uint32_t led_tick = HAL_GetTick();
/* 周期性发布者的编译期开关:两个套件都禁用本任务的发布(见下方 poll 函数的说明) */
#if defined(TEST_SUITE_CH395F) || defined(TEST_SUITE_GDRAM)
#define DEFAULT_TASK_DI_PUBLISH_EN 0
#else
#define DEFAULT_TASK_DI_PUBLISH_EN 1
#endif
/* 开入第一次读取放在 bring-up 之后:此刻 MX_GPIO_Init 早已配好引脚(模块初始化期),
* 且看门狗尚未启动,几十微秒的移位读不会影响任何节拍。 */
(void)default_task_di_poll();
/* 注册控制台写者:本任务此后是串口唯一发送者(其余任务只写环形缓冲)。
* 见 App/log/console_log.c "控制台单写者日志"——消除并发写造成的日志逐字符交错,
* 并让脏指针无法再进入 HAL_UART_Transmit 的缓冲遍历。 */
@@ -305,6 +340,11 @@ void default_task_func(void *argument) {
cfg_file_poll();
#endif
}
/* 开入采集(8 路 74HC165):读、去抖、发布快照。**不单独占喂狗段**
* (见函数说明:单次裸读上界见 IOBOARD_DI_READ_MAX_US,去抖是纯比较,无需新增段号)。 */
task_prof_enter(TASK_PROF_DEF_DI);
(void)default_task_di_poll();
task_prof_exit(TASK_PROF_DEF_DI);
/* LED 心跳:500ms 翻转一次(与旧 500ms 循环节奏等效;循环基准改 50ms 后
* 不能再每轮翻转,否则变成 10Hz 闪烁) */
task_wd_seg(TASK_WD_SEG_LED);
@@ -887,3 +927,95 @@ static void default_task_net_cfg_save_notify(void) {
}
}
#endif
/*
* 函数功能:开入(8 路 74HC165)采样一拍——读、逐通道去抖、发布快照
* 入口参数:无
* 返回值:1 = 本拍成功并发布了有效快照;0 = 本拍读失败
* 限定条件:仅 defaultTask 调用(启动期一次 + 主循环每轮一次;**唯一写者**)
* 函数说明:
*
* 一、【节拍与去抖粒度 —— 必须讲清楚,别让人误以为真能 20 ms】
* 本函数挂在 defaultTask 的 50 ms 基准拍上(osEventFlagsWait(..., 50u) 的兜底,
* 无事件时一轮 = 50 ms;有事件时一轮更短)。因此**一个轮询周期只喂一拍**,
* 20 ms 去抖窗口的实际粒度是 **50 ms 而不是 20 ms**。
* 这与设计目标一致(开关量与继电器辅助触点的变位时标以"秒"计,50 ms 远够),
* 代价是单次变位的上报时延最坏约"一拍轮询 + 一个窗口"≈ 100 ms。
* 想要真 20 ms 需另建硬件定时器中断,那要动 RAM/任务预算,本次**不做**。
* 有事件唤醒时一轮会更短(>= 若干 ms),此时去抖精度随之细化 —— 只会更准,不会更差。
*
* 二、【耗时与喂狗段】
* 单次 ioboard_di_read() 上界见 ioboard.h 的 IOBOARD_DI_READ_MAX_US
* (装载 + 8 拍,每拍两相各 1 us;全程在临界区内关中断)。
* **不要在这个函数里硬写数字**:该宏是驱动的时序规格唯一出处,驱动改时序时
* 这里必须跟着改就说明注释写错了——用宏名。
* 以当前值(26 us)计:对 50 ms 一拍是 0.05%,且远小于任何中断的响应预算,故:
* · **不新增 task_wd_seg 段号**(段号是复位取证用的契约,为几十 µs 加一个段
* 只会稀释 PREVRUN 的信息量,且 enum 是新契约、要对齐文档);
* · 只加一个 task_prof 探针,把"它到底多久"变成可观测值(见 task_prof.h)。
* 临界区长度已由驱动负责(其注释写明"时序内不含任何可能阻塞的调用")。
*
* 三、【失败语义:读失败绝不当全 0 上报】
* 读失败时:不更新 s_di_ch(不喂去抖 → 候选值与计时全长不动),
* **用上一有效值 s_di_pub_mask 再次发布**,valid 置 0,并累加失败拍数。
* 于是消费者看到的是"mask 还是旧的 + valid = 0",而不是一个新鲜的全 0 ——
* 后者在现场会被读成"开入全部复归",是最危险的假信息。
* 恢复:第一拍成功读即整组重新确立去抖基准(ioboard_di_ch_reset + 喂一拍),
* 避免把"故障期间积累的旧计时"当成合法窗口。
*
* 四、【故障留痕】
* 有效性下降沿(有效 → 失效)各落一条 run.log。判据用 fail_edges 的**边沿**
* 而不是失败计数,保证一个故障 episode 只记一条(与 task_wd_poll 的位图边沿同款)。
* 写日志点放在本函数内而非 ioboard_di.c:纯逻辑层不碰文件系统。
* 且只在 !TEST_SUITE_CH395F && !TEST_SUITE_GDRAM 时发布 —— 那两个套件构建下
* 卷由 testTask 独占(与 TEST_SUITE_STORAGE 同款理由),defaultTask 侧只读不算不写盘。
*/
static uint8_t default_task_di_poll(void) {
uint8_t mask = 0u;
uint8_t rc = 0u;
uint8_t i;
uint32_t now = HAL_GetTick();
uint32_t edges = 0u;
int32_t fails = 0;
#if (DEFAULT_TASK_DI_PUBLISH_EN == 0)
/* 测试套件构建:卷上写者不是本任务,本函数不发布也不写日志(见函数说明四) */
(void)mask; (void)rc; (void)i; (void)now; (void)edges; (void)fails;
return 0u;
#else
if (ioboard_di_read(&mask) == BSP_OK) {
/* 成功:第一拍(或刚从故障恢复)先整组重新确立基准,再喂本拍 */
if (s_di_snap.valid == 0u) {
ioboard_di_ch_reset(s_di_ch, (uint8_t)IOBOARD_DI_CH_NUM, now);
}
for (i = 0u; i < (uint8_t)IOBOARD_DI_CH_NUM; i++) {
uint8_t lvl = (uint8_t)((mask >> i) & 1u);
(void)ioboard_di_ch_feed(&s_di_ch[i], lvl, now, IOBOARD_DI_DEBOUNCE_MS);
}
/* 用**去抖后**的稳定值重新组合发布值(原始 mask 只用一次,不等抖就上报) */
mask = 0u;
for (i = 0u; i < (uint8_t)IOBOARD_DI_CH_NUM; i++) {
if (s_di_ch[i].stable != 0u) {
mask = (uint8_t)(mask | (uint8_t)(1u << i));
}
}
s_di_pub_mask = mask;
(void)ioboard_di_snap_publish(&s_di_snap, mask, 1u, 1u);
rc = 1u;
} else {
/* 失败:不喂去抖、不写 mask,只把"旧值 + 无效"发布出去 */
(void)ioboard_di_snap_publish(&s_di_snap, s_di_pub_mask, 0u, 0u);
rc = 0u;
}
/* 故障下降沿留痕(每个 episode 一条;recovers 由下一拍的有效发布体现) */
ioboard_di_snap_faults(&s_di_snap, &edges, &fails);
if (edges != s_di_fail_edges_seen) {
s_di_fail_edges_seen = edges;
syslog_post(SYSLOG_SELFTEST, "di read fault");
}
return rc;
#endif
}
+217
View File
@@ -0,0 +1,217 @@
/*
* 模块名称:开入(DI)去抖与快照——纯逻辑实现(本模块可主机侧测试的那一半)
* 模块功能:ioboard_di.h 全部纯函数。零 HAL、零 FreeRTOS、零全局可变状态,
* MCU(ARMCC C99)与主机侧 MSVC 编译**同一份源码**。
* 适用平台:任何 C99
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建
*/
#include "ioboard_di.h"
/* 空指针统一按 "0" 处理:本层是纯逻辑,不为防御性检查引入错误码;
* 调用方(defaultTask)传的都是静态对象地址,NULL 只可能出现在测试里 */
static uint8_t di_is_null(const void *p)
{
return (p == 0) ? 1U : 0U;
}
/* ======================== 通道去抖 ======================== */
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;
}
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;
}
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;
}
}
+180
View File
@@ -0,0 +1,180 @@
/*
* 模块名称:开入(DI)去抖与快照——纯逻辑层
* 模块功能:把「每拍读一次 8 路开入」拆成两个与硬件无关的部件——
* ① 通道去抖:每个通道独立计时,电平连续稳定满 DI_DEBOUNCE_WINDOW_MS 才翻转;
* ② 双区快照:消费者拿到的 mask 与 seq 永远来自同一份已稳定的副本。
* 读引脚在 App/util/ioboard_di.c 的 .c 部分(本 .c 就是那一半,属于同一模块的
* 可测部分);本头文件**不 include** HAL / FreeRTOS / ioboard.h / main.h,
* 可被主机侧 MSVC 单测直接编译。
*
* 为什么去抖不放进 ioboard.c:BSP 只回答"让硬件动起来并如实汇报",去抖与
* 失败语义是上报层的事;而且 ioboard.c 依赖 HAL/FreeRTOS,主机侧编不过。
* 为什么不做成通用 di_debounce 工具:去抖的具体语义(20 ms、8 路、失败拍
* 推时间戳)是开入业务的一部分,抽成泛化工具会造出第二个真相源。
* 适用平台:任何 C99(ARMCC v5 / MSVC / GCC);仅 <stdint.h>。
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建
*
* 失败语义(本模块最重要的一条,单测与调用方都依赖它):
* 本项目铁律是「读失败不得把开入当全 0 上报」。本模块的落点有三处:
* · 快照 mask **只**由成功读更新:失败拍喂进去的是"上一有效值",绝不自行产生 0;
* · 但失败拍**照样推进**去抖计时并更新候选值——否则一次跨过整段失败窗口的真实
* 变位会被永久吞掉,104/UI 上看到的仍是旧值且无痕迹;
* · 有效性下降沿 / 恢复沿各记一次(fail_edges / valid),由调用方决定是否留痕;
* 本模块本身不碰文件系统、不依赖 CMSIS,所以能在 PC 上跑。
*/
#ifndef IOBOARD_DI_H
#define IOBOARD_DI_H
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* ======================== 常量 ======================== */
/* 去抖窗口(ms):某通道电平须连续稳定这么久,快照才允许翻转。
* 取 20 ms:现场开关与继电器辅助触点抖动在 5~10 ms 量级,20 ms 是常见两倍余量;
* 且 20 ms < defaultTask 的 50 ms 基准拍(最快两拍后翻转)、
* 远小于 100 ms 喂狗判定,不影响任何既有节拍。 */
#define IOBOARD_DI_DEBOUNCE_MS 20u
/* 开入路数。**刻意不复用 IOBOARD_DI_COUNT**:IOBOARD 头里的 HC165 引脚宏会展开成
* main.h 的符号,一旦被 .c 真正使用就把 MCU 头拉进本纯逻辑单元,主机侧编不过。
* 两者的一致性由主机侧测试在编译期静态断言(test/host/ioboard/ioboard_test.c)。 */
#define IOBOARD_DI_CH_NUM 8u
/* 读失败累计上界:到顶后不再增加,防止长时间断线把 int32 计数绕成负数,
* 让"一直失败"看起来像"从未失败" */
#define IOBOARD_DI_FAIL_COUNT_CAP 0x7FFFFFFFL
/* 读侧重试上限:写者一次发布是十几条指令,正常第二遍必一致;
* 20 次仍不一致 = 被持续抢占,返回 0 让调用方本次不用这个值 */
#define IOBOARD_DI_SNAP_RETRY 20u
/* ======================== 通道去抖 ======================== */
/*
* 单通道去抖状态。结构体公开是为了让调用方放进静态存储(本仓禁用 C 库堆分配)。
* 字段语义(一律走下面的函数读改写,别直接写):
* t_ms - raw 最近一次变化的时刻
* raw - 最近一拍读到的电平(0/1)
* stable - 已确认稳定的电平(就是快照里那一位)
* started - 是否已收到第一拍(0 = 尚未确立)
*/
typedef struct {
uint32_t t_ms;
uint8_t raw;
uint8_t stable;
uint8_t started;
} ioboard_di_ch_t;
/*
* 函数功能:把一组通道复位成"下一拍即整组确立"
* 入口参数:ch - 通道数组
* 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);
/*
* 函数功能:喂一拍采样给单个通道
* 入口参数:c - 通道状态(已复位或已初始化)
* level - 本拍电平(非 0 即 1;传更宽的值也安全)
* now_ms - 本拍时刻(ms,任意起点、允许 32 位回绕)
* window_ms - 去抖窗口(ms;0 = 不滤波,下一拍立即跟随)
* 返回值:1 = 稳定电平在本拍翻转;0 = 未翻转
* 限定条件:相邻两拍间隔须 < 2^32 ms(49 天)——本项目 50 ms 节拍天然满足
* 函数说明:
* 一、首个样本直接确立(否则上电后要空等一个窗口才有开入值)。
* 二、raw 变化 → 记新 raw 与时刻、计时重开始(抖动不断推迟翻转,这就是去抖)。
* 三、raw 未变、已稳定、且 (now - t_ms) **>=** window → stable 跟随 raw。
* 用无符号减法而不是 `now >= t + window`:后者在 tick 回绕附近会错误地
* "永久成立"或"永久不成立"(单测"回绕"一条扫这个窗口)。边界取 >=:满 20 ms 即翻。
*/
uint8_t ioboard_di_ch_feed(ioboard_di_ch_t *c, uint8_t level, uint32_t now_ms,
uint32_t window_ms);
/* ======================== 双区快照 ======================== */
/*
* 快照。**单写者**(run 期 = defaultTask;同一时刻只有一个写者),**多读者**
* (任意上下文、无锁)。读者按"序号偶数且前后一致"取一致值;写者按"奇-写-偶"发布。
*/
typedef struct {
volatile uint32_t seq; /* 偶数 = 稳定;奇数 = 正在写 */
volatile uint8_t mask; /* 去抖后的 8 路开入(bit0 = A … bit7 = H) */
volatile uint8_t valid; /* 1 = 至少成功读过一次、且当前不在失败态 */
volatile int32_t fail_count; /* **连续**读失败拍数(成功一拍即归零;饱和于 CAP) */
volatile uint32_t fail_edges; /* 有效 → 失效 的下降沿次数(= 故障次数) */
volatile uint32_t change_seq; /* 去抖后 mask 翻转次数 */
} ioboard_di_snapshot_t;
/*
* 函数功能:写者发布一拍
* 入口参数:s - 快照对象
* mask - 本拍去抖结果(读失败时**必须**传上一有效值)
* valid - 本拍之后是否有效(0/1)
* is_fail - 本拍是否读失败(0 = 失败;非 0 = 成功)
* 返回值:去抖后 mask 相对上一拍是否翻转(1 = 翻转,change_seq 已加一)
* 限定条件:单写者;不加锁;可在临界区内调用
* 函数说明:第一次发布(change_seq == 0)也返回 1,让上位机区分"还没有任何值"与
* "已建立基线"。本函数**从不自行生成 0**:mask 就是调用方传进来的值,
* 失败拍传的是上一有效值——这就是"失败不当全 0"的落点。
*/
uint8_t ioboard_di_snap_publish(ioboard_di_snapshot_t *s, uint8_t mask, uint8_t valid,
uint8_t is_fail);
/*
* 函数功能:读者取一致的一组值
* 入口参数:s - 快照对象
* out_mask - 输出,去抖后开入(可为 NULL)
* out_seq - 输出,change_seq(可为 NULL)
* 返回值:1 = 读到一致且有效的快照;0 = 快照尚无效 / 读取期间持续被打断
* 限定条件:任意上下文、无锁、不阻塞
* 函数说明:返回 0 时 out_mask 仍被写为"最近一次发布值",但**不得**当新数据用——
* 消费者按"本次无新数据"处理(保留自己上一次保存的值)。
*/
uint8_t ioboard_di_snap_read(const ioboard_di_snapshot_t *s, uint8_t *out_mask,
uint32_t *out_seq);
/*
* 函数功能:把快照清成"从未成功读过"的初始态
* 入口参数:s - 快照对象
* 返回值:无
* 限定条件:单写者(初始化期 / 尚无读者)
* 函数说明:全字段清零。**mask = 0 此时不表示"开入全 0"**——消费者必须看 valid 与
* change_seq。
*/
void ioboard_di_snap_reset(ioboard_di_snapshot_t *s);
/* 诊断副本:不保证一致性,仅供自检/串口打印 */
void ioboard_di_snap_copy(const ioboard_di_snapshot_t *s, ioboard_di_snapshot_t *out);
/*
* 函数功能:读"有效 → 失效 下降沿"累计次数与"连续失败拍数"
* 入口参数:s - 快照对象
* out_edges - 输出,fail_edges(可为 NULL)
* out_fails - 输出,fail_count(可为 NULL)
* 返回值:无
* 限定条件:任意上下文;单字读,值可能来自相邻两拍(诊断用途够用)
* 函数说明:调用方(defaultTask)用它把"开入读失败"这一事实经 syslog 留痕——
* 本模块自己不碰文件系统,留痕点只有调用方知道该写哪个日志、写多频。
*/
void ioboard_di_snap_faults(const ioboard_di_snapshot_t *s, uint32_t *out_edges,
int32_t *out_fails);
#ifdef __cplusplus
}
#endif
#endif /* IOBOARD_DI_H */
+4 -2
View File
@@ -107,6 +107,7 @@ static void prof_send(int n, uint32_t raw) {
* uiw/uis/uisn uiTask 单轮工作最坏 / 推流往返最坏 / 仍在推流段内(us)
* adc/adcm/adcn adcTask 单拍次数 / 单拍最坏 / 仍在拍内(us)
* [PROF2] defd/defs defaultTask 控制台排空最坏 / syslog 落盘最坏(us)
* defi defaultTask 开入采样一拍最坏(读 + 去抖 + 发布,us)
* netp/netn netTask 驱动轮询最坏 / 仍在轮询内(us)
* adcp/adcq adcTask ADC 单次最坏 / 仍在 ADC 内(us)
* 两行的 gl 丢弃样本数(DWT 不可用或计数器被重置)
@@ -162,13 +163,14 @@ static void prof_emit(uint32_t raw) {
(unsigned long)gl);
prof_send(n, raw);
/* 行 2:段级(占用者指认:defaultTask 排空/落盘、netTask 驱动、adcTask ADC) */
/* 行 2:段级(占用者指认:defaultTask 排空/落盘/开入、netTask 驱动、adcTask ADC) */
n = snprintf(s_prof_line, sizeof(s_prof_line),
"[PROF2] t=%lu defd=%lu defs=%lu netp=%lu netn=%lu adcp=%lu "
"[PROF2] t=%lu defd=%lu defs=%lu defi=%lu netp=%lu netn=%lu adcp=%lu "
"adcq=%lu gl=%lu\r\n",
(unsigned long)t,
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_DEF_DRAIN].max),
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_DEF_SYSLOG].max),
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_DEF_DI].max),
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_NET_POLL].max),
(unsigned long)prof_cyc_to_us(netn),
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_ADC_POLL].max),
+2
View File
@@ -33,6 +33,7 @@
* ADC_POLL adcTask adc_input_poll() 单次(enter/exit)——隔离 ADC 超时成本
* DEF_DRAIN defaultTask dbg_console_drain()(enter/exit)——控制台忙等发送
* DEF_SYSLOG defaultTask syslog_drain()(enter/exit)——NAND/FTL 写
* DEF_DI defaultTask 开入采样一拍(默认Task,任务级 max)——开入读+去抖+发布
* NET_POLL netTask net_poll()(enter/exit)——CH395F 驱动轮询
*
* 后四个探针用于**指认占用者**:UI 心跳缺席时,谁的最坏耗时在同一窗口抬起来,
@@ -58,6 +59,7 @@ typedef enum {
TASK_PROF_DEF_DRAIN = 5, /* defaultTask 控制台排空耗时 */
TASK_PROF_DEF_SYSLOG = 6, /* defaultTask syslog 落盘耗时 */
TASK_PROF_NET_POLL = 7, /* netTask net_poll() 耗时(CH395F 驱动) */
TASK_PROF_DEF_DI = 8, /* defaultTask 开入采样一拍(读 + 去抖 + 发布) */
TASK_PROF_ID_COUNT
} task_prof_id_t;