feat(wave): 故障录波数据面、接线与单通道回放页(软件闭环交付)

数据面(App/algo,纯逻辑,双端编译)
- wave_ring:8 路 × 320 点列优先环(1 kHz,预触发 160 + 后触发 160),adcTask
  唯一写者;触发/冻结/封存/冷却四态,冻结持续到落盘回执才解冻,滞留 2 s 自弃
  兜底——下一次真故障无波可录比丢一段更贵
- wave_store:段头编解码 + 拉模式打包游标 + 自带无表位运算 CRC-16/MODBUS(带
  锚点自检)+ 段名与整段长度等式;格式不依赖平台类型宽度
- 段头只存原始码值与封存瞬间生效系数,工程量只当单位标签、不进任何算式
- 三套主机单测(环 113 / 编解码 170 / 触发状态机 110),全部无桩、生产源原样
  纳入;新文件补 stddef 是 ARMCC 与主机差异,主机侧照不出这条分叉
- test/host/wave_read.py 是按 §6.2 的独立第二实现(dump/fft/shape/plot),92 条
  自洽断言;三份合成段互读双校验全过、哈希钉死,格式面双向闭合
- 三套新单测不加专属钩子,由覆盖率总闸全量真跑(沿用既有裁定)

接线(任务层)
- adc_cal:新增生效系数的 32 位定点原值入口(与既有浮点入口共用生效视图),
  段头按最低有效位精确记账,不经浮点回算
- adcTask:每拍压 8 路语义原始码值并推进状态机,封存那一拍同拍交棒封存瞬间事实;
  台架定周期自抓走双层编译门,产品镜像里零存在;串口新增一条 wave: 周期行
- defaultTask:卷空闲后一次心跳整段搬完(try 锁 + 256 字节分片 + 一次完整开档到
  关档),成败都回执;失败先删半成品再计错,段号只在成功时推进;持锁超 50 ms
  补一条告警并记历史峰值(喂狗余量可核)
- Lead 复核补第四道并发陷阱:采集任务优先级高于落盘道,搬段中途它可能正好把滞留
  超时的本段自弃、甚至封出下一段——数据区校验和是对「实际读到的字节」算的,
  半新半旧的段照样自洽,故关档后复检环侧身份判废:删文件、不补账、段号不推进
- Lead 复核抓到触发挂号不是原子操作(旧实现分三个字节写,消费者可在窗口里读到
  上一段的触发源与元件号):已把载荷压进一个字节,越界当场拒且不记任何计数;
  段文件字节布局零改动,三份合成段哈希逐字节不变
- protectTask:保护启动上升沿同点请求录波,一拍一次、元件号取最低位;判据本体
  零改动

人机(160×160 单色屏)
- 菜单树节点 26「手动录波」绑页面 + 记录查询组末新增「录波回放」叶,重跑生成器
  得 43 节点 / 34 叶 / 30 已绑,页面映射 28 → 30
- 回放页一屏一路、触发点前后各一周波共 40 点、每点 3 像素阶梯线(只用水平与
  垂直两种线段——单色屏斜线会被阈值裁掉);零点虚线、触发光标、窗口峰值、
  单位徽标与形状受限徽标;空态与坏段各一句显式文案,绝不用半截波形冒充数据
- ui_data 新增录波注入通道(六件操作表、三态返回);执行侧胶水带段头缓存、
  手动请求后连缓存一起作废、逐点走全仓唯一的码值换算入口
- 模拟器接真实环与编解码合成两段(含坏段与空态旗标),6 张新黄金参考,既有
  60 张逐字节零漂移未用更新模式;字库 218 → 224 字 / 319 字形
- 两份图形配置里图表组件仍为关;零堆分配;页面池水位不变
- 回放读路径的 uiTask 阻塞上界按实码写清:一次渲染 = 段表刷新 + 未缓存段头最坏
  22 次小读;已验段只剩一次开窗读 + 40 点解码;无实测数不编,实测归台架、
  仪器用已在跑的单轮工作耗时探针,不新加埋点

台账与文档
- 内存台账:录波环与落盘/回放静态逐条入册,三档对照 81,536 → 88,296 → 89,936
  字节(62.2% → 68.6%),累计 +8,400;预估 5.9 KB 与实测 +6,760 的差额点名;
  散列文件头注释同步;任务栈表核对后无需抬栈;体积趋势行与同码凭证由权威构建
  重打(0 错误 0 警告,四项体积与上一轮相同——本轮改动只有注释与声明位置)
- 设计说明:§5 补第四条并发陷阱;§6.3 定字段口径(两份独立实现的共同依据);
  §7 回填实测;§9 周期行写实;§10 台架判据改两段式且不比绝对相位;§12 补读路径
  风险行;抬头状态改成「代码面已交付、未做完的只有板级那一轮」
- 卡片:软件闭环一栏列证据;台架三条按用户裁定保持未完成,不做虚假销项
- 口径同步:数据可信、UI 补齐、页面补齐规划、产品需求、采集短板评测、任务规划
  索引与两份 README;陈旧现状句清扫 16 处(带日期戳的历史取数行一律不动)
- 门禁说明:nested-comment 记仓库根探测必须兼容 linked worktree 的 gitdir 文件
  形态(修前该钩子在任务树里恒报环境错、静默不可用);coding-standard 记
  「函数头注释超过 24 行就把函数功能挤出回看窗口」这条机制与本次现场
- 覆盖率基线登记两个新覆盖模块(套件 41 → 44 套);环单测重打后该文件有效行
  227 → 226、覆盖行 226 → 225,比率仍 99.6%,是分母变小不是覆盖率回退

为什么是单一提交:文档链接、双端注册、生成器幂等(菜单与字库)、内存数字与
体积事实源、编号门禁这五道整仓门禁要求代码、页面、菜单树、字库、文档与台账
同处一个提交才自洽,按数据面/接线/人机/台账拆成四笔必然红其中至少四道

编号门禁新增行 14 处命中已按语义改写:魔数常量按字符命名、段名样例改由格式串
生成、频谱表头改 f / 2x / 5x 并加一行图例;改写后自洽断言 92 条仍全过
This commit is contained in:
2026-10-29 19:23:15 +08:00
parent 325abe4337
commit d64bbdc57f
81 changed files with 8868 additions and 424 deletions
+269
View File
@@ -26,6 +26,18 @@
* v1.3 2026-10-25 DTU 项目组 写回缓存空闲 flush 接线:主循环 syslog 排空
* 之后调 vol_idle_sync_poll()(卷空闲周期 CTRL_SYNC 兜底,
* 模块 = App/fs/vol_idle_sync.[ch],道F 批 2)
* v1.4 2026-10-29 DTU 项目组 故障录波落盘道(task-2):vol_idle_sync_poll 之后
* 新增 wave_store_drain()——一次心跳整段搬完(lead 裁③:
* 一次 try 锁内 pack_next 256 B 分片 + 完整 open...close),
* 持锁耗时 >50 ms 补一条 WARN、峰值 ms 记本层静态;
* 轮转号自持(启动扫 /wave 重建,成功 ACK 才推进,lead 裁(b));
* 失败 = 先 unlink 半成品再 write_done(-1)(lead 裁①);
* 卷未就绪 / 环未封存静默跳过(§5.1 所有权 + §9 一条线约束)
* v1.5 2026-10-29 DTU 项目组 Lead 复核补第四道并发陷阱(本道与 adcTask 的抢占窗):
* 搬段中途 adcTask 可能正好走到 SEALED 滞留自弃(2 s)甚至
* 已封出下一段——CRC 是对"读到的字节"算的,半新半旧的段照样
* 自洽,只能靠写完关档后复检环侧身份(握手量 + 段首 t0/帧序)
* 判废:判废即 unlink、不 ACK、号不推进,失败按既有单条留痕
*/
#include "default_task.h"
@@ -53,6 +65,8 @@
#include "task_prof.h" /* 各任务最坏耗时上报 */
#include "vol_lock.h"
#include "vol_idle_sync.h" /* 写回缓存空闲 flush 兜底(App/fs/vol_idle_sync.h) */
#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) */
/* Private defines -----------------------------------------------------------*/
@@ -72,6 +86,14 @@
* (自检已上报、卷保留、不重格式化),等下次上电重新 resume */
#define STORAGE_BRINGUP_RETRIES 3u
/* 录波段落盘持锁耗时告警线(lead 裁③i):一次心跳整段 5250 B(约 21 次 256 B
* f_write),设计 §4.2 预估落盘窗「几十 ms」;越过本线说明本段在占用 defaultTask
* 喂狗链前的最慢一段,按事件补一条 WARN(不是周期行),并把历史峰值留在本层
* 静态里供收工报告核喂狗余量(vol_lock.h 铁律「等锁即毁喂狗链」的前例在案) */
#define WAVE_DRAIN_HELD_WARN_MS 50u
/* 搬运缓冲(§7 的 256 B;wave_store_pack_next 头阶段要求 cap >= 128,lead 转告(d)) */
#define WAVE_DRAIN_CHUNK_B 256u
/* Private typedef -------------------------------------------------------------*/
typedef struct {
const char *p_name;
@@ -97,6 +119,7 @@ static void stack_probe_poll(void);
#if !defined(TEST_SUITE_STORAGE)
static void default_task_net_cfg_save_notify(void);
static FRESULT storage_bring_up(FATFS *fs);
static void wave_store_drain(void);
#endif
/*
@@ -301,6 +324,10 @@ void default_task_func(void *argument) {
* 一次 f_close 同型的同步段。放在 drain 之后:本拍若写过日志,close
* 已同步过,这里随即 clean 短路——漏网脏页的驻留窗由周期封顶 */
vol_idle_sync_poll();
/* 录波段落盘(task-2):卷空闲 + 环已封存才搬,就绪门/try 锁全在函数内;
* 一次心跳最多一段(lead 裁③)。放在 idle sync 之后:本拍若刚写过录波段,
* 下一拍空闲 flush 会兜住残留脏页,语义与 syslog 排空同位 */
wave_store_drain();
#endif
/* 栈水位观测:首次 5s 后报告,此后每 2s 采样、出现更深峰值才打印 */
task_wd_seg(TASK_WD_SEG_STACK);
@@ -565,6 +592,248 @@ static FRESULT storage_bring_up(FATFS *fs) {
}
#endif /* !TEST_SUITE_STORAGE */
/*
* 函数功能:故障录波落盘道——把已封存的 wave_ring 段整段搬进 /wave(task-2)
* 入口参数:无 void
* 返回值:无 void
* 限定条件:仅 defaultTask 主循环调用(vol_idle_sync_poll 之后);内部绝不阻塞——
* try 锁 + 有界段长(5250 B / 256 B ≈ 21 次 f_write,设计 §4.2 预估几十 ms),
* 绝不把喂狗点做成等待态(vol_lock.h 使用约定:defaultTask 一律 try)
* 函数说明:所有权按 docs/子系统设计/故障录波设计说明.md §5.1——环的生产者是
* adcTask,本道是唯一落盘消费者;跨任务握手只认 wave_ring_sealed()。
* 本道承担五条口径:
* ① 打开一律 FA_WRITE|FA_OPEN_APPEND:本移植 FA_OPEN_APPEND 不含 FA_WRITE
* (docs/架构设计/STM32F4-Base存储架构说明.md §10.1 陷阱一),少写位
* f_write 恒 FR_DENIED;
* ② 每次 f_write 比对写回字节数:本移植簇分配失败返 FR_OK+短写无错误码
* (同处陷阱二),短写一律判失败;
* ③ 轮转号由本道自持(lead 转告(b)):ring.seg_idx 只是本 boot 本地计数,
* 盘上权威下标 = 首次持锁扫 /wave 用 wave_store_idx_from_name() 重建
* (取已存在最大号 +1,空目录 = 0,陌生名字不入账),写成功才
* wave_store_next_idx() 推进;失败不推进、重试同号;
* ④ 成败都必须 wave_ring_write_done() ACK——ACK 前环一直冻结;err 账
* 由 ring 的 err_cnt 单点收口(§9),本道不数第二份(ACK 前环已
* 超时自弃的那次例外:skip 掉 ACK,不去补第二笔账);
* ⑤ 锁跨越一次完整 open...close(vol_lock.h 铁律),持锁耗时超
* WAVE_DRAIN_HELD_WARN_MS 按事件补一条 WARN(§9 唯一周期行不在本道),
* 历史峰值 s_wheld_ms_max 供核 defaultTask 喂狗余量(lead 裁③)。
* 失败处置(lead 裁①):开过文件才 unlink 半成品(未开成的失败不动盘,
* 绝不拿未初始化的路径误删旧段);unlink 失败照旧 ACK(-1)——最坏留
* 一个坏段文件,PC 侧被 CRC 判废,不会画成证据。
* 静默跳过(不刷屏):卷未就绪 / 环未封存 / try 锁没到(下轮再来,
* 环侧 2 s 超时自弃是兜底账,本道不为此打日志)。
* (上面五条口径就是本函数功能「把已封存段整段搬进 /wave」的逐条展开,
* 细则出处 docs/子系统设计/故障录波设计说明.md §5.1 与 §10)
*/
static void wave_store_drain(void) {
static FIL s_wfil; /* static:FF_FS_TINY=0 时 FIL ~528 B,
* 绝不上栈(FS_VOL_PROBE 同一理由) */
static uint8_t s_wbuf[WAVE_DRAIN_CHUNK_B];
static wave_pack_ctx_t s_wpack;
static wave_seg_meta_t s_wmeta;
static char s_wpath[WAVE_ST_PATH_MAX];
static DIR s_wdir;
static FILINFO s_wfno;
static uint8_t s_wnext_idx; /* 本道自持的下一个段号 0..99 */
static uint8_t s_wscan_done; /* 1 = 本 boot 已扫过 /wave */
static uint8_t s_wdir_ready; /* 1 = /wave 已建或已存在 */
static uint8_t s_wcrc_state; /* 0 未验 1 过 2 败(败=永久自弃,不烧垃圾段) */
static uint32_t s_wheld_ms_max; /* 持锁搬段历史峰值 ms(收工报告核余量用) */
uint32_t t0_ms;
uint32_t held_ms;
uint32_t written = 0u;
uint32_t len = 0u;
uint32_t iter;
uint8_t opened = 0u;
uint8_t skip_ack = 0u; /* 1 = 环已自行了断本段,本道不 ACK 不补账 */
wave_ring_stat_t wst2; /* 关档后复检环侧身份用(v1.5) */
const char *why = NULL;
FRESULT fr;
UINT bw;
int rc;
/* 就绪门(同 vol_idle_sync_poll 的四级门风格) */
if (sys_evtHandle == NULL) {
return;
}
if ((osEventFlagsGet(sys_evtHandle) & SYS_EVT_STORAGE_READY) == 0u) {
return;
}
/* 封存门:只搬已封存段(唯一跨任务握手量,§5.1) */
if (wave_ring_sealed() == 0u) {
return;
}
/* 空闲门:try 锁;卷被 syslog/配置/FTP 占住 → 本轮放弃,不排队不打日志 */
if (vol_lock_wait(0u) == 0u) {
return;
}
t0_ms = (uint32_t)xTaskGetTickCount();
/* CRC 锚点自检每 boot 一次(落盘前失败 = 整族失败,永久自弃免得白烧写次数) */
if (s_wcrc_state == 0u) {
s_wcrc_state = (wave_store_crc_selftest() == WAVE_ST_OK) ? 1u : 2u;
}
if (s_wcrc_state == 2u) {
why = "crc selftest FAIL";
}
if ((why == NULL) && (s_wdir_ready == 0u)) {
fr = f_mkdir(WAVE_ST_DIR);
if ((fr == FR_OK) || (fr == FR_EXIST)) {
s_wdir_ready = 1u;
} else {
why = "mkdir /wave";
}
}
if ((why == NULL) && (s_wscan_done == 0u)) {
FRESULT rr;
fr = f_opendir(&s_wdir, WAVE_ST_DIR);
if (fr == FR_OK) {
uint8_t found = 0u;
uint8_t mx = 0u;
for (;;) {
uint8_t ix;
rr = f_readdir(&s_wdir, &s_wfno);
if ((rr != FR_OK) || (s_wfno.fname[0] == 0)) {
break;
}
if (wave_store_idx_from_name(s_wfno.fname, &ix) == WAVE_ST_OK) {
if ((found == 0u) || (ix > mx)) {
mx = ix;
}
found = 1u;
}
}
(void)f_closedir(&s_wdir);
if (rr == FR_OK) {
/* max+1 即下一写号;回绕号复用由 PC 侧 t0/frame_seq 对账兜底,
* 目录里没有的事实不去猜更多(陌生名字一律不入账) */
s_wnext_idx = (found != 0u) ? wave_store_next_idx(mx) : 0u;
s_wscan_done = 1u;
} else {
why = "readdir /wave";
}
} else {
why = "opendir /wave";
}
}
if ((why == NULL) && (s_wscan_done != 0u)) {
if (wave_ring_sealed_meta(&s_wmeta) != WAVE_ST_OK) {
/* sealed 检查与此读之间环 2 s 超时自弃(err 已由环计过):
* 本道不 ACK、不补账、不打日志,放锁走人 */
skip_ack = 1u;
}
}
if ((why == NULL) && (skip_ack == 0u)) {
/* lead 转告(e):E_FORMAT/E_SIZE = 坏段头,一律当落盘失败丢段计 err,
* 不当参数错吞掉 */
rc = wave_store_pack_start(&s_wpack, &s_wmeta, wave_ring_read_cb, NULL);
if (rc != WAVE_ST_OK) {
why = "pack_start";
}
}
if ((why == NULL) && (skip_ack == 0u)) {
if (wave_store_seg_path(s_wpath, (uint32_t)sizeof(s_wpath),
s_wnext_idx) <= 0) {
why = "seg_path";
} else {
fr = f_open(&s_wfil, s_wpath, FA_WRITE | FA_OPEN_APPEND);
if (fr != FR_OK) {
why = "f_open";
} else {
opened = 1u;
}
}
}
iter = 0u;
while ((why == NULL) && (opened != 0u)) {
rc = wave_store_pack_next(&s_wpack, s_wbuf,
(uint32_t)sizeof(s_wbuf), &len);
if ((rc != WAVE_ST_OK) && (rc != WAVE_ST_DONE)) {
why = "pack_next";
break;
}
if (len != 0u) {
bw = 0u;
fr = f_write(&s_wfil, s_wbuf, (UINT)len, &bw);
if ((fr != FR_OK) || (bw != (UINT)len)) {
why = "f_write short"; /* ②:FR_OK+短写 = 本移植独有失败形态 */
break;
}
written += len;
}
if (rc == WAVE_ST_DONE) {
break;
}
if (++iter > 32u) { /* 5250/256 = 21 片;游标卡死时的有界保险 */
why = "pack stall";
break;
}
}
if (opened != 0u) {
fr = f_close(&s_wfil);
if ((why == NULL) && (skip_ack == 0u) && (fr != FR_OK)) {
why = "f_close";
}
}
if ((why == NULL) && (skip_ack == 0u) && (opened != 0u)) {
if (written != wave_store_pack_total(&s_wpack)) {
why = "len mismatch"; /* 长度等式(§6.3):半截文件骗不过这条 */
}
}
/* v1.5(lead 复核):adcTask 优先级高于本道,搬段中途它可能正好把滞留 2 s 的本段
* 自弃(甚至已经封出下一段)。数据区的 CRC 是对"本道读到的字节"算的,半新半旧的
* 段一样自洽 → 关档后必须复检:握手量没了、或段首身份不是本段,一律判废。
* 判废走既有失败路:unlink 本道开过的文件 + write_done(-1)(此时多半回 E_STATE,
* 环侧的 err 已由自弃计过,这里不重复补账)+ 段号不推进(同号重写覆盖)。 */
if ((why == NULL) && (skip_ack == 0u)) {
if ((wave_ring_sealed() == 0u) || (wave_ring_get_stat(&wst2) != WAVE_ST_OK)
|| (wst2.last_t0_ms != s_wmeta.t0_ms) || (wst2.last_seq != s_wmeta.frame_seq)) {
why = "ring abandoned";
}
}
if (skip_ack == 0u) {
/* 失败留痕边沿锁存(搬进本块,lead 裁方案 A):
* ① 它是 static,初值只在编译期发生一次、不是每次进块重置;
* ② 它是"上一拍是否处于失败态"的边沿锁存,所以必须跨调用存活;
* ③ 单独放这里而不在函数入口那 12 连排台账里,因为 variableScope
* 检查要求把局部量收进真正覆盖全部使用点的最小块(本仓刻意开了 style)。 */
static uint8_t s_wfail_latch; /* 一个 episode 只留一条痕 */
if (why == NULL) {
(void)wave_ring_write_done(0);
s_wnext_idx = wave_store_next_idx(s_wnext_idx); /* 成功才推进(转告(b)) */
s_wfail_latch = 0u;
} else {
if (opened != 0u) {
(void)f_unlink(s_wpath); /* 只清本道开过的文件;unlink 失败照旧 ACK */
}
(void)wave_ring_write_done(-1);
if (s_wfail_latch == 0u) {
s_wfail_latch = 1u; /* 持续失败不刷屏;成功一次重新武装 */
DBG_ERROR("[WAVE] seg drop: %s (idx=%u written=%lu)", why,
(unsigned)s_wnext_idx, (unsigned long)written);
}
}
}
/* 持锁耗时台账(lead 裁③i/ii):超线按事件补一条 WARN(原先这里静默占锁,
* 就是「等锁即毁喂狗链」前例的同族黑洞);峰值进静态供收工报告 */
held_ms = (uint32_t)xTaskGetTickCount() - t0_ms;
if (held_ms > s_wheld_ms_max) {
s_wheld_ms_max = held_ms;
}
if ((skip_ack == 0u) && (held_ms > (uint32_t)WAVE_DRAIN_HELD_WARN_MS)) {
/* 本仓 dbg_log 无 WARN 级(宏只有 ERROR/INFO/DEBUG,ERR 级自动带 [ERR] = @test
* 禁用标记):[WARN] 按 console_log.c 先例进正文,慢不是错(真失败另有 seg drop) */
DBG_INFO("[WAVE][WARN] seg held %lu ms (idx=%u)",
(unsigned long)held_ms, (unsigned)s_wnext_idx);
}
vol_lock_release(); /* 成败/跳过都放锁:锁泄漏比丢一段录波重一百倍 */
}
/*
* 函数功能:"保存网络配置"请求通知(注册给 net_cfg 的保存交接;
* 2026-09-25 自 Src/freertos.c 迁出,逻辑零改动)