wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

Net 层阻塞模型架构设计 §2 架构总览改用 SVG 矢量图

Browse Source
This commit is contained in:
Wanderingss
2026-09-29 06:00:48 +08:00
parent 0485e79da0
commit 0ddf8c9aca
4 changed files with 402 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/arch_diagram/gen_net_pending_svg.py
+299
View File
@@ -0,0 +1,299 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""生成 docs/images/Net层阻塞模型.svg —— pending 请求模型架构图（纯标准库）。
结构：左右两栏 + 主循环横带 + 五路判定带
左 = 调用方任务（net_recv → 数据已在? → 登记挂起 / 睡任务通知）
右 = netTask 立即 SPI 读出（快速路径）+ CH395F 芯片
中 = netTask 主循环（~1ms 节拍：net_poll / net_pending_tick / ...）
下 = 五路完成/取消判定 → xTaskNotify 唤醒调用方
目的：把"等数据"从执行者内的自旋改为执行者外的登记——登记后调用方在自己上下文
睡眠，netTask 零占用地继续服务整个队列。
用法（仓库根目录，任意 python3）：
python tools/arch_diagram/gen_net_pending_svg.py
输出：
docs/images/Net层阻塞模型.svg
改流程时：编辑本文件顶部的 CALLER_STEPS / LOOP_STEPS / PHASES 数据后重跑。
"""
import html
import math
import os
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
OUT = os.path.join(ROOT, "docs", "images", "Net层阻塞模型.svg")
# ----------------------------- 画布与样式 -----------------------------
W = 1440
H = 1030
PAD = 40
FONT = "Microsoft YaHei, Segoe UI, PingFang SC, sans-serif"
TITLE_FONT = 21
SUB_FONT = 13
PANEL_TITLE_FONT = 15
STEP_TITLE_FONT = 14
STEP_NOTE_FONT = 12
LANE_FONT = 12.5
FOOT_FONT = 12
C_CALLER, BG_CALLER = "#2563eb", "#eff6ff"
C_ACTOR, BG_ACTOR = "#7c3aed", "#f5f3ff"
C_CHIP, BG_CHIP = "#0d9488", "#f0fdfa"
C_TICK, BG_TICK = "#d97706", "#fffbeb"
C_CANCEL = "#dc2626"
C_OK = "#16a34a"
ARROW_W = 2.2
def esc(s):
return html.escape(s, quote=True)
def text_w(s, fs):
"""粗略估算文本像素宽：CJK/全角 ≈ 1.0em，其余 ≈ 0.58em。"""
w = 0.0
for ch in s:
w += fs * (1.0 if ord(ch) >= 0x2E80 else 0.58)
return w
# ----------------------------- 数据（改这里） -----------------------------
# 左栏：调用方流程（自上而下）
CALLER_STEPS = [
("net_recv(fd, buf, len, timeout)", "公开 API 与调用契约不变（签名 / 返回值 / 超时语义）"),
("数据已在？", "readable 标志由 net_poll 每轮刷新"),
("登记 pending 到 s_net_pending[fd]", "占用执行者到此结束（微秒级）· 每 fd 至多一个，不覆盖"),
("调用方在自己上下文睡任务通知", "与 LwIP 消费者线程模型同构 · 取消必通知，永不挂死"),
]
FAST_PATH = ("立即 SPI 读出",
"GET_REMV_LEN / READ → 通知调用方（结果 = 字节数）")
LOOP_STEPS = [
("net_poll()", "刷新 readable", C_CHIP),
("net_pending_tick()", "了结挂起", C_TICK),
("net_relisten_retry_tick()", "重试对账", C_ACTOR),
("排空消息队列", "服务所有消费者", "#64748b"),
]
PHASES = [
("①", "数据到达", "SPI 读出，通知调用方（结果 = 字节数）", C_CHIP),
("②", "到点 deadline", "通知 NET_ERR_TIMEDOUT（对外 -2 映射保持）", C_TICK),
("③", "EOF / DISCONNECT", "按 0(EOF) 完成 + auto-relisten + 通知", C_ACTOR),
("④", "同 fd 后续操作", "先行结算该 fd 挂起，再执行新操作", C_CALLER),
("⑤", "网络重建（芯片复位）", "取消 + 必须通知（否则调用方永久挂死）", C_CANCEL),
]
WATCHDOG = "看门狗：到点后 1s 仍未了结 = 完成逻辑缺位 → 强制了结 + DBG_ERROR"
FOOT = ("关键性质：挂起期间 netTask 零额外占用（判据复用主循环既有 net_poll 的 readable，"
"不引入额外 SPI 事务）；公开 API 不变，既有调用方 / 测试 / 模拟器零改动。")
# ----------------------------- 生成 -----------------------------
def build():
out = []
add = out.append
def poly(points, color, dash=False, head=True, width=ARROW_W):
pts = " ".join("%.1f,%.1f" % p for p in points)
d = ' stroke-dasharray="7 5"' if dash else ''
add('<polyline points="%s" fill="none" stroke="%s" stroke-width="%.1f" '
'stroke-linejoin="round"%s/>' % (pts, color, width, d))
if head:
(x1, y1), (x2, y2) = points[-2], points[-1]
ang = math.atan2(y2 - y1, x2 - x1)
hl, hw = 11.0, 5.5
bx, by = x2 - hl * math.cos(ang), y2 - hl * math.sin(ang)
px, py = -math.sin(ang) * hw, math.cos(ang) * hw
add('<path d="M %.1f %.1f L %.1f %.1f L %.1f %.1f z" fill="%s"/>'
% (x2, y2, bx + px, by + py, bx - px, by - py, color))
def line(x1, y1, x2, y2, color, dash=False, head=False, width=ARROW_W):
poly([(x1, y1), (x2, y2)], color, dash=dash, head=head, width=width)
def box(x, y, w, h, color, bg, title, note=None, tfs=STEP_TITLE_FONT):
add('<rect x="%.1f" y="%.1f" width="%.1f" height="%.1f" rx="10" fill="%s" '
'stroke="%s" stroke-opacity="0.55" stroke-width="1.6"/>'
% (x, y, w, h, bg, color))
add('<text x="%.1f" y="%.1f" font-size="%.1f" font-weight="700" fill="#0f172a">%s</text>'
% (x + 16, y + 32, tfs, esc(title)))
if note:
add('<text x="%.1f" y="%.1f" font-size="%.1f" fill="#64748b">%s</text>'
% (x + 16, y + 56, STEP_NOTE_FONT, esc(note)))
# ---- 画布 ----
add('<rect x="0" y="0" width="%d" height="%d" fill="#ffffff"/>' % (W, H))
# ---- 标题 ----
add('<text x="%d" y="44" font-size="%d" font-weight="700" fill="#0f172a">%s</text>'
% (PAD, TITLE_FONT, esc("Net 层阻塞模型 · pending 请求架构")))
add('<text x="%d" y="70" font-size="%d" fill="#64748b">%s</text>'
% (PAD, SUB_FONT,
esc("把「等数据」从执行者内的自旋，改为执行者外的登记 —— 调用方在自己上下文睡眠，"
"netTask 零占用地服务整个队列")))
# ---- 图例 ----
lx = PAD
for color, label in [(C_CALLER, "调用方任务"),
(C_ACTOR, "netTask（唯一执行者）"),
(C_CHIP, "CH395F 芯片"),
(C_TICK, "主循环节拍 ~1ms")]:
add('<rect x="%.1f" y="100" width="16" height="16" rx="4" fill="#ffffff" '
'stroke="%s" stroke-width="2"/>' % (lx, color))
add('<text x="%.1f" y="112" font-size="%.1f" fill="#475569">%s</text>'
% (lx + 24, LANE_FONT, esc(label)))
lx += 30 + text_w(label, LANE_FONT) + 18
# ---- 布局参数 ----
LANE_Y, LANE_H = 140, 600
LB_X, LB_W = PAD, 440
MB_X, MB_W = LB_X + LB_W + 30, W - PAD - (LB_X + LB_W + 30)
STEP_H = 74
STEP_GAP = 30
sx, sw = LB_X + 24, LB_W - 48
# 左栏背景
add('<rect x="%d" y="%d" width="%d" height="%d" rx="14" fill="#f8fafc" '
'stroke="#64748b" stroke-opacity="0.28"/>' % (LB_X, LANE_Y, LB_W, LANE_H))
add('<text x="%d" y="%d" font-size="%.1f" font-weight="700" fill="#334155">%s</text>'
% (LB_X + 18, LANE_Y + 28, PANEL_TITLE_FONT, esc("调用方任务（消费者）")))
# 左栏四个步骤
step_y = []
y = LANE_Y + 56
for i, (title, note) in enumerate(CALLER_STEPS):
color = C_ACTOR if i == 2 else C_CALLER
bg = BG_ACTOR if i == 2 else BG_CALLER
box(sx, y, sw, STEP_H, color, bg, title, note)
step_y.append(y)
if i < len(CALLER_STEPS) - 1:
line(sx + sw / 2, y + STEP_H, sx + sw / 2, y + STEP_H + STEP_GAP,
color, head=True)
y += STEP_H + STEP_GAP
# 分支标签
add('<text x="%.1f" y="%.1f" font-size="12" font-weight="700" fill="%s">%s</text>'
% (sx + sw + 12, step_y[1] + 30, C_OK, esc("是")))
add('<text x="%.1f" y="%.1f" font-size="12" font-weight="700" fill="%s">%s</text>'
% (sx + 14, step_y[1] + STEP_H + 22, C_CANCEL, esc("否，timeout > 0")))
# ---- 快速路径（中栏右上，与"数据已在？"对齐） ----
fp_x = MB_X + 30
fp_w = MB_W - 60
fp_y = step_y[1]
box(fp_x, fp_y, fp_w, STEP_H, C_CHIP, BG_CHIP, FAST_PATH[0], FAST_PATH[1])
line(sx + sw, fp_y + STEP_H / 2, fp_x - 2, fp_y + STEP_H / 2, C_OK, head=True)
# ---- 登记 → 主循环（箭头说明） ----
reg_y = step_y[2]
lw_x, lw_w = MB_X + 30, MB_W - 60
lw_h = 100
lw_y = reg_y - 12
line(sx + sw, reg_y + STEP_H / 2, lw_x - 2, reg_y + STEP_H / 2, C_ACTOR, head=True)
add('<text x="%.1f" y="%.1f" font-size="11.5" fill="#64748b" text-anchor="middle">%s</text>'
% ((sx + sw + lw_x) / 2, reg_y + 14, esc("登记即返回")))
add('<text x="%.1f" y="%.1f" font-size="11.5" fill="#64748b" text-anchor="middle">%s</text>'
% ((sx + sw + lw_x) / 2, reg_y + 28, esc("（微秒级）")))
# ---- 主循环横带 ----
add('<rect x="%d" y="%d" width="%d" height="%d" rx="12" fill="%s" '
'stroke="%s" stroke-opacity="0.5" stroke-width="1.6"/>'
% (lw_x, lw_y, lw_w, lw_h, BG_TICK, C_TICK))
add('<text x="%d" y="%d" font-size="%.1f" font-weight="700" fill="#b45309">%s</text>'
% (lw_x + 16, lw_y + 26, STEP_TITLE_FONT,
esc("netTask 主循环（~1ms 节拍）—— 挂起期间照常服务整个队列")))
n = len(LOOP_STEPS)
gap = 12
cw = (lw_w - 32 - gap * (n - 1)) / n
for i, (name, note, color) in enumerate(LOOP_STEPS):
cx = lw_x + 16 + i * (cw + gap)
cy = lw_y + 42
add('<rect x="%.1f" y="%.1f" width="%.1f" height="46" rx="8" fill="#ffffff" '
'stroke="%s" stroke-opacity="0.6"/>' % (cx, cy, cw, color))
add('<text x="%.1f" y="%.1f" font-size="12.5" font-weight="700" fill="%s">%s</text>'
% (cx + 10, cy + 20, color, esc(name)))
add('<text x="%.1f" y="%.1f" font-size="11" fill="#64748b">%s</text>'
% (cx + 10, cy + 38, esc(note)))
# ---- 五路判定带 ----
ph_y = LANE_Y + LANE_H + 26
ph_h = 234
add('<rect x="%d" y="%d" width="%d" height="%d" rx="14" fill="#f8fafc" '
'stroke="#64748b" stroke-opacity="0.28"/>'
% (PAD, ph_y, W - 2 * PAD, ph_h))
add('<text x="%d" y="%d" font-size="%.1f" font-weight="700" fill="#334155">%s</text>'
% (PAD + 18, ph_y + 28, PANEL_TITLE_FONT,
esc("net_pending_tick()：五路完成 / 取消判定（每轮对每个挂起 fd 按序）")))
# 主循环 → 五路
line(lw_x + lw_w / 2, lw_y + lw_h, lw_x + lw_w / 2, ph_y - 2, C_TICK, head=True)
rows_y = ph_y + 50
rh = 27
for i, (no, cond, act, color) in enumerate(PHASES):
ry = rows_y + i * rh
add('<text x="%d" y="%.1f" font-size="14" font-weight="700" fill="%s">%s</text>'
% (PAD + 26, ry + 16, color, esc(no)))
add('<text x="%d" y="%.1f" font-size="12.5" font-weight="700" fill="#0f172a">%s</text>'
% (PAD + 56, ry + 16, esc(cond)))
add('<text x="%d" y="%.1f" font-size="12.5" fill="#475569">%s</text>'
% (PAD + 230, ry + 16, esc("→ " + act)))
wd_y = rows_y + len(PHASES) * rh + 10
add('<text x="%d" y="%d" font-size="12" font-weight="700" fill="%s">%s</text>'
% (PAD + 56, wd_y + 8, C_CANCEL, esc(WATCHDOG)))
# xTaskNotify 回环 → 调用方睡眠盒
nb_w, nb_h = 250, 62
nb_x = W - PAD - 30 - nb_w
nb_y = ph_y + 46
add('<rect x="%d" y="%d" width="%d" height="%d" rx="10" fill="%s" '
'stroke="%s" stroke-opacity="0.55" stroke-width="1.6"/>'
% (nb_x, nb_y, nb_w, nb_h, BG_CALLER, C_CALLER))
add('<text x="%d" y="%d" font-size="13.5" font-weight="700" fill="%s">%s</text>'
% (nb_x + 14, nb_y + 26, C_CALLER, esc("xTaskNotify")))
add('<text x="%d" y="%d" font-size="11.5" fill="#64748b">%s</text>'
% (nb_x + 14, nb_y + 46, esc("唤醒调用方（结果 = 字节数 / 负错误码）")))
# 五路 → notify（左向短箭头）
line(W - PAD - 30 - nb_w - 40, nb_y + nb_h / 2, nb_x - 2, nb_y + nb_h / 2,
C_CALLER, head=True)
# notify → 调用方睡眠盒（虚线长回环：沿判定带下缘走左外侧）
slp_y = step_y[3]
back_x = PAD + 10
bus_y = ph_y + ph_h - 12
poly([(nb_x + nb_w / 2, nb_y + nb_h),
(nb_x + nb_w / 2, bus_y),
(back_x, bus_y),
(back_x, slp_y + STEP_H / 2),
(sx - 8, slp_y + STEP_H / 2)],
C_CALLER, dash=True, head=True)
# ---- 页脚 ----
add('<text x="%d" y="%d" font-size="%d" fill="#64748b">%s</text>'
% (PAD, H - 24, 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">' % (W, H, W, H, FONT)]
svg.extend(out)
svg.append('</svg>')
return "\n".join(svg)
def main():
svg = build()
os.makedirs(os.path.dirname(OUT), exist_ok=True)
with open(OUT, "w", encoding="utf-8") as f:
f.write(svg)
print("已生成: %s (%d bytes)" % (OUT, len(svg.encode("utf-8"))))
if __name__ == "__main__":
main()