#!/usr/bin/env python3 # -*- coding: utf-8 -*- """生成 docs/images/采样有效性校验数据流.svg —— 采样有效性校验「观测计数 → 快照 → 判定 → 位图 → 消费者」(纯标准库)。 为什么不用 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 、不碰寄存器 / 不取数 / 不打日志)→ 主机侧以 #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('' % (W, total_h)) add('%s' % (PAD, TITLE_FONT, INK, esc("采样有效性校验(adc_health)· 数据流与出口"))) add('%s' % (PAD, SUB_FONT, MUTED, esc("三条量车道平行流过五个阶段;判定层每拍一次、常数次整数运算,输入只是计数快照"))) # ---- 阶段标题 ---- for ci, st in enumerate(STAGES): x, cw = COLS[ci] add('' % (x, cw, BG_HEAD, C_HEAD)) add('%s' % (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('' % (PAD, y0, LANE_LABEL_W - 14, CELL_H, bg, color)) add('%s' % (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('' % (x, y0, cw, CELL_H, bg, color)) add('%s' % (x + 13, y0 + 30, CELL_TITLE_FONT, color, esc(cell["title"]))) yy = y0 + 56 for ln in cell["lines"]: add('%s' % (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('' % (x + cw, cy, nx - 9, cy, color)) add('' % (nx, cy, nx - 11, cy - 5.5, nx - 11, cy + 5.5, color)) # ---- 底部说明 ---- add('' % (PAD, bottom + 30, W - 2 * PAD)) add('%s' % (PAD + 16, bottom + 58, FOOT_FONT, esc(FOOT))) svg = ('\n%s\n\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()