feat(NET): SEND pending 二期落地 + 末块挂起越界缺陷修复(台架复测闭环)

net_pending.c/h 增设第二张挂起表 s_net_send[](与 recv 表完全独立,收发
互不阻塞);net_send_locked 快速路径改为有界自旋,单次等待超出
NET_SEND_SPIN_MS(2ms) 即登记挂起 send,由 net_send_pending_tick 按主循环
节拍分块推进,netTask 最坏停滞由 1s 压到 2ms。net_listener_retry_tick 的
挂起保险扩展到 send 侧;net_close_locked / 网络重建 / 状态对账三路均先
取消再动作(取消必通知,调用方永不挂死)。

台架复测(A/B 对照 + 插桩定位)发现并修复末块挂起越界缺陷:内层"等本块
发完(SENBUF_FREE)"位于写块之后,写完末块时 sent 已 == len,若该次等待越过
2ms 预算便会调用 net_send_pending_register,而登记函数按 sent >= len 拒收
并回 -1,把一次实际已完整交付芯片的发送报成失败。修复为内层等待开头判
sent >= len 即跳出(末块已交付、SENBUF_FREE 等待是纯保守自旋),并置于
超时/自旋判定之前;该守卫同时保证后续登记必伴随 sent < len。

复验:ftp_regression 连续 19 次 11/11;ftp_integrity_test 20 轮 x 64KB
STOR/RETR SHA-256 20/20 一致(两轮),吞吐稳定约 80KB/s;设备日志零
write error;ST-LINK 回读 No difference found。

文档:Net层阻塞模型架构设计.md 补二期设计与新增 9.1 缺陷记录,netTask
栈实测峰值按本次台架 920B 订正为 1116/3840(FTP 传输期 1164);网络自愈
架构设计.md 吸收原监听生命周期文档、新增编号术语导读表,并把 5.2
"实验锚点速查"的 E 编号含义与 E-02 审计编号歧义写在表头(用户反馈该表
E 编号无法读懂)。

门禁:Keil 0 错 0 警;cppcheck / 编码规范 / 乱码零告警;
check_mem_numbers PASS;check_doc_links --all --sections-strict 142 篇 PASS。
This commit is contained in:
2026-10-14 12:05:21 +08:00
parent df13dec479
commit f849c79b7a
24 changed files with 1626 additions and 882 deletions
+25 -17
View File
@@ -2,14 +2,14 @@
# -*- coding: utf-8 -*-
"""生成 docs/images/Net层阻塞模型.svg —— pending 请求模型架构图(纯标准库)。
结构:左右两栏 + 主循环横带 + 五路判定带
左 = 调用方任务(net_recv → 数据已在? → 登记挂起 / 睡任务通知)
结构:左右两栏 + 主循环横带 + recv 五路 / send 四路判定带
左 = 调用方任务(net_recv → 数据已在? → 登记挂起 / 睡任务通知;net_send 同构)
右 = netTask 立即 SPI 读出(快速路径)+ CH395F 芯片
中 = netTask 主循环(~1ms 节拍:net_poll / net_pending_tick / ...)
下 = 五路完成/取消判定 → xTaskNotify 唤醒调用方
中 = netTask 主循环(~1ms 节拍:net_poll / net_pending_tick / net_send_pending_tick / ...)
下 = recv 五路 + send 四路完成/取消判定 → xTaskNotify 唤醒调用方
目的:把"等数据"从执行者内的自旋改为执行者外的登记——登记后调用方在自己上下文
睡眠,netTask 零占用地继续服务整个队列。
目的:把"等数据 / 等发送缓冲"从执行者内的自旋改为执行者外的登记——登记后调用方在自己
上下文睡眠,netTask 零占用地(send 为有界自旋 ≤ NET_SEND_SPIN_MS)继续服务整个队列。
用法(仓库根目录,任意 python3):
python tools/arch_diagram/gen_net_pending_svg.py
@@ -25,8 +25,8 @@ 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
W = 1620
H = 1074
PAD = 40
FONT = "Microsoft YaHei, Segoe UI, PingFang SC, sans-serif"
@@ -74,7 +74,8 @@ FAST_PATH = ("立即 SPI 读出",
LOOP_STEPS = [
("net_poll()", "刷新 readable", C_CHIP),
("net_pending_tick()", "结束挂起", C_TICK),
("net_pending_tick()", "结束挂起 recv", C_TICK),
("net_send_pending_tick()", "推进挂起 send", C_TICK),
("net_listener_retry_tick()", "重试对账", C_ACTOR),
("排空消息队列", "服务所有消费者", "#64748b"),
]
@@ -88,8 +89,8 @@ PHASES = [
]
WATCHDOG = "挂起超时留痕探针(编译期选项,默认关):挂起超阈值仍未结束 → 只 DBG_ERROR 留痕(不强制结束、不伪造返回值)"
FOOT = ("关键性质:挂起期间 netTask 零额外占用(判据复用主循环既有 net_poll 的 readable,"
"不引入额外 SPI 事务);公开 API 不变,既有调用方 / 测试 / 模拟器零改动。")
FOOT = ("关键性质:挂起期间 netTask 零额外占用(recv 判据复用 net_poll 的 readable,不引入额外 SPI;"
"send 有界自旋 ≤ NET_SEND_SPIN_MS,netTask 最坏停滞由 1s 压到 2ms);公开 API 不变。")
# ----------------------------- 生成 -----------------------------
@@ -132,8 +133,8 @@ def build():
% (PAD, TITLE_FONT, esc("Net 层阻塞模型 · pending 请求架构")))
add('<text x="%d" y="70" font-size="%d" fill="#64748b">%s</text>'
% (PAD, SUB_FONT,
esc("把「等数据」从执行者内的自旋,改为执行者外的登记 —— 调用方在自己上下文睡眠,"
"netTask 零占用地服务整个队列")))
esc("把「等数据 / 等发送缓冲」从执行者内的自旋,改为执行者外的登记 —— 调用方在自己"
"上下文睡眠,netTask 零占用地服务整个队列")))
# ---- 图例 ----
lx = PAD
@@ -216,20 +217,20 @@ def build():
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>'
add('<text x="%.1f" y="%.1f" font-size="11.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)))
# ---- 五路判定带 ----
# ---- recv 五路 / send 四路判定带 ----
ph_y = LANE_Y + LANE_H + 26
ph_h = 234
ph_h = 264
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 按序)")))
esc("挂起 recv:五路完成 / 取消判定(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)
@@ -249,6 +250,13 @@ def build():
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)))
# send 四路(net_send_pending_tick,二期)
sg_y = wd_y + 30
add('<text x="%d" y="%d" font-size="12" font-weight="700" fill="%s">%s</text>'
% (PAD + 26, sg_y + 8, C_TICK,
esc("挂起 send 四路:①断连(以已发字节数结束)②推进(每轮至多一块 ≤ NET_SEND_CHUNK_MAX)"
"③写完(以总长度结束)④无进展超时(短写)—— net_send_pending_tick 每轮判定")))
# xTaskNotify 回环 → 调用方睡眠盒
nb_w, nb_h = 250, 62
nb_x = W - PAD - 30 - nb_w