docs: 文档去阶段化——清理"自愈收敛阶段 / L3 pending / 一期二期"标签
代码注释去阶段化已在 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:
+4
-4
@@ -13,7 +13,7 @@
|
||||
> | `暂缓-RS485.md` | B2 RS-485 整簇冻结清单（用户决定） | 极少 |
|
||||
> | `登记簿.md` | N-x / S-x / T-x 长期登记（网络 / 存储 / 硬件 / 测试 / 报告并轨） | 中频——新发现进对应表 |
|
||||
> | `测试与架构专项.md` | P1-10 收尾 + S1x / A-x 专项 | 低频 |
|
||||
> | `基线与待确认.md` | 待确认 · 设计基线（pending 二期 / 错误码四要素）· 诊断基线 · 内存预算 | 参考，少改 |
|
||||
> | `基线与待确认.md` | 待确认 · 设计基线（ACCEPT pending 化 / 错误码四要素）· 诊断基线 · 内存预算 | 参考，少改 |
|
||||
>
|
||||
> **怎么用**：想知道"现在该做什么、按什么顺序" → 本文件 **§2**；想知道"当前波次任务卡状态 / 验收判据 / 并行道" → `W1-采集保护收尾.md`；
|
||||
> 想知道"某条待办的来龙去脉" → 按编号查 `登记簿.md` / `测试与架构专项.md`；想知道"还差哪些验证" → `排期详述.md` §2。
|
||||
@@ -64,7 +64,7 @@
|
||||
| 类别 | 数量 | 条目 |
|
||||
|---|---|---|
|
||||
| P1 收尾 | 1 | P1-10 测试固件构建实测（`测试与架构专项.md` §1） |
|
||||
| 网络 | 5 | N-2（49s 日志静默，**低风险观察项**）· N-3（L5 基线重验）· N-4（pending 二期）· N-16（A2/A4 负向台架）· N-17（探针窗口心跳缺口） |
|
||||
| 网络 | 5 | N-2（49s 日志静默，**低风险观察项**）· N-3（L5 基线重验）· N-4（ACCEPT pending 化）· N-16（A2/A4 负向台架）· N-17（探针窗口心跳缺口） |
|
||||
| 存储 / 日志 | 3 | **S-3（USART1 TX-only 根治）** · S-4（dhara 重试自旋）· S-5（可选全序列卷锁） |
|
||||
| 数据正确性 | 1 | **N-21（dhara `is_free`/`copy`，全簿最高风险）** |
|
||||
| 结构 / 健壮性 | 9 | N-20（Error_Handler 死循环）· N-22（写回 flush）· N-23（注册校验残余白名单）· N-24（日志逐条开关）· N-25（性能/语义簇）· N-26（NAND DMA 断言）· N-27（内存优化簇，三件套 ✅ 前半落地）· N-28（Flash 死代码簇）· **N-33（栈余量收口，W1）** |
|
||||
@@ -101,7 +101,7 @@
|
||||
| **W1 采集+保护收尾** | **里程碑制 + 并行道**：M1 台架闭环 ✅ 达成（B6 ✅→N-33 ✅）∥ M2 功能面（代码道 B7 ✅→{B8∥B9}）→ M3 送检（B10，Fixed Date）——任务卡/判据/写范围见 `W1-采集保护收尾.md` | **用户决定（2026-10-12）：先把 ADC 采集、保护等相关功能完成**。B4/B5 代码已落地但未台架闭环、功能面不完整（定值不落盘 / 无频率保护 / 无动作记录 / 栈两处 FAIL）——本波收口到"可用 + 可验收"；真约束只有**台架**与**送检窗口**两个稀缺资源，其余任务按写范围切分并行 |
|
||||
| **W2 数据正确性** | **N-21** dhara `is_free`/`copy`（报告 N-12/13） | 低概率、后果重（数据丢失）；修复须配主机侧移植层测试，一并补报告"覆盖率"缺口 |
|
||||
| **W3 预算与内存** | **N-27 后半**：R-9 池 40→16 KB → R-2 后半（54 KB→CCM）→ R-3~R-6 逐项评估 | 依赖 W1 三件套产出的台账数据；**B5 堆扩容后 CCM 只剩 ≈8 KB**（56 KB 堆），R-2 后半更被堵死（解锁链见 `docs/内存管理/RAM预算台账.md` §3） |
|
||||
| **W4 结构债** | **N-20 → C6（S-3）→ C3（N-2+N-24）→ C1 pending 二期 → C5（含 N-23 残余）→ N-22/N-25/N-26/N-28**（详表 `排期详述.md` §1） | 无紧急，按性价比排：C6 灭 IWDG 误复位机制根源；C1 体量大、验证重，放后（N-23 钩子已落地 2026-10-12，残余并入 C5） |
|
||||
| **W4 结构债** | **N-20 → C6（S-3）→ C3（N-2+N-24）→ C1 ACCEPT pending 化 → C5（含 N-23 残余）→ N-22/N-25/N-26/N-28**（详表 `排期详述.md` §1） | 无紧急，按性价比排：C6 灭 IWDG 误复位机制根源；C1 体量大、验证重，放后（N-23 钩子已落地 2026-10-12，残余并入 C5） |
|
||||
| **W5 验证常态** | P1-10 收尾 · T-7 CI · D2 N-3 · D5 N-16 · D6 N-17 · D7 串口助手 · S12 · S1-c · A-5（详表 `排期详述.md` §2） | 窗口性，逢机顺带，不单独排期 |
|
||||
| **W6 UI 扩展** | U4 残余（golden + 字符集差集挂门禁）→ U1 令牌层 → U2/U3 → **27 页**落地 | 产品驱动、体量大，需单独立项（顺序按 `docs/问题记录/项目审查与优化建议报告.md` §6.5）；**本轮不排期（2026-10-11 已确认）** |
|
||||
| **W7 仓库决策** | **N-29** `.git` 149 MB + 图片 36.3 MB | **已决策（2026-10-11）：暂不处理、登记观察**——推送/协作前重评（`git filter-repo` 历史重写影响未推送提交与协作者） |
|
||||
@@ -118,7 +118,7 @@ W2 数据 N-21 dhara is_free/copy（配主机侧移植层测试）
|
||||
↓
|
||||
W3 预算 R-9 池瘦身 → R-2 后半（54KB→CCM）→ R-3~R-6 评估
|
||||
↓
|
||||
W4 结构 N-20 → C6(S-3) → C3(N-2/N-24) → C1 pending 二期 → C5(含 N-23 残余) → N-22/25/26/28
|
||||
W4 结构 N-20 → C6(S-3) → C3(N-2/N-24) → C1 ACCEPT pending 化 → C5(含 N-23 残余) → N-22/25/26/28
|
||||
↓
|
||||
W5 验证 P1-10 · T-7 CI · D2/D5/D6/D7 · S12 · S1-c · A-5
|
||||
↓
|
||||
|
||||
+10
-10
@@ -11,34 +11,34 @@
|
||||
|
||||
## 2. 设计基线（供后续接入参考）
|
||||
|
||||
### 2.1 pending 二期设计基线（SEND 已落地 / ACCEPT 待办）
|
||||
### 2.1 ACCEPT pending 化设计基线（recv/send 挂起已落地）
|
||||
|
||||
> **来源**：recv/send 架构现状见 `docs/网络/Net层阻塞模型架构设计.md`（演进史查 git 历史）；
|
||||
> 本节仅保留**二期仍要用的设计基线**。
|
||||
> 本节仅保留 **ACCEPT pending 化仍要用的设计基线**。
|
||||
|
||||
**一期已验证的机制骨架**（二期沿用，勿重新发明）：独立静态 pending 表 + `net_pending_tick`
|
||||
**已验证的机制骨架**（ACCEPT 沿用，勿重新发明）：独立静态 pending 表 + `net_pending_tick`
|
||||
主循环按节拍结束挂起（recv 五路：数据/到点/断连/同 fd 串行/重建取消必通知）+ 登记守卫（每 fd 至多一个、
|
||||
不覆盖、拒绝 netTask 自等待）+ 挂起超时留痕探针（tripwire，只留痕不伪造返回值）。
|
||||
|
||||
**二期扩展点**：
|
||||
**扩展点**：
|
||||
|
||||
| 项 | 目标 | 对应缺陷 | 状态 |
|
||||
|---|---|---|---|
|
||||
| **SEND pending** | 发送续传改为"登记 → send_ready 完成"，消除 1s/分片 stall 对队列的冻结 | E-02 残余（SEND 位置） | ✅ **2026-10-14 已落地**（`net_send_pending_tick` + 有界自旋 `NET_SEND_SPIN_MS`；架构见 `docs/网络/Net层阻塞模型架构设计.md` §4.5/§5.5/§7） |
|
||||
| **ACCEPT pending** | accept 等待改为"登记 → CONNECT 事件完成"，退役 100ms/200ms 轮询循环 | E-06（accept 轮询计时失真） | ⬜ 待做 |
|
||||
|
||||
**二期门禁**（一期门禁的加强版）：
|
||||
**ACCEPT 门禁**（在已落地机制的门禁基础上加强）：
|
||||
|
||||
1. CH395F NET 层全套件（含一期未跑的 Phase 7 / Phase 10，视 RAM 预算）；
|
||||
2. L3/L5 基线重锁（一期已重锁 M3，二期须再锁）；
|
||||
1. CH395F NET 层全套件（含此前未跑的 Phase 7 / Phase 10，视 RAM 预算）；
|
||||
2. 延迟探针 L3/L5 基线重锁（recv 挂起落地时已重锁 M3，ACCEPT 落地须再锁）；
|
||||
3. `e02_probe.py` **探针族扩充**：close / reconfig / EOF / disconnect-during-pending 四专项；
|
||||
4. `ftp_regression.py`（D20）+ E-06 假 425 场景**独立重跑**（一期是借 M3 压力档覆盖的）；
|
||||
4. `ftp_regression.py`（D20）+ E-06 假 425 场景**独立重跑**（recv 挂起那轮是借 M3 压力档覆盖的）；
|
||||
5. UI 远端推流压力 + timeSync 三场景；
|
||||
6. 产品 `@test` 闭环 + ST-LINK 全片回读；
|
||||
7. `ram_report.py` / `stack_report.py` 前后对比（铁律）；
|
||||
8. 看门狗接 selftest 留痕 + 模拟器差距清单 +1（`net_socket_sim.c` 无法建模 pending）。
|
||||
|
||||
**已知代价（延续一期，需文档化）**：pending 完成判定随主循环节拍运行，被长操作占用时超时
|
||||
**已知代价（延续，需文档化）**：pending 完成判定随主循环节拍运行，被长操作占用时超时
|
||||
顺延（~1ms 级）；**SEND 已 pending 化（2026-10-14）**，该顺延面已收窄——发送停滞不再顺延整层；
|
||||
剩余 ACCEPT 化不改变此结论。
|
||||
|
||||
@@ -84,7 +84,7 @@
|
||||
| timeSyncTask 栈峰值 | 792 / 2048（余量 61%） | 同上 |
|
||||
| adcTask 栈峰值（B1，2026-10-10 新建） | **496 / 2048**（余 1552 B / 75%，台架 `@test` 实测）；静态最坏链 504 B | 台架 `@test` + `stack_report.py` |
|
||||
| testTask 栈峰值（产品态空转） | 496 / 8192（余量 93%） | 同上 |
|
||||
| 队列响应性（挂起客户端） | 92.5ms（pending 一期） | `e02_probe.py` |
|
||||
| 队列响应性（挂起客户端） | 92.5ms（recv 挂起落地后） | `e02_probe.py` |
|
||||
| M3 压力档帧周期 | med 60.1 / p95 66.4 / max 69.3ms，零尖峰 | `链路延迟测试说明.md` |
|
||||
|
||||
## 4. 内存预算（支撑 §3 与定栈规则）
|
||||
|
||||
+1
-1
@@ -12,7 +12,7 @@
|
||||
| **N-20** | **`Error_Handler` 统一降级** | 一处初始化失败 = 整机挂死（只剩 IWDG 兜底）→ 记自检 + 禁用该子系统 + 其余照常。详见 `登记簿.md` | 报告 N-03c |
|
||||
| **C6** | **USART1 TX-only 结构根治（S-3）** | 灭 ORE 僵尸机制根源（2026-10-02 台架 IWDG 误复位的机制根源）：改 `.ioc` 令 USART1 不使能 RX / PA10 不复用为 `USART1_RX` → CubeMX 重生成 → 跑 `check_cubemx_survival.py`。结构性改动，需单开一轮 + 复跑台架闭环 | S-3 |
|
||||
| **C3** | **存储侧日志管线（N-2 + N-24）** | 丢弃可观测性**代码已具备**（`console_log.c` `s_con_drop`+`[ERR] CONSOLE dropped`、`sys_log_mcu.c` 队列满 `DBG_ERROR`、TX 僵尸通道自愈）；V5 30 min 日志**未复现 49s 静默**（运行期 >10s 静默全为 ~28s、均在 `e02_probe` 窗口内＝N-17）。剩余：与 S8（非阻塞日志）合并评估 + 日志逐条 `f_open/f_write/f_close` 改造评估（N-24） | N-2 / N-24 |
|
||||
| **C1** | **pending 二期（ACCEPT + SEND）** | 沿一期机制扩展；同期消化 E-25（net_select 语义）、E-24/E-27/E-28（跨上下文收口）；基线重锁 + 探针族扩充 + 看门狗接 selftest。**设计基线见 `基线与待确认.md` §2.1** | N-4 |
|
||||
| **C1** | **ACCEPT + SEND 阻塞路径 pending 化** | 沿用已落地的 recv 挂起机制扩展；同期消化 E-25（net_select 语义）、E-24/E-27/E-28（跨上下文收口）；基线重锁 + 探针族扩充 + 看门狗接 selftest。**设计基线见 `基线与待确认.md` §2.1** | N-4 |
|
||||
| **C5** | 一档剩余 | E-15（ringbuf 定去留——**已确认零调用者，倾向删除**）、E-61（SD2506 注释订正）、E-16（cfg_file 段名长度）、E-26（UDP 定案，倾向移除）、E-23、E-30；**N-23 残余**（`KNOWN_GAPS` 白名单清理 + `app_cfg.h` 未接线开关，见 `登记簿.md`）。**E-49（RS485 DE 收尾）已移入 `暂缓-RS485.md`** | 一档/二档 |
|
||||
| **N-22/25/26/28** | 评估簇 | 写回 flush / 性能与语义一致性 / NAND DMA 断言 / Flash 死代码——逐项见 `登记簿.md` 对应行，随窗口评估 | 报告各条 |
|
||||
|
||||
|
||||
+1
-1
@@ -13,7 +13,7 @@
|
||||
|---|---|---|---|---|
|
||||
| N-2 | **49s 全系统日志静默（defaultTask/NAND syslog 排空停滞）**——串口日志 49s 无行，期间 net 栈照常处理外部连接 → 日志管线停滞，队列满后各任务日志行被丢；系统功能不受损 | 2026-09-22（L3 台架 F2，gen 181） | **A/B 归因：既有存储侧现象**。**2026-10-03 降级为低风险观察项**：① 丢弃可观测性**代码已具备**（`console_log.c` `s_con_drop` + `[ERR] CONSOLE dropped`；`sys_log_mcu.c` 队列满 `DBG_ERROR`；UART TX 僵尸通道自愈）；② V5 30 min **未复现 49s**（>10s 静默全为 ~28s、均在 `e02_probe` 窗口内＝N-17）。**残余待办**：与 S8（非阻塞日志）合并评估（C3） | `错误码传播审计.md` E-02 阶段二 |
|
||||
| N-3 | **L5 队列往返基线（1223/988µs）的 L3 后重验**——L5 测 DONTWAIT 队列全程；L3 对该路径逐位不变 → 机制上无影响，但基线数值属分片时代，严格重锁需跑一轮 Phase 13（需 PC peer） | 2026-09-22（L3 收尾留档） | 低风险：10ms/100ms 阈值余量 >8×；下次 Phase 13 窗口顺带重锁即可 | `链路延迟测试说明.md` §6.4 L5 注¹ |
|
||||
| N-4 | **pending 机制二期：ACCEPT 阻塞路径 pending 化**（SEND 部分已完成）——E-06、E-20、E-21 剩余分量共用该机制扩展；届时 L3/L5 基线再重锁、探针族扩充、看门狗接 selftest 留痕、模拟器差距清单 +1 | — | 一期（RECV）已落地；二期 **SEND 已于 2026-10-14 落地**（构建门禁过、台架复测待做），**ACCEPT 仍待做**（收益性质不同，优先级低——见 `Net层阻塞模型架构设计.md` §10 判据）。架构现状见 `Net层阻塞模型架构设计.md`，ACCEPT 设计基线见 `基线与待确认.md` §2.1 | `错误码传播审计.md` 第二档 #2 |
|
||||
| N-4 | **ACCEPT 阻塞路径 pending 化**（recv/send 挂起机制已落地，扩展到 accept）——E-06、E-20、E-21 剩余分量共用该机制扩展；届时延迟探针 L3/L5 基线再重锁、探针族扩充、看门狗接 selftest 留痕、模拟器差距清单 +1 | — | **recv 挂起已落地**；**send 挂起已于 2026-10-14 落地**（构建门禁过、台架复测待做），**ACCEPT 仍待做**（收益性质不同，优先级低——见 `Net层阻塞模型架构设计.md` §10 判据）。架构现状见 `Net层阻塞模型架构设计.md`，ACCEPT 设计基线见 `基线与待确认.md` §2.1 | `错误码传播审计.md` 第二档 #2 |
|
||||
| N-16 | **A2/A4 专项场景台架验证待办**（正常路径已实测零回归）：① PHY 拔线负向测试——断链需断 **DTU 侧**线缆或关**受管交换机端口**；② A2 芯片级 `net_init` 失败分支（需 SPI 故障注入）；③ A4 短写压测（需远显客户端 + UI 推流压力） | 2026-10-03（台架拓扑 = CH395↔交换机，拔线操作受限） | 待专项台架窗口 | `实机测试实施指南.md` §10 |
|
||||
| N-17 | **`time_sync` 30s 挂起客户端掉线 + 监听重建期间，网络任务心跳缺口达 800ms~1s（声明 stall 但未复位）。**待办**：定位监听重建为何阻塞 NET/FTP/UI；评估缩短重建重试（5×2s）或让掉线路径不阻塞其它任务 | 2026-10-03（V5 台架） | V5 长跑 44 次 `task stall: mask=0x00000001`，**100% 与 `e02_probe` 的 30s 挂起客户端触发 `time_sync: no TIME packet in 30s, drop conn` → 监听重建（约 4s）重合**；隔离实验（仅 FTP，120s）**0 次 stall** → 探针场景专属。缺口（~1s）< IWDG 最坏超时（1701ms），余量仅 ~0.7s。 | `实机测试实施指南.md` §4；`../子系统设计/看门狗设计说明.md` |
|
||||
| N-30 | **relisten 沉降段统一到驱动 `sock_reset` 原语受阻**——"去重复实现"的收口已实测回退：原语版 `ftp_abort_probe` RST **0/10**、FIN **0/5**（中止后首笔复连仍被截断到 ≤2048B），另新增 `sock_reset_sync timeout (600ms)` 与 `close: sock_reset not done` 两条 `[ERR]`；同场 net 层自建序列 **10/10 + 5/5** | 2026-10-14（同一块板 A/B，判据 `test/host/ftp_abort_probe.py`；快复连 50/50、背靠背 30/30 两版都过 → 失效面精确落在"中止后首笔复连"） | **现状 = `net_listener.c` 保留自建排渣序列**（排空 + CLOSE + 排事件 + 等 CLOSED，30 ms 重试轮持续清）。重开前置三条语义：① 隔离窗内**持续**排空/关闭（残渣在 CLOSE 之后才落进 RX，一次排空接不住）② **复用让位**（复位机不得拆上层刚在同一芯片 Socket 上重建的监听）③ `net_sock_reset_sync` 改"已在运行 = 加入等待"（`begin` 返 -1 ≠ 失败） | `../网络/网络自愈架构设计.md` §8 延后项 1、§5.2 E16；`../问题记录/CH395F_Trap_Records.md` TRAP-NET-18 |
|
||||
|
||||
@@ -131,7 +131,7 @@
|
||||
数据通道复用同一 socket（accept 返回即 listen fd）；EOF 时 net 层 auto_relisten，
|
||||
应用层**不得**关 fd（`client == listen` 分支）；仅模拟器多连接后端（fd 不同）显式关。
|
||||
- **门控 + 兜底**：`net_listener_armed`/`net_can_read`（纯 RAM 读）省无谓 RPC 往返
|
||||
（自愈收敛阶段1：门控从只认 ESTABLISHED 的 `net_can_accept` 迁移——旧门控把监听
|
||||
（门控不用只认 ESTABLISHED 的 `net_can_accept`——那会把监听
|
||||
服役窗口全挡掉，CONNECT 事件补 accept 探针从不运行）；
|
||||
每 32 轮无条件 recv 一次防 RECV_OK 事件未收到（ui_net_sink I-1/I-2 先例）。
|
||||
- **网络代次自愈**：`net_get_generation()` 变化 → 关旧 fd 重建监听（netTask
|
||||
@@ -177,7 +177,7 @@
|
||||
7. **后连优先未实现**（V0.1 = 首到优先）：单连接 socket 连接态无法 accept，
|
||||
旧会话结束前新主站接入被拒；后连优先需 net 层（CH395F 单连接模型）支持，
|
||||
真需要冗余切换时随 net 扩展立项。
|
||||
8. 公共地址固定 1、监听端口固定 2404：可配置化（config.ini）随二期。
|
||||
8. 公共地址固定 1、监听端口固定 2404：可配置化（config.ini）留待后续产品分期，尚未登记具体条目。
|
||||
|
||||
## 变更记录
|
||||
|
||||
|
||||
@@ -1101,9 +1101,9 @@ IDLE → ACCEPT → [SEND: 分块发 → DONE] / [RECV: 分块收+校验 → DON
|
||||
|
||||
|
||||
|
||||
## 12.5 阶段 15：自愈收敛阶段 2 驱动原语（硬件层，无需 PC）
|
||||
## 12.5 阶段 15：自愈驱动原语（硬件层，无需 PC）
|
||||
|
||||
验证 `ch395f` 新增自愈原语（`docs/网络/网络自愈架构设计.md` §4.4；形态定案锚点
|
||||
验证 `ch395f` 自愈原语（`docs/网络/网络自愈架构设计.md` §4.4；形态定案锚点
|
||||
同文档 §5.2 E2/E3/E4）。硬件层模式独占芯片，用 Socket 7
|
||||
（产品监听 0~4 不涉），无需 PC 配合。污染会话下的复位载荷完整性不在本 Phase
|
||||
（已由 E4 bench 60 轮实证），本 Phase 只验状态机跑通与判据语义。
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
> **用途**：把散落在各子系统文档里的"模拟器无法建模 X"汇成**单一事实源**，回答一个关键问题——
|
||||
> **模拟器回归通过 ≠ 真机通过，那么差在哪？差多少？哪些必须真机补测？**
|
||||
> **性质**：**登记册**（living document）。新增模拟器后端差异时必须在此登记一行，不得只写在别处。
|
||||
> **上游依据**：`docs/任务规划/基线与待确认.md` §2.1（N-4 二期门禁）。
|
||||
> **上游依据**：`docs/任务规划/基线与待确认.md` §2.1（N-4 门禁）。
|
||||
> **相关**：`UI设计/LVGL模拟器部署与使用说明.md`（部署与使用）、`simulator/README.md`（目录与架构）、
|
||||
> `测试说明/测试开发标准流程.md`（L3 门禁在测试分层中的位置）。
|
||||
|
||||
@@ -40,12 +40,12 @@
|
||||
|
||||
| # | 差距 | 模拟器行为 | 真机行为 | 影响 | 回归补测 |
|
||||
|---|---|---|---|---|---|
|
||||
| N-1 | **无 pending 机制** | `net_accept`/`net_send` 直接失败或阻塞于宿主 socket；无"挂起队列"概念 | 异步 TCP 状态机，`accept`/`send` 可处于 pending，由 `net_poll` 推进 | **E-06**（accept 轮询计时失真）、**E-20**（lftpd 控制通道 errno 分类）、**E-21**（timeSync errno 分级）等在模拟器上无法复现 | `@test` + FTP 套件；N-4 二期专门建模 |
|
||||
| N-1 | **无 pending 机制** | `net_accept`/`net_send` 直接失败或阻塞于宿主 socket；无"挂起队列"概念 | 异步 TCP 状态机，`accept`/`send` 可处于 pending，由 `net_poll` 推进 | **E-06**（accept 轮询计时失真）、**E-20**（lftpd 控制通道 errno 分类）、**E-21**（timeSync errno 分级）等在模拟器上无法复现 | `@test` + FTP 套件；N-4（ACCEPT pending 化）专门建模 |
|
||||
| N-2 | **代次号恒为 0** | `net_get_generation()` 恒返 0（无"网络重建"概念） | 每次 `net_stack_bring_up` / 重配置递增，各 TCP 服务据此重建监听 | "网络重建后服务是否重建监听" 的逻辑**在模拟器上恒走同一分支** | `@test` 网络重配置用例（UI 改 IP 免重启生效） |
|
||||
| N-3 | ~~`net_recv_to` 缺失~~（**2026-10-13 自愈收敛阶段 1.5 已消除**：sim 以 `GetTickCount64` + `Sleep(1)` 轮询兑现预算，含 -2 返回码与 `timeout_ms=0` 拒 INVAL）；`net_process_messages` 仍缺失 | `net_recv_to` 已实现（包装层模拟）；消息泵未实现（MCU 专属：CH395F 消息队列驱动） | 由 `netMsgQueue` 串行化 SPI 事务、支持毫秒级超时接收 | 依赖"消息泵"的上层逻辑在模拟器上**不可编译/不可运行**；带超时接收的**外部语义**已可双端共测，但预算兑现精度为 Sleep(1) 粒度 | 板端 CH395F / NET 套件 |
|
||||
| N-4 | **Socket 失效语义不同** | 以 `in_use` 判活（`net_socket_sim.c` 设计要点 4） | 监听 Socket 随客户端一同失效，由 net 层 `auto_relisten`/pump 自动重建（自愈收敛阶段1 后无手动 `net_relisten`） | "客户端断线 → 监听失效 → 重连" 的黏滞状态在模拟器上不出现 | `check_remo_sink.py` 覆盖重连；真机 `@test` |
|
||||
| N-3 | ~~`net_recv_to` 缺失~~（**已消除**：sim 以 `GetTickCount64` + `Sleep(1)` 轮询兑现预算，含 -2 返回码与 `timeout_ms=0` 拒 INVAL）；`net_process_messages` 仍缺失 | `net_recv_to` 已实现（包装层模拟）；消息泵未实现（MCU 专属：CH395F 消息队列驱动） | 由 `netMsgQueue` 串行化 SPI 事务、支持毫秒级超时接收 | 依赖"消息泵"的上层逻辑在模拟器上**不可编译/不可运行**；带超时接收的**外部语义**已可双端共测，但预算兑现精度为 Sleep(1) 粒度 | 板端 CH395F / NET 套件 |
|
||||
| N-4 | **Socket 失效语义不同** | 以 `in_use` 判活（`net_socket_sim.c` 设计要点 4） | 监听 Socket 随客户端一同失效，由 net 层 `auto_relisten` + 对账形态③④自动重建（无手动 `net_relisten`） | "客户端断线 → 监听失效 → 重连" 的黏滞状态在模拟器上不出现 | `check_remo_sink.py` 覆盖重连；真机 `@test` |
|
||||
| N-5 | **单连接 backlog** | `NET_SIM_BACKLOG = 1` | CH395F 多 socket 并发 | 多客户端并发场景（FTP + 推流 + timeSync 同时）不可在模拟器验证 | 板端 NET 套件 + 台架并发场景 |
|
||||
| N-6 | **非阻塞语义模拟** | 创建即 `FIONBIO`（Winsock 句柄恒非阻塞，UI 主循环安全底线）；**阻塞/非阻塞按控制块 `blocking` 属性在包装层模拟**（自愈收敛阶段 1.5：`net_recv` 无限轮询等待 / `net_recv_nb` / `NET_MSG_DONTWAIT` 立即 WOULDBLOCK，`net_setblocking` 双端同名） | 中断驱动 + 状态机 + L3 挂起 recv（等待睡任务通知，netTask 零占用） | 外部语义**对齐**（登记以说明"为何模拟器能测非阻塞路径与显式预算路径"）；内部挂起模型（N-1）仍不建模 | —— |
|
||||
| N-6 | **非阻塞语义模拟** | 创建即 `FIONBIO`（Winsock 句柄恒非阻塞，UI 主循环安全底线）；**阻塞/非阻塞按控制块 `blocking` 属性在包装层模拟**（`net_recv` 无限轮询等待 / `net_recv_nb` / `NET_MSG_DONTWAIT` 立即 WOULDBLOCK，`net_setblocking` 双端同名） | 中断驱动 + 状态机 + 挂起 recv（等待睡任务通知，netTask 零占用） | 外部语义**对齐**（登记以说明"为何模拟器能测非阻塞路径与显式预算路径"）；内部挂起模型（N-1）仍不建模 | —— |
|
||||
|
||||
### 2.2 日志与配置
|
||||
|
||||
@@ -101,7 +101,7 @@
|
||||
- **何时登记**：新增/修改 `simulator/sim/` 下任何后端、或发现"某逻辑模拟器走了不同分支"时，**必须**在 §2 加一行。
|
||||
- **格式**：沿用本表列（差距 / 模拟器行为 / 真机行为 / 影响 / 回归补测）。
|
||||
- **联动**：若该差距影响 L3 门禁的可信度，须同步在 `UI设计/UI_自动化测试流程.md` 引用本清单。
|
||||
- **收敛**：当某差距被 N-4 二期之类的工作**消除**时，不删行——改标 ~~删除线~~ + 注明消除日期与提交，保留"曾经差在哪"的历史。
|
||||
- **收敛**：当某差距被 N-4 之类的工作**消除**时，不删行——改标 ~~删除线~~ + 注明消除日期与提交，保留"曾经差在哪"的历史。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+14
-14
@@ -61,7 +61,7 @@ sequenceDiagram
|
||||
Note over F: D8 最多等 100ms 才轮到下一次 fetch_screen
|
||||
F->>C: LCDMEM 请求 10B
|
||||
C-->>N: RECV 中断 → net_poll
|
||||
Note over N: D3 netMsgQueue 头阻塞窗口（已两阶段修复：分片 → L3 pending 零占用）
|
||||
Note over N: D3 netMsgQueue 头阻塞窗口（已两阶段修复：分片 → 挂起 recv 零占用）
|
||||
U->>N: net_recv(64B)（队列 + TaskNotify）
|
||||
Note over U: D5 最多 10ms 相位 + LVGL 渲染占时（渲染实测 ~1ms）
|
||||
N-->>U: 按键注入 UI
|
||||
@@ -88,10 +88,10 @@ sequenceDiagram
|
||||
| `NET_SEND_CHUNK_MAX` | **1KB**（受发送缓冲与 DMA 载荷 2048 双重钳制） | `net_socket.c` |
|
||||
| LCDMEM 一帧分块数 / 分段数 | **4**（1024×3 + 137） | 3209 ÷ 1024 |
|
||||
| CH395F 内部 RAM | 48 块 × 512B = 24KB，`net_init` 按 8 socket 均分 6 块 | `net_init` |
|
||||
| TCP 重传 | **8 次 × 200ms = 1.6s 窗口**（固定周期，非 RTT 自适应；P0-a 2026-09-22 实装，原 8×500ms=4s） | `NET_RETRANS_COUNT/PERIOD_MS`（`net_config.h`） |
|
||||
| TCP 重传 | **8 次 × 200ms = 1.6s 窗口**（固定周期，非 RTT 自适应；原 8×500ms=4s） | `NET_RETRANS_COUNT/PERIOD_MS`（`net_config.h`） |
|
||||
| SPI2 速率 | APB1 42MHz ÷ 8 ≈ **5.25 Mbit/s** → 1KB ≈ **1.6ms**（分频 8 为 PCB 约束，勿"优化"） | `Src/spi.c` |
|
||||
| 发送等待超时 | 1s（`NET_SEND_TIMEOUT_MS`） | `net_config.h` |
|
||||
| 接收超时 | **无默认预算**（自愈收敛阶段 1.5：`net_recv` 无限阻塞，超时归调用方——`net_select` / `net_recv_to`；原 30s `NET_RECV_TIMEOUT_MS` 已删） | `net_config.h`（宏已移除） |
|
||||
| 接收超时 | **无默认预算**（`net_recv` 无限阻塞，超时归调用方——`net_select` / `net_recv_to`；无 30s `NET_RECV_TIMEOUT_MS`） | `net_config.h`（宏已移除） |
|
||||
| 调试串口 | USART1 115200，**逐字节阻塞发送**（`fputc` = `HAL_UART_Transmit` 单字节） | `Src/usart.c` |
|
||||
| LVGL 刷新周期 / 色深 | 20ms / 1bpp（`RENDER_MODE_FULL`） | `lv_conf.h`、`ui_port.c` |
|
||||
|
||||
@@ -406,7 +406,7 @@ D10 修复后实测 89ms（= 30ms 重试间隔 + 约 60ms 芯片沉降），故
|
||||
| 连接 / 断开重连（+INIT） | 20.9ms / 22.6ms（3/32.6） | 10.5ms / 32.0ms | — | ≤150ms |
|
||||
|
||||
（模拟器列为 2026-09-21 基线，模拟器工程不受 L3 影响（公开 API 不变）；真机列 =
|
||||
**2026-09-22 16:42 L3 pending 构建重锁**（`m3_data/m3_pending_quiet.json`，50/50 帧全 OK、零尖峰）。
|
||||
**2026-09-22 16:42 挂起 recv 构建重锁**（`m3_data/m3_pending_quiet.json`，50/50 帧全 OK、零尖峰）。
|
||||
上一档真机值（P0-a/P0-b 分片代码，同日 11:35）：帧周期 61.6ms / 首字节 9.6ms / 尾批 52.6ms /
|
||||
重连 17.1/22.4ms → pending 构建：帧周期 med **58.9ms**（−2.7ms）、尾批 **50.4ms**（−2.2ms）——
|
||||
执行器零占用使生产路径净缩短（更早的空闲窗口）。）
|
||||
@@ -416,10 +416,10 @@ D10 修复后实测 89ms（= 30ms 重试间隔 + 约 60ms 芯片沉降），故
|
||||
| 分桶 | n | med | p95 | max | 尖峰(≥500ms) |
|
||||
|---|---|---|---|---|---|
|
||||
| quiet（0~24 帧） | 25 | 58.4ms | 69.0ms | 69.8ms | 0 |
|
||||
| stress（25~49 帧，**L3 pending 构建**） | 25 | **60.1ms** | 66.4ms | **69.3ms** | **0** |
|
||||
| stress（25~49 帧，**挂起 recv 构建**） | 25 | **60.1ms** | 66.4ms | **69.3ms** | **0** |
|
||||
|
||||
（E-02 修复前 stress 档 med 17718ms、尖峰 1 次 = 17.7s 全网冻结（旧固件）；阶段一 5ms 分片修复后
|
||||
med 65.0ms/max 133.5ms（133.5 = 压力启动瞬态单帧）；**L3 pending 化后 med 60.1ms/max 69.3ms**
|
||||
med 65.0ms/max 133.5ms（133.5 = 压力启动瞬态单帧）；**挂起 recv 化后 med 60.1ms/max 69.3ms**
|
||||
——p99 尾部较分片档压缩近半（133.5→69.3），MCU 侧 `prod_cycle_mcu` 6706µs 在压力下纹丝不动
|
||||
（min 6698/max 6720）：头阻塞工况不再向 UI 帧周期传导 = 结构性收益。本档重锁 =
|
||||
`m3_data/m3_pending_stress.json`，2026-09-22 16:43。）
|
||||
@@ -447,7 +447,7 @@ med 65.0ms/max 133.5ms（133.5 = 压力启动瞬态单帧）；**L3 pending 化
|
||||
（µs 级）——机制上不影响 L5；M2 重验未在本轮执行（低风险，留待 Phase 13 下次窗口，见 `docs/任务规划/README.md` N-3）。
|
||||
|
||||
数据来源：L1/L2 = §6.1；L3/L5/L6/L7 = M2 B2 档（200ms、per-recv 日志已删）串口 `[LAT]` 行
|
||||
（`m2_data/m2_quiet_r200.json`）；L8/L9/L11 = **L3 pending 构建 2026-09-22 16:42/16:43 重锁**
|
||||
（`m2_data/m2_quiet_r200.json`）；L8/L9/L11 = **挂起 recv 构建 2026-09-22 16:42/16:43 重锁**
|
||||
（`m3_data/m3_pending_quiet.json` / `m3_pending_stress.json` 之 MCU 侧 `[LAT]` 行）；L10 = M3 静默档
|
||||
（`m3_data/m3_dev_quiet_r200.json`，与 L3 无关的串口税段）；A/B 对照档 = `m2_quiet_r500.json`（旧条件）；
|
||||
peer 侧 = `m3_data/m3_pending_*.json`（L3 重锁）与 `m3_data/m3_dev_*_r200.json`（上一档，历史对照）。
|
||||
@@ -610,14 +610,14 @@ sock4 auto-relisten ok / relisten retry ok ← 监听器随后自行恢复
|
||||
轮询到点执行；若让调用方每次立即重试并重置时刻，会永不重试。重试间隔 100ms→30ms 后恢复时间
|
||||
147ms→89ms（芯片沉降约 60ms）；
|
||||
2. **（历史，阶段一）E-02 分片长度 = 其他任务的最坏等待**：100ms 片下受压帧仍 ~750ms（多片排队），收到
|
||||
**5ms** 片后才降到 ~75ms——该"分片即上限"模型已于 2026-09-22 由 **L3 pending 化**取代
|
||||
**5ms** 片后才降到 ~75ms——该"分片即上限"模型已于 2026-09-22 由 **挂起 recv 化**取代
|
||||
（`a45c0cb`）：执行器零占用后，其他任务的最坏等待 = 一个主循环节拍（~1ms），与任何片长无关
|
||||
（M3 压力档实测：med 60.1ms/max 69.3ms，p99 尾部较分片档 133.5ms 压缩近半）；
|
||||
3. **（历史，阶段一）分片循环必须显式让出 CPU**：某片可能因 `net_poll` 自身耗时首轮即返回超时 → 本任务
|
||||
（Normal）立即重排队会形成忙循环并**饿死 BelowNormal 的 uiTask**（实测 2.4~3.4s 周期尖刺）；
|
||||
`vTaskDelay(1)` 后尖刺归零——L3 pending 化后该让出协议随分片循环一并退役（调用方改睡任务通知，
|
||||
`vTaskDelay(1)` 后尖刺归零——挂起 recv 化后该让出协议随分片循环一并退役（调用方改睡任务通知，
|
||||
天然让出；netTask 侧无循环可忙）；
|
||||
4. **（现行，L3 pending 化）阻塞等待不在执行器内发生**：`net_recv_locked` 阻塞分支在数据不可得时登记
|
||||
4. **（现行，挂起 recv 化）阻塞等待不在执行器内发生**：`net_recv_locked` 阻塞分支在数据不可得时登记
|
||||
pending（每 fd 至多一个、**不可覆盖**；`caller==NULL`/netTask 自身拒绝）即返回哨兵
|
||||
`NET_PENDING_REGISTERED`；完成判定在 `net_pending_tick`（主循环节拍，与 `net_process_messages`
|
||||
同位）按 数据→截止→CLOSED 排空/EOF+relisten→1s 看门狗 顺序执行，**cancel/settle 必通知**
|
||||
@@ -653,7 +653,7 @@ sock4 auto-relisten ok / relisten retry ok ← 监听器随后自行恢复
|
||||
| L1/L2 超 crit | SPI 走线/PCB/SPI2 分频或 DMA 配置 | 对照 `docs/问题记录/CH395F_Trap_Records.md`；逻辑分析仪抓 SCK/CS |
|
||||
| L3 spike ≥200ms（连续台阶；旧固件 500ms） | **D1 重传 / D7 链路** | Wireshark `tcp.analysis.retransmission`；查 PHY 协商/网线/Wi-Fi |
|
||||
| L3 基线（非 spike）抬高 | 芯片发送路径 / 中断响应 | 对照 `docs/芯片手册/CH395F.md` §5.17/5.18（注意：状态寄存器**不被 SET 类命令更新**，`GET_CMD_STATUS` 恒读到 RESET 的 0x10 陈旧残留，2026-09-22 台架实证——不可用作 SET 值验收） |
|
||||
| L5 压力档爆表 | **E-02 头阻塞（已修）→ 回归** | 定位触发源（阻塞 recv 的 FTP/对时）；核对 L3 pending 在位（`net_recv_locked` 阻塞分支 = 登记 pending 而非等待；`net_pending_tick` 在主循环） |
|
||||
| L5 压力档爆表 | **E-02 头阻塞（已修）→ 回归** | 定位触发源（阻塞 recv 的 FTP/对时）；核对 挂起 recv 在位（`net_recv_locked` 阻塞分支 = 登记 pending 而非等待；`net_pending_tick` 在主循环） |
|
||||
| L5/L6 静默档抬高 | D5 调度（任务抢占/节拍） | 查任务优先级与 osDelay；`stack_report.py` 核对栈水位 |
|
||||
| L6/L7 整体抬高且 L1~L5 正常 | 线路+PC 段（L4） | Wireshark 段间间隙；`Δ` 对照定位 MCU 侧净贡献 |
|
||||
| **L7/L8 尾批固定迟到 ~50ms** | 已定性（§7.3）：次 MSS 尾段被 Nagle 扣住 + Windows 延迟 ACK | 客户端侧解法已实测（§7.4）：`--ack-probe` / `--ack-fast` → tail 52→3.9ms；生产客户端已实装；**设备侧无解**，不必再投入 |
|
||||
@@ -664,12 +664,12 @@ sock4 auto-relisten ok / relisten retry ok ← 监听器随后自行恢复
|
||||
| **`[LAT]` 段行缺失/截断、wait-idle 判不出空闲** | **D12-b**：热路径日志洪水 | 删除 net 热路径逐调用日志（§8 D12-b） |
|
||||
| **开机日志连续丢行**（含必检标记 `net init: OK` 等）但系统健康 | **日志并发竞态**：多任务并发 `printf` → 非重入 `fputc`/`HAL_UART_Transmit` 丢整行、UART 状态短暂卡住（2026-09-22 台架实证：boot 时 testTask 启动行与 netTask 日志并发 → 连续 4 行丢失、~2s 后自恢复） | 必现证据行采用"静默采集 + 延迟到安静窗口打印"模式（范例：P0-a 验收行曾按此模式实装，验收完成后探针已移除）；根治 = S8 日志非阻塞/串行化（§10.2） |
|
||||
| **`relisten` 段 FAIL、断线固定 ~588ms** | **D10** 回归（退回 `osDelay(500)`） | 核对 `net_listener_request`/`net_listener_tick` 非阻塞重试在位（§8 D10） |
|
||||
| **远端显示整帧卡住十几秒后自恢复** | **E-02** 回归 | 核对 L3 pending 在位：`net_recv_locked` 阻塞分支登记 pending（哨兵 `NET_PENDING_REGISTERED`）+ `net_pending_tick` 在主循环 + 调用方剩余预算循环（lftpd/timeSync）（§8.3 要点 4） |
|
||||
| **远端显示整帧卡住十几秒后自恢复** | **E-02** 回归 | 核对 挂起 recv 在位：`net_recv_locked` 阻塞分支登记 pending（哨兵 `NET_PENDING_REGISTERED`）+ `net_pending_tick` 在主循环 + 调用方剩余预算循环（lftpd/timeSync）（§8.3 要点 4） |
|
||||
| **INIT 应答帧字节数字段恒为 0** | **D17** 回归 | 核对 `remo_send_init` 发满 8B（§8 D17） |
|
||||
| **开机首个 FTP 会话第 2 个数据连接 425** | **D20**（已定位未修，§8.2） | 复现：`test/host/ftp_regression.py`（复位开边界）；现场规避：客户端重试 425（瞬态 4xx）；根治方向：数据 Socket 轮换 |
|
||||
| **`[LAT]` 多段数值雷同 / 全 0 却 verdict=OK** | **D18/D19**（测试工装） | 核对 `lat_probe_add_seg` 段名过滤 + `lat_time_init` 调用 + `med==0` 判无效 |
|
||||
| **连接建立后 15~30s 无流量即被 RST** | **D13**：芯片空闲超时（芯片行为） | 客户端须容忍并重连（peer `--wait` 重试是正常路径） |
|
||||
| **peer 重连后 MCU 状态滞留、新连接字节被吞** | **D14**：芯片静默回收 Socket | 对账⑤自动认领（自愈收敛阶段1：手动 `net_resync_listen`/`net_relisten` 已退役，Phase 13 abort 期自愈亦交 net 层） |
|
||||
| **peer 重连后 MCU 状态滞留、新连接字节被吞** | **D14**：芯片静默回收 Socket | 对账⑤自动认领（手动 `net_resync_listen`/`net_relisten` 已退役，Phase 13 abort 期自愈亦交 net 层） |
|
||||
| L8 超而 L7 正常 | 生产路径附加成本（uiTask 节拍/LVGL/日志） | 对照 L10/L11 与 §10.1（渲染已排除；per-recv 日志已删，S8 非阻塞日志仍待办） |
|
||||
| Δ 显著 >80ms | CH395F 栈净开销异常 | 回到 L1~L9 逐段排查 |
|
||||
|
||||
@@ -683,7 +683,7 @@ sock4 auto-relisten ok / relisten retry ok ← 监听器随后自行恢复
|
||||
|---|---|---|---|
|
||||
| D1 | CH395F TCP 重传固定周期（非 RTT 自适应） | 台架链路（有线 100M 全双工）多轮零重传尖峰 → 台架无丢包；**弱网（Wi-Fi/双工不匹配）仍是秒级卡顿首要嫌疑**，200ms 粒度台阶 = 重传指纹（旧固件 500ms） | **已修（P0-a，2026-09-22）**：`NET_RETRANS_PERIOD_MS` 500→**200**（窗口 8×200=1.6s，原 4s）。台架验收说明：`GET_CMD_STATUS` 对 SET 类命令无判别力（500/2000ms 超限对照均读 0x10 陈旧残留，§9.2）→ 接受性以手册范围（≤1000ms）+ 全套件零回归（§6.2/§6.3）+ 与 500ms 行为同构为准。验收探针（3×20ms 状态轮询 + 证据行）验收完成后已从代码移除，结论保留于本文档 |
|
||||
| D2 | 3209B × 1KB 发送 FIFO 停止等待（4 次串行分块握手，期间 netTask 全程占用） | `chunk_wait` 219µs/块 ≈ SPI 搬运成本的 1/7 → 握手本身**不是瓶颈**；每帧固定成本小（MCU 净 7.1ms） | 基线成本，可接受；根治 = 差量/RLE + 帧版本号（待办 S2） |
|
||||
| D3 | netMsgQueue 头阻塞（= §8 E-02） | 已量化：一条空闲 FTP 控制连接冻结全网 17.7s | **两阶段闭环**：① 5ms 分片有界读 + 让出（f8d6e90/4a1605b，缓解）② **L3 pending 化**（`a45c0cb`，结构性——执行器零占用，缺陷类消灭，§8.3 要点 4） |
|
||||
| D3 | netMsgQueue 头阻塞（= §8 E-02） | 已量化：一条空闲 FTP 控制连接冻结全网 17.7s | **两阶段闭环**：① 5ms 分片有界读 + 让出（f8d6e90/4a1605b，缓解）② **挂起 recv 化**（`a45c0cb`，结构性——执行器零占用，缺陷类消灭，§8.3 要点 4） |
|
||||
| D4 | PC 端延迟 ACK 与"每段等 ACK"停止等待交互 | `--ack-fast` 带内实验证实：关掉延迟 ACK 尾批自行消失（52→3.9ms） | **已客户端侧解决**（生产客户端关延迟 ACK/轻推兜底，§7.4） |
|
||||
| D5 | uiTask 节拍：10ms 循环 + 每拍一次 64B recv + step 在 poll 前 | `ui_loop` 10986µs ≈ 设计值（渲染 ~1ms）；拾取调度 ~2.3ms（P0-b 删 per-recv 日志后，原 ~6.8ms） | 基线行为；可选优化 S7（poll 前置 + while 排空），低优先 |
|
||||
| D6 | 阻塞式日志在关键路径（fputc 逐字节 @115200） | `logtax_line` 4402µs/行；per-recv 日志已删（2026-09-22）：`queue_rt_recv` 5997→1223µs、帧周期 66.0→61.6ms、首字节 13.9→9.6ms | **部分已修（P0-b，2026-09-22）**；S8 非阻塞日志仍待办（同时是开机日志并发丢行 §9.2 的根治项） |
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# BSD Socket API 使用指南
|
||||
|
||||
> **恢复说明**：本文档曾在提交 `4e9ac0d`（2026-08-28）中误删，2026-09-13 从 git 历史恢复。API 随代码多轮同步（2026-09-13：`net_init` 4 参数 / `net_socket` 2 参数 / 网络代次号 / `NET_NO_OS` 双端构建；2026-09-23：`net_recv_to` / `net_sock_state` / `net_resync_listen` / `net_relisten`、L3 pending 化、D10 非阻塞重监听、TRAP-NET-17 周期对账、TRAP-NET-18 排渣隔离）。详见文末变更记录。
|
||||
> **恢复说明**：本文档曾在提交 `4e9ac0d`（2026-08-28）中误删，2026-09-13 从 git 历史恢复。API 随代码多轮同步（2026-09-13：`net_init` 4 参数 / `net_socket` 2 参数 / 网络代次号 / `NET_NO_OS` 双端构建；2026-09-23：`net_recv_to` / `net_sock_state` / `net_resync_listen` / `net_relisten`、挂起 recv 化、D10 非阻塞重监听、TRAP-NET-17 周期对账、TRAP-NET-18 排渣隔离）。详见文末变更记录。
|
||||
>
|
||||
> **伴读文档**：本文回答"上层该怎么调"；**内部函数之间的调用关系、每个函数的设计作用与意图**（netTask / 消息队列 / L3 挂起 / D10 重试 / TRAP-NET-17 对账 / TRAP-NET-18 排渣各子系统，含总体调用图与端到端时序）见 `docs/网络/BSD_Socket_API_函数调用关系.md`。
|
||||
> **伴读文档**：本文回答"上层该怎么调"；**内部函数之间的调用关系、每个函数的设计作用与意图**（netTask / 消息队列 / 挂起 recv / D10 重试 / TRAP-NET-17 对账 / TRAP-NET-18 排渣各子系统，含总体调用图与端到端时序）见 `docs/网络/BSD_Socket_API_函数调用关系.md`。
|
||||
|
||||
## 目录
|
||||
|
||||
@@ -41,7 +41,7 @@
|
||||
| 特性 | Linux Socket | 本实现 |
|
||||
|------|--------------|--------|
|
||||
| Socket 数量 | 无限制 | 最多 8 个 |
|
||||
| 阻塞默认 | 默认阻塞（无隐藏超时） | **同**（自愈收敛阶段 1.5：`net_recv()` 无限阻塞，超时归调用方——`net_select` / `net_recv_to`） |
|
||||
| 阻塞默认 | 默认阻塞（无隐藏超时） | **同**（`net_recv()` 无限阻塞，超时归调用方——`net_select` / `net_recv_to`） |
|
||||
| 非阻塞模式 | `O_NONBLOCK` / `MSG_DONTWAIT` | `net_setblocking(fd, 0)`（模式属性）/ `net_recv_nb()` / `NET_MSG_DONTWAIT`（单次） |
|
||||
| 错误码 | errno | `net_get_errno()` |
|
||||
| 头文件 | `<sys/socket.h>` | `"net_socket.h"` |
|
||||
@@ -62,9 +62,9 @@
|
||||
| `net_config.h` | 配置宏定义（最大 Socket 数、超时时间等） |
|
||||
| `net_types.h` | 类型定义（地址结构、Socket 控制块等） |
|
||||
| `net_socket.h` | BSD Socket API 头文件，含 `net_msg_t` 消息类型定义 |
|
||||
| `net_socket.c` | API 核心实现：消息队列处理与线程安全封装、内部 `_sock()` 版本；另含 L3 pending 化 recv |
|
||||
| `net_events.c`（**真机专属**） | **状态面收敛**（2026-10-14 从 `net_socket.c` 抽出，与 `net_listener.c` 同族）：5 个 `handle_*_event`（`net_poll` 检测中断后的分派目标）+ `fire_event` + TRAP-NET-17 周期对账 + 监听重建**合一** reconciler（`net_reconcile_tick`，100ms，分级去抖+冷却，形态①②③④⑤/U11，自愈收敛阶段 3）+ `net_lost_connect_probe`；**只置事实与登记意图**，重建动作在 `net_listener_tick`；内部头 `net_events.h`，模拟器不编译 |
|
||||
| `net_listener.c`（**真机专属**） | **监听生命周期**（N-32 §10 模块化，E17 单一所有者收口）：`net_listener_request`（**只登记意图**，5 个登记点）/ `net_listener_tick`（**唯一执行者**，门集 + D10 重试 30ms/2s）/ `net_listener_clear` / `net_listener_settle`（沉降/隔离 100ms/400ms）；"该不该重建"的周期判据在 `net_reconcile_tick` 形态③④（自愈收敛阶段 3，单一 100ms tick）；内部头，模拟器不编译 |
|
||||
| `net_socket.c` | API 核心实现：消息队列处理与线程安全封装、内部 `_sock()` 版本；另含挂起 recv 登记路径 |
|
||||
| `net_events.c`（**真机专属**） | **状态面收敛**（2026-10-14 从 `net_socket.c` 抽出，与 `net_listener.c` 同族）：5 个 `handle_*_event`（`net_poll` 检测中断后的分派目标）+ `fire_event` + TRAP-NET-17 周期对账 + 监听重建**合一** reconciler（`net_reconcile_tick`，100ms，分级去抖+冷却，形态①②③④⑤/U11）+ `net_lost_connect_probe`；**只置事实与登记意图**，重建动作在 `net_listener_tick`；内部头 `net_events.h`，模拟器不编译 |
|
||||
| `net_listener.c`（**真机专属**） | **监听生命周期**（E17 单一所有者收口）：`net_listener_request`（**只登记意图**，5 个登记点）/ `net_listener_tick`（**唯一执行者**，门集 + D10 重试 30ms/2s）/ `net_listener_clear` / `net_listener_settle`（沉降/隔离 100ms/400ms）；"该不该重建"的周期判据在 `net_reconcile_tick` 形态③④（单一 100ms tick）；内部头，模拟器不编译 |
|
||||
| `net_select.h` | select/poll API 头文件 |
|
||||
| `net_select.c` | select/poll 实现（仅 MCU 端编译） |
|
||||
| `net_socket_sim.c`（`simulator/sim/`） | Winsock2 后端（模拟器端，与 `net_socket.c` 互斥编译），详见 §2.3 |
|
||||
@@ -82,7 +82,7 @@ PC 模拟器（`simulator/`，CMake + SDL2）与 MCU 端共用同一份上层网
|
||||
| 底层后端 | CH395F（SPI2） | Winsock2（链接 `ws2_32`） |
|
||||
| `net_init()` | 芯片初始化 / 复位 / 配置 IP·MAC / 分配 Socket 缓冲 | 仅确保 `WSAStartup`（幂等）；ip/mask/gw/mac 四参数全部忽略 |
|
||||
| fd 模型 | 控制块索引 0~7 | 相同（并行数组 `s_ws[]` 存 Winsock 句柄，不侵入共享的 `net_sock_t`） |
|
||||
| 并发 / 阻塞 | 消息队列 + `netTask` 串行化 | 单线程直调；Winsock 句柄创建即非阻塞（FIONBIO），阻塞语义按控制块 `blocking` 属性在包装层模拟（`net_recv` 轮询等待 / `net_recv_nb` 立即返回，自愈收敛阶段 1.5 与 MCU 端对齐） |
|
||||
| 并发 / 阻塞 | 消息队列 + `netTask` 串行化 | 单线程直调；Winsock 句柄创建即非阻塞（FIONBIO），阻塞语义按控制块 `blocking` 属性在包装层模拟（`net_recv` 轮询等待 / `net_recv_nb` 立即返回，与 MCU 端对齐） |
|
||||
| `net_poll()` | CH395F 中断轮询 + 状态机更新 | 空操作（返回 0，非阻塞 I/O 直接反映事件） |
|
||||
| `net_accept()` | 单连接：监听 Socket 自身即数据通道（返回监听 Socket 自身） | Winsock 语义：返回独立于监听 Socket 的新 fd（监听 Socket 保持 `LISTENING`） |
|
||||
| 事件回调 | `net_poll` 检测后主动触发 | 仅存储，不主动触发（上层自行非阻塞轮询感知） |
|
||||
@@ -156,10 +156,10 @@ sequenceDiagram
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| **`netTask` 外（任意应用任务）** | 公共 API：`net_send()` / `net_recv()` / `net_recv_to()` / `net_accept()` / `net_connect()` / `net_close()` / `net_listen()` / `net_drop_conn()`——请求入队列，netTask 串行执行，调用方阻塞等回执。**自愈无显式 API**（自愈收敛阶段1：`net_relisten()` / `net_resync_listen()` 已退役，静默回收/监听失位由对账⑤与 reconciler 形态③④自动认领，见 §3.6） |
|
||||
| **`netTask` 外（任意应用任务）** | 公共 API：`net_send()` / `net_recv()` / `net_recv_to()` / `net_accept()` / `net_connect()` / `net_close()` / `net_listen()` / `net_drop_conn()`——请求入队列，netTask 串行执行，调用方阻塞等回执。**自愈无显式 API**（`net_relisten()` / `net_resync_listen()` 已退役，静默回收/监听失位由对账⑤与 reconciler 形态③④自动认领，见 §3.6） |
|
||||
| **`netTask` 内** | 内部 API `net_send_sock()` / `net_recv_sock()` / `net_close_sock()` / `net_listen_locked()` |
|
||||
| **`net_socket()` / `net_bind()`** | 直接调用，无需队列；实际在就绪屏障后的服务任务（timeSyncTask / ftpTask / uiTask）中创建监听 |
|
||||
| **`net_poll()` 和 `net_process_messages()`** | 必须在 `netTask` 主循环调用；`net_process_messages()` 每轮先跑 **4 个非阻塞 tick**（D10 重监听重试 → L3 挂起 recv 完成 → L3 挂起 send 推进 → TRAP-NET-17 对账+监听重建合一 reconciler 100ms），再处理队列 |
|
||||
| **`net_poll()` 和 `net_process_messages()`** | 必须在 `netTask` 主循环调用；`net_process_messages()` 每轮先跑 **4 个非阻塞 tick**（D10 重监听重试 → 挂起 recv 完成 → 挂起 send 推进 → TRAP-NET-17 对账+监听重建合一 reconciler 100ms），再处理队列 |
|
||||
|
||||
### 3.4 内部 API 说明
|
||||
|
||||
@@ -177,21 +177,21 @@ int net_close_sock(net_sock_t *p_sock);
|
||||
- **消息队列由 CubeMX 创建**：在 `MX_FREERTOS_Init()`（`osKernelInitialize()` 之后）中调用 `osMessageQueueNew(8, sizeof(net_msg_t), NULL)` 创建
|
||||
- **队列句柄全局可见**：通过 `extern osMessageQueueId_t netMsgQueueHandle` 引用
|
||||
- **`netTask` 不可向自身发消息**：`netTask` 中直接调 `net_send()` 会死锁（等待自己处理消息），必须在 `netTask` 中使用 `net_send_sock()` 等内部版本
|
||||
- **阻塞 recv 不再独占 netTask（L3 pending 化，2026-09-22）**：无数据时公共 `net_recv()` / `net_recv_to()` **登记挂起请求后返回**（每 fd 至多一个，禁止覆盖——覆盖即丢失前调用方通知 = 永久挂死）；完成由 `net_pending_tick()` 按主循环节拍检查（①数据 ②到点[仅显式预算] ③断连）并经任务通知唤醒调用方——等待期间调用方在自己上下文睡通知，netTask 零占用（消除 E-02 头阻塞）。副作用：`buf` 指针须保持有效至返回；close / 网络重建 / 陈旧重同步会**显式取消并通知**（`NET_ERR_CONNRESET` 等），调用方永不挂死
|
||||
- **recv 语义主流化（自愈收敛阶段 1.5，2026-10-13）**：对齐 POSIX/Python——**模式归使用者、超时归调用方、API 不强加默认预算**。`net_recv()` 默认**无限阻塞**（`NET_RECV_TIMEOUT_MS` 30s 默认已删），唤醒源 = 数据 / EOF / close / 网络重建（CONNRESET），会话死亡由对账① ~400ms 判死兜底；非阻塞具名入口 `net_recv_nb()`（原 `NET_MSG_DONTWAIT` 路径转正），模式属性 `net_setblocking(fd, on)` 挂 socket 控制块；超时首选 `net_select(...)`，`net_recv_to(...)` 保留为**显式预算**便捷入口。内部看门狗降级为 **tripwire**：挂起超 60s 只 `[ERR]` 留痕一条（完成逻辑缺位探针），不再伪造 TIMEDOUT 返回值。⚠ **文档契约（嵌入式特有）**：IWDG `required_mask` 内任务**禁止无限阻塞 recv**——必须 `net_select` 超时或 `net_recv_to` 显式预算（"超时归使用者"对受监控任务是义务不是选项）
|
||||
- **阻塞 send 不再独占 netTask（L3 send pending 化，2026-10-14）**：`net_send()` 快路径**有界自旋**等发送缓冲腾出（预算 `NET_SEND_SPIN_MS` = 2ms；健康链路实测块间等待 med 219µs ≪ 2ms，故正常发送不会触发挂起），超预算即登记挂起 send 返回；推进由 `net_send_pending_tick()` 按主循环节拍分块完成（①断连 ②推进 ③写完 ④无进展超时），调用方睡任务通知——netTask 最坏停滞由 `NET_SEND_TIMEOUT_MS`（1s）压到 2ms。返回值恒为**已写入字节数**：`= len` 全部写入，`< len` 为**短写**，调用方**必须**检查并重试剩余（断连/超时/取消均以已发字节数结束，不会伪造全部成功）。停滞计时按**无进展**刷新（每次成功写块重置），大文件传输不会被误判超时
|
||||
- **阻塞 recv 不独占 netTask（挂起 recv 模型）**：无数据时公共 `net_recv()` / `net_recv_to()` **登记挂起请求后返回**（每 fd 至多一个，禁止覆盖——覆盖即丢失前调用方通知 = 永久挂死）；完成由 `net_pending_tick()` 按主循环节拍检查（①数据 ②到点[仅显式预算] ③断连）并经任务通知唤醒调用方——等待期间调用方在自己上下文睡通知，netTask 零占用（消除 E-02 头阻塞）。副作用：`buf` 指针须保持有效至返回；close / 网络重建 / 陈旧重同步会**显式取消并通知**（`NET_ERR_CONNRESET` 等），调用方永不挂死
|
||||
- **recv 语义主流化**：对齐 POSIX/Python——**模式归使用者、超时归调用方、API 不强加默认预算**。`net_recv()` 默认**无限阻塞**（`NET_RECV_TIMEOUT_MS` 30s 默认已删），唤醒源 = 数据 / EOF / close / 网络重建（CONNRESET），会话死亡由对账① ~400ms 判死兜底；非阻塞具名入口 `net_recv_nb()`（原 `NET_MSG_DONTWAIT` 路径转正），模式属性 `net_setblocking(fd, on)` 挂 socket 控制块；超时首选 `net_select(...)`，`net_recv_to(...)` 保留为**显式预算**便捷入口。内部看门狗降级为 **tripwire**：挂起超 60s 只 `[ERR]` 留痕一条（完成逻辑缺位探针），不再伪造 TIMEDOUT 返回值。⚠ **文档契约（嵌入式特有）**：IWDG `required_mask` 内任务**禁止无限阻塞 recv**——必须 `net_select` 超时或 `net_recv_to` 显式预算（"超时归使用者"对受监控任务是义务不是选项）
|
||||
- **阻塞 send 不独占 netTask（挂起 send 模型）**：`net_send()` 快路径**有界自旋**等发送缓冲腾出（预算 `NET_SEND_SPIN_MS` = 2ms；健康链路实测块间等待 med 219µs ≪ 2ms，故正常发送不会触发挂起），超预算即登记挂起 send 返回；推进由 `net_send_pending_tick()` 按主循环节拍分块完成（①断连 ②推进 ③写完 ④无进展超时），调用方睡任务通知——netTask 最坏停滞由 `NET_SEND_TIMEOUT_MS`（1s）压到 2ms。返回值恒为**已写入字节数**：`= len` 全部写入，`< len` 为**短写**，调用方**必须**检查并重试剩余（断连/超时/取消均以已发字节数结束，不会伪造全部成功）。停滞计时按**无进展**刷新（每次成功写块重置），大文件传输不会被误判超时
|
||||
- **队列阻塞语义**：只有 `osMessageQueuePut` 失败（8 长度固定队列，极端情形）时公共 API 阻塞；recv / send 挂起等待**不计入**队列占用（完成前队列中无消息滞留）
|
||||
- **哪些操作要求 netTask 已运行**：`net_listen()` / `net_accept()` / `net_connect()` / `net_send()` / `net_recv()` / `net_close()` 全经消息队列 → 只能在就绪屏障后的任务调用；`net_socket()` / `net_bind()` 为直接调用，但同样建议屏障后；**`net_listener_armed()` / `net_can_read()` 是纯 RAM 读控制块**（§10.1），不入队、不等回执，**任意任务可安全周期调用**（用途 = 门控，把"无谓的 RPC"降为 0）
|
||||
|
||||
### 3.6 芯片/本层状态对账与重监听自愈（TRAP-NET-09/-17/-18）
|
||||
|
||||
单连接模型下"监听 Socket = 数据通道"，多种芯片行为会造成**芯片侧与本层状态失同步**，纯事件（中断）驱动无法自愈。当前版本有**四层自愈**（自愈收敛阶段 3：原 200ms 周期对账与 100ms 监听器 pump 合并为**单一 100ms `net_reconcile_tick`**），全在 netTask 内、全非阻塞、不冻结主循环：
|
||||
单连接模型下"监听 Socket = 数据通道"，多种芯片行为会造成**芯片侧与本层状态失同步**，纯事件（中断）驱动无法自愈。当前有**四层自愈**（周期对账与监听重建合并在**单一 100ms `net_reconcile_tick`**），全在 netTask 内、全非阻塞、不冻结主循环：
|
||||
|
||||
| 机制 | 触发 | 动作 | 关键参数 |
|
||||
|---|---|---|---|
|
||||
| **`auto_relisten`** | 数据通道正常 EOF / DISCONNECT | 重开 + 重新 LISTEN，回 LISTENING；应用层无需 close/重 listen | `net_listen()` 置位；`net_close()` 清 |
|
||||
| **D10 非阻塞重监听重试** | 重开失败（TRAP-NET-09：芯片 close 后需沉降） | 单次尝试失败即登记待重试，每轮到点重试；超时限放弃并记 `relisten give up` | 重试间隔 30ms / 时限 2s（自首次尝试）；同 fd 有在途挂起 recv / send 时跳过（L3 保险，防毁在途连接 / 截断在途传输） |
|
||||
| **TRAP-NET-17 周期对账 + 监听重建（合一 `net_reconcile_tick`，自愈收敛阶段 3；对账①②⑤ + 原 pump③④/U11）** | 芯片 CONNECT/DISCONNECT 事件未收到（快速复连，读清消费竞态——E14 复核：非芯片侧丢失）；静默回收 Socket（peer FIN，无 DISCONNECT 事件）；监听型 fd 芯片监听失位 / 本层状态滞后 | 每 100ms 对在用 socket 读**驱动状态缓存**（`ch395f_sock_state_cached`，唯一刷新点 = `net_poll` 每轮全量刷新，E2 实测单次回读 18.1µs），修正**五类**失同步 + 一类被动重同步：① 本层 ESTABLISHED 而芯片已断 → 按断开处理（只置事实）；② 本层 LISTENING 而芯片已握手 → 补 accept（N-30 幽灵甄别）；③ 本层 LISTENING 而芯片监听失位 → 重建（`net_listener_request`）；④ 本层 CLOSED（监听型 fd）而芯片不在 LISTEN → 重建；⑤ 本层 ESTABLISHED 而芯片已静默回收回 LISTEN（0x05/0x01）→ RESYNC 语义只修本层、不发芯片命令（自愈收敛阶段1 新增，原手动 API `net_resync_listen` 的语义并入）；U11 本层 CLOSED 而芯片**正在** LISTEN → 只做状态重同步、不发芯片命令 | 周期 100ms；**分级去抖**：②=1 轮、③④⑤=2 轮、①=4 轮（M3 让位窗 400ms，**勿改小**）+ 动手后 **1s 冷却**（防"刚 open 未生效"瞬态重建风暴；U11 被动重同步不去抖、不占冷却）；其它位置只置事实、不做重建动作 |
|
||||
| **D10 非阻塞重监听重试** | 重开失败（TRAP-NET-09：芯片 close 后需沉降） | 单次尝试失败即登记待重试，每轮到点重试；超时限放弃并记 `relisten give up` | 重试间隔 30ms / 时限 2s（自首次尝试）；同 fd 有在途挂起 recv / send 时跳过（挂起保险，防毁在途连接 / 截断在途传输） |
|
||||
| **TRAP-NET-17 周期对账 + 监听重建（合一 `net_reconcile_tick`；对账①②⑤ + 原 pump③④/U11）** | 芯片 CONNECT/DISCONNECT 事件未收到（快速复连，读清消费竞态——E14 复核：非芯片侧丢失）；静默回收 Socket（peer FIN，无 DISCONNECT 事件）；监听型 fd 芯片监听失位 / 本层状态滞后 | 每 100ms 对在用 socket 读**驱动状态缓存**（`ch395f_sock_state_cached`，唯一刷新点 = `net_poll` 每轮全量刷新，E2 实测单次回读 18.1µs），修正**五类**失同步 + 一类被动重同步：① 本层 ESTABLISHED 而芯片已断 → 按断开处理（只置事实）；② 本层 LISTENING 而芯片已握手 → 补 accept（N-30 幽灵甄别）；③ 本层 LISTENING 而芯片监听失位 → 重建（`net_listener_request`）；④ 本层 CLOSED（监听型 fd）而芯片不在 LISTEN → 重建；⑤ 本层 ESTABLISHED 而芯片已静默回收回 LISTEN（0x05/0x01）→ RESYNC 语义只修本层、不发芯片命令（原手动 API `net_resync_listen` 的语义并入）；U11 本层 CLOSED 而芯片**正在** LISTEN → 只做状态重同步、不发芯片命令 | 周期 100ms；**分级去抖**：②=1 轮、③④⑤=2 轮、①=4 轮（M3 让位窗 400ms，**勿改小**）+ 动手后 **1s 冷却**（防"刚 open 未生效"瞬态重建风暴；U11 被动重同步不去抖、不占冷却）；其它位置只置事实、不做重建动作 |
|
||||
| **TRAP-NET-18 排渣隔离** | 异常释放（芯片 TIMEOUT，如客户端中止上传）：在途数据落进 RX 缓冲，直接复监听 → 下条连接把 ~2048B 残渣当自己的数据读走（上传静默截断）；正常 FIN 释放亦有残留 DISCONNECT 收尾问题 | 复监听前沉降/隔离：持续排空 RX 残渣 + 主动 close + 排空中断，等芯片回 CLOSED/TCP_CLOSED 才 open+listen；到期强制放行 | 沉降等级（`net_listener_settle`）：异常释放 QUARANTINE **400ms** / 正常释放 GRACEFUL **100ms**（2026-09-24 起正常 FIN 亦需沉降）；上限 **800ms** 强制放行（**必须 < 2s 时限**，否则监听被放弃） |
|
||||
|
||||
**行为结论**：监听器恢复从"一次性事件"变为"登记 → 到点重试"过程：
|
||||
@@ -249,7 +249,7 @@ int main(void)
|
||||
- 更新所有 Socket 的连接状态（CONNECT / DISCONNECT / RECV / TIMEOUT）
|
||||
- 触发事件回调
|
||||
- 处理数据接收
|
||||
- `net_process_messages()` 每轮先跑 4 个**非阻塞**检查再取队列：D10 重监听重试（断连后监听器恢复）→ L3 挂起 recv 完成检查（阻塞 recv 唤醒，E-02 修复）→ L3 挂起 send 推进（阻塞 send 唤醒）→ TRAP-NET-17 芯片/本层对账 + 监听重建合一 reconciler（100ms 周期，读驱动状态缓存，事件未收到/静默回收/监听失位自愈，§3.6）
|
||||
- `net_process_messages()` 每轮先跑 4 个**非阻塞**检查再取队列：D10 重监听重试（断连后监听器恢复）→ 挂起 recv 完成检查（阻塞 recv 唤醒，E-02 修复）→ 挂起 send 推进（阻塞 send 唤醒）→ TRAP-NET-17 芯片/本层对账 + 监听重建合一 reconciler（100ms 周期，读驱动状态缓存，事件未收到/静默回收/监听失位自愈，§3.6）
|
||||
- **监听 Socket 建立**：由就绪屏障后的服务任务（timeSyncTask / ftpTask / uiTask）经队列 API 建立（`net_socket` → `net_bind` → `net_listen`）；断连后 net 层自动重监听（§3.6），服务层只需循环 `net_accept`，无需维护重监听逻辑
|
||||
|
||||
```c
|
||||
@@ -889,7 +889,7 @@ int net_can_read(int sockfd); /* 1 = 应发一次 recv；0 = 可跳过本
|
||||
| 项 | 说明 |
|
||||
|------|------|
|
||||
| 代价 | **零 RPC**：只读 Socket 控制块（`net_get_sock()`），不入队、不等 netTask 回执 → 任意任务上下文可安全周期调用，**不被 netTask 忙碌程度拖住** |
|
||||
| `net_listener_armed` 判据 | `ESTABLISHED`（CONNECT 已处理、待应用 accept——单连接模型的"连接已到"电平，漏放行则任务周期慢的消费者永不 accept），或 `LISTENING`，或 `CLOSED + auto_relisten` **且 RX 有残留**（closed-with-data 救回窗）——表达"这个监听器还在服役、这一轮值不值得发起 accept"，而非"一定有连接"。（前身 `net_can_accept()` 只认 `ESTABLISHED`，会把监听服役窗口全挡掉、丢 CONNECT 探针从不运行——自愈收敛阶段1 已退役，其 ESTABLISHED 放行态并入本函数，勿再引入） |
|
||||
| `net_listener_armed` 判据 | `ESTABLISHED`（CONNECT 已处理、待应用 accept——单连接模型的"连接已到"电平，漏放行则任务周期慢的消费者永不 accept），或 `LISTENING`，或 `CLOSED + auto_relisten` **且 RX 有残留**（closed-with-data 救回窗）——表达"这个监听器还在服役、这一轮值不值得发起 accept"，而非"一定有连接"。（前身 `net_can_accept()` 只认 `ESTABLISHED`，会把监听服役窗口全挡掉、丢 CONNECT 探针从不运行——已退役，其 ESTABLISHED 放行态并入本函数，勿再引入） |
|
||||
| `net_can_read` 判据 | `ESTABLISHED` → 看 `readable`；**非 `ESTABLISHED` 一律返 1**（必须让上层 recv 一次拿到 EOF/错误并复位自身状态，门掉它会把"连接已消失"永久藏住）；描述符失效也返 1（让 recv 报 BADF 走既有错误分支） |
|
||||
| 用途 | **门控**：无活时跳过 `net_accept()`/`net_recv()`——两者内部都是 `osMessageQueuePut(osWaitForever)` + `xTaskNotifyWait(portMAX_DELAY)`，**均无上界**（队列深 8 且与 FTP/timeSync 共享） |
|
||||
| ⚠ 不可作为唯一判据 | `readable` 只由 RECV_OK 中断置位，而 §3.6 的对账**不含**"芯片 RX 非空但 `readable=0`" → 事件未收到时 `net_can_read()` 恒返 0。**调用方必须保留低频兜底 recv**（`ui_net_sink.c` 每 32 轮无条件收一次，教训见 `docs/子系统设计/看门狗设计说明.md` §11.5 第 1 条） |
|
||||
@@ -937,9 +937,9 @@ int net_recv(int sockfd, void *buf, int len, int flags);
|
||||
| `flags` | 0=按 socket 阻塞属性等待，`NET_MSG_DONTWAIT`=单次强制非阻塞 |
|
||||
| 返回值 | 实际接收字节数 (>0)；`0`=对端关闭（net 层随即自动重监听）；`-1`=错误（非阻塞无数据=`NET_ERR_WOULDBLOCK`；close/网络重建/陈旧重同步取消=`NET_ERR_CONNRESET`；**阻塞形态无"预算内无数据"一档——默认无限等待，超时是调用方策略**） |
|
||||
|
||||
> **语义主流化（自愈收敛阶段 1.5，2026-10-13）**：对齐 POSIX/Python——`net_recv()` 默认**无限阻塞**（旧 `NET_RECV_TIMEOUT_MS` 30s 默认预算已删，API 不再强加隐藏值）。唤醒源 = 数据 / EOF / close / 网络重建（`NET_ERR_CONNRESET`）；会话死亡由对账①在 ~400ms 内判死兜底（§3.6），不存在"对端消失后永久挂死"窗口。需要"等但不无限等"：首选 `net_select(r,w,e,timeout_ms)`（§7.1），或 `net_recv_to()` 显式预算。
|
||||
> **语义主流化**：对齐 POSIX/Python——`net_recv()` 默认**无限阻塞**（旧 `NET_RECV_TIMEOUT_MS` 30s 默认预算已删，API 不再强加隐藏值）。唤醒源 = 数据 / EOF / close / 网络重建（`NET_ERR_CONNRESET`）；会话死亡由对账①在 ~400ms 内判死兜底（§3.6），不存在"对端消失后永久挂死"窗口。需要"等但不无限等"：首选 `net_select(r,w,e,timeout_ms)`（§7.1），或 `net_recv_to()` 显式预算。
|
||||
>
|
||||
> **L3 pending 化（2026-09-22）**：无数据时阻塞接收**不占 netTask**——登记挂起请求（每 fd 至多一个，禁止覆盖：覆盖会丢失前调用方通知 = 永久挂死）后**立即返回**；完成按主循环节拍检查（①数据 ②到点[仅显式预算] ③断连）并经任务通知唤醒调用方。等待期间调用方在自己上下文睡通知，netTask 全程零占用（消除 E-02 头阻塞）。内部 tripwire（原看门狗降级）：挂起超 60s 只 `[ERR]` 留痕一条（"完成逻辑缺位"探针），**绝不伪造 TIMEDOUT 返回值**。
|
||||
> **挂起 recv 模型**：无数据时阻塞接收**不占 netTask**——登记挂起请求（每 fd 至多一个，禁止覆盖：覆盖会丢失前调用方通知 = 永久挂死）后**立即返回**；完成按主循环节拍检查（①数据 ②到点[仅显式预算] ③断连）并经任务通知唤醒调用方。等待期间调用方在自己上下文睡通知，netTask 全程零占用（消除 E-02 头阻塞）。内部 tripwire（原看门狗降级）：挂起超 60s 只 `[ERR]` 留痕一条（"完成逻辑缺位"探针），**绝不伪造 TIMEDOUT 返回值**。
|
||||
>
|
||||
> ⚠ **文档契约（嵌入式特有，Python 没有）**：IWDG `required_mask` 内任务（当前产品掩码 `0x1F7`：default/net/ftp/ui/timeSync/adc/iec104/protect）**禁止无限阻塞 recv**——必须 `net_select` 超时或 `net_recv_to` 显式预算并周期喂心跳，否则"对端连上不发数据"这种完全正常的场景 = IWDG 复位。
|
||||
|
||||
@@ -954,7 +954,7 @@ int net_recv_nb(int sockfd, void *buf, int len);
|
||||
| `sockfd` / `buf` / `len` | 同 `net_recv` |
|
||||
| 返回值 | >0 字节数；`0`=对端关闭；`-1`=无数据（`NET_ERR_WOULDBLOCK`）或真错误（`net_get_errno` 可查） |
|
||||
|
||||
原 `NET_MSG_DONTWAIT` 路径转正（自愈收敛阶段 1.5）：等价 `net_recv(sockfd, buf, len, NET_MSG_DONTWAIT)`，单次强制非阻塞、不改变 socket 的 blocking 属性。受 IWDG 监控 / 有周期职责的任务的推荐默认入口（生产用户：`ui_net_sink` :7003、`iec104_serv` :2404）。
|
||||
原 `NET_MSG_DONTWAIT` 路径转正：等价 `net_recv(sockfd, buf, len, NET_MSG_DONTWAIT)`，单次强制非阻塞、不改变 socket 的 blocking 属性。受 IWDG 监控 / 有周期职责的任务的推荐默认入口（生产用户：`ui_net_sink` :7003、`iec104_serv` :2404）。
|
||||
|
||||
#### net_setblocking - 设置阻塞模式属性
|
||||
|
||||
@@ -979,7 +979,7 @@ int net_recv_to(int sockfd, void *buf, int len, uint32_t timeout_ms);
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `sockfd` / `buf` / `len` | 同 `net_recv` |
|
||||
| `timeout_ms` | 本片等待预算（ms，**必须 >0**；0 = `net_recv` 的无限等待语义，恰与本接口"有界"存在理由相反，直接拒 `NET_ERR_INVAL`——自愈收敛阶段 1.5 起本接口是**显式预算**入口，不再有"默认 30s"隐藏值） |
|
||||
| `timeout_ms` | 本片等待预算（ms，**必须 >0**；0 = `net_recv` 的无限等待语义，恰与本接口"有界"存在理由相反，直接拒 `NET_ERR_INVAL`——本接口是**显式预算**入口，没有"默认 30s"隐藏值） |
|
||||
| 返回值 | >0=字节数（允许部分读，TCP 分段）；`0`=对端关闭（排空残留后）；`-1`=真错误（`net_get_errno` 可查）；**-2=本片预算内无数据**（**不是 errno**，不得依赖 errno 判超时——`s_net_errno` 是跨任务共享全局量） |
|
||||
|
||||
调用方累计自身总预算：见到 -2 发起下一片，直到收齐 / EOF / 总预算耗尽。生产用途：lftpd 数据行读、timeSync 帧读（E-02 头阻塞修复，完整例 §11.2）；受 IWDG 监控任务的长等待必须走本接口（或 `net_select`）+ 每片喂心跳。
|
||||
@@ -1006,7 +1006,7 @@ int net_close(int sockfd);
|
||||
|
||||
释放 Socket 控制块，TCP 先断开连接。⚠ **单连接模型（MCU 端 CH395F）不得对监听 fd 调本 API**——连接与监听同一 fd，close 会连监听一起毁掉（§12.4）；EOF 时 net 层已 `auto_relisten`，应用层**不得**在 EOF 时 close 该 fd。"放弃会话但保监听"用下面的 `net_drop_conn()`。
|
||||
|
||||
#### net_drop_conn - 主动拆会话、保留监听（自愈收敛阶段 3，E-02 收口）
|
||||
#### net_drop_conn - 主动拆会话、保留监听（E-02 收口）
|
||||
|
||||
```c
|
||||
int net_drop_conn(int sockfd);
|
||||
@@ -1031,12 +1031,12 @@ int net_sock_state(int sockfd);
|
||||
|
||||
跨任务只读快照（单字节读）；描述符无效/未占用返回 -1；值可能滞后 netTask 最新状态。用于**状态轮询**（客户端等 ESTABLISHED，§5.2），不替代 accept/connect。
|
||||
|
||||
**net_resync_listen / net_relisten — 已退役（自愈收敛阶段1，勿再引入）**
|
||||
**net_resync_listen / net_relisten — 已退役（勿再引入）**
|
||||
|
||||
两者曾是"应用层手动自愈"入口：`net_resync_listen()` 只修 MCU 侧状态（D14 静默回收），`net_relisten()` 无条件芯片侧 open+listen。现状：
|
||||
|
||||
- **静默回收**由对账⑤自动认领（§3.6：本层 ESTABLISHED 而芯片 0x05/0x01 → RESYNC 语义，≤400ms 去抖 + 1s 冷却，纪律"不发芯片命令"原样保留在认领动作内）——应用无需判定"连接是否已死"，也就消除了"误判活连接调 resync 把活连接标成监听态"的 footgun。
|
||||
- **监听重建**由 reconciler 形态③④（100ms 周期，唯一重建入口；自愈收敛阶段 3 起原 pump 已并入 `net_reconcile_tick`）/ D10（30ms 重试）单一所有者负责——`net_relisten()` 对健康监听器反而是 footgun（无条件 open→USE→close 自毁 ~1s，原注释自认）。
|
||||
- **监听重建**由 reconciler 形态③④（100ms 周期，唯一重建入口 = `net_reconcile_tick`）/ D10（30ms 重试）单一所有者负责——`net_relisten()` 对健康监听器反而是 footgun（无条件 open→USE→close 自毁 ~1s，原注释自认）。
|
||||
|
||||
生产调用者本就为零（仅板级测试 Phase 13，已改由自动机制接管）。历史实现见 `net_socket.c` git 历史。
|
||||
|
||||
@@ -1059,11 +1059,11 @@ void net_process_messages(void);
|
||||
处理其他任务投递的请求（send/recv/connect/accept/close/drop_conn）。每次调用先跑 4 个**非阻塞** tick，再取队列消息（0 超时出队）：
|
||||
|
||||
1. **D10 重监听重试**（`net_listener_tick`）：断连后监听器恢复的到点重试（30ms 间隔 / 2s 时限，§3.6）
|
||||
2. **L3 挂起 recv 完成检查**（`net_pending_tick`）：按 ①数据 ②到点（仅显式预算） ③断连 检查每个挂起请求并通知调用方；④ 挂起超时留痕探针（编译期选项，默认关）：挂起超阈值只 `[ERR]` 留痕一次，不强制结束
|
||||
3. **L3 挂起 send 推进**（`net_send_pending_tick`）：按 ①断连 ②推进（每轮至多一块 `NET_SEND_CHUNK_MAX`） ③写完 ④无进展超时 推进挂起 send 并通知调用方（结果恒为已发字节数，短写由调用方检查）
|
||||
2. **挂起 recv 完成检查**（`net_pending_tick`）：按 ①数据 ②到点（仅显式预算） ③断连 检查每个挂起请求并通知调用方；④ 挂起超时留痕探针（编译期选项，默认关）：挂起超阈值只 `[ERR]` 留痕一次，不强制结束
|
||||
3. **挂起 send 推进**（`net_send_pending_tick`）：按 ①断连 ②推进（每轮至多一块 `NET_SEND_CHUNK_MAX`） ③写完 ④无进展超时 推进挂起 send 并通知调用方（结果恒为已发字节数，短写由调用方检查）
|
||||
4. **TRAP-NET-17 芯片/本层对账 + 监听重建（合一 `net_reconcile_tick`）**：100ms 周期，判据读驱动状态缓存（`ch395f_sock_state_cached`），修正**五类**失同步（①②③④⑤）+ U11 被动重同步——原 200ms 对账与 100ms 监听器 pump 已合并为单一 tick，**唯一重建入口**=形态③④（§3.6）
|
||||
|
||||
> `net_msg_t.timeout_ms`：L3 显式预算（`net_recv_to()`），0=**无限等待**（自愈收敛阶段 1.5 删除 `NET_RECV_TIMEOUT_MS` 30s 默认预算——超时归调用方）。消息类型 7 种（send/recv/close/connect/listen/accept/drop_conn）——自愈类消息 `NET_MSG_RESYNC_LISTEN` / `NET_MSG_RELISTEN` 已随 API 退役删除（自愈收敛阶段1）。
|
||||
> `net_msg_t.timeout_ms`：显式预算（`net_recv_to()`），0=**无限等待**（无 `NET_RECV_TIMEOUT_MS` 30s 默认预算——超时归调用方）。消息类型 7 种（send/recv/close/connect/listen/accept/drop_conn）——自愈类消息 `NET_MSG_RESYNC_LISTEN` / `NET_MSG_RELISTEN` 已随 API 退役删除。
|
||||
|
||||
#### net_send_sock - 发送数据（内部版本）
|
||||
|
||||
@@ -1207,7 +1207,7 @@ void tcp_client_reconnect(void)
|
||||
net_send(sock, "heartbeat", 9, 0);
|
||||
}
|
||||
|
||||
/* 检查接收（自愈收敛阶段 1.5：非阻塞具名入口 net_recv_nb） */
|
||||
/* 检查接收（非阻塞具名入口 net_recv_nb） */
|
||||
char buf[128];
|
||||
int len = net_recv_nb(sock, buf, sizeof(buf) - 1);
|
||||
if (len > 0) {
|
||||
@@ -1234,7 +1234,7 @@ void tcp_client_reconnect(void)
|
||||
|
||||
### 11.2 分片阻塞读（`net_recv_to`，timeSync 模式）
|
||||
|
||||
长等待 recv 曾独占 netTask（E-02 头阻塞）。L3 pending 化后：单次 `net_recv_to` 单次占用有界（≤ 本片预算）且等待期间 netTask 零占用（挂起模型）；调用方累计总预算，收齐协议帧再返回：
|
||||
长等待 recv 曾独占 netTask（E-02 头阻塞）。挂起 recv 模型下：单次 `net_recv_to` 单次占用有界（≤ 本片预算）且等待期间 netTask 零占用（挂起模型）；调用方累计总预算，收齐协议帧再返回：
|
||||
|
||||
```c
|
||||
#define FRAME_LEN 8 /* "TIME" + uint32 大端 本地时间 */
|
||||
@@ -1278,7 +1278,7 @@ static int read_time_frame(int conn_sock, uint8_t buf[FRAME_LEN]) {
|
||||
**是的**，且 `net_poll()` 与 `net_process_messages()` 缺一不可：
|
||||
|
||||
- `net_poll()`：GPIO 轮询 INT#，**每轮批处理一批**中断，更新各 Socket 状态、触发事件回调（RECV 为电平触发，每轮只处理一批，避免饿死主循环）。
|
||||
- `net_process_messages()`：除串行处理队列请求外，每轮先跑 4 个**非阻塞**检查——D10 重监听重试（断连后监听器恢复）→ L3 挂起 recv 完成检查（阻塞 recv 的唤醒）→ L3 挂起 send 推进（阻塞 send 的唤醒）→ TRAP-NET-17 芯片/本层对账 + 监听重建合一 reconciler（100ms 周期，读驱动状态缓存，事件未收到/静默回收/监听失位自愈，§3.6）。
|
||||
- `net_process_messages()`：除串行处理队列请求外，每轮先跑 4 个**非阻塞**检查——D10 重监听重试（断连后监听器恢复）→ 挂起 recv 完成检查（阻塞 recv 的唤醒）→ 挂起 send 推进（阻塞 send 的唤醒）→ TRAP-NET-17 芯片/本层对账 + 监听重建合一 reconciler（100ms 周期，读驱动状态缓存，事件未收到/静默回收/监听失位自愈，§3.6）。
|
||||
|
||||
建议主循环周期 ≤ 10ms（本项目 1ms）。若 netTask 主循环停摆（断点、任务被挂起），监听器不会恢复、阻塞 recv 不会完成——这是软件侧"监听死机"的最常见原因。
|
||||
|
||||
@@ -1307,7 +1307,7 @@ if (len <= 0) {
|
||||
}
|
||||
```
|
||||
|
||||
**方式二：非阻塞接收（`net_recv_nb`，自愈收敛阶段 1.5 转正）**
|
||||
**方式二：非阻塞接收（`net_recv_nb`）**
|
||||
```c
|
||||
int len = net_recv_nb(sock, buf, sizeof(buf));
|
||||
if (len < 0 && net_get_errno() == NET_ERR_WOULDBLOCK) {
|
||||
@@ -1338,7 +1338,7 @@ if (len < 0 && net_get_errno() == NET_ERR_WOULDBLOCK) {
|
||||
|
||||
**芯片静默回收（D14，2026-09-22 台架实证）**：对端发 FIN 后，芯片可能**自行把 Socket 回收回 LISTEN 且不发 DISCONNECT 中断** → 本层滞留 ESTABLISHED，应用继续往死连接上读写，新连接的字节被旧会话吞掉。
|
||||
|
||||
**无需应用处理（自愈收敛阶段1 起）**：对账⑤自动认领此形态（§3.6：2 轮去抖 ≈200ms + 1s 冷却）→ RESYNC 语义只修本层状态 + 取消本 fd 挂起 recv，**不发任何芯片命令**（发 close/重监听会摧毁芯片侧健康监听器 → 连接永拒，run8 实证 170s 拒绝）。等待期间该端口实际可接新连接（芯片侧已 LISTEN），新连接经对账补 accept 被本层感知。原显式 API `net_resync_listen(fd)` 已退役——"应用判定连接已死"这一步本身就是误判源（对活连接调用会把活连接标成监听态）。
|
||||
**无需应用处理**：对账⑤自动认领此形态（§3.6：2 轮去抖 ≈200ms + 1s 冷却）→ RESYNC 语义只修本层状态 + 取消本 fd 挂起 recv，**不发任何芯片命令**（发 close/重监听会摧毁芯片侧健康监听器 → 连接永拒，run8 实证 170s 拒绝）。等待期间该端口实际可接新连接（芯片侧已 LISTEN），新连接经对账补 accept 被本层感知。原显式 API `net_resync_listen(fd)` 已退役——"应用判定连接已死"这一步本身就是误判源（对活连接调用会把活连接标成监听态）。
|
||||
|
||||
⚠ 切勿用**单次**芯片状态读决定重建：单次读可能落在"刚 open 未生效"瞬态，曾致监听反复重建直至 `relisten give up`（2026-09-23 实测风暴，三服务口全死）——任何重建动作必须去抖（连续确认）+ 冷却（§3.6）。
|
||||
|
||||
@@ -1422,7 +1422,7 @@ CH395F 底层驱动返回的状态码（`ch395f_get_cmd_status()` 或 `ch395f_po
|
||||
|
||||
**问题：`netTask` 内可以直接调用 `net_send()` / `net_recv()` 吗？**
|
||||
|
||||
不可以。`netTask` 中必须使用 `net_send_sock()` / `net_recv_sock()` 等内部版本，否则会死锁（任务向自身发送消息，永远无人处理）。netTask 上下文的"立即看有无数据"需求用 `NET_MSG_DONTWAIT`（L3：挂起请求对执行任务自身发起时直接拒绝，防自等自通知死锁）。
|
||||
不可以。`netTask` 中必须使用 `net_send_sock()` / `net_recv_sock()` 等内部版本，否则会死锁（任务向自身发送消息，永远无人处理）。netTask 上下文的"立即看有无数据"需求用 `NET_MSG_DONTWAIT`（挂起请求对执行任务自身发起时直接拒绝，防自等自通知死锁）。
|
||||
|
||||
**问题：哪些操作要求 netTask 已运行？**
|
||||
|
||||
@@ -1443,13 +1443,13 @@ CH395F 底层驱动返回的状态码（`ch395f_get_cmd_status()` 或 `ch395f_po
|
||||
需要回传请用调用方提供的指针，或复用通知值。（2026-09-21 实证：曾按"加 `msg.err` 字段"方式修错误码，
|
||||
结果 `ui_net_sink` 每次空轮询都拿到栈垃圾 → 误判为"真错误" → 连上即 `net_close`。）
|
||||
|
||||
### 12.10 监听器自愈行为与沉降/隔离（D10 / TRAP-NET-09、TRAP-NET-17、TRAP-NET-18 / N-32）
|
||||
### 12.10 监听器自愈行为与沉降/隔离（D10 / TRAP-NET-09、TRAP-NET-17、TRAP-NET-18）
|
||||
|
||||
**默认行为**（无需应用代码）：断连 → `auto_relisten` 重开监听；重开失败 → 30ms 节奏重试（2s 时限）；芯片事件未收到/静默回收/监听失位 → 单一 reconciler 100ms 自愈（分级去抖，自愈收敛阶段 3 起对账与 pump 合一）；中止复连首上传 → 沉降/隔离。全在 netTask 内，应用只需保证 `net_poll()` + `net_process_messages()` 主循环在跑。
|
||||
**默认行为**（无需应用代码）：断连 → `auto_relisten` 重开监听；重开失败 → 30ms 节奏重试（2s 时限）；芯片事件未收到/静默回收/监听失位 → 单一 reconciler 100ms 自愈（分级去抖，对账与重建合一）；中止复连首上传 → 沉降/隔离。全在 netTask 内，应用只需保证 `net_poll()` + `net_process_messages()` 主循环在跑。
|
||||
|
||||
| 场景 | 修复前症状 | 机制 | 生产验证（2026-09-23） |
|
||||
|---|---|---|---|
|
||||
| **TRAP-NET-17** 快速复连事件面未收到 → 监听静默死亡（E14 复核：非芯片丢事件，是读清消费竞态） | 待机后 UI `:7003` 快速复连 2/10 且**永久**拒连；FTP `:21` 100ms 间隔自第 29 轮死亡；设备日志**无报错**（状态静默滞留） | 单一 reconciler `net_reconcile_tick()`（100ms，对账①②⑤ + 重建③④/U11 合一，**唯一重建入口**=形态③④，自愈收敛阶段 3；判据读驱动状态缓存）+ 分级去抖（②1 轮/③④⑤2 轮/①4 轮）+ 冷却（1s）；`handle_disconnect_event` 只置沉降事实、不再自行重建 | `:7003` 10/10；`:21` 100ms/0ms/600ms 各 50/50；UI 20/20；FTP 正常 10/10（SHA-256）；中止 RST/FIN 5/5 + 5/5；零重建风暴（2026-10-13 合并后复测 `:7003` 50/50、`:21` 三档各 50/50 全绿） |
|
||||
| **TRAP-NET-17** 快速复连事件面未收到 → 监听静默死亡（E14 复核：非芯片丢事件，是读清消费竞态） | 待机后 UI `:7003` 快速复连 2/10 且**永久**拒连；FTP `:21` 100ms 间隔自第 29 轮死亡；设备日志**无报错**（状态静默滞留） | 单一 reconciler `net_reconcile_tick()`（100ms，对账①②⑤ + 重建③④/U11 合一，**唯一重建入口**=形态③④；判据读驱动状态缓存）+ 分级去抖（②1 轮/③④⑤2 轮/①4 轮）+ 冷却（1s）；`handle_disconnect_event` 只置沉降事实、不再自行重建 | `:7003` 10/10；`:21` 100ms/0ms/600ms 各 50/50；UI 20/20；FTP 正常 10/10（SHA-256）；中止 RST/FIN 5/5 + 5/5；零重建风暴（2026-10-13 合并后复测 `:7003` 50/50、`:21` 三档各 50/50 全绿） |
|
||||
| **TRAP-NET-18** 中止后首笔复连上传被静默截断 ≤2048B 并误报 226 成功 | RST/FIN 中止上传 → 紧接着的首笔上传"收"到 ~2KB 残留后判结束回 226 → 客户端以为成功 = **静默数据损坏**（第二笔起正常） | 异常释放（TIMEOUT）预重监听隔离：`net_drain_chip_rx()` 分块排空 RX 残渣 + 主动 close + 排空中断 + 等 CLOSED/TCP_CLOSED（400ms 起 / 800ms 上限 < 2s 时限） | RST 10/10、FIN 5/5 全通过；正常路径 30/30 + 20/20，SHA-256 全匹配 |
|
||||
| **TC-NET-604**"接收冻结"虚警 | 旧判读脚本把"对端填满 2KB RX 窗口"误判为 STALL/WEDGE | **结论：非缺陷**（芯片 RX 缓冲即窗口，对端填满是常态）；判据改为脚本层 STEP + 客户端内容校验（RET SHA-256），虚警工具归档（`MDK-ARM/retracted_bench_20260922/`，README 禁重跑） | 真实 FTP 路径 227 轮全通过（8KB×10 … 1MB×2）；并发 UI 流 600/600 CRC；设备零 FAIL/ERROR/WARN |
|
||||
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
> **定位**：本文档是 `docs/网络/BSD_Socket_API_使用指南.md`（下称"使用指南"）的**内部视图**伴读文档。
|
||||
> 使用指南回答"**上层该怎么调**"（公开语义 / 示例 / 常见问题）；本文回答"**内部函数各自做什么、互相怎么调用、为什么这么设计**"（调用关系 / 设计意图 / 踩坑）。
|
||||
>
|
||||
> **范围**：MCU 端 `Drivers/BSP/NET/net_socket.c`（约 3660 行）+ 其拆出的
|
||||
> `Drivers/BSP/NET/net_listener.c`（约 550 行，**监听生命周期**，N-32 §10 模块化）+
|
||||
> `Drivers/BSP/NET/net_pending.c`（约 690 行，**挂起 recv / send 请求表**；send 组为 2026-10-14 二期新增）。
|
||||
> **范围**：MCU 端 `Drivers/BSP/NET/net_socket.c` + 其拆出的
|
||||
> `Drivers/BSP/NET/net_listener.c`（**监听生命周期**）+
|
||||
> `Drivers/BSP/NET/net_pending.c`（**挂起 recv / send 请求表**）。
|
||||
> 模拟器端后端 `simulator/sim/net_socket_sim.c`（Winsock）是另一套实现，见 `docs/网络/BSD_Socket_API_使用指南.md` §2.3；`net_select.c` 不在此展开，见 `docs/网络/BSD_Socket_API_使用指南.md` §7 / §10.5。
|
||||
> `net_listener.c` / `net_pending.c` 真机专属（模拟器不编译）；设计依据分别见
|
||||
> `docs/网络/网络自愈架构设计.md` §11 与
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
## 1. 一句话架构
|
||||
|
||||
**一切芯片（CH395F）操作收敛到唯一执行者 netTask 串行完成**；其他任务通过"入队消息 + 任务通知"表达请求，结果只经**任务通知值**回传；阻塞等待**不独占 netTask**（挂起登记 + 主循环节拍完成）；监听器**常驻**（`auto_relisten` + D10 非阻塞重试 + **TRAP-NET-17 周期对账 + 监听重建合一 `net_reconcile_tick`（唯一重建入口=形态③④，100ms）** + TRAP-NET-18 排渣隔离，四层自愈；自愈收敛阶段 3 起原 N-32 监听器 pump 已并入对账）。
|
||||
**一切芯片（CH395F）操作收敛到唯一执行者 netTask 串行完成**；其他任务通过"入队消息 + 任务通知"表达请求，结果只经**任务通知值**回传；阻塞等待**不独占 netTask**（挂起登记 + 主循环节拍完成）；监听器**常驻**（`auto_relisten` + D10 非阻塞重试 + **TRAP-NET-17 周期对账 + 监听重建合一 `net_reconcile_tick`（唯一重建入口=形态③④，100ms）** + TRAP-NET-18 排渣隔离，四层自愈；原监听器 pump 已并入对账）。
|
||||
|
||||
---
|
||||
|
||||
@@ -25,7 +25,7 @@
|
||||
|
||||
| 执行域 | 运行位置 / 节奏 | 允许的操作 | 典型调用者 |
|
||||
|---|---|---|---|
|
||||
| **netTask 主循环** | 独立 FreeRTOS 任务，1ms/tick | **唯一**可碰芯片（SPI2）的地方；4 个非阻塞 tick（D10 重试 / L3 挂起 recv / L3 挂起 send / TRAP-NET-17 对账+监听重建合一 reconciler）；队列分派；事件处理器；用户回调 | `net_poll` / `net_process_messages` 及其下游全部 `_locked` / `_tick` / `handle_*` |
|
||||
| **netTask 主循环** | 独立 FreeRTOS 任务，1ms/tick | **唯一**可碰芯片（SPI2）的地方；4 个非阻塞 tick（D10 重试 / 挂起 recv / 挂起 send / TRAP-NET-17 对账+监听重建合一 reconciler）；队列分派；事件处理器；用户回调 | `net_poll` / `net_process_messages` 及其下游全部 `_locked` / `_tick` / `handle_*` |
|
||||
| **应用任务侧** | ftpTask / uiTask / timeSyncTask / testTask 等 | 经队列的公共 API（入队 + `xTaskNotifyWait` 等回执）；纯 RAM 直调 API；**禁止直碰芯片** | 各服务任务 |
|
||||
| **直调快路径** | 同步调用，不经过队列 | `net_socket` / 查询族 / 回调注册（纯 RAM）；**直碰 SPI 的三例外**：`net_bind`(UDP) / `net_sendto` / `net_recvfrom` | 初始化阶段、netTask 上下文、测试套件（硬件层测试模式下 netTask 自挂起，testTask 独占芯片） |
|
||||
|
||||
@@ -51,9 +51,9 @@ flowchart TB
|
||||
NPM["netProcessMessages<br/>先跑 4 个 tick，再排空队列分派"]
|
||||
NP["netPoll<br/>INT# GPIO 轮询 → 全局中断 → 各 Socket SINT → 状态缓存全量刷新 + sock_reset 步进 → 每轮一批"]
|
||||
T1["① netListenerRetryTick<br/>D10 重监听重试：30ms / 2s 时限"]
|
||||
T2["② netPendingTick<br/>L3 挂起 recv：①数据 ②到点(仅显式预算) ③断连 ④tripwire 60s 只留痕"]
|
||||
T2B["③ netSendPendingTick<br/>L3 挂起 send：①断连 ②推进(每轮≤1块) ③写完 ④无进展超时"]
|
||||
T3["④ netReconcileTick<br/>TRAP-NET-17 对账 + 监听重建合一（自愈收敛阶段 3）：100ms / 分级去抖 / 冷却<br/>读驱动状态缓存（①②③④⑤ + U11）"]
|
||||
T2["② netPendingTick<br/>挂起 recv：①数据 ②到点(仅显式预算) ③断连 ④tripwire 60s 只留痕"]
|
||||
T2B["③ netSendPendingTick<br/>挂起 send：①断连 ②推进(每轮≤1块) ③写完 ④无进展超时"]
|
||||
T3["④ netReconcileTick<br/>TRAP-NET-17 对账 + 监听重建合一：100ms / 分级去抖 / 冷却<br/>读驱动状态缓存（①②③④⑤ + U11）"]
|
||||
DISP["队列分派 switch<br/>SEND · RECV · CLOSE<br/>CONNECT · LISTEN · ACCEPT · DROP_CONN"]
|
||||
subgraph LK["_locked / 内部分派目标（仅 netTask 上下文）"]
|
||||
LL["netListenLocked<br/>初次监听（open 重试 3× + sock_reset 排渣）"]
|
||||
@@ -80,8 +80,8 @@ flowchart TB
|
||||
T1 --> RLS
|
||||
T3 -->|"① 已断"| EV
|
||||
T3 -->|"② 补 accept"| EV
|
||||
T3 -->|"⑤ 静默回收：RESYNC 只修本层 + 取消挂起（不发芯片命令，自愈收敛阶段1 吸收原 net_resync_listen 语义）"| RSY["reconcile⑤ RESYNC 动作"]
|
||||
T3 -->|"③④ 监听失位 / 孤儿监听即重建（原 pump，自愈收敛阶段 3）"| RLS
|
||||
T3 -->|"⑤ 静默回收：RESYNC 只修本层 + 取消挂起（不发芯片命令，吸收原 net_resync_listen 语义）"| RSY["reconcile⑤ RESYNC 动作"]
|
||||
T3 -->|"③④ 监听失位 / 孤儿监听即重建（原 pump）"| RLS
|
||||
DC -->|"拆会话后登记重监听"| RLS
|
||||
NP --> EV
|
||||
EV --> FE
|
||||
@@ -105,7 +105,7 @@ flowchart TB
|
||||
|
||||
1. 应用侧只有两种"等"：① 入队后 `xTaskNotifyWait` 等回执（同步语义）；② 挂起 recv / send 的等待（同一通道，只是"完成"由 `netPendingTick` / `netSendPendingTick` 判定，不由 netTask 立即处理）。
|
||||
2. `net_process_messages()` 开头的 **4 个 tick 是网络层自愈主干**：没有任何应用消息时，重试 / 挂起 recv 完成 / 挂起 send 推进 / 状态对账 + 监听重建照常运转——"断连后即使没人发消息，监听器也能自己活过来"靠的就是它们。
|
||||
3. 事件处理器**只由 `net_poll` 驱动**，例外是 `net_reconcile_tick`（分级去抖 + 1s 冷却）可再入 `handle_disconnect_event` / `handle_connect_event`——对账是事件未收到的自愈通道（TRAP-NET-17）。**注意职责边界（N-32 P2，自愈收敛阶段 3 合并后）**：对账与事件处理器**只置事实**（置 CLOSED / 登记沉降），**重建监听的动作统一由 `net_reconcile_tick` 形态③④ 做**（本层唯一重建入口）——"谁先看到 DISCONNECT 就谁重建"的竞争在结构上消失。
|
||||
3. 事件处理器**只由 `net_poll` 驱动**，例外是 `net_reconcile_tick`（分级去抖 + 1s 冷却）可再入 `handle_disconnect_event` / `handle_connect_event`——对账是事件未收到的自愈通道（TRAP-NET-17）。**注意职责边界（对账与重建合并后）**：对账与事件处理器**只置事实**（置 CLOSED / 登记沉降），**重建监听的动作统一由 `net_reconcile_tick` 形态③④ 做**（本层唯一重建入口）——"谁先看到 DISCONNECT 就谁重建"的竞争在结构上消失。
|
||||
4. 回调 `event_cb` 在 **netTask 上下文**执行：回调内不得阻塞、不得发网络操作。
|
||||
5. **模块归属**：`T1`（D10 重试）/ `RLS` 的 `net_listener_request` / `ST`（settle）在 `net_listener.c`（真机专属、模拟器不编译）；挂起 recv 完成检查（`net_pending_tick`）、挂起 send 推进（`net_send_pending_tick`）与两张挂起表（`PR` / `SR`）在 `net_pending.c`（真机专属）；其余 tick（含合并后的 `T3` reconciler）与 `_locked` 在 `net_socket.c`。
|
||||
|
||||
@@ -125,8 +125,8 @@ flowchart TB
|
||||
|
||||
| 函数 | 设计作用 | 主要调用 | 意图 / 注意 |
|
||||
|---|---|---|---|
|
||||
| `net_poll()` | 事件泵：GPIO 轮询 INT#（低=有待处理）→ `GET_GLOB_INT_STATUS_ALL`（读=清）→ 按位图逐 Socket 读 SINT → 分派 5 类事件；**每轮末尾**对在用 Socket 全量刷新**驱动状态缓存** + 步进 `ch395f_sock_reset_poll`（自愈收敛阶段 3） | `HAL_GPIO_ReadPin` → `ch395f_get_glob_int_status_all` → `ch395f_get_sock_int_status` ×n → `handle_connect/disconnect/recv/send/timeout_event` → `ch395f_get_sock_state` ×n（刷新缓存）+ `ch395f_sock_reset_poll` ×n | **RECV 中断是电平触发**：每次调用**只处理一批**（do-while(0)），处理完立即返回，否则主循环（echo/应用逻辑）饿死（TRAP-NET-08）；SENBUF_FREE 只置 `send_ready` 不记事件；状态缓存**唯一刷新点**在此（reconciler 只读缓存，E2 实测单次回读 18.1µs）；`sock_reset_poll` 步进使同步包装 600ms 放弃后的复位机不搁浅（IDLE 槽纯 RAM 判零 SPI） |
|
||||
| `net_process_messages()` | 队列入口 + 自愈 tick 宿主：每轮**先**跑 4 个非阻塞 tick，再排空队列逐条分派，结果 `xTaskNotify` 回传 | `net_listener_tick` → `net_pending_tick` → `net_send_pending_tick` → `net_reconcile_tick`（对账+重建合一）→ `osMessageQueueGet`(0 超时) ×n → switch 分派 → `xTaskNotify` | ① tick 放在队列**之前**：断连后即使没有任何应用消息，监听器也能自主恢复、挂起 recv / send 也能完成；② RECV 若返回 `NET_PENDING_REGISTERED`（哨兵 0x70000000）则**不发即时回执**（`do_notify=0`），完成时才通知；③ 失败结果把 `s_net_errno`（具体负错误码）压入通知值——调用方恢复 errno 后对外统一 -1（BSD 语义）；④ 通知值**整个 32 位**都是结果（不压位域标签，否则 32768 这类大字节数会溢出为负）；⑤ **对账①置 CLOSED 后形态③④同轮即可重建**（自愈收敛阶段 3 合并，原"pump 置于对账之后"的顺序依赖在单 tick 内自然成立） |
|
||||
| `net_poll()` | 事件泵：GPIO 轮询 INT#（低=有待处理）→ `GET_GLOB_INT_STATUS_ALL`（读=清）→ 按位图逐 Socket 读 SINT → 分派 5 类事件；**每轮末尾**对在用 Socket 全量刷新**驱动状态缓存** + 步进 `ch395f_sock_reset_poll` | `HAL_GPIO_ReadPin` → `ch395f_get_glob_int_status_all` → `ch395f_get_sock_int_status` ×n → `handle_connect/disconnect/recv/send/timeout_event` → `ch395f_get_sock_state` ×n（刷新缓存）+ `ch395f_sock_reset_poll` ×n | **RECV 中断是电平触发**：每次调用**只处理一批**（do-while(0)），处理完立即返回，否则主循环（echo/应用逻辑）饿死（TRAP-NET-08）；SENBUF_FREE 只置 `send_ready` 不记事件；状态缓存**唯一刷新点**在此（reconciler 只读缓存，E2 实测单次回读 18.1µs）；`sock_reset_poll` 步进使同步包装 600ms 放弃后的复位机不搁浅（IDLE 槽纯 RAM 判零 SPI） |
|
||||
| `net_process_messages()` | 队列入口 + 自愈 tick 宿主：每轮**先**跑 4 个非阻塞 tick，再排空队列逐条分派，结果 `xTaskNotify` 回传 | `net_listener_tick` → `net_pending_tick` → `net_send_pending_tick` → `net_reconcile_tick`（对账+重建合一）→ `osMessageQueueGet`(0 超时) ×n → switch 分派 → `xTaskNotify` | ① tick 放在队列**之前**：断连后即使没有任何应用消息，监听器也能自主恢复、挂起 recv / send 也能完成；② RECV 若返回 `NET_PENDING_REGISTERED`（哨兵 0x70000000）则**不发即时回执**（`do_notify=0`），完成时才通知；③ 失败结果把 `s_net_errno`（具体负错误码）压入通知值——调用方恢复 errno 后对外统一 -1（BSD 语义）；④ 通知值**整个 32 位**都是结果（不压位域标签，否则 32768 这类大字节数会溢出为负）；⑤ **对账①置 CLOSED 后形态③④同轮即可重建**（合并后，原"pump 置于对账之后"的顺序依赖在单 tick 内自然成立） |
|
||||
|
||||
### 4.3 经队列的公共 API 及其 netTask 侧实现
|
||||
|
||||
@@ -134,17 +134,17 @@ flowchart TB
|
||||
|
||||
| 公共 API | 消息 | netTask 侧实现 | 关键芯片命令 | 返回语义 | 设计意图 / 注意 |
|
||||
|---|---|---|---|---|---|
|
||||
| `net_listen` | `NET_MSG_LISTEN` | `net_listen_locked` | `set_proto_type` + `set_sour_port` + `open_socket`（**open 重试 3×，失败走 `net_sock_reset_sync` 确定性排渣**，自愈收敛阶段 3）+ `tcp_listen` + 清**本 Socket** 中断状态 | 0 / -1 | **初次**监听允许有界重试（启动期无竞争）；成功后置 `auto_relisten=1`——监听常驻的源头；启动前只清本 Socket SINT（B3/F-NET-7：全局寄存器唯一读者 = `net_poll`，全量读清会焊死其它 Socket 事件位）；open 失败重试原"close+盲等 500ms"已换 sock_reset（GRACEFUL 100ms 底，E4 定案复位后 open 必成） |
|
||||
| `net_accept` | `NET_MSG_ACCEPT` | `net_accept_locked` | 无（先 `net_poll` 泵一次 + 状态判定） | 监听 fd 自身（单连接）/ -1（WOULDBLOCK） | 单连接：监听 Socket 在 CONNECT 后**自身即数据通道**，返回的就是它；CLOSED + auto_relisten 时触发**非阻塞** `net_listener_request`；**accept 路径不做自愈**——单次状态读会误判"刚 listen 未生效"致重建风暴（2026-09-23 实测），统一交给 `net_reconcile_tick` 形态③④（自愈收敛阶段 3 合并后的单一重建入口） |
|
||||
| `net_listen` | `NET_MSG_LISTEN` | `net_listen_locked` | `set_proto_type` + `set_sour_port` + `open_socket`（**open 重试 3×，失败走 `net_sock_reset_sync` 确定性排渣**）+ `tcp_listen` + 清**本 Socket** 中断状态 | 0 / -1 | **初次**监听允许有界重试（启动期无竞争）；成功后置 `auto_relisten=1`——监听常驻的源头；启动前只清本 Socket SINT（B3/F-NET-7：全局寄存器唯一读者 = `net_poll`，全量读清会焊死其它 Socket 事件位）；open 失败重试原"close+盲等 500ms"已换 sock_reset（GRACEFUL 100ms 底，E4 定案复位后 open 必成） |
|
||||
| `net_accept` | `NET_MSG_ACCEPT` | `net_accept_locked` | 无（先 `net_poll` 泵一次 + 状态判定） | 监听 fd 自身（单连接）/ -1（WOULDBLOCK） | 单连接：监听 Socket 在 CONNECT 后**自身即数据通道**，返回的就是它；CLOSED + auto_relisten 时触发**非阻塞** `net_listener_request`；**accept 路径不做自愈**——单次状态读会误判"刚 listen 未生效"致重建风暴（2026-09-23 实测），统一交给 `net_reconcile_tick` 形态③④（合并后的单一重建入口） |
|
||||
| `net_connect` | `NET_MSG_CONNECT` | `net_connect_locked` | `set_proto_type` + `open_socket`（open 重试 3× + `net_sock_reset_sync` 排渣）+ 清残留中断（只清本 Socket SINT，`ch395f_sock_events`）+ `set_sour_port` / `set_des_ip`（大端数组）/ `set_des_port` + `tcp_connect` | 0 = 请求已发出（**异步**）/ -1 | open **先于**寄存器写入（open 会复位寄存器）；open 后清残留 DISCONNECT，防新连接秒断（TRAP-NET-12）；目的 IP 字节序写反 = CONNECT TIMEOUT（TRAP-NET-14）；返回 0 ≠ 已建立——调用方以 `net_sock_state` 轮询等 ESTABLISHED |
|
||||
| `net_send` | `NET_MSG_SEND` | `net_send_locked` | `ch395f_write_send_buf`（分块）+ 等 SENBUF_FREE（`net_poll` 轮询，**有界自旋 ≤ `NET_SEND_SPIN_MS`**）；超预算登记挂起 send（`net_send_pending_register`） | 实际字节数 / -1 | 分块 ≤ `NET_SEND_CHUNK_MAX` = 1KB（**硬件发送 FIFO 硬上限**，TRAP-NET-16：写穿 FIFO = 数据错位）；`send_ready` 门控用 `net_poll` 轮询而非 osDelay，**自旋超 `NET_SEND_SPIN_MS`（2ms）即转挂起**（netTask 最坏停滞由 1s 压到 2ms）；短写**必须**告警——静默截断会让对端永久等待剩余字节（2026-09-21 实证：UI 推流应答截断 → 客户端失联） |
|
||||
| `net_recv` | `NET_MSG_RECV`（timeout=0→**无限等待**，自愈收敛阶段 1.5 删 30s 默认） | `net_recv_locked` | `net_poll` + `get_recv_len` / `read_recv_buf` | >0 / 0(EOF) / -1（errno = WOULDBLOCK / CONNRESET；阻塞形态无 TIMEDOUT 一档） | 快路径：数据已在 → 立即读出返回（允许部分读）；无数据 + 阻塞（`blocking` 属性=1 且未 DONTWAIT）→ **登记挂起后立即返回**（L3，netTask 零占用），唤醒源=数据/EOF/close/网络重建；DONTWAIT / `blocking=0` + CLOSED/session_dead → EOF + 触发重监听；⚠ IWDG 受监控任务禁用无限形态（`net_socket.h` 文档契约） |
|
||||
| `net_recv_nb` | `NET_MSG_RECV`（flags=DONTWAIT） | `net_recv_locked` | 同上 | >0 / 0 / -1（WOULDBLOCK 等） | 原 `NET_MSG_DONTWAIT` 路径转正的具名入口（自愈收敛阶段 1.5）；不改变 `blocking` 属性；受 IWDG 监控 / 有周期职责任务的推荐默认（ui_net_sink / iec104_serv 已迁） |
|
||||
| `net_recv_to` | `NET_MSG_RECV`（timeout>0） | `net_recv_locked` | 同上 | >0 / 0 / -1 / **-2（本片超时无数据）** | E-02 头阻塞修复配套 + **显式预算**入口（自愈收敛阶段 1.5，等价 Python settimeout，无隐藏默认值）：调用方把长等待切成有界片（如剩余预算），**总超时语义不变、单次占用有界**；`timeout_ms=0` 直接拒（0 = 无限等待，与本接口"有界"存在理由相反）；超时**只凭 -2 判定、不得依赖 errno**（`s_net_errno` 是跨任务共享全局量，随时被别的任务覆盖） |
|
||||
| `net_close` | `NET_MSG_CLOSE` | `net_close_locked` | `ch395f_cmd_done(CLOSE)` 快路径（芯片已 CLOSED → 只清本 Socket 残留事件）/ `net_sock_reset_sync(GRACEFUL)` 确定性排渣（自愈收敛阶段 3） | 0 / -1 | **先**结束本 fd 挂起 recv（排空/取消 + 必通知，关不得让等待者悬挂）；排空只碰本 Socket SINT，**不再读清全局中断寄存器**（F-NET-7：全局唯一读者 = `net_poll`）；原"close + 500ms 盲等排空循环"已换 sock_reset（内置 LISTEN 态二段 CLOSE 补发，E2 补充发现）；控制块整体清零（`last_peer_port` 幽灵基准跨 fd 保留，N-30） |
|
||||
| `net_drop_conn` | `NET_MSG_DROP_CONN`（自愈收敛阶段 3 新增） | `net_drop_conn_locked` | `net_pending_settle_close` + `net_sock_reset_sync(QUARANTINE)` +（auto_relisten）`net_listener_request` | 0（含幂等）/ -1 | **拆会话保监听**（E-02 收口）：应用放弃会话（对时 30s 预算耗尽 / 协议超时）而单连接监听被挂起对端永久占住时的应用侧出口；EOF 路径**不得**调（`auto_relisten` 已接管）；非 ESTABLISHED/CONNECTING 直接返 0 不动监听；本层收口 CLOSED 不清 fd（保留 local_port/auto_relisten），监听型 fd 登记重监听、失败交 D10 + reconciler 形态④ |
|
||||
| ~~`net_relisten`~~ | ~~`NET_MSG_RELISTEN`~~ | **自愈收敛阶段1 已删除**（消息类型同删） | — | — | 原"无条件芯片侧重建"与 pump/D10 完全重叠，且对健康监听器是 footgun（open→USE→close 自毁 ~1s）；生产零调用。历史实现见 `net_socket.c` git 历史 |
|
||||
| ~~`net_resync_listen`~~ | ~~`NET_MSG_RESYNC_LISTEN`~~ | **自愈收敛阶段1 已删除**（语义并入对账⑤） | — | — | D14 静默回收（芯片自行回监听、不发 DISCONNECT）现由 `net_reconcile_tick` 判据⑤自动认领：本层 ESTABLISHED 且芯片 0x05/0x01 → 只修本层（state→LISTENING + 转登 `last_peer_port` + 清 `lost_conn_seen` + 取消挂起 recv），**不发芯片命令**（纪律原样保留，run8 实证 170s 拒绝）；去抖/冷却沿用对账框架 |
|
||||
| `net_recv` | `NET_MSG_RECV`（timeout=0→**无限等待**，无 30s 默认预算） | `net_recv_locked` | `net_poll` + `get_recv_len` / `read_recv_buf` | >0 / 0(EOF) / -1（errno = WOULDBLOCK / CONNRESET；阻塞形态无 TIMEDOUT 一档） | 快路径：数据已在 → 立即读出返回（允许部分读）；无数据 + 阻塞（`blocking` 属性=1 且未 DONTWAIT）→ **登记挂起后立即返回**（挂起登记，netTask 零占用），唤醒源=数据/EOF/close/网络重建；DONTWAIT / `blocking=0` + CLOSED/session_dead → EOF + 触发重监听；⚠ IWDG 受监控任务禁用无限形态（`net_socket.h` 文档契约） |
|
||||
| `net_recv_nb` | `NET_MSG_RECV`（flags=DONTWAIT） | `net_recv_locked` | 同上 | >0 / 0 / -1（WOULDBLOCK 等） | 原 `NET_MSG_DONTWAIT` 路径转正的具名入口；不改变 `blocking` 属性；受 IWDG 监控 / 有周期职责任务的推荐默认（ui_net_sink / iec104_serv 已迁） |
|
||||
| `net_recv_to` | `NET_MSG_RECV`（timeout>0） | `net_recv_locked` | 同上 | >0 / 0 / -1 / **-2（本片超时无数据）** | E-02 头阻塞修复配套 + **显式预算**入口（等价 Python settimeout，无隐藏默认值）：调用方把长等待切成有界片（如剩余预算），**总超时语义不变、单次占用有界**；`timeout_ms=0` 直接拒（0 = 无限等待，与本接口"有界"存在理由相反）；超时**只凭 -2 判定、不得依赖 errno**（`s_net_errno` 是跨任务共享全局量，随时被别的任务覆盖） |
|
||||
| `net_close` | `NET_MSG_CLOSE` | `net_close_locked` | `ch395f_cmd_done(CLOSE)` 快路径（芯片已 CLOSED → 只清本 Socket 残留事件）/ `net_sock_reset_sync(GRACEFUL)` 确定性排渣 | 0 / -1 | **先**结束本 fd 挂起 recv（排空/取消 + 必通知，关不得让等待者悬挂）；排空只碰本 Socket SINT，**不再读清全局中断寄存器**（F-NET-7：全局唯一读者 = `net_poll`）；原"close + 500ms 盲等排空循环"已换 sock_reset（内置 LISTEN 态二段 CLOSE 补发，E2 补充发现）；控制块整体清零（`last_peer_port` 幽灵基准跨 fd 保留，N-30） |
|
||||
| `net_drop_conn` | `NET_MSG_DROP_CONN` | `net_drop_conn_locked` | `net_pending_settle_close` + `net_sock_reset_sync(QUARANTINE)` +（auto_relisten）`net_listener_request` | 0（含幂等）/ -1 | **拆会话保监听**（E-02 收口）：应用放弃会话（对时 30s 预算耗尽 / 协议超时）而单连接监听被挂起对端永久占住时的应用侧出口；EOF 路径**不得**调（`auto_relisten` 已接管）；非 ESTABLISHED/CONNECTING 直接返 0 不动监听；本层收口 CLOSED 不清 fd（保留 local_port/auto_relisten），监听型 fd 登记重监听、失败交 D10 + reconciler 形态④ |
|
||||
| ~~`net_relisten`~~ | ~~`NET_MSG_RELISTEN`~~ | **已删除**（消息类型同删） | — | — | 原"无条件芯片侧重建"与 pump/D10 完全重叠，且对健康监听器是 footgun（open→USE→close 自毁 ~1s）；生产零调用。历史实现见 `net_socket.c` git 历史 |
|
||||
| ~~`net_resync_listen`~~ | ~~`NET_MSG_RESYNC_LISTEN`~~ | **已删除**（语义并入对账⑤） | — | — | D14 静默回收（芯片自行回监听、不发 DISCONNECT）现由 `net_reconcile_tick` 判据⑤自动认领：本层 ESTABLISHED 且芯片 0x05/0x01 → 只修本层（state→LISTENING + 转登 `last_peer_port` + 清 `lost_conn_seen` + 取消挂起 recv），**不发芯片命令**（纪律原样保留，run8 实证 170s 拒绝）；去抖/冷却沿用对账框架 |
|
||||
|
||||
### 4.4 直调 API（不经队列）
|
||||
|
||||
@@ -152,8 +152,8 @@ flowchart TB
|
||||
|---|---|---|---|
|
||||
| `net_socket(domain,type)` | 分配空闲控制块（`alloc_socket` 线性扫描 `in_use=0`）→ CREATED | `alloc_socket` + `net_listener_clear` + `net_pending_clear` | 新 fd 不得继承上一次的待重试/挂起状态（复用描述符的经典坑）；domain 仅 `NET_AF_INET` |
|
||||
| `net_bind(sockfd,addr,addrlen)` | TCP：仅记录本地端口（port=0 → 动态端口 49152 起递增）→ BOUND，**无芯片命令**；UDP：完整开 Socket → UDP_OPEN | UDP 路径：`set_proto_type(UDP)` + `set_sour_port` + `set_des_ip(0xFFFFFFFF)` + `set_des_port(0)` + `open_socket`（Socket 4~7 兜底重设缓冲） | TCP 的 bind 只是"记账"，真正的芯片动作在 listen/connect；UDP 直碰 SPI（§2 三例外之一）；动态端口回绕 65535→49152 |
|
||||
| `net_sendto` / `net_recvfrom` | UDP 收发（直碰 SPI，不经队列） | `set_des_ip` / `set_des_port` + `write_send_buf`（分块 1KB + `net_poll` 门控）；`net_poll` + `get_recv_len` + `read_recv_buf` | 同 §2 上下文约束；recv 时 UDP Server 模式前 8 字节是固定头（源 IP + 端口 + 长度），先剥头填 `src_addr` 再读数据；recvfrom 阻塞语义与 net_recv 同构（自愈收敛阶段 1.5：blocking 属性 / DONTWAIT，无默认预算；轮询自旋实现，生产零调用） |
|
||||
| `net_setblocking(sockfd,on)` | 设置阻塞**模式属性**（自愈收敛阶段 1.5，直写控制块，不经队列） | 写 `s_net_socks[fd].blocking` | 对齐 BSD `O_NONBLOCK` / Python `setblocking`："模式归使用者、超时归调用方"；单字节原子写（先例 `net_set_event_cb`），最坏一次在途 recv 用旧模式；`net_socket()` 默认置 1（close 的 memset 清零后新 fd 必须显式重置） |
|
||||
| `net_sendto` / `net_recvfrom` | UDP 收发（直碰 SPI，不经队列） | `set_des_ip` / `set_des_port` + `write_send_buf`（分块 1KB + `net_poll` 门控）；`net_poll` + `get_recv_len` + `read_recv_buf` | 同 §2 上下文约束；recv 时 UDP Server 模式前 8 字节是固定头（源 IP + 端口 + 长度），先剥头填 `src_addr` 再读数据；recvfrom 阻塞语义与 net_recv 同构（blocking 属性 / DONTWAIT，无默认预算；轮询自旋实现，生产零调用） |
|
||||
| `net_setblocking(sockfd,on)` | 设置阻塞**模式属性**（直写控制块，不经队列） | 写 `s_net_socks[fd].blocking` | 对齐 BSD `O_NONBLOCK` / Python `setblocking`："模式归使用者、超时归调用方"；单字节原子写（先例 `net_set_event_cb`），最坏一次在途 recv 用旧模式；`net_socket()` 默认置 1（close 的 memset 清零后新 fd 必须显式重置） |
|
||||
| `net_wait_result(kind,sockfd)` | 调用侧两段式等待：**零等待拾取** → 阻塞等回执 | `xTaskNotifyWait` ×2 | ① 零等待段兜住"入队→等待入口"间隙落地的通知（2026-09-22 台架实证丢通知）；② **清除掩码必须全 1**（传 0 = 不清 → 上次结果残留被重读，run3~11 挂死/错位的真根因）；③ 必须判 **pdTRUE** 而非 `v!=0`（合法结果 0 = EOF 会被误判"无通知"→ 永久挂死）；④ 32 位整体作结果（32768 大字节数不截断）；⑤ 本路径**禁止**加逐调用日志（曾占日志 98.6%、冲掉 [LAT] 证据行，run14 实证） |
|
||||
| `net_sock_state(sockfd)` | 跨任务只读状态快照（单字节读，无锁） | 无 | 描述符无效/未占用 → -1；值可能滞后 netTask 最新状态——用于**轮询**（客户端等 ESTABLISHED），不替代 accept/connect |
|
||||
| `net_get_sock(sockfd)` | 返回控制块指针 | 无 | netTask 上下文内用；跨任务只可读单字节 `state`（即 `net_sock_state`），不得读结构体其他成员 |
|
||||
@@ -162,7 +162,7 @@ flowchart TB
|
||||
| `net_getsockname(sockfd,addr,addrlen)` | 本地地址（IP + 端口） | 读 `s_local_ip`（`net_init` 缓存）+ `local_port` | IP 是 `net_init` 时的值（DHCP 场景不更新——本构建固定 IP）；port=0 时返回已分配动态端口 |
|
||||
| 字节序族 `net_htons/ntohs/htonl/ntohl/inet_addr/inet_ntoa` | 纯计算转换 | 无 | 无状态、任意上下文可调 |
|
||||
|
||||
### 4.5 L3 pending recv 子系统（阻塞等待不独占 netTask）
|
||||
### 4.5 挂起 recv 子系统（阻塞等待不独占 netTask）
|
||||
|
||||
**模型**：阻塞等待 = **挂起请求登记**（每 fd 至多一个，禁止覆盖）+ **主循环节拍完成检查** + **通知唤醒**（LwIP netconn 模型）。消除 E-02 头阻塞（旧实现：netTask 自旋等数据，一次 30s 空闲 recv 冻住全网 17.7s）。
|
||||
|
||||
@@ -179,21 +179,22 @@ flowchart TB
|
||||
|
||||
**模型**：重开失败 = **登记待重试**（30ms 节奏 / 2s 时限），`net_listener_tick` 到点重试——任何时刻不阻塞任务。旧实现 `osDelay(500)` 忙等：netTask 冻结 500ms（全网停摆）、实测恢复 588ms、期间重连被拒（M3 台架）。
|
||||
|
||||
> **N-32 §10（2026-10-12）**：本子系统的函数已从 `net_socket.c` **抽出到 `net_listener.c`**（真机专属，模拟器不编译）；并新增 `net_listener_settle` 取代外部直接写 `s_relisten_quarantine[]`（沉降等级化）。
|
||||
> **模块归属**：本子系统的函数在 `net_listener.c`（真机专属，模拟器不编译）；沉降等级只经
|
||||
> `net_listener_settle` 登记，外部不得直接写 `s_relisten_quarantine[]`。
|
||||
|
||||
| 函数 | 设计作用 | 主要调用 | 意图 / 注意 |
|
||||
|---|---|---|---|
|
||||
| `net_listener_settle` | 登记"本 fd 会话已结束，重建前需沉降/隔离"（**只置事实**） | 写 `s_relisten_quarantine[fd]`（等级：GRACEFUL 100ms / QUARANTINE 400ms） | N-32 P1：取代此前外部直接写 `s_relisten_quarantine[]`；由 `handle_disconnect_event`（GRACEFUL）/ `handle_timeout_event`（QUARANTINE）调用。**只置事实，动作只在 `net_listener_tick` 一处发生**；越界 fd 静默忽略 |
|
||||
| `net_listener_settle` | 登记"本 fd 会话已结束，重建前需沉降/隔离"（**只置事实**） | 写 `s_relisten_quarantine[fd]`（等级：GRACEFUL 100ms / QUARANTINE 400ms） | 由 `handle_disconnect_event`（GRACEFUL）/ `handle_timeout_event`（QUARANTINE）调用。**只置事实，动作只在 `net_listener_tick` 一处发生**；越界 fd 静默忽略 |
|
||||
| `net_listener_request` | **登记**"本 fd 期望回到 LISTEN"（只置意图，**不碰芯片**） | 写 `s_relisten_req[fd]`（来源 +1）+ `next=0`（下一轮 tick 即尝试） | 取代原 `net_listener_try`（当场动作 → 4 个调用点各自补 `state == CLOSED` 门，U12 漏一处即事故；E17 收口后门上收到 tick）。已在请求中 → **不重置重试时刻**：否则 10ms 一次的 accept 轮询会把重试时刻不断往后推 → 永不重试（饥饿）；越界 fd 静默忽略 |
|
||||
| `net_relisten_locked` | 真正的 open + listen（**单次尝试**） | （沉降期）`net_drain_chip_rx` + `close_socket` + `get_sock_int_status` / `get_glob_int_status_all` + `get_socket_status` → `set_proto_type` + `set_sour_port` + `open_socket` + `tcp_listen` + 清中断 | ① **严禁 osDelay 忙等**：失败只清理并返回，沉降交给重试轮询；② **TRAP-NET-18 沉降门**：带沉降标记的 socket（异常释放 TIMEOUT → QUARANTINE 400ms；正常释放 DISCONNECT → GRACEFUL 100ms）→ 排空 RX 残渣 + 主动 close + 排空中断 + 等芯片回 CLOSED/TCP_CLOSED；**上限强制放行**（必须 < 2s 重试时限，否则沉降耗尽重试预算 → `relisten give up` 监听被弃——2026-09-23 实测修正）；③ 成功只置 state=LISTENING，**不 memset**（fd 与 `auto_relisten` 保留——BSD 风格监听常驻） |
|
||||
| `net_listener_tick` | 监听重建的**唯一执行者**（netTask 每轮，非阻塞；原名 `net_listener_retry_tick` 只做 D10 到点重试） | `net_relisten_locked` → `net_relisten_done` / 顺延 30ms / 超预算清登记 + `[ERR]` | **门集集中这一处**：控制块有效 + `in_use` + 状态 ∈ {LISTENING, CLOSED} + 监听型（`auto_relisten` / STREAM / `local_port≠0`）+ **芯片已在 LISTEN 即视为请求已达成、静默了结、绝不 open**（U12 结构性防护，读驱动状态缓存零 SPI）+ **同 fd 有在途挂起 recv / send 时跳过**（重开 Socket 会摧毁在途连接 / 截断在途传输，L3 保险）+ 30ms 节奏 / 2s 预算（D10；超预算清登记并留痕，之后由 reconciler 形态③④ 重新登记，监听不永久失效） |
|
||||
| `net_relisten_done` | 标记完成 | `net_listener_clear` +（探针构建）恢复计时样本 | 恢复时延 = 首次尝试 → 完成（L3 探针 `relisten` 段） |
|
||||
| `net_relisten_locked` | 真正的 open + listen（**单次尝试**） | （沉降期）`net_drain_chip_rx` + `close_socket` + `get_sock_int_status` / `get_glob_int_status_all` + `get_socket_status` → `set_proto_type` + `set_sour_port` + `open_socket` + `tcp_listen` + 清中断 | ① **严禁 osDelay 忙等**：失败只清理并返回，沉降交给重试轮询；② **TRAP-NET-18 沉降门**：带沉降标记的 socket（异常释放 TIMEOUT → QUARANTINE 400ms；正常释放 DISCONNECT → GRACEFUL 100ms）→ 排空 RX 残渣 + 主动 close + 排空中断 + 等芯片回 CLOSED/TCP_CLOSED；**上限（800ms）只留痕、不强行放行**——芯片未回 CLOSED 时 open 注定吃 USE 错，兜底 = D10 预算到期 + 形态④ 重新登记；③ 成功只置 state=LISTENING，**不 memset**（fd 与 `auto_relisten` 保留——BSD 风格监听常驻） |
|
||||
| `net_listener_tick` | 监听重建的**唯一执行者**（netTask 每轮，非阻塞） | `net_relisten_locked` → `net_relisten_done` / 顺延 30ms / 超预算清登记 + `[ERR]` | **门集集中这一处**：控制块有效 + `in_use` + 状态 ∈ {LISTENING, CLOSED} + 监听型（`auto_relisten` / STREAM / `local_port≠0`）+ **芯片已在 LISTEN 即视为请求已达成、静默了结、绝不 open**（U12 结构性防护，读驱动状态缓存零 SPI）+ **同 fd 有在途挂起 recv / send 时跳过**（重开 Socket 会摧毁在途连接 / 截断在途传输，挂起保险）+ 30ms 节奏 / 2s 预算（D10；超预算清登记并留痕，之后由 reconciler 形态③④ 重新登记，监听不永久失效） |
|
||||
| `net_relisten_done` | 标记完成 | `net_listener_clear` +（探针构建）恢复计时样本 | 恢复时延 = 首次尝试 → 完成（延迟探针 `relisten` 段） |
|
||||
| `net_listener_clear` | 取消该 fd 的重建请求 / 沉降 | 清 `req/next/dead` + `settle_dead/settle_start` + `quarantine` | 触发点：`net_socket`（新 fd 不继承）/ `net_close_locked`（关闭即取消）/ tick 内"登记已陈旧或已达成"；沉降/隔离状态必须一并清，否则残留标记会污染下一次复监听 |
|
||||
| `net_drain_chip_rx` | 排空芯片 RX 残留（256B 分块，≤16 次 = 4KB 上限） | `get_recv_len` + `read_recv_buf` | TRAP-NET-18：中止/异常断开时芯片 RX 缓冲残留上一条连接的数据（实测 ~2048B），不排空会被下一条连接当自己的数据读走（静默截断）；分块读避免新增静态缓冲（内存预算紧张） |
|
||||
|
||||
### 4.7 监听重建（原 N-32 监听器 pump；自愈收敛阶段 3 已并入 `net_reconcile_tick` 形态③④/U11）
|
||||
### 4.7 监听重建（原监听器 pump；已并入 `net_reconcile_tick` 形态③④/U11）
|
||||
|
||||
> **自愈收敛阶段 3（2026-10-13）**：`net_listener_pump()` 已**删除**——其全部三种情形作为**形态③④ + U11** 并入 `net_reconcile_tick`（§4.8，单一 100ms tick，判据读驱动状态缓存）。本节保留"单一重建所有者"的设计口径与情形表；实现位置与参数以 §4.8 为准。
|
||||
> **现状**：`net_listener_pump()` 已**删除**——其全部三种情形作为**形态③④ + U11** 并入 `net_reconcile_tick`（§4.8，单一 100ms tick，判据读驱动状态缓存）。本节保留"单一重建所有者"的设计口径与情形表；实现位置与参数以 §4.8 为准。
|
||||
|
||||
**设计意图（设计文档 §4 不变量 II）**：其它所有位置**只置事实**（会话结束 / 状态迁移 / 事件派发），**不做重建动作**——于是"谁先看到 DISCONNECT 就谁重建"这类**多所有者竞争在结构上消失**。`net_reconcile_tick` 形态③④是**本层唯一**的周期性重建决策者。
|
||||
|
||||
@@ -205,7 +206,7 @@ flowchart TB
|
||||
| ④ | 本层 CLOSED（会话已结束）而芯片**不在** LISTEN | 重建（`net_listener_request`） | 原对账④ / 原 pump② |
|
||||
| U11 | 本层 CLOSED 而芯片**正在** LISTEN | **只做状态重同步**（CLOSED→LISTENING），**不发任何芯片命令** | U11 缺口 |
|
||||
|
||||
情形 U11 的理由：芯片监听器是**健康**的，重下发 open+listen 会因 `USE` 错误走进关闭分支、把正听着的 Socket 关掉（U12 同源事故）；只把本层状态收回 LISTENING 即可（与对账⑤ RESYNC 同一纪律——原 `net_resync_listen`，自愈收敛阶段1 已退役）。
|
||||
情形 U11 的理由：芯片监听器是**健康**的，重下发 open+listen 会因 `USE` 错误走进关闭分支、把正听着的 Socket 关掉（U12 同源事故）；只把本层状态收回 LISTENING 即可（与对账⑤ RESYNC 同一纪律——原 `net_resync_listen` 已退役）。
|
||||
|
||||
**去抖 + 冷却**（③④ 沿用原实测结论，取值不变）：同一失配需**连续 2 轮**（`NET_RECON_STABLE_RELISTEN`，≈200ms）才动手；同一 Socket 动手后**冷却 1s**（防抖成风暴，2026-09-23 实证）；U11 被动重同步**不去抖、不占冷却**（零风险）。**tick 周期 100ms**（原 pump 周期；合并后对账也从 200ms 提到 100ms）：比 200ms 快、又不至于像 50ms 那样频繁 close/open 与消费者收发撞车（2026-10-12 台架实测 50ms 会把 uiTask 最坏单轮从 172ms 推到 1034ms）。
|
||||
|
||||
@@ -213,7 +214,7 @@ flowchart TB
|
||||
|
||||
### 4.8 TRAP-NET-17 周期对账 + 监听重建（合一 `net_reconcile_tick`，事件未收到自愈，`net_events.c`）
|
||||
|
||||
`net_reconcile_tick()`（`net_process_messages` 每轮调用；周期 **100ms**，`NET_RECONCILE_PERIOD_MS`；自愈收敛阶段 3 起含原 pump 形态③④/U11）：
|
||||
`net_reconcile_tick()`（`net_process_messages` 每轮调用；周期 **100ms**，`NET_RECONCILE_PERIOD_MS`；含原 pump 形态③④/U11）：
|
||||
|
||||
**问题**：芯片在快速复连场景会**收不到 CONNECT/DISCONNECT 事件**（读清消费竞态——E14 复核：非芯片侧丢失；或芯片静默回收 Socket 不发中断）；事件未收到时纯事件驱动无法自愈——典型：对端连接一直占着单连接监听的"后备"（芯片 TCP 仍 ESTABLISHED），后续 SYN 全被拒，而应用因未收到 DISCONNECT 仍以为有客户端（永不调 accept）。
|
||||
|
||||
@@ -225,11 +226,12 @@ flowchart TB
|
||||
| ② | 本层 LISTENING 而芯片已完成握手（tcp = ESTABLISHED） | 补做 standalone accept 簿记 | `handle_connect_event` |
|
||||
| ③ | 本层 LISTENING（监听型 fd）而芯片监听失位 | 重建 | `net_listener_request`（原 pump①） |
|
||||
| ④ | 本层 CLOSED（监听型 fd）而芯片不在 LISTEN | 重建 | `net_listener_request`（原 pump②） |
|
||||
| ⑤ | 本层 ESTABLISHED 而芯片静默回收回 LISTEN（0x05/0x01，无 DISCONNECT 中断） | RESYNC 只修本层、不发芯片命令 | 原 `net_resync_listen` 语义（自愈收敛阶段1 并入） |
|
||||
| ⑤ | 本层 ESTABLISHED 而芯片静默回收回 LISTEN（0x05/0x01，无 DISCONNECT 中断） | RESYNC 只修本层、不发芯片命令 | 原 `net_resync_listen` 语义（已并入） |
|
||||
| U11 | 本层 CLOSED（监听型 fd）而芯片**正在** LISTEN | 只重同步 CLOSED→LISTENING，不发芯片命令 | 原 pump③ |
|
||||
|
||||
> ⚠ **N-32 P2（2026-10-12）**：原③（本层 LISTENING 丢监听）与④（孤儿监听）曾**整体移交 `net_listener_pump`**——本函数内**不再有任何重建动作**（单一所有者），认领门槛相应收窄为 ESTABLISHED/LISTENING（原为驱动④而多认领"CLOSED + auto_relisten + 已绑端口"）。
|
||||
> ⚠ **自愈收敛阶段 3（2026-10-13）**：pump 已删除，③④/U11 **回到本 tick**（单一 100ms tick 覆盖①②③④⑤/U11）；"单一所有者"不变量不变——重建决策仍只此一处，认领门槛按原 pump 口径以 `listener_fd` 门恢复。
|
||||
> ⚠ **单一所有者不变量**：重建决策**只此一处**（原 `net_listener_pump` 已删除，③④/U11 就在本 tick）；
|
||||
> 认领门槛见 §4.7（在用 + `auto_relisten` + TCP + 已绑端口）——少了它"本层 CLOSED + 已绑端口"的
|
||||
> 出向连接会被误判为监听器并 relisten。
|
||||
|
||||
**去抖 + 冷却（缺一不可）**：单次状态读可能落在"刚 open/listen 尚未生效"的瞬态——**2026-09-23 实测**：无去抖的 accept 路径自愈把监听反复重建直至 `relisten give up`（三服务口全死、89 行 ERROR）。故**分级去抖**（单位=轮，100ms/轮）：②=1 轮（`NET_RECON_STABLE_ACCEPT`，幽灵甄别兜底假阳性）；③④⑤=2 轮（`NET_RECON_STABLE_RELISTEN`）；①=4 轮（`NET_RECON_STABLE_DEATH`，**勿改小**——F-NET-17 M3 可疑电平让位再入的 400ms 租约，E9a 实证）；同一 Socket 动手后**冷却 1s**（`NET_RECONCILE_COOLDOWN_MS`；U11 被动重同步不去抖不占冷却）。开销：每 100ms 每在用 Socket 的状态回读已收拢在 `net_poll`（≈100µs/轮），本 tick 本身零额外 SPI。
|
||||
|
||||
@@ -238,7 +240,7 @@ flowchart TB
|
||||
| 函数 | 设计作用 | 主要调用 | 意图 / 注意 |
|
||||
|---|---|---|---|
|
||||
| `handle_connect_event` | LISTENING → standalone accept（回读对端地址 → ESTABLISHED + `send_ready=1` + 清残留 TIMEOUT + 回调）；CONNECTING → 客户端连接成功（回读对端 + 使能 KeepAlive + 回调） | `ch395f_get_remot_ipp` + `get_sock_int_status` +（client）`set_keepalive_enable` + `fire_event` | GET_REMOT_IPP 为**小端**输出（与 set_des_ip 的大端相反）——解析别抄反；`session_dead` 的**唯一清零点** |
|
||||
| `handle_disconnect_event` | 状态机迁移 + 陈旧事件甄别 + **登记沉降事实**（不再自己重建） | `ch395f_get_socket_status`（事件路径**主动 SPI**，不用缓存——缓存刷新在 net_poll 末尾，事件路径上必然滞后）→（LISTENING：只回读留痕，监听失位交 **reconciler 形态③** 重建；仍在监听 → 判陈旧丢弃）/（ESTABLISHED：芯片仍 ESTABLISHED → 判陈旧丢弃；F-NET-17 M3 可疑门 → 置可疑电平让位对账①） | ① **陈旧 DISCONNECT 甄别**（D20）：同一 fd"关闭→重监听→再连接"循环复用，上一条连接的 FIN/ACK 可能在 fd 已复用时才上报 → 不甄别则新连接秒断（实测：FTP 同会话第二个数据连接必 425）；② 正常释放（FIN）→ **GRACEFUL 沉降 100ms**（只置事实，重建由 `net_reconcile_tick` 形态③④ 做，N-32 P1/P2 + 自愈收敛阶段 3）；③ 置 CLOSED 后**不立即关芯片 Socket**——留给 `net_recv_locked` 排空剩余数据（FIN 可能先于数据到达） |
|
||||
| `handle_disconnect_event` | 状态机迁移 + 陈旧事件甄别 + **登记沉降事实**（不再自己重建） | `ch395f_get_socket_status`（事件路径**主动 SPI**，不用缓存——缓存刷新在 net_poll 末尾，事件路径上必然滞后）→（LISTENING：只回读留痕，监听失位交 **reconciler 形态③** 重建；仍在监听 → 判陈旧丢弃）/（ESTABLISHED：芯片仍 ESTABLISHED → 判陈旧丢弃；F-NET-17 M3 可疑门 → 置可疑电平让位对账①） | ① **陈旧 DISCONNECT 甄别**（D20）：同一 fd"关闭→重监听→再连接"循环复用，上一条连接的 FIN/ACK 可能在 fd 已复用时才上报 → 不甄别则新连接秒断（实测：FTP 同会话第二个数据连接必 425）；② 正常释放（FIN）→ **GRACEFUL 沉降 100ms**（只置事实，重建由 `net_reconcile_tick` 形态③④ 做）；③ 置 CLOSED 后**不立即关芯片 Socket**——留给 `net_recv_locked` 排空剩余数据（FIN 可能先于数据到达） |
|
||||
| `handle_recv_event` | 置 `readable` + 回调；**不读 recv_len** | `fire_event` | 不读长度是为了避免与 `net_recv_locked` 的 `ch395f_get_recv_len` 竞争（旧"分批读归零"机理，未证实）；`readable` 供 `net_select` 无 SPI 访问判读 |
|
||||
| `handle_send_event` | 发送缓冲已空：触发回调（`send_ready` 由 SENBUF_FREE 前置位） | `fire_event` | — |
|
||||
| `handle_timeout_event` | CONNECTING → CREATED（连接超时）；**ESTABLISHED → 登记隔离 + CLOSED**（TRAP-NET-18）；LISTENING → 仅记日志 | **`net_listener_settle(fd, NET_LISTENER_SETTLE_QUARANTINE)`** + `fire_event` | TIMEOUT = 异常释放（如客户端中止上传）：对端在途数据随后落进 RX 缓冲 → 必须隔离（400ms）后才许复监听；正常 FIN 释放走 disconnect 路径（GRACEFUL 100ms），**不走**隔离 |
|
||||
@@ -286,7 +288,7 @@ sequenceDiagram
|
||||
A->>A: 返回字节数 / -1（errno 已恢复；短写按 ret < len 处理）
|
||||
```
|
||||
|
||||
### 5.2 阻塞接收无数据（L3 pending 路径）
|
||||
### 5.2 阻塞接收无数据（挂起 recv 路径）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
@@ -342,7 +344,7 @@ sequenceDiagram
|
||||
Note over N: 2s 超限时 → 清状态 + "relisten give up"（错误日志，应用可感知）
|
||||
```
|
||||
|
||||
### 5.4 事件未收到自愈（TRAP-NET-17 对账 + 监听重建合一 reconciler，自愈收敛阶段 3）
|
||||
### 5.4 事件未收到自愈（TRAP-NET-17 对账 + 监听重建合一 reconciler）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
@@ -385,7 +387,7 @@ sequenceDiagram
|
||||
|---|---|---|
|
||||
| 1 | **一切芯片访问收敛 netTask**（唯一执行者）；跨任务调用走队列 | TRAP-NET-14：跨任务 SPI 竞争破坏芯片寄存器 → 连接必超时 |
|
||||
| 2 | **结果只经任务通知值回传**；消息按值入队，调用方看不到 netTask 对消息的写入；勿给消息加"回传用"字段 | TRAP-NET-10：6 个 API 永远返回 -1；"加 msg.err 字段"的修法曾致 `ui_net_sink` 每次空轮询误判真错误 → 连上即断 |
|
||||
| 3 | **netTask 不为任何人自旋等待**：阻塞 recv = 挂起登记（L3）；重开失败 = 重试登记（D10）；初次 listen/connect 的 open 重试环（`net_sock_reset_sync` 有界等待，GRACEFUL 100ms 底 / 600ms 封顶）是唯一豁免（启动期无竞争，自愈收敛阶段 3 起原 3×500ms 盲等已换确定性排渣） | E-02：一次空闲 30s recv 冻住全网 17.7s；旧重监听 osDelay(500) → 恢复 588ms、期间重连被拒 |
|
||||
| 3 | **netTask 不为任何人自旋等待**：阻塞 recv = 挂起登记；重开失败 = 重试登记（D10）；初次 listen/connect 的 open 重试环（`net_sock_reset_sync` 有界等待，GRACEFUL 100ms 底 / 600ms 封顶）是唯一豁免（启动期无竞争，原 3×500ms 盲等已换确定性排渣） | E-02：一次空闲 30s recv 冻住全网 17.7s；旧重监听 osDelay(500) → 恢复 588ms、期间重连被拒 |
|
||||
| 4 | **netTask 不向自身发消息 / 不自我挂起**（挂起登记对执行任务自身发起直接拒绝） | 自等自通知 = 死锁 |
|
||||
| 5 | **基于状态读的重建动作必须去抖 + 冷却**：分级门槛 ②=1 轮 / ③④⑤=2 轮 / ①=4 轮（100ms/轮）+ 冷却 1s | 2026-09-23：无去抖 → 监听反复重建直至 `relisten give up`，三服务口全死 |
|
||||
| 6 | **异常释放（TIMEOUT）后复监听前必须隔离**：排空 RX 残渣 + 等 CLOSED/TCP_CLOSED；隔离上限 < 重试放弃时限 | TRAP-NET-18：~2KB 残渣被下条连接当自己的数据 → 首笔上传截断 2048B 并误报 226 成功；上限=2s 时隔离耗尽重试预算 → 监听被弃 |
|
||||
@@ -393,7 +395,7 @@ sequenceDiagram
|
||||
| 8 | **close 前先结束挂起 recv + 排空残留 DISCONNECT** | TRAP-NET-12：锁存的陈旧 DISCONNECT 秒断下一连接 |
|
||||
| 9 | **两段式等待防丢失通知**：零等待拾取 + 阻塞；清除掩码全 1；以 pdTRUE 判定 | run3~11：丢失通知 → 挂死 / 结果错位；0 结果误判"无通知" → 永久挂死 |
|
||||
| 10 | **网络重建先取消并通知全部挂起，再复位芯片** | 取消不通知 = 调用方永久挂死 |
|
||||
| 11 | **监听重建只有一个所有者**（`net_reconcile_tick` 形态③④，自愈收敛阶段 3 合并后；原 `net_listener_pump` 已删）；其它位置**只置事实**（置 CLOSED / 登记沉降），不做重建动作 | N-32 P2 / B10：多所有者导致"谁先看到 DISCONNECT 就谁重建"的竞争与重建风暴 |
|
||||
| 11 | **监听重建只有一个所有者**（`net_reconcile_tick` 形态③④；原 `net_listener_pump` 已删）；其它位置**只置事实**（置 CLOSED / 登记沉降），不做重建动作 | B10：多所有者导致"谁先看到 DISCONNECT 就谁重建"的竞争与重建风暴 |
|
||||
|
||||
---
|
||||
|
||||
@@ -411,13 +413,13 @@ sequenceDiagram
|
||||
| `ch395f_get_glob_int_status_all` | **仅 `net_poll`**（F-NET-7 / B3：全局寄存器唯一读者；`net_listen_locked` / `net_connect_locked` / `net_close_locked` / `net_relisten_locked` 的原全局读清已全部删除） | **读 = 清**（中断清除机制，无按位手段）——其他位置读清会焊死 net_poll 的按 Socket 门控 |
|
||||
| `ch395f_get_sock_int_status` | `net_poll`（逐 Socket SINT）；各 open 路径后清残留；事件处理器清 TIMEOUT | **读 = 清** |
|
||||
| `ch395f_sock_events` | `net_connect_locked`（open 后清残留，F-NET-7 护栏原语）；`net_close_locked`（芯片已 CLOSED 快路径只清本 Socket 残留事件） | 只碰**本 Socket** SINT 的护栏原语 |
|
||||
| `ch395f_open_socket` / `ch395f_close_socket` | `net_bind`(UDP)、`net_listen_locked`、`net_connect_locked`、`net_relisten_locked`（含沉降期主动 close）；`net_close_locked` 的 CLOSE 已改经 `ch395f_cmd_done` / `ch395f_sock_reset_*`（自愈收敛阶段 3） | TRAP-NET-09：close 后需沉降才能重开 |
|
||||
| `ch395f_open_socket` / `ch395f_close_socket` | `net_bind`(UDP)、`net_listen_locked`、`net_connect_locked`、`net_relisten_locked`（含沉降期主动 close）；`net_close_locked` 的 CLOSE 已改经 `ch395f_cmd_done` / `ch395f_sock_reset_*` | TRAP-NET-09：close 后需沉降才能重开 |
|
||||
| `ch395f_tcp_listen` / `ch395f_tcp_connect` | `net_listen_locked` / `net_relisten_locked`；`net_connect_locked` | — |
|
||||
| `ch395f_set_proto_type` / `set_sour_port` / `set_des_ip` / `set_des_port` | `net_bind`(UDP)、`net_listen_locked`、`net_connect_locked`、`net_relisten_locked`、`net_sendto` | open 之后写端口/IP（open 会复位寄存器）；set_des_ip 期望**大端数组** |
|
||||
| `ch395f_write_send_buf` | `net_send_locked` / `net_send_pending_tick`（二期挂起 send 推进）/ `net_sendto` | 单次 ≤1KB（硬件 FIFO 上限，TRAP-NET-16） |
|
||||
| `ch395f_write_send_buf` | `net_send_locked` / `net_send_pending_tick`（挂起 send 推进）/ `net_sendto` | 单次 ≤1KB（硬件 FIFO 上限，TRAP-NET-16） |
|
||||
| `ch395f_get_recv_len` / `ch395f_read_recv_buf` | `net_recv_locked`、`net_pending_tick`、`net_pending_settle_close`、`net_recvfrom`、`net_drain_chip_rx`、`handle_disconnect_event`（M3 可疑门 RX 非空判据） | `handle_recv_event` **故意不读**（防竞争，旧机理未证实） |
|
||||
| `ch395f_get_socket_status` | `handle_disconnect_event`（两处甄别——事件路径**主动 SPI**，缓存必然滞后于刚到达的中断）、`net_relisten_locked`（沉降门）、`net_connect_locked`（诊断回读）。⚠ **周期对账不再直接调**——改读缓存（下行） | 输出 **2 字节**（[0]=Socket 状态 [1]=TCP 状态），缓冲必须给 2 字节 |
|
||||
| `ch395f_get_sock_state` / `ch395f_sock_state_cached` | 刷新**仅 `net_poll`** 每轮对在用 Socket 调 `get_sock_state`（唯一刷新点）；`sock_state_cached` 读缓存 = `net_reconcile_tick`（形态①②③④⑤/U11 判据） | 自愈收敛阶段 3：芯片状态唯一事实源；E2 实测单次回读 18.1µs，缓存新鲜度 ≤1ms |
|
||||
| `ch395f_get_sock_state` / `ch395f_sock_state_cached` | 刷新**仅 `net_poll`** 每轮对在用 Socket 调 `get_sock_state`（唯一刷新点）；`sock_state_cached` 读缓存 = `net_reconcile_tick`（形态①②③④⑤/U11 判据） | 芯片状态唯一事实源；E2 实测单次回读 18.1µs，缓存新鲜度 ≤1ms |
|
||||
| `ch395f_sock_reset_begin` / `ch395f_sock_reset_poll` | `net_sock_reset_sync`（`net_listen_locked` / `net_connect_locked` open 重试、`net_close_locked`、`net_drop_conn_locked`）；`net_poll` 每轮对在用 Socket **步进**（IDLE 槽纯 RAM 判零 SPI） | 驱动复位状态机：读空 RX → CLOSE → 排空事件(quiescent) → 等 byte0=00H；内置 LISTEN 态二段 CLOSE 补发（E2 补充发现）；GRACEFUL 100ms 底 / QUARANTINE 400ms 底 |
|
||||
| `ch395f_cmd_done` | `net_close_locked`（CLOSED 快路径判据） | 命令完成判定（OPEN/LISTEN/CLOSE 三形态，读缓存不额外发 SPI） |
|
||||
| `ch395f_link_up_cached` / `ch395f_link_change_count` | `net_reconcile_tick`（链路态订阅留痕，F-DRV-13） | 驱动 link 变化计数，net_poll 喂 |
|
||||
@@ -432,8 +434,8 @@ sequenceDiagram
|
||||
|---|---|
|
||||
| 监听恢复策略（节奏/时限/沉降） | `net_listener_request` / `net_relisten_locked` / `net_listener_tick`；常量 `NET_RELISTEN_*_MS`（`net_listener.c` 内）；重建决策在 `net_reconcile_tick` 形态③④（下行） |
|
||||
| 阻塞接收等待语义 | `net_pending_register` / `net_pending_tick` / `net_pending_complete`；常量 `NET_PENDING_WATCHDOG_MS` |
|
||||
| 阻塞发送等待语义（二期 SEND pending） | `net_send_pending_register` / `net_send_pending_tick` / `net_send_pending_complete`；常量 `NET_SEND_SPIN_MS`（有界自旋预算）/ `NET_SEND_TIMEOUT_MS`（无进展超时）/ `NET_SEND_CHUNK_MAX`（分块上限，`net_pending.h` 唯一定义处） |
|
||||
| 事件未收到自愈 + 监听重建策略（合一 tick，自愈收敛阶段 3） | `net_reconcile_tick`（`NET_RECONCILE_PERIOD_MS` / `NET_RECONCILE_COOLDOWN_MS` / `NET_RECON_STABLE_ACCEPT|RELISTEN|DEATH`，①②③④⑤+U11，唯一重建入口=形态③④）+ `handle_disconnect_event` / `handle_connect_event` |
|
||||
| 阻塞发送等待语义（挂起 send） | `net_send_pending_register` / `net_send_pending_tick` / `net_send_pending_complete`；常量 `NET_SEND_SPIN_MS`（有界自旋预算）/ `NET_SEND_TIMEOUT_MS`（无进展超时）/ `NET_SEND_CHUNK_MAX`（分块上限，`net_pending.h` 唯一定义处） |
|
||||
| 事件未收到自愈 + 监听重建策略（合一 tick） | `net_reconcile_tick`（`NET_RECONCILE_PERIOD_MS` / `NET_RECONCILE_COOLDOWN_MS` / `NET_RECON_STABLE_ACCEPT|RELISTEN|DEATH`，①②③④⑤+U11，唯一重建入口=形态③④）+ `handle_disconnect_event` / `handle_connect_event` |
|
||||
| 新增一个公共 API | 模式：`net_socket.h` 声明（`NET_NO_OS` 条件编译）→ `net_msg_type_t` 加类型（如需要）→ `net_process_messages` 加 dispatch 分支 → netTask 侧 `_locked` 实现；调用侧复制"参数检查 → 入队 → `net_wait_result` → errno 恢复"骨架 |
|
||||
| 缓冲布局 / MSS / 重传 / KeepAlive 参数 | `net_init` + `net_config.h` + `ch395f.h`（`CH395F_RECV/SEND_BLOCKS`、`CH395F_TCP_MSS`）；改完必须 0 错 0 警构建 + 全测试套件回归 |
|
||||
| 队列容量 / 消息结构 | CubeMX 生成的 `MX_FREERTOS_Init`（8 槽）+ `net_socket.h` 的 `net_msg_t`（**勿加回传字段**） |
|
||||
@@ -444,10 +446,10 @@ sequenceDiagram
|
||||
## 9. 相关文档
|
||||
|
||||
- `docs/网络/BSD_Socket_API_使用指南.md` —— 公开 API 语义、示例、常见问题（本文的上半部）
|
||||
- `docs/网络/网络自愈架构设计.md` —— **监听生命周期权威设计**（N-32：边沿→电平、单一所有者重建（自愈收敛阶段 3 起为 `net_reconcile_tick` 形态③④）、`net_listener.c` 模块化边界 §11）
|
||||
- `docs/网络/网络自愈架构设计.md` —— **监听生命周期权威设计**（边沿→电平、单一所有者重建 = `net_reconcile_tick` 形态③④、`net_listener.c` / `net_events.c` 模块化边界 §11）
|
||||
- `docs/问题记录/CH395F_Trap_Records.md` —— TRAP-NET-01~23 机制细节（本文引用处）
|
||||
- `docs/网络/Net层阻塞模型架构设计.md` —— 阻塞等待模型的现状架构设计（pending 请求模型 / 五路完成语义）
|
||||
- `docs/问题记录/错误码传播审计.md` —— E-02 头阻塞与错误码回传全审计
|
||||
- `docs/测试说明/链路延迟测试说明.md` —— D1/D10/L3/D14 等时延探针与自愈路径的台架证据
|
||||
- `docs/测试说明/链路延迟测试说明.md` —— 芯片 / 队列 / 挂起 recv 等分段时延基线与自愈路径的台架证据
|
||||
- `docs/子系统设计/网络配置说明.md` §4 —— 代次号与网络重建时序
|
||||
- `docs/测试说明/CH395F_Test_Guide.md` —— 单连接模型测试规则（TC-NET-6xx）
|
||||
|
||||
@@ -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 |
|
||||
|
||||
## 台架注入陷阱（方法论，持续补充）
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
属"接 RS485 消费者前必修"（§5 第三档前置条件）。
|
||||
|
||||
> **2026-09-25 变更**：**E-03 已修复**（错误码改按任务隔离，见 §3.1）。
|
||||
> 它是本次审计中唯一"并发条件下会说谎"的通道，且 pending 二期不覆盖它，故独立小修先行。
|
||||
> 它是本次审计中唯一"并发条件下会说谎"的通道，且 N-4（SEND/ACCEPT pending 化）不覆盖它，故独立小修先行。
|
||||
>
|
||||
> **2026-10-03 变更**：**E-34 / E-04 已修复并通过真机验证**（CH395F 字节命令有限超时 + `remo_send` 返回值校验；见 §5 第一档）。
|
||||
> **2026-10-03 变更②**：**GD5F 错误通道统一（E-10 / E-42 / E-53 / E-54 / E-56 / E-57）已修复并通过台架套件回归**（`=== GD5F2GQ5UE Tests: 16/16 PASSED (failed=0) ===`，只读模式；见 §5 第二档 #1）。
|
||||
@@ -125,7 +125,7 @@
|
||||
|---|---|---|---|
|
||||
| **E-01** | `App/cfg/cfg_file.c` | `cfg_file_poll` 的"超长=损坏"检查是**死代码**（读长被钉死在阈值）→ >4096B 配置被截断当有效解析 → 界外内容静默回工厂默认 → 基线粘住错误状态 → 下次开机 load 守卫判"损坏" → **用户配置文件整体销毁** | `d030cb0` + 关联 `70f1cc8`（`f_rename` 不覆盖既有目标） |
|
||||
| **E-31** | `nand_ftl.c` / `journal.c` | 扫描读失败被**覆盖为 `TOO_BAD`** → 非空白卷在 I/O 故障下被误判"全新"→ 直接 `clear` → 映射表整体丢失 | `da1a6e8` |
|
||||
| **E-02** | `net_socket.c` / `lftpd` / `time_sync` | 一条空闲 FTP 控制连接把 netTask 独占 30s → **全体消费者队列停摆**（实测冻结远端显示 17.7s） | `f8d6e90`+`4a1605b`（分片）→ `a45c0cb`（L3 pending 化，结构性消灭） |
|
||||
| **E-02** | `net_socket.c` / `lftpd` / `time_sync` | 一条空闲 FTP 控制连接把 netTask 独占 30s → **全体消费者队列停摆**（实测冻结远端显示 17.7s） | `f8d6e90`+`4a1605b`（分片）→ `a45c0cb`（挂起 recv 化，结构性消灭） |
|
||||
| **E-63** | `App/cfg/cfg_file.c` | 外科手术保存 3 处 `s_encode(...) == 0` 判定恒假（函数成功返回**文本长度**）→ 受管值改写为**死码**：对已存在 `/config.ini` 保存时受管键从不改写（**静默不落盘**，`net_cfg_save` 仍报 OK） | **2026-10-02**（L0.5 `cfg_file` 单测首跑抓出）——判据由 `== 0` 改 `>= 0`；见 [`../测试说明/配置文件单元测试说明.md`](../测试说明/配置文件单元测试说明.md) §5 |
|
||||
|
||||
### 2.2 P1 二十一项
|
||||
@@ -233,7 +233,7 @@ E-57（`int` / `int32_t` 混用）、**E-10 / E-42 / E-56（GD5F init / BBT / ra
|
||||
`lftpd_inet.c:64`）都在 **NET_READY 屏障之后**才可能执行 → 当前不可达。
|
||||
- **建议**：维持 P2。`net_getsockname` 改为经队列请求（或至少把 4 字节打包成单次 32 位读
|
||||
+ netTask 侧序贯穿），使契约与其余 socket API 一致；不作为独立修复项排期，
|
||||
随 N-4 二期顺带处理。
|
||||
随 N-4 顺带处理。
|
||||
|
||||
---
|
||||
|
||||
@@ -383,7 +383,7 @@ E-57（`int` / `int32_t` 混用）、**E-10 / E-42 / E-56（GD5F init / BBT / ra
|
||||
- **后果**：无法区分"监听器上有新连接"与"有数据"；参数错误无从定位。
|
||||
- **当前状态（复核）**：**仍然存在，休眠缺陷**。当前无 `net_select` 调用者
|
||||
（各服务都是 `accept` 轮询 / pending 模式）。
|
||||
- **建议**：随 N-4 二期或首个 `select` 消费者落地时一并订正；
|
||||
- **建议**：随 N-4 或首个 `select` 消费者落地时一并订正；
|
||||
同时在头文件把"LISTENING 恒可读"作为**契约**写出来。
|
||||
|
||||
---
|
||||
@@ -502,7 +502,7 @@ E-57（`int` / `int32_t` 混用）、**E-10 / E-42 / E-56（GD5F init / BBT / ra
|
||||
| # | 项 | 内容 |
|
||||
|---|---|---|
|
||||
| 1 | ~~**GD5F 错误通道统一**（E-10 / E-42 / E-53 / E-54 / E-56 / E-57）~~ | **已修复并通过台架套件回归（2026-10-03）**：`gd5f_wait_busy` 内检查三次 HAL 调用并区分"超时"（`GD5F_BUSY_TIMEOUT`，可重试）与"真故障"（`GD5F_ERROR`）；`gd5f_bbt_scan` 检查读返回值 + 每轮 `spare` 清零 + 读失败中止，`bbt_rebuild` 扫描失败时**放弃持久化**（保留好副本）；init 全链路检查返回值；init 后**回读 B0h 校验 ECC 使能（bit4）**；`gd5f2gq5ue_read` 的 raw 契约文档化（E-56）；返回类型统一 `int32_t`（E-57）；`nand_ftl.c` 2 处未检查的 `gd5f_read_from_cache` 补检查。套件回归 `=== GD5F2GQ5UE Tests: 16/16 PASSED (failed=0) ===` ✅ |
|
||||
| 2 | **N-4 二期：ACCEPT + SEND 阻塞路径 pending 化** | 沿用一期（RECV）机制扩展；同期消化 **E-25**（`net_select` 语义）、**E-24 / E-27 / E-28**（跨上下文裸指针收口为状态查询 API）。基线重锁 + 探针族扩充 + 看门狗接 selftest 留痕 |
|
||||
| 2 | **N-4：ACCEPT + SEND 阻塞路径 pending 化** | 沿用 recv 挂起机制扩展；同期消化 **E-25**（`net_select` 语义）、**E-24 / E-27 / E-28**（跨上下文裸指针收口为状态查询 API）。基线重锁 + 探针族扩充 + 看门狗接 selftest 留痕 |
|
||||
| 3 | **E-16** | 在 `cfg_file.h` 显式定义段名 / 键名最大长度，注册 API 拒绝超长名字（把余量变成编译期可验证）；`snprintf` 返回值改检查式 |
|
||||
| 4 | **E-26** | UDP 路径定案：并入队列 / 移除 / 文档化"单任务独占"。倾向 **移除**（无用户） |
|
||||
| 5 | **E-30** | sim 后端 errno 语义对齐 + 缺陷记录标注 sim 复现盲区 |
|
||||
@@ -594,13 +594,13 @@ E-57（`int` / `int32_t` 混用）、**E-10 / E-42 / E-56（GD5F init / BBT / ra
|
||||
| bit5 | `CFG_SAVE` | 命令位（可消费） | uiTask | defaultTask（`WaitAny` 500ms + pending 锁存 ✓） |
|
||||
|
||||
> **bit3 说明**：`TIMESYNC_READY` 仍未置位，属 E-19 的残留项。因当前无消费者，
|
||||
> 影响为零；建议在 N-4 二期一并处置（置位或删除，不要长期留一个"假位"）。
|
||||
> 影响为零；建议在 N-4 一并处置（置位或删除，不要长期留一个"假位"）。
|
||||
|
||||
## 附录 C：队列清单与回传机制
|
||||
|
||||
| 队列 | 定义处 | 深度 | 条目形态 | 回传机制 | 风险 |
|
||||
|---|---|---|---|---|---|
|
||||
| `netMsgQueue` | `Src/freertos.c:166` | 8 | `net_msg_t` **按值** | 任务通知值（精确错误码 / 字节数）+ 指针字段回写 | 头阻塞已由 L3 pending 化解；errno 竞态已由 E-03 修复（按任务隔离） |
|
||||
| `netMsgQueue` | `Src/freertos.c:166` | 8 | `net_msg_t` **按值** | 任务通知值（精确错误码 / 字节数）+ 指针字段回写 | 头阻塞已由 挂起 recv 化解；errno 竞态已由 E-03 修复（按任务隔离） |
|
||||
| syslog 队列 | `App/log/sys_log_mcu.c:218-223`（惰性创建） | 64 | 输入型（id + 静态串指针） | 无（fire-and-forget） | 结构免疫 P1；preboot 窗口已并轨 |
|
||||
| `cfgSaveQueue` | `Src/freertos.c` | 8 | 输入型（路径指针） | `s_save_pending` 锁存 + `s_save_result` 状态机 | 协议无损 ✓ |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user