Files
STM32F4-Base/tools/arch_diagram/gen_adc_health_flow_svg.py
T
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

257 lines
11 KiB
Python
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.
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""生成 docs/images/采样有效性校验数据流.svg —— L1-6「观测计数 → 快照 → 判定 → 位图 → 消费者」(纯标准库)。
为什么不用 Mermaid:本图要表达**三条量车道(TPAFE / STM32 / 时基)平行流过五个阶段**,
Mermaid 自动布局会把三条车道挤成交叉线、也保不住"同一拍取数"的横向对齐。
这里按车道手工排布:每车道一行,箭头全部水平,行内可直接横向读一遍判据。
用法(仓库根目录,任意 python3):
python tools/arch_diagram/gen_adc_health_flow_svg.py
输出:
docs/images/采样有效性校验数据流.svg
改内容时:只编辑本文件顶部的 STAGES / LANES 数据后重跑。
"""
import html
import os
import xml.etree.ElementTree as ET
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
OUT = os.path.join(ROOT, "docs", "images", "采样有效性校验数据流.svg")
# ----------------------------- 画布与尺寸 -----------------------------
W = 1580
PAD = 40
TITLE_FONT = 21
SUB_FONT = 13
HEAD_FONT = 13
CELL_TITLE_FONT = 12.5
CELL_NOTE_FONT = 11
LANE_FONT = 12
FOOT_FONT = 12
CELL_H = 148
LANE_GAP = 34
MAIN_Y = 214
LANE_LABEL_W = 96
COLS = [
(PAD + LANE_LABEL_W, 268), # 阶段 1:观测计数(ISR / 消费侧)
(PAD + LANE_LABEL_W + 288, 236), # 阶段 2:本拍快照
(PAD + LANE_LABEL_W + 544, 276), # 阶段 3:判定(纯逻辑)
(PAD + LANE_LABEL_W + 840, 264), # 阶段 4:出口位图
(PAD + LANE_LABEL_W + 1124, 250), # 阶段 5:消费者
]
FONT = "Microsoft YaHei, Segoe UI, PingFang SC, sans-serif"
C_LANE = ["#0d9488", "#2563eb", "#7c3aed"]
BG_LANE = ["#f0fdfa", "#eff6ff", "#f5f3ff"]
C_HEAD, BG_HEAD = "#475569", "#f1f5f9"
INK, MUTED = "#0f172a", "#64748b"
# ----------------------------- 数据(改这里) -----------------------------
STAGES = [
"1. 观测计数(ISR / 驱动侧)",
"2. 本拍计数快照",
"3. 判定(adc_health.c 纯逻辑)",
"4. 出口位图(32 位)",
"5. 消费者与处置",
]
# 每条车道 = 一行;cells 与 STAGES 一一对应
LANES = [
dict(
name="TPAFE",
color=0,
cells=[
dict(title="tpafe5160.c 的 BUSY EXTI",
lines=["s_frame_seq++:每读完一帧 +1",
"s_frstdata_err++:无跳变帧累计计数",
"ISR 内只加计数,不打日志"] ),
dict(title="adcTask 每拍 poll 之后取值",
lines=["tpafe_seq",
"tpafe_frst_err(uint16 放宽)",
"⚠ 必须取本拍 poll 之后的值"] ),
dict(title="序号差值 d = seq - 上次",
lines=["d < 0 → 置倒退位并重新对齐",
"d > 1 → tgap += d-1 + 当拍事件",
"d >= 1 → 刷新「最后前进时刻」"] ),
dict(title="本车道出口",
lines=["bit0 ADC_HF_TPAFE_STALL(自愈)",
"bit2 ADC_HF_SEQ_BACKWARD(锁存)",
"bit6/bit3 ADC_HE_TPAFE_GAP / FRSTDATA"] ),
dict(title="闭锁 + 留痕 + 计数",
lines=["protectTask 每 20 ms 读 bit0/bit2",
"gap / FRSTDATA 事件 → 编排层日志",
"tgap → 10 s 心跳字段"] ),
],
),
dict(
name="STM32",
color=1,
cells=[
dict(title="adc_input.c(DMA2 Stream4)",
lines=["s_dma_seq++:半区/整区完成各一次",
"s_stm32_gaps += d-1:丢帧点数",
"s_stm32_errs++:连续 >=2 拍无新帧",
"s_stm32_hw_errs++:HAL 错误回调"] ),
dict(title="同一拍的四个 STM32 计数",
lines=["stm32_seq / stm32_errs",
"stm32_gaps / stm32_hw_errs",
"gap 细账不重复取(L1 已算)"] ),
dict(title="序号差值 d + 三处计数增量",
lines=["d < 0 → 同一个 SEQ_BACKWARD 位",
"d >= 1 → 刷新最后前进时刻",
"增量 != 0 → 事件 + 锁存"] ),
dict(title="本车道出口",
lines=["bit1 ADC_HF_STM32_STALL(自愈)",
"bit2 共用(两车道同一位)",
"bit7/bit4/bit5 GAP / ERR / HW_ERR"] ),
dict(title="闭锁 + 严重事件",
lines=["bit1/bit2 → 同左闭锁路径",
"STM32_ERR / HW_ERR:恒 0 增量",
"出现即 DBG_ERROR + 自检留痕"] ),
],
),
dict(
name="时基",
color=2,
cells=[
dict(title="osKernelGetTickCount()",
lines=["HAL 时基 TIM7,tick = 1 ms",
"2^32 ms 后自然回绕"] ),
dict(title="now_ms:本拍唯一一份",
lines=["健康判定与心跳上报共用",
"不在判定层内再取一次"] ),
dict(title="差值法 (int32_t)(now - adv)",
lines=["回绕安全(取有符号差)",
">= ADC_HEALTH_STALL_MS(100)",
"可判定窗 ±2^31 ≈ ±24.85 天"] ),
dict(title="tpafe_stall_ms",
lines=["静默期内给出停滞时长",
"正常态恒为 0",
"STM32 侧未上报(观测盲区)"] ),
dict(title="上升沿日志可读性",
lines=["health: flags=… stall_ms=…",
"回答到底停了多少毫秒"] ),
],
),
]
FOOT = ("判定层零平台依赖(只 include <stdint.h>、不碰寄存器 / 不取数 / 不打日志)→ 主机侧以 #include 原样纳入、免桩全覆盖单测。"
"详见 docs/算法/采样有效性校验设计说明.md")
# ----------------------------- 工具函数 -----------------------------
def esc(s):
return html.escape(s, quote=True)
def text_w(s, fs):
"""粗略估算文本像素宽:CJK/全角 ≈ 1.0em,其余 ≈ 0.58em(宁可偏大)。"""
return sum(fs * (1.0 if ord(ch) >= 0x2E80 else 0.58) for ch in s)
OVERFLOW = []
def check_fit(s, fs, avail, where):
if text_w(s, fs) > avail:
OVERFLOW.append("%s: %.0f > %.0f [%s]" % (where, text_w(s, fs), avail, s))
# ----------------------------- 生成 -----------------------------
def build():
out = []
add = out.append
n_cells = max(len(l["cells"]) for l in LANES)
for li, lane in enumerate(LANES):
for ci, cell in enumerate(lane["cells"]):
_, cw = COLS[ci]
avail = cw - 26
check_fit(cell["title"], CELL_TITLE_FONT, avail,
"lane %s col %d title" % (lane["name"], ci + 1))
for ln in cell["lines"]:
check_fit(ln, CELL_NOTE_FONT, avail,
"lane %s col %d line" % (lane["name"], ci + 1))
for ci, st in enumerate(STAGES):
check_fit(st, HEAD_FONT, COLS[ci][1] - 20, "stage head %d" % (ci + 1))
if len(OVERFLOW):
for o in OVERFLOW:
print("OVERFLOW WARN " + o)
lane_h = CELL_H + LANE_GAP
bottom = MAIN_Y + len(LANES) * lane_h - LANE_GAP
total_h = bottom + 92
add('<rect x="0" y="0" width="%d" height="%d" fill="#ffffff"/>' % (W, total_h))
add('<text x="%d" y="44" font-size="%d" font-weight="700" fill="%s">%s</text>'
% (PAD, TITLE_FONT, INK, esc("采样有效性校验(adc_health)· 数据流与出口")))
add('<text x="%d" y="70" font-size="%d" fill="%s">%s</text>'
% (PAD, SUB_FONT, MUTED,
esc("三条量车道平行流过五个阶段;判定层每拍一次、常数次整数运算,输入只是计数快照")))
# ---- 阶段标题 ----
for ci, st in enumerate(STAGES):
x, cw = COLS[ci]
add('<rect x="%d" y="150" width="%d" height="34" rx="8" fill="%s" stroke="%s" '
'stroke-opacity="0.35"/>' % (x, cw, BG_HEAD, C_HEAD))
add('<text x="%d" y="172" font-size="%d" font-weight="700" fill="#334155">%s</text>'
% (x + 12, HEAD_FONT, esc(st)))
# ---- 车道 ----
for li, lane in enumerate(LANES):
color, bg = C_LANE[lane["color"]], BG_LANE[lane["color"]]
y0 = MAIN_Y + li * lane_h
# 车道标签
add('<rect x="%d" y="%d" width="%d" height="%d" rx="10" fill="%s" stroke="%s" '
'stroke-opacity="0.5"/>' % (PAD, y0, LANE_LABEL_W - 14, CELL_H, bg, color))
add('<text x="%d" y="%d" font-size="%d" font-weight="700" fill="%s" '
'text-anchor="middle">%s</text>'
% (PAD + (LANE_LABEL_W - 14) / 2.0, y0 + CELL_H / 2.0 + 5, LANE_FONT,
color, esc(lane["name"])))
for ci, cell in enumerate(lane["cells"]):
x, cw = COLS[ci]
add('<rect x="%d" y="%d" width="%d" height="%d" rx="10" fill="%s" stroke="%s" '
'stroke-opacity="0.45"/>' % (x, y0, cw, CELL_H, bg, color))
add('<text x="%d" y="%d" font-size="%d" font-weight="700" fill="%s">%s</text>'
% (x + 13, y0 + 30, CELL_TITLE_FONT, color, esc(cell["title"])))
yy = y0 + 56
for ln in cell["lines"]:
add('<text x="%d" y="%d" font-size="%d" fill="#334155">%s</text>'
% (x + 13, yy, CELL_NOTE_FONT, esc(ln)))
yy += 22
# 水平箭头到下一列
if ci + 1 < len(lane["cells"]):
nx = COLS[ci + 1][0]
cy = y0 + CELL_H / 2.0
add('<line x1="%d" y1="%.1f" x2="%d" y2="%.1f" stroke="%s" '
'stroke-width="2.2"/>' % (x + cw, cy, nx - 9, cy, color))
add('<path d="M %.1f %.1f L %.1f %.1f L %.1f %.1f z" fill="%s"/>'
% (nx, cy, nx - 11, cy - 5.5, nx - 11, cy + 5.5, color))
# ---- 底部说明 ----
add('<rect x="%d" y="%d" width="%d" height="46" rx="10" fill="#fffbeb" '
'stroke="#d97706" stroke-opacity="0.45"/>' % (PAD, bottom + 30, W - 2 * PAD))
add('<text x="%d" y="%d" font-size="%d" fill="#7c2d12">%s</text>'
% (PAD + 16, bottom + 58, FOOT_FONT, esc(FOOT)))
svg = ('<svg xmlns="http://www.w3.org/2000/svg" width="%d" height="%d" '
'viewBox="0 0 %d %d" font-family="%s">\n%s\n</svg>\n'
% (W, total_h, W, total_h, FONT, "\n".join(out)))
d = os.path.dirname(OUT)
if not os.path.isdir(d):
os.makedirs(d)
with open(OUT, "w", encoding="utf-8", newline="\n") as fp:
fp.write(svg)
ET.fromstring(svg)
print("OK %d bytes, canvas %dx%d -> %s" % (len(svg.encode("utf-8")), W, total_h, OUT))
if len(OVERFLOW):
print("!! %d 处文字可能溢出,见上方 WARN" % len(OVERFLOW))
if __name__ == "__main__":
build()