docs: 文档去阶段化——清理"自愈收敛阶段 / L3 pending / 一期二期"标签
CI / L0 静态门禁 (pre-commit) (push) Failing after 2m11s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 17s

代码注释去阶段化已在 task-arch-docs-sync 分支 d770e36 落地,本次把
同一口径补到文档正文(文末变更记录行作为历史保留不动)。

- BSD 使用指南 / 函数调用关系:删 自愈收敛阶段 N、N-32 P1/P2、
  L3 pending、一期二期;职责边界与实现位置改为现状口径
- CH395F_Trap_Records:TRAP-NET-17 / -21 / B10 状态行改述为现行形态
- 链路延迟测试说明:L3 pending → 挂起 recv;P0-a 阶段标签删除
- 模拟器差距清单:N-3 / N-4 / N-6 行改述(对账形态③④、无手动 relisten)
- 错误码传播审计:L3 pending → 挂起 recv;"N-4 二期" → N-4
- 任务规划 README / 登记簿 N-4 / 排期详述 C1 / 基线与待确认 §2.1:
  一期二期 → recv 挂起已落地 / ACCEPT pending 化(§2.1 标题同步)
- CH395F_Test_Guide:阶段 15 标题去掉撞名的"自愈收敛阶段 2"
- IEC104 上行设计说明:门控迁移改现状口径;"随二期" → 未登记具体条目
- 保留可检索锚点:TRAP-NET-*、E* / U* / D10、形态③④、N-4、Phase 15

门禁:check_doc_links.py --all 通过(143 文档、可判定章节引用 1282 处、
0 错 0 警);check_mojibake 全过;CR=0、U+FFFD=0、无 BOM 变化。
本轮只改 .md,无代码改动,故不跑 @build。
This commit is contained in:
2026-10-14 23:03:48 +08:00
parent 1e568b8549
commit 617c84f570
12 changed files with 139 additions and 137 deletions
+5 -5
View File
@@ -108,12 +108,12 @@ CH395F 以太网驱动与 NET 层的实证陷阱:现象、定案根因、修
## TRAP-NET-17 · 快速复连事件面未收到 → 监听静默死亡(E14 复核:非芯片丢事件)
- **状态**:✅(周期对账 `net_reconcile_tick` 是自愈架构 reconciler 的前身;收敛阶段 3 已并入单一 100ms tick)
- **状态**:✅(周期对账 `net_reconcile_tick` 即自愈架构的 reconciler:单一 100ms tick 覆盖①②③④⑤/U11)
- **现象**:单连接监听 socket 快速复连后**永久失效**(后续 SYN 被拒或超时,10s 内不自恢复),芯片其余部分完全正常(其他监听端口照常工作)。两种表现:芯片完成握手但本层收不到 CONNECT 事件 → 控制块滞留 LISTENING;或 DISCONNECT 事件未收到 → 本层仍以为有客户端。两种情况芯片侧都占住单连接监听;应用侧连锁 `net_send` 被拒、读不到 EOF。
- **复现(可信判据,纯客户端;工具 `MDK-ARM/tcp_reconnect_probe.py`)**:待机 60s 后 `:7003` 300ms 快速复连 → 修复前首 2 次成功、之后永久拒连(2/10);FTP `:21` 100ms×50 → 第 29 轮起永久拒连。对照 `:21` 0ms/600ms 与 `:8888` 正常 → 触发条件 = 复连间隔 <~1s + 轻负载。
- **机制(设备侧日志实证)**:① 本层收不到对应事件;② 此后本层**收不到任何中断**,纯事件驱动无路可走;③ 故必须**周期回读芯片状态对账**。**归因更正(E14 复核,2026-10-14,48 轮直读 SINT 矩阵)**:旧"芯片丢中断、芯片天性"结论已被推翻——SINT 可靠锁存事件,"丢失"实为**读清消费竞态**(台架 post-listen drain 吞掉即时到达的 CONNECT,drain-int 探针现场抓获 3/48)与**门控观察伪象**(2/48,SINT 30ms 内即捕获)。对账机制保留不变:事件可被其它合法读者消费,且状态面存在事件覆盖不了的幽灵态。
- **修复(`net_socket.c`)**:
1. **周期对账 `net_reconcile_tick()`**(与 pump 合并为单一 100ms tick):修正失同步形态——①本层 ESTABLISHED 而芯片已无连接→按断开处理;②本层 LISTENING 而芯片已握手→补 accept;③本层 LISTENING 而芯片监听消失→重建;④孤儿监听(B10)→重建。**去抖+冷却**:同一失配连续 2 次才动手,动手后冷却 1s。
1. **周期对账 `net_reconcile_tick()`**(单一 100ms 对账+重建合一 tick):修正失同步形态——①本层 ESTABLISHED 而芯片已无连接→按断开处理;②本层 LISTENING 而芯片已握手→补 accept;③本层 LISTENING 而芯片监听消失→重建;④孤儿监听(B10)→重建。**去抖+冷却**:同一失配连续 2 次才动手,动手后冷却 1s。
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**。三类失同步均有自愈实测计数留痕。
@@ -155,7 +155,7 @@ CH395F 以太网驱动与 NET 层的实证陷阱:现象、定案根因、修
3. **做法**:直接 `ch395f_close_socket()`;`disconnect` 纯属多余且会**制造** DISCONNECT 事件(bit3=1 下必须被消费/预清,否则污染下一条连接,TRAP-NET-12/23 实证);
4. **观测口径**:§5.22 第 1 字节只有 `00H/05H`,第 2 字节(TCP 态)**仅在 byte0=OPEN 时有意义**——关闭后轮询**第 1 字节**等 `00H` 再 open,别拿 byte1 当"卡住"判据。
- **边界(E-02 台架)**:`close` 无 RST 的适用条件——对端配合(收到 FIN 后其内核 close):芯片走 `TIME_WAIT` ~150ms → relisten → 新连接接入;**对端内核存活但不 close**:芯片停在 **`FIN_WAIT_2`(byte0=05H/byte1=06H)长尾**——没有 RST 就拆不掉,**监听恢复受限于对端 close**。不配合场景的兜底 = 芯片自身 TIMEOUT/KeepAlive 拆僵尸会话(判死窗 30~90s,`docs/网络/网络自愈架构设计.md` §5.2 E13)——**不是**应用可加速的路径。
- **应用侧出口 = `net_drop_conn(fd)`**(自愈收敛阶段 3):netTask 侧走驱动 `sock_reset` QUARANTINE(FIN+排渣+排空事件+等 byte0=00H,400ms 底)+ 本层收口 CLOSED + `auto_relisten` 登记重监听(≤1ms 后 `net_listener_tick` 执行);**保监听不毁**(单连接模型不得 `net_close` 监听 fd)。对端不 close 时复位机等在 `net_poll` 步进里(`ch395f_sock_reset_poll`),对端 FIN 到达即自动走完——**不搁浅**。
- **应用侧出口 = `net_drop_conn(fd)`**:netTask 侧走驱动 `sock_reset` QUARANTINE(FIN+排渣+排空事件+等 byte0=00H,400ms 底)+ 本层收口 CLOSED + `auto_relisten` 登记重监听(≤1ms 后 `net_listener_tick` 执行);**保监听不毁**(单连接模型不得 `net_close` 监听 fd)。对端不 close 时复位机等在 `net_poll` 步进里(`ch395f_sock_reset_poll`),对端 FIN 到达即自动走完——**不搁浅**。
## TRAP-NET-09 · 沉降窗:PHY link up 后 / close 后不能立即 open
@@ -228,7 +228,7 @@ CH395F 以太网驱动与 NET 层的实证陷阱:现象、定案根因、修
## TRAP-NET-21 · IP 显示段序与对端地址(getsockname ≠ 对端)
- **状态**:✅(自愈收敛阶段 3 收尾修复)
- **状态**:✅
- **现象**:FTP 日志把 IP 打成 `100.1.168.192`(字节反转),且打印的是**本机** IP:21 而非客户端地址——排查连接来源时被误导。
- **根因(定案)**:① `net_inet_ntoa` 段序反转——`NET_NTOHL` 后主机数字的 **MSB 才是点分首段**,原实现低段在前;② lftpd 打印 `net_getsockname` = 本机监听地址(端口恒 21),对端地址应读 `net_getpeername`。PASV 227 消费点做了 `net_htonl` 再 MSB 拆,**双重反转恰好正确,勿误判**。
- **修复**:`net_inet_ntoa` 段序改 MSB 首(MCU+模拟器同步);新增 `net_getpeername`(读 CONNECT 事件缓存,零 SPI);lftpd 改打印**对端** IP:port(台架判据:日志 `connection received from 192.168.1.x:<高位端口>`)。
@@ -276,7 +276,7 @@ CH395F 以太网驱动与 NET 层的实证陷阱:现象、定案根因、修
| B7 | 低 | `ch395f_test_task.c` Phase 5 | 单次写 4093B 超 1KB 发送缓冲与 2048 DMA 载荷 → 整块被丢;注释仍写旧上限。写路径金丝雀(A6)会打 `[ERR]` | ⏳ 待修(chunk 改 ≤1024 或分块) |
| B8 | 低 | `ch395f_test_task.c` Phase 4 | 把 sock6 缓冲重排到块 24-27,与 `net_init` 固定布局中 sock4 的 24-27 **交叠**(§5.45 禁止) | ⏳ 待修 |
| B9 | 低 | `ch395f_reuse_bench.c`、`net_socket.c` | bench 用 `get_phy_status()!=0` 判链路(01H=断开也成立,应 `!= CH395F_PHY_DISCONN`);`NET_PHY_CHECK_INTERVAL_MS` 死宏;无芯片版本门控(§5.16 <0x44 不支持 ALL 版、§5.52 bit3/4 需 ≥0x46,实测 0x4A 无影响) | ⏳ 待修(前两项死代码/卫生) |
| B10 | **中** | `net_reconcile_tick` 认领范围 + `handle_disconnect_event` 释放分支 | **孤儿监听 → 端口永久拒连**:释放分支把状态置 CLOSED 等"应用重新监听",但 `ui_net_sink` 只在 `net_recv` 返 0(EOF)时才清 `g_client`,而 EOF 已被事件分支消费 → net 层等应用重建 / 应用等 net 层给 EOF / 对账只裁 ESTABLISHED·LISTENING 直接跳过 / 芯片不会自己回 LISTEN,**四方互等**。对账①③都要求本层处于 ESTABLISHED/LISTENING,**孤儿态恰好落在两类之外** | ✅ 已修:对账新增**形态④**认领孤儿(`in_use`+`state==CLOSED`+`auto_relisten`+`type==STREAM`+`local_port!=0`,芯片侧不在 LISTEN)→ `net_relisten_try`。⚠ `auto_relisten` 是决定性门:少了它出向连接会被误判孤儿 relisten 成监听器。⚠ ④ 的副作用:`net_recv` 的 EOF 是**边沿**——④抢先 relisten 会把慢消费者的 EOF 永久吞掉。**根治出口 = `net_drop_conn` + 生命周期设计**(自愈收敛阶段 3 已落):原理与决策记录 → `docs/网络/网络自愈架构设计.md` §1.1~§1.4、§4.6、§10 |
| B10 | **中** | `net_reconcile_tick` 认领范围 + `handle_disconnect_event` 释放分支 | **孤儿监听 → 端口永久拒连**:释放分支把状态置 CLOSED 等"应用重新监听",但 `ui_net_sink` 只在 `net_recv` 返 0(EOF)时才清 `g_client`,而 EOF 已被事件分支消费 → net 层等应用重建 / 应用等 net 层给 EOF / 对账只裁 ESTABLISHED·LISTENING 直接跳过 / 芯片不会自己回 LISTEN,**四方互等**。对账①③都要求本层处于 ESTABLISHED/LISTENING,**孤儿态恰好落在两类之外** | ✅ 已修:对账新增**形态④**认领孤儿(`in_use`+`state==CLOSED`+`auto_relisten`+`type==STREAM`+`local_port!=0`,芯片侧不在 LISTEN)→ `net_relisten_try`。⚠ `auto_relisten` 是决定性门:少了它出向连接会被误判孤儿 relisten 成监听器。⚠ ④ 的副作用:`net_recv` 的 EOF 是**边沿**——④抢先 relisten 会把慢消费者的 EOF 永久吞掉。**根治出口 = `net_drop_conn` + 生命周期设计**:原理与决策记录 → `docs/网络/网络自愈架构设计.md` §1.1~§1.4、§4.6、§10 |
## 台架注入陷阱(方法论,持续补充)