wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
712 Commits 3 Branches 0 Tags
69d70af4cf2a9ad63292d454f062f63cb426b508
Commit Graph

7 Commits

Author SHA1 Message Date
wandering1 4c74cfa825 refactor(编号·批次二): 文档侧 194 处保护功能号改成功能名，定义表 7 张首格改语义标识 
批次二文档半（道 gate-docs 执行）。先纠三个数的口径账，别再拿任何旧数当准：**234 处是准数** —— 卡片写
52（Lead 用了门禁 Checker 的引用集合，它**刻意排除属主文档内部的定义位**）、道里先报 265（裸正则把
`SDL2-2.32.10` 里的 `L2-2` 当成功能号，误报 10 处）。最终边界口径 = 带左边界 + 跳过反引号代码段。

· 19 只文件 HEAD 共 234 处 → 现 40 处，**40 处 100% 落在变更记录行**（冻结历史，按 Q3 一条没动），
  非变更记录残留 **0**；改写 163 行 / 16 只文档。站点最多：规划文档 110→37、相量层单测说明 25→1、
  采集与数据处理短板评测 21→0、App/algo/README 26→0。
  （`App/algo/README.md` 由上一笔代码提交带上车，路径归属已在该笔正文注明，内容是本批改写）
· **定义表首列由编号改成语义标识**（编号规范 §3.3「表首格就是短语」的完全形态）：首列原为编号的表
  共 **7 张**（不是 5 张），删掉与之重复的「语义名」列；表头标签按域词区分——三张 L3 保护**元件**表
  保留 `| 元件 |`，四张 L1/L2 表用 `| 功能名 |`（把「元件」统一洗成功能名会丢掉领域信息）。
  七张表逐张核：表头竖线数 == 分隔行 == 首条数据行 == 列数+1；与 HEAD 逐块对拍**净新增不一致块 0**，
  并且正是这个对拍抓到第一版「三张表数据行已删列、表头没删」的破表。
· 7 处删号留下的残词/重复解释括号人工收口（如「L1-5（通道标定）」→「通道标定（一次系数 + 零漂）」），
  复扫待收口站点 0；措辞逐字取自映射表，无第二种说法。
· tools/arch_diagram 三只生成器 4 处（3 处 docstring + 1 处图形文案）与产物同批：重跑后**只有位图那张
  变 2 个 text 节点的换行位置**，画布 1580x740 与总行数不变，另两张逐字节未变；改前先干跑对照证明三张
  svg 原本与生成器一致（不在 stale 基线里）——`check_generated_fresh --only docs-svg` PASS。

本笔另含 **F-* 半批的文档面**（同一轮 `git add docs tools/arch_diagram AGENTS.md` 一并收进
，非误伤）：BSD
函数调用关系里 9 处反引号紧邻指针、属主文档 §7 的停发句与导读行（**12 条定义行原样保留、不删登记族**）、
以及 `gen_net_instability_svg.py` 与它的产物 `网络不稳根因总览.svg`（「唯一读者红线」那条的框宽自适应
526 → 551，右缘 1411 未越界，画布 1560x1468 不变）——该半批的**代码注释面**在下一笔。

⚠ 因 `docs/任务规划/登记簿.md` 与 `docs/任务规划/UI补齐.md` 正被另一张卡（UI 叶数复核）改动，本笔**不含
那两只文件**，批次二的 §9 存量收尾与它们同批提交。
 2026-10-27 09:05:24 +08:00
wandering1 0f7b5a87fb chore(编号): 存量编号全量转语义短语，门禁识别面与语料同批重打 
登记簿、文档与代码注释里的存量字母加数字编号（N-x / S-x / T-x / E-x / A-x / 卡号）
一律改写为语义短语，净删 2,028 处引用；删除基线与待确认、并行分道方案、排期详述、
采集保护收尾 4 篇（内容已并入 docs/任务规划/README 与登记簿）。

门禁机器与三张账同批重打：check_ids.py 新增变更记录行豁免与第二根护栏
undecidable_total_ceiling；check_test_traceability.py 只加 stdout/stderr UTF-8
reconfigure（TC_RE 未动）；check_cubemx_survival.py 的 --write 固定 newline=LF；
id_registry / id_aliases（+19 条 retired-to-phrase）/ id_known_backlog 重打。

test/ 56 个文件同步 TC 标签语义化，其中 18 个 TU 改了 CHECK / printf 里的标签文字，
是本批唯一改变构建产物的文件集合。

为什么合成一笔、不拆四笔（实测撞闸，非偏好）：pre-commit 跑钩子前会 stash 未 staged
部分，拆开后中间提交必然是「新规则 + 旧语料」——实跑可判定 85.15% < 基线 86.00%、
不可判定 1,453 > 上限 1,166，编号门禁直接拦下。编号识别面与它描述的语料只能同码移动。

实跑基线（工作区全量）：754 文件 / 8,230 处编号字面量 / 可判定 7,079 = 86.01%
（基线 86.0%，容差 0.1pp）/ 不可判定绝对数 1,151（上限 1,166）/ 校验 1-6 错误级 0 /
告警 = 悬空 2（App/algo/freq.c 的 S2，属 §4.4 同号不同义）+ 孤儿 50。

基线从 84.0 抬到 86.0 的理由见 docs/门禁说明/id-check.md §7.6：本批真删了 2,028 处
引用，可判定面随真实内容上升，不是把分母做小。同批新增排除 docs/硬件平台/ 语料，使
识别面少 264 处——芯片手册位号与网表料号不属编号空间（registry 有 excluded_paths_note）。

⚠ 余量只剩 0.11pp（约 10 处）与绝对数 15 处：把「可判定的引用」改成散文会立刻撞第二
根护栏。另遗留一项：id_aliases 里 retired 的 N / S / T / A 别名没有 scope（U1~U5 有），
今后有人新写一个 A-4，校验 3 不会响，只能靠人，建议下批补 scope。

固件不变证据：115 个 .c/.h 剥注释并归一字符串后与 HEAD 逐字节全等，残留代码差异 0；
App / Src / Drivers 的字符串字面量零改动。@build 0 错误 0 警告；40/40 主机套件、2,889
断言全通过；覆盖率 line 89.2% / func 92.6%；pre-commit 48 钩子 --all-files 全绿；
check_doc_links --all 通过（176 文档，章节引用无法判定 0）；逐字节卫生核过：14 个带
BOM 文件与 HEAD 一致、0 个 CR、0 个 U+FFFD，字符串字面量纯 ASCII。

.cubemx_survival_baseline.json 的 watchdog-module 哈希 56bf27 变 2bb051 属合法：
Src/freertos.c 的 USER CODE 区内只有注释文字随编号改写，代码未变。

同批带上体积同码凭证与 RAM 台账行（@build 之后盖戳）：RW_IRAM1 79,008 B / 60.3%，
RW_CCM 57,376 B / 87.9%，阈值 92%。
 2026-10-26 12:28:14 +08:00
wandering1 504db26698 docs(内存): 阶段子项改层级编号 4.阶段.项，消除与顶层章节同号撞面
CI / L0 静态门禁 (pre-commit) (push) Failing after 2m1s
Details
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
Details 
根因：`RAM使用分析与优化方案.md` 顶层有 §1 背景 / §2 现状测量（2.1~2.6），而 §4
「方案」下"阶段 N"的子项也用裸号 0.x / 1.x / 2.x——阶段 2 的 2.1/2.2/2.3 与顶层
2.x **完全同号**，阶段 1 的 1.x 又长得像"第 1 章第 x 节"。`doc-links` 对本文自
引用按设计直接放过，于是门禁和人一起看错：AGENTS.md 把"栈余量台账"写成 §1.4，
而 §1.4 其实是阶段 1 的 lftpd 静态化项（上一笔提交的信息里我把它误判成断链，
已 amend 更正）。

改法：阶段子项一律改层级编号，阶段号不变、只加 `4.` 前缀 —— 0.x→4.0.x、
1.x→4.1.x、2.x→4.2.x。共改 14 个标题；文内自引用与实施序列表（S4~S9 那套）、
暂缓清单、§5 预期效果列里的裸号一并补成 §4.x.y。

外部引用同步 15 处：AGENTS.md、lftpd/README ×2、菜单页面设计、RAM预算台账 ×2、
项目架构总览 ×3、FTP_Test_Guide ×3、boot_log_data/README、部署环境要求、审查
报告、ram_baseline.py ×3。最有说服力的两处歧义：审查报告与 RAM预算台账都写
"缩堆见 …§2.2"——既可读成顶层 §2.2（静态大项排行）也可读成阶段 2 第 2 项，
现均为 §4.2.2（阶段 2 第 2 项"缩堆"）。

另修 4 处把 §1.4 当"栈台账"的错指：采样有效性校验设计说明 :441/:593/:650 改
指 §2.3（任务栈配置与实测峰值）与 §4.0.6（静态最坏链与判定）；id_aliases.json
 的 note 改指 §4.0.6 并标注"原 §1.4，2026-10-22 层级编号"。

冻结与示例：其它文档**变更记录行**里的旧编号按项目纪律不改写（项目架构总览
:367、RAM预算台账 :98），改在被引文档 §4 开头留一张换算表 + 约定说明；把旧号
当语法示例写的 7 处一并换掉（文档规范 ×3、check_doc_links ×3、rename_ref ×1），
否则示例本身指向已改名的锚点。主文档版本行 bump 到 v1.3 / 2026-10-22。

门禁：check_doc_links.py --all --sections-strict → 146 个文档 0 问题（章节引用
2513 处、机器可判定 1491）；check_ids.py --strict 增量拦截通过；mem-numbers、
ram_baseline --gate（SRAM1 57.4% / CCM 87.9%）、task-table 全绿；本轮未改任何
.c/.h。16 个文件字节卫生自查 BOM/CR/U+FFFD/行尾空格全清。已提交本地，未推送。
 2026-10-22 15:38:14 +08:00
wandering1 790e153cd6 fix(adc_input): 丢帧计数改按帧点数累计，与 TPAFE 侧 tgap 同单位 
读码确认的口径缺陷：两片转换器的丢帧计数单位不一致——TPAFE 侧
adc_health_tpafe_gaps() 按 (d-1) 加权记「帧点数」，STM32 侧
adc_input_stm32_gaps() 每次事件只 +1 记「次数」。两者都被当作心跳字段
并排打印（adc1_gap / tgap），一次跨多帧时数值就分叉：同样丢 3 帧，
一边记 2、一边记 1。跨字段对比或做除法会得出错误结论。

选 A（改代码，真对称）而不是只改字段名：
- 单拍超一帧（d=2）时两者数值相同，历史上绝大多数样本本来就等价，
  换单位对既有判读习惯冲击很小；
- 只在一次跨 ≥2 帧时分叉，而那正是心跳日志突发期最常见的形态，
  留在文档里当"注意点"迟早还会读错一次。

改动：
- adc_input.c：s_stm32_gaps += (d - 1u)（d = seq - s_dma_seq_seen，
  顺带把已算过的差值提成局部变量 d，不再重复算一遍）
- adc_input.h / adc_input.c 函数头：单位写明「Σ 每次前进的超出部分」，
  并点名 2026-10-21 之前固件该字段是次数口径，跨版本日志不可直接对比
- 用例：原两档只跨 1 帧（前进 2 记 1），钉不出单位；补第二档——连投
  3 帧不消费（一次跨 2 帧）必须记 2 点、累计 1+2=3。补充断言沿用所属
  用例覆盖点，不另立新编号，也不在文档外复制用例号（编号门禁按文件内
  实例数比对台账豁免，多写一处即被判新债）
- 文档同步：ADC采样节拍设计说明 §8/§9 字段口径与稳态基线、采集与算法
  层设计说明 §3/§4、采样有效性校验设计说明 §6.2/§10/§11（并把"两车道
  单位不同"从观测盲区降级为"历史日志口径差异"）、ADC输入层单元测试
  说明用例表该行；两张配图生成器文案同步

实测：
- @build 0 错 0 警；Program Size 与上一提交**逐字节相同**（Code=213520
  RW=1184 ZI=131504）——编译器早已为半区推导算过同一差值并复用，
  故本次净增 0 B，不产生新的台账漂移
- 主机单测：ADC 输入层 103/103、ADC 有效性 45/45
- stack_report：adcTask 1320 B / protectTask 872 B 均不变
- 字节卫生：BOM 无 / CR 0 / U+FFFD 0 / 文件尾换行齐
- id-check：Passed（曾因新增用例号实例触发"台账之外 +2"，已按不复制
  用例号的方式消除，未动 id_known_backlog.json 台账）

gate: only mem-budget/mem-numbers pending lead ledger backfill
pre-commit run --all-files 失败仅这两条，漂移量来自上一条提交 6f90600
（+96 B Code / +24 B ZI）；本条自身 0 B。按并行分支约定本分支不跑
--write，台账由 Lead 合并后统一回填。
 2026-10-22 00:43:32 +08:00
wandering1 9f826dbb4d fix(protect): 采样陈旧时独立闭锁保护（判定层失明的兜底门） 
问题：L5-4 闭锁读的 adc_health_flags() 只有 adcTask 每拍跑
adc_health_check() 才可能置位。TIM3 一停，adcTask 就永久阻塞在
osThreadFlagsWait（刻意的 fail-safe），check() 不再执行 → stall 位
永远是 0，而 protectTask 仍每 20 ms 拿冻在最后一帧的相量继续判据。
窗口最坏约 800 ms（停喂阈值）+ 2498 ms（IWDG 标称）≈ 3.3 s。

方案：保护侧建一条与消费者存活完全解耦的兜底新鲜度门。
- adc_health.c/h 新增 adc_health_age_stale()：无模块状态的纯判据，
  参照系 adc_health_age_t 由调用方自存。故意不让 protectTask 去调
  adc_health_check()——那是「每拍一次、单写者」的契约，两个上下文
  同写会互相刷新差值基线，把现有判定层一起弄坏。
- 新增 ADC_HF_STALE = bit8（与判定层 bit0..bit7 位段错开）。本位
  不由判定层写、不进 sticky、不进编排层 logged 位图。
- protect_task.c 用自己的时基直接读两个**中断侧递增**的计数器
  （tpafe5160_frame_seq / adc_input_stm32_seq），并入掩码。两条车道
  各自一份 primed：共用会让先观测的那条把标志置 1，另一条首拍拿
  adv_ms = 0 算年龄 → 开机即误锁保护。
- 门限 PROT_STALE_AGE_MS = 100 + 20 = 120 ms，买的是时序阶梯：
  判定层活着时它先报 0x1/0x2（带日志与自检留痕），死了只出现
  0x100。闭锁最迟 140 ms，仍远小于最小动作延时（默认 1000 ms）。

实测：
- @build 0 错 0 警：Code 213424 → 213520（+96 B）；ZI 131480 →
  131504（+24 B = 两份 age 结构）；RW-data 1184 不变
- stack_report：protectTask 静态最坏链 872 B 不变（余 1176 B / 57%）、
  adcTask 1320 B 不变——新判据无日志，不进最坏链
- 主机单测 45/45（新增 TC-ADCHEALTH-012..017 共 14 条断言：首拍只建
  基线 / 超拍不判老 / 门限含等号 / 跨 tick 回绕 / 倒退按分工不判老 /
  双观察者互不污染 / 空参数不判老）
- 台架注入（一次性停 TIM3 300 ms 探针，验完已撤；探针固件与最终
  固件 Program Size 逐字节相同）：
  [+5462ms] [ERR][PROT] sampling FAULT -> protection blocked (hf=0x00000100)
  [+5757ms] [PROT] sampling recovered -> protection resumed
  同次开机 [ADC_TASK] health: 出现 0 次；MISS 快照缺的正是 bit6
  （0x1F7 - 0x1B7 = 0x40，实证 adcTask 当时确实阻塞，不是"在跑但没报"）；
  reset cause: 仅 1 次（300 ms 被 800 ms 容忍吸收，闭锁不靠复位）
  证据 docs/测试说明/boot_log_data/20261021_probe_stale_gate_boot_log.txt
- 字节卫生：BOM 无 / CR 0 / U+FFFD 0；新增行无非法字面量

gate: only mem-budget/mem-numbers pending lead ledger backfill
pre-commit run --all-files 失败仅这两条（台账受管快照与本树 .map 的
Flash/RAM 水位漂移，即本次 +96 B Code、+24 B ZI）。按并行分支约定
本分支不跑 --write，台账由 Lead 合并后统一回填。

文档同步：设计说明新增 §15（原相关文档改 §16），§7 位表加 bit8 行、
§8 责任矩阵与「已知窗口」段改写为已闭合、§10 盲区第 3 条、§11 用例
表、§12 判读手册、§14 改前清单全部跟上；位图配图补 bit8 列，并修掉
生成器把列数硬编码成 8 列导致新列被备注框盖住的问题。
 2026-10-22 00:43:32 +08:00
wandering1 60a650c175 fix(adc_task): 接上从未被调用的任务初始化入口（含判定层参照系） 
问题：adc_task_func 函数头写「限定条件：adc_task_init() 已调用」，但
adc_task_init() 全库无调用点；同类空壳 net_task_init()（体内只有一条
DBG_INFO，函数头却写「创建 TCP Server 监听 Socket」）同样无人调用。

判定层为什么今天还没坏：状态全在 .bss（复位即 0），且 adc_health 的
首拍只建基线、不判定，所以漏调 init 只是「少清一次」。但假契约会让
下一个接手者照它推理，故必须修在成灾之前。

改动：
- adc_task_func 进入循环之前（开闸 s_consumer_ready 之前）自己调用
  adc_task_init()，不依赖外部接线；init 与首拍之间无抢占窗口
- adc_task_init() 去掉 DBG_INFO 并在函数头标注禁止加日志：它落在
  adcTask 静态最坏调用链上，每条 DBG_* 约 216 B 栈，而这条启动行
  无诊断价值（存活由首帧日志与 TASK_WD_ADC 心跳证明）
- 删除 net_task.c/.h 里的空壳 net_task_init()（声明 + 定义 + 误述）
- docs/算法/采样有效性校验设计说明.md §14 与变更记录同步改写：
  原来登记的「init 不在产品路径」事实已修复，不留过时结论

实测（任务工作树 adc-health，构建 + 静态分析）：
- @build 0 错 0 警；Code 213356 → 213424（+68 B）
- RW-data 1184 / ZI-data 131480 逐字节不变 ⇒ RAM 零增量
- stack_report：adcTask 静态最坏链 1320 B → 1320 B 不变，
  余 1240 B / 48% 仍 PASS（netTask 1912 B、protectTask 872 B 不变）
- ADC 有效性单测 31/31 通过（钩子按 adc_task.c 自动触发）
- 字节卫生自查：BOM 无 / CR 0 / U+FFFD 0，字符串字面量纯 ASCII
  （中文只在注释里），新增行无非 ASCII 字面量

gate: only mem-budget/mem-numbers pending lead ledger backfill
pre-commit run --all-files = 33 Passed / 2 Failed，失败仅这两条，
均为台账受管区与本树 .map 的 Flash 差异（233,120 → 233,188，即本次
+68 B）；RW_IRAM1 75,240 与 RW_CCM 57,376 与台账完全一致。按并行
分支约定本分支不跑 --write，台账由 Lead 合并后统一回填。

另记一处门禁缺口（非本次引入）：ui-golden 的黄金参考 simulator/
tests/ref/ 被 .gitignore 排除、从未入库，新工作树里必然失败；本树
用 check_content_pages.py --update 生成 11 页基线后 ui-golden Passed
（即本次改动对 UI 像素中性）。是否让基线入库待裁。
 2026-10-22 00:43:31 +08:00
wandering1 513becd61d docs(algo): 新增 adc_health 单文件深设计与三张配图 
- 新建 docs/算法/采样有效性校验设计说明.md（15 章）：判据推导
  （100 ms 门限的三条独立依据）、电平/锁存/事件三种位语义与
  位号对齐的收益代价、闭锁与 IWDG 兜底责任矩阵、观测盲区、
  主机侧验证分工（11 组 TC / 31 断言映射）、现场判读手册、
  自测问题与改前必读清单
- 配图走 draw-diagram 生成器路线（脚本 + 产物一并提交）：
  tools/arch_diagram/gen_adc_health_flow_svg.py 等三个脚本 →
  docs/images/ 下三张 SVG；文内另有 2 张 Mermaid（判定主干
  flowchart、静默位生命周期 stateDiagram-v2，沿用仓内既有方言）
- 登记与指针：docs/README.md §5.2 加一行 + 变更记录；
  docs/算法/采集与算法层设计说明.md §4 与 §13 加深读指针；
  本文只写「为什么」，接口表仍由该文档属主，不重复
- 读码确认并如实登记三项（本提交不改代码，待裁）：
  1) adc_task_init() 全库无调用点，adc_health_init() 因此不在
     产品路径，判定正确只依赖 .bss 清零 + 首拍建基线
  2) tgap 计帧点数（d-1 加权），adc1_gap 计次数——两侧单位
     不对称，心跳里不可直接对比
  3) TIM3 停摆时判定层随消费者一起停，最坏约 800 ms + 2498 ms
     窗口内 protectTask 仍以旧相量判据（细节见 §10 / §14）
- 门禁自查：pre-commit 目标集全绿（doc-links / id-check /
  空白 / EOF / 大文件）；主机单测 adc_health 31/31 复跑通过；
  9 个新增或改动文件 BOM=无、CR=0、U+FFFD=0
 2026-10-22 00:43:31 +08:00