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

228 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:本图的核心信息是**位号对齐**(同一 bit 在三张位图与四个消费者掩码
里落在同一列),必须等宽网格逐列对齐;Mermaid 无法控制列位。
用法(仓库根目录,任意 python3):
python tools/arch_diagram/gen_adc_health_bitmap_svg.py
输出:
docs/images/采样有效性位图与掩码.svg
改内容时:编辑本文件顶部的 GROUPS 数据后重跑。
"""
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
ROW_LABEL_FONT = 12.5
BIT_FONT = 11
TAG_FONT = 10.5
NOTE_FONT = 11.5
HEAD_FONT = 12.5
LABEL_X, LABEL_W = PAD, 262
GRID_X = PAD + LABEL_W + 8
BIT_W, BIT_H, BIT_GAP = 112, 46, 4
NOTE_W = 340
GROUP_GAP = 26
FONT = "Microsoft YaHei, Segoe UI, PingFang SC, sans-serif"
INK, MUTED = "#0f172a", "#64748b"
C_LEVEL = ("#0d9488", "#f0fdfa") # 电平(可自愈)
C_LATCH = ("#e11d48", "#fff1f2") # 锁存(不自愈)
C_EVENT = ("#d97706", "#fffbeb") # 仅边沿事件
C_MASK = ("#7c3aed", "#f5f3ff") # 消费者掩码命中
C_NONE = ("#94a3b8", "#f8fafc") # 未使用 / 不适用
# ----------------------------- 数据(改这里) -----------------------------
# kind: level / latch / event / mask / none
GROUPS = [
dict(head="判定层写出的三张位图(adc_health.c)", rows=[
dict(label="flags 电平位", sub="adc_health_flags(),当前活跃",
note="protectTask 每 20 ms 读它做 L5-4 闭锁;不看事件位",
bits=[("bit0", "TPAFE_STALL", "level"), ("bit1", "STM32_STALL", "level"),
("bit2", "SEQ_BACKWARD", "latch"), ("bit3", "—", "none"),
("bit4", "—", "none"), ("bit5", "—", "none"),
("bit6", "—", "none"), ("bit7", "—", "none")]),
dict(label="sticky 锁存位", sub="adc_health_sticky(),直到 init 才清",
note="只留痕不闭锁:曾停摆/曾出错必须可追溯",
bits=[("bit0", "TPAFE_STALL", "latch"), ("bit1", "STM32_STALL", "latch"),
("bit2", "SEQ_BACKWARD", "latch"), ("bit3", "FRSTDATA", "latch"),
("bit4", "STM32_ERR", "latch"), ("bit5", "HW_ERR", "latch"),
("bit6", "不入锁存", "none"), ("bit7", "不入锁存", "none")]),
dict(label="events 事件位", sub="adc_health_check() 出参,仅当拍有效",
note="adc_health_report() 的唯一输入:按位分三级处置",
bits=[("bit0", "—", "none"), ("bit1", "—", "none"), ("bit2", "—", "none"),
("bit3", "FRSTDATA", "event"), ("bit4", "STM32_ERR", "event"),
("bit5", "HW_ERR", "event"), ("bit6", "TPAFE_GAP", "event"),
("bit7", "STM32_GAP", "event")]),
]),
dict(head="消费者侧的掩码与记忆位图", rows=[
dict(label="PROT_HF_LOCK_MASK", sub="protect_task.c 编译期常量",
note="命中即 prot_elm_init() 复位元件 + 本拍不 eval;SOE 类型 5/6",
bits=[("bit0", "闭锁", "mask"), ("bit1", "闭锁", "mask"),
("bit2", "闭锁", "mask"), ("bit3", "不闭锁", "none"),
("bit4", "不闭锁", "none"), ("bit5", "不闭锁", "none"),
("bit6", "—", "none"), ("bit7", "—", "none")]),
dict(label="serious 严重事件", sub="adc_task.c 的 adc_health_report()",
note="三类计数增量恒应为 0 → 每次 DBG_ERROR + 自检留痕",
bits=[("bit0", "—", "none"), ("bit1", "—", "none"), ("bit2", "—", "none"),
("bit3", "FRSTDATA", "mask"), ("bit4", "STM32_ERR", "mask"),
("bit5", "HW_ERR", "mask"), ("bit6", "—", "none"),
("bit7", "—", "none")]),
dict(label="gap 丢帧事件", sub="同一函数里的丢帧分支",
note="刻意不告警:超拍是常态(启动突发期即累计 23 次),只累计",
bits=[("bit0", "—", "none"), ("bit1", "—", "none"), ("bit2", "—", "none"),
("bit3", "—", "none"), ("bit4", "—", "none"), ("bit5", "—", "none"),
("bit6", "TPAFE_GAP", "mask"), ("bit7", "STM32_GAP", "mask")]),
dict(label="s_health_logged", sub="编排层记忆位图(每类一次留痕)",
note=" |= (serious | rise):用同一位号把 SYSLOG 压成每类每次开机一条",
bits=[("bit0", "记过", "mask"), ("bit1", "记过", "mask"),
("bit2", "记过", "mask"), ("bit3", "记过", "mask"),
("bit4", "记过", "mask"), ("bit5", "记过", "mask"),
("bit6", "不记", "none"), ("bit7", "不记", "none")]),
]),
]
FOOT = ("bit3 / bit4 / bit5 在 events 与 sticky 中刻意用同一位号 → 消费者能把事件位直接"
"套在锁存位图上做每类一次留痕;bit8 以上全 32 位保留未用。"
"详见 docs/算法/采样有效性校验设计说明.md")
KIND_COLOR = dict(level=C_LEVEL, latch=C_LATCH, event=C_EVENT, mask=C_MASK, none=C_NONE)
# ----------------------------- 工具函数 -----------------------------
def esc(s):
return html.escape(s, quote=True)
def text_w(s, fs):
return sum(fs * (1.0 if ord(ch) >= 0x2E80 else 0.58) for ch in s)
WARN = []
def fit(s, fs, avail, where):
if text_w(s, fs) > avail:
WARN.append("%s: %.0f > %.0f [%s]" % (where, text_w(s, fs), avail, s))
# ----------------------------- 生成 -----------------------------
def build():
body = []
addb = body.append
for g in GROUPS:
fit(g["head"], HEAD_FONT, W - 2 * PAD, "group head")
for r in g["rows"]:
fit(r["label"], ROW_LABEL_FONT, LABEL_W - 16, "row label")
fit(r["sub"], TAG_FONT, LABEL_W - 16, "row sub")
for ln in wrap(r["note"], NOTE_FONT, NOTE_W - 24):
fit(ln, NOTE_FONT, NOTE_W - 24, "row note")
for b, tag, kind in r["bits"]:
fit(tag, TAG_FONT, BIT_W - 12, "bit tag " + b)
fit(FOOT, NOTE_FONT, W - 2 * PAD - 32, "foot")
for w in WARN:
print("OVERFLOW WARN " + w)
row_h = BIT_H + 10
y = 178
for g in GROUPS:
addb('<text x="%d" y="%d" font-size="%d" font-weight="700" fill="#334155">%s</text>'
% (PAD, y, HEAD_FONT, esc(g["head"])))
y += 22
for r in g["rows"]:
cy = y
addb('<text x="%d" y="%d" font-size="%d" font-weight="700" fill="%s">%s</text>'
% (PAD, cy + 20, ROW_LABEL_FONT, INK, esc(r["label"])))
addb('<text x="%d" y="%d" font-size="%d" fill="%s">%s</text>'
% (PAD, cy + 38, TAG_FONT, MUTED, esc(r["sub"])))
for i, (b, tag, kind) in enumerate(r["bits"]):
fg, bg = KIND_COLOR[kind]
x = GRID_X + i * (BIT_W + BIT_GAP)
addb('<rect x="%d" y="%d" width="%d" height="%d" rx="8" fill="%s" '
'stroke="%s" stroke-opacity="%s"/>'
% (x, cy, BIT_W, BIT_H, bg, fg, "0.55" if kind != "none" else "0.35"))
addb('<text x="%d" y="%d" font-size="%d" font-weight="700" fill="%s">'
'%s</text>' % (x + 10, cy + 19, BIT_FONT, fg, esc(b)))
addb('<text x="%d" y="%d" font-size="%d" fill="#334155">%s</text>'
% (x + 10, cy + 36, TAG_FONT, esc(tag)))
nx = GRID_X + 8 * (BIT_W + BIT_GAP) + 12
addb('<rect x="%d" y="%d" width="%d" height="%d" rx="8" fill="#f8fafc" '
'stroke="#64748b" stroke-opacity="0.25"/>' % (nx, cy, NOTE_W, BIT_H))
lines = wrap(r["note"], NOTE_FONT, NOTE_W - 24)
ty = cy + (BIT_H - (len(lines) - 1) * 15 + 4) / 2.0
for ln in lines:
addb('<text x="%d" y="%d" font-size="%d" fill="#475569">%s</text>'
% (nx + 12, ty, NOTE_FONT, esc(ln)))
ty += 15
y += row_h
y += GROUP_GAP
# 图例
lx, ly = GRID_X, 118
for label, kind in [("电平位(可自愈)", "level"), ("锁存位(不自愈)", "latch"),
("边沿事件位(仅当拍)", "event"), ("消费者掩码命中 / 记忆位", "mask"),
("不适用", "none")]:
fg, bg = KIND_COLOR[kind]
addb('<rect x="%d" y="%d" width="16" height="16" rx="4" fill="%s" stroke="%s" '
'stroke-width="1.6"/>' % (lx, ly - 12, bg, fg))
lx += 22
addb('<text x="%d" y="%d" font-size="12" fill="#475569">%s</text>'
% (lx, ly, esc(label)))
lx += text_w(label, 12) + 30
total_h = y + 74
foot_y = total_h - 58
body.insert(0, '<rect x="0" y="0" width="%d" height="%d" fill="#ffffff"/>' % (W, total_h))
head = ['<text x="%d" y="44" font-size="%d" font-weight="700" fill="%s">%s</text>'
% (PAD, TITLE_FONT, INK, esc("采样有效性校验 · 出口位图与消费者掩码(逐位对齐)")),
'<text x="%d" y="70" font-size="%d" fill="%s">%s</text>'
% (PAD, SUB_FONT, MUTED,
esc("同一 bit 在三张位图与四个掩码里始终落在同一列:位号对齐 = 消费者可以位图代打表"))]
svg = ('<svg xmlns="http://www.w3.org/2000/svg" width="%d" height="%d" '
'viewBox="0 0 %d %d" font-family="%s">\n%s\n%s\n'
'<rect x="%d" y="%d" width="%d" height="44" rx="10" fill="#fffbeb" '
'stroke="#d97706" stroke-opacity="0.45"/>\n'
'<text x="%d" y="%d" font-size="%d" fill="#7c2d12">%s</text>\n</svg>\n'
% (W, total_h, W, total_h, FONT, "\n".join(head), "\n".join(body),
PAD, foot_y, W - 2 * PAD, PAD + 16, foot_y + 27, NOTE_FONT, esc(FOOT)))
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(WARN):
print("!! %d 处文字可能溢出" % len(WARN))
def wrap(s, fs, avail):
"""按估算宽度做中文换行(无空格语言:逐字累计)。"""
lines, cur = [], ""
for ch in s:
if text_w(cur + ch, fs) > avail and cur:
lines.append(cur)
cur = ""
cur += ch
if cur:
lines.append(cur)
return lines
if __name__ == "__main__":
build()