docs(网络): 自愈架构 §4.1 形态详解 / §4.10 读即清审计 / §1.5 横向对照

四块内容,都是"把已经做完的事写进文档",无新增设计。

1. §4.1 形态表扩成 6 小节:两个所有者 / 四个词 / 形态表(补"芯片命令"列与
   U11 独立行)/ 每个形态为什么长这样、怎么验的 / 为什么 ①③⑤ 常态 0 命中 /
   M3 可疑门与沿革。
   ⚠ 修一处文档 bug:原 ④ 行实际描述的是 U11,真正的 ④ 没有行。已补 U11
   独立行,并在 ⚠ 注记里记录这次更正及其 U12 后果。

2. §4.10 读即清信源审计:两个读即清寄存器与两级门控、现存读清点全量清单
   (产品代码 6 处)、已根除的三条互吞实例、一处"看着像缺陷其实是配对
   消费"、新增一处读清的三条准入判据 + 结构性残余。AGENTS.md 的 CH395F
   单连接 socket 条目加指针。

3. §1.5 与主流 offload 驱动的代码级对照(正面回答"是不是过度设计"):
   ioLibrary close()/listen() 原文、四个机制一一映射、三条约束差异表、
   "死等把代价挪到运行时"、lwIP/Zephyr 对照、诚实清单(可省 16 B / 不可省
   沉降窗 + D10 + listen 前排清 + 登记执行分离)、唯一杠杆是芯片。

4. 模块归属修正(承接 63cf73b 的 net_events.c 抽出):
   - §11.5 新增一节,含"为什么是一个模块而不是两个"(对账真实调用事件
     处理器 2 处 + NET_RECON_STABLE_DEATH 两边共用)与三处非纯搬移;
   - §9 行数快照更新,并加警告:这类快照**当天就会漂移**,是地图不是判据;
   - §1.5 的 net_listener.c 行数随注释精简同步(508/277 → 386/155)。
   引用修正波及 5 个文件:BSD_Socket_API 使用指南文件职责表(拆出
   net_events.c 行)、函数调用关系 §4.8 标题、Net 层阻塞模型两处形态⑤表格、
   CH395F_Trap_Records 两处"对应文件"(保留"原在 net_socket.c"的历史)。
   ⚠ doc-links 只校验 § 编号存在性,照不出"函数在哪个文件"——这类归属
   漂移门禁不拦,必须人工扫。

验证:check_doc_links --all --sections-strict PASS(2146 处引用,可判定
1263,无法判定 0,142 文档);ci_local L0 32 钩子 + L0.5 953/953 全过。
This commit is contained in:
2026-10-14 18:18:06 +08:00
parent dd51221ebc
commit 2a6080827d
6 changed files with 286 additions and 25 deletions
+2 -2
View File
@@ -117,7 +117,7 @@ CH395F 以太网驱动与 NET 层的实证陷阱:现象、定案根因、修
2. `handle_disconnect_event` LISTENING 分支:回读芯片状态——已不可监听即重建。
- **踩坑记录(务必先读)**:基于单次状态读的重建动作放在 accept 热路径 → 把"刚 open/listen 尚未生效"的瞬态误判为失配 → 监听反复重建直至 `relisten give up` → **三个监听口全部死亡(风暴)**。**结论:凡基于单次状态读的重建动作,必须去抖。**
- **回归基线**:`:7003` 300ms×10:**10/10**;`:21` 100ms×50:**50/50**;`:21` 0ms/600ms×50:**50/50**;`:7003` 200ms×20:**20/20**;FTP 10×64KB SHA-256:**10/10**;`relisten give up`:**0**。三类失同步均有自愈实测计数留痕。
- **对应文件**:`net_socket.c`(`net_reconcile_tick`);`MDK-ARM/tcp_reconnect_probe.py`。
- **对应文件**:`net_events.c`(`net_reconcile_tick`;原在 `net_socket.c`,2026-10-14 抽出);`MDK-ARM/tcp_reconnect_probe.py`。
## TRAP-NET-20 · FTP 数据连接三连故障——三重定案
@@ -135,7 +135,7 @@ CH395F 以太网驱动与 NET 层的实证陷阱:现象、定案根因、修
- **定案三:LIST 吞包 = 背靠背小段写毒化芯片 TX**:决定性对照——同一目录,LIST #1(行间天然间隔)通过;LIST #4/#7(每行一次 `net_send` ~60B 背靠背小段)必挂。芯片对同一连接的**背靠背多段小写入**会毒化 TX(芯片报 SEND_OK 但对端全部丢弃,无 RST 无 DISCONNECT);RETR 1KB 满块连发不受影响。**修复**:`send_list`/`send_nlst` 整份目录**一次性批量发送**(static 1536B 缓冲;注意 `lftpd_inet_write` 成功返回**字节数**非 0)。
- **与 TRAP-NET-17 的关系**:周期对账对常驻监听器有效;FTP 数据通道是"活 1 秒就死"的短命监听器,对账②无幽灵甄别时既救不全又帮凶。本条把"看状态补 accept"内联进 accept 热路径(短去抖、无冷却)+ 端口甄别,对账②保留为兜底网。
- **教训(总纲)**:**CH395F 的"成功"(中断位/状态码)只代表芯片本地动作完成,不代表对端收到;判定必须回到对端可见证据(主机侧收发)+ 手册语义(FUN_PARA §5.52、状态码 §5.22)**。
- **对应文件**:`net_socket.c`(`net_lost_connect_probe`/closed-with-data accept/`net_reconcile_tick`②/`last_peer_port`)、`net_types.h`、`lftpd.c`(批量发送);台架 `test/board/ch395f_reuse_bench.{c,h}` + `test/host/ch395f_reuse_host.py`(主分支存档)。
- **对应文件**:`net_events.c`(`net_lost_connect_probe` / `net_reconcile_tick`②;原在 `net_socket.c`,2026-10-14 抽出)、`net_socket.c`(closed-with-data accept)、`net_types.h`(`last_peer_port`)、`lftpd.c`(批量发送);台架 `test/board/ch395f_reuse_bench.{c,h}` + `test/host/ch395f_reuse_host.py`(主分支存档)。
---