From 1a17d73e351cc9705abeaaac82b050f6a43578ef Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Mon, 12 Oct 2026 19:16:31 +0800 Subject: [PATCH] =?UTF-8?q?docs(net):=20N-32=20=E7=9B=91=E5=90=AC=E7=94=9F?= =?UTF-8?q?=E5=91=BD=E5=91=A8=E6=9C=9F=E6=96=87=E6=A1=A3=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=EF=BC=884=20tick/=E4=BA=94=E5=B1=82=E8=87=AA=E6=84=88/net=5Fli?= =?UTF-8?q?stener.c=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit N-32 把监听生命周期抽为 net_listener.c，并把周期性重建收敛到 唯一入口 net_listener_pump；文档与代码注释滞后于实现，本次同步： - 主循环自愈 tick 3 → 4（新增 net_listener_pump，100ms） - 自愈分层 四层 → 五层（新增 N-32 pump 行） - net_reconcile_tick 对账收窄为 ①②，③④ 移交 pump - 函数更名：net_relisten_try/clear/retry_tick → net_listener_* - Trap 23 沉降等级订正：异常 400ms / 正常 100ms（正常 FIN 亦沉降） - net_socket.c 注释同步（四个自愈 tick、函数名、pump 条目） 权威设计见 docs/子系统设计/网络Socket监听生命周期设计说明.md §10。 --- Drivers/BSP/NET/net_socket.c | 22 ++-- docs/网络/BSD_Socket_API_使用指南.md | 28 ++--- docs/网络/BSD_Socket_API_函数调用关系.md | 131 ++++++++++++++--------- docs/网络/Net层阻塞模型架构设计.md | 7 +- 4 files changed, 113 insertions(+), 75 deletions(-) diff --git a/Drivers/BSP/NET/net_socket.c b/Drivers/BSP/NET/net_socket.c index b6a6858a..d565980c 100644 --- a/Drivers/BSP/NET/net_socket.c +++ b/Drivers/BSP/NET/net_socket.c @@ -651,19 +651,21 @@ static void net_reconcile_tick(void) { * 失败=具体错误码），调用方 net_wait_result 拾取，对外统一 -1。 * 限定条件：必须在 netTask 上下文中调用（独占 CH395F 与 s_net_socks 访问权）； * 由 net_task.c 在 net_stack_bring_up 之后每次 1ms 循环调用。 - * 函数说明：1. 三个自愈 tick 均非阻塞（绝不 osDelay 忙等，netTask 永不冻结），先于消息分派执行 - * 2. net_relisten_retry_tick（D10）：断连后按 30ms + * 函数说明：1. 四个自愈 tick 均非阻塞（绝不 osDelay 忙等，netTask 永不冻结），先于消息分派执行 + * 2. net_listener_retry_tick（D10）：断连后按 30ms * （NET_RELISTEN_RETRY_MS）节拍重试 open+listen；2s（NET_RELISTEN_DEADLINE_MS） * 总时限到期放弃留痕 * 3. D10：本 fd 有在途挂起 recv 时跳过（L3 保险） * 4. net_pending_tick（L3）：按节拍了结挂起 recv（数据/到点/断连） * 5. L3 看门狗：到点后 1s（NET_PENDING_WATCHDOG_MS）未了结 → 强制了结 + DBG_ERROR 留痕 - * 6. net_reconcile_tick（Trap 22）：每 200ms（NET_RECONCILE_PERIOD_MS）对账 - * 7. 对账以连续 2 次失配去抖 + 1s 冷却，自愈三类失同步 - * 8. net_msg_t 按值入队，netTask 侧副本调用方不可见 → 结果只能搭任务通知值回传 - * 9. 32 位整体即结果，不做位域压缩 - * 10. RECV 特例：无数据+阻塞 → 登记 pending 哨兵 NET_PENDING_REGISTERED（0x70000000） - * 11. RECV 特例 do_notify=0，回执推迟到 net_pending_tick 完成时 + * 6. net_reconcile_tick（Trap 22）：每 200ms（NET_RECONCILE_PERIOD_MS）对账①② + * 7. 对账以连续 2 次失配去抖 + 1s 冷却，自愈两类失同步 + * 8. net_listener_pump（N-32 P2）：每 100ms 监听器 pump，本层**唯一**重建入口 + * （原对账③④；本层 CLOSED 而芯片在听时只重同步）——置于对账之后 + * 9. net_msg_t 按值入队，netTask 侧副本调用方不可见 → 结果只能搭任务通知值回传 + * 10. 32 位整体即结果，不做位域压缩 + * 11. RECV 特例：无数据+阻塞 → 登记 pending 哨兵 NET_PENDING_REGISTERED（0x70000000） + * 12. RECV 特例 do_notify=0，回执推迟到 net_pending_tick 完成时 */ void net_process_messages(void) { net_msg_t msg; @@ -1922,7 +1924,7 @@ static int net_recv_locked(net_sock_t *p_sock, void *buf, int len, int flags, if ((p_sock->state == NET_SOCK_STATE_CLOSED) || (p_sock->session_dead != 0U)) { /* 启用自动重监听：先把监听器重新置回 LISTEN。 * ⚠ 内层 `state == CLOSED` 门是**必需的**，不是冗余： - * `net_relisten_try` 无状态门，对已 LISTENING 的 fd 再 open+listen + * `net_listener_try` 无状态门，对已 LISTENING 的 fd 再 open+listen * 会让 ch395f_open_socket 返 USE，其失败分支会 ch395f_close_socket * —— 把正听着新 SYN 的 Socket 当场关掉（U12 同源事故）。 * session_dead + 已回 LISTENING = 重建已由别处完成，这里只报 EOF。 @@ -3072,7 +3074,7 @@ int net_resync_listen(int sockfd) { * 函数说明：1. 用于"断连后监听器可能已失位"的自愈场景（2026-09-22 run9 实证） * 2. 一次性 net_listen 落在 Trap 09 窗口失败且被静默忽略 → 监听器永久丢失 * 3. 后续连接全部拒绝 - * 4. 与 auto_relisten 内部路径同一实现（net_relisten_locked：单次尝试 + 非阻塞重试，见 net_relisten_retry_tick） + * 4. 与 auto_relisten 内部路径同一实现（net_relisten_locked：单次尝试 + 非阻塞重试，见 net_listener_retry_tick） * 5. 芯片侧已在监听时：首次 open 失败 → close 重建 → 监听短暂中断 ~1s */ int net_relisten(int sockfd) { diff --git a/docs/网络/BSD_Socket_API_使用指南.md b/docs/网络/BSD_Socket_API_使用指南.md index 8b132ba2..e31aeb94 100644 --- a/docs/网络/BSD_Socket_API_使用指南.md +++ b/docs/网络/BSD_Socket_API_使用指南.md @@ -60,7 +60,8 @@ | `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、D10 非阻塞重监听重试（30ms/2s）、Trap 22 周期对账（200ms，去抖+冷却）、Trap 23 排渣隔离（400ms 起/800ms 上限） | +| `net_socket.c` | API 核心实现：消息队列处理与线程安全封装、内部 `_sock()` 版本；另含 L3 pending 化 recv、Trap 22 周期对账（200ms，去抖+冷却，只剩①②） | +| `net_listener.c`（**真机专属**） | **监听生命周期**（N-32 §10 模块化）：`net_listener_try` / `net_listener_clear` / `net_listener_retry_tick`（D10 重试 30ms/2s）/ `net_listener_pump`（唯一重建入口，100ms）/ `net_listener_settle`（沉降/隔离 100ms/400ms）；内部头，模拟器不编译 | | `net_select.h` | select/poll API 头文件 | | `net_select.c` | select/poll 实现（仅 MCU 端编译） | | `net_socket_sim.c`（`simulator/sim/`） | Winsock2 后端（模拟器端，与 `net_socket.c` 互斥编译），详见 §2.3 | @@ -155,7 +156,7 @@ sequenceDiagram | **`netTask` 外（任意应用任务）** | 公共 API：`net_send()` / `net_recv()` / `net_recv_to()` / `net_accept()` / `net_connect()` / `net_close()` / `net_listen()`，及自愈 `net_relisten()` / `net_resync_listen()`——请求入队列，netTask 串行执行，调用方阻塞等回执 | | **`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()` 每轮先跑 D10 重监听重试 → L3 挂起 recv 完成 → Trap 22 对账（200ms）三个非阻塞 tick，再处理队列 | +| **`net_poll()` 和 `net_process_messages()`** | 必须在 `netTask` 主循环调用；`net_process_messages()` 每轮先跑 **4 个非阻塞 tick**（D10 重监听重试 → L3 挂起 recv 完成 → Trap 22 对账 200ms → N-32 监听器 pump 100ms），再处理队列 | ### 3.4 内部 API 说明 @@ -179,14 +180,15 @@ int net_close_sock(net_sock_t *p_sock); ### 3.6 芯片/本层状态对账与重监听自愈（Trap 09 / 22 / 23） -单连接模型下"监听 Socket = 数据通道"，多种芯片行为会造成**芯片侧与本层状态失同步**，纯事件（中断）驱动无法自愈。当前版本有四层自愈，全在 netTask 内、全非阻塞、不冻结主循环： +单连接模型下"监听 Socket = 数据通道"，多种芯片行为会造成**芯片侧与本层状态失同步**，纯事件（中断）驱动无法自愈。当前版本有**五层自愈**，全在 netTask 内、全非阻塞、不冻结主循环： | 机制 | 触发 | 动作 | 关键参数 | |---|---|---|---| | **`auto_relisten`** | 数据通道正常 EOF / DISCONNECT | 重开 + 重新 LISTEN，回 LISTENING；应用层无需 close/重 listen | `net_listen()` 置位；`net_close()` 清 | | **D10 非阻塞重监听重试** | 重开失败（Trap 09：芯片 close 后需沉降） | 单次尝试失败即登记待重试，每轮到点重试；超时限放弃并记 `relisten give up` | 重试间隔 30ms / 时限 2s（自首次尝试）；同 fd 有在途挂起 recv 时跳过（L3 保险，防毁在途连接） | -| **Trap 22 周期对账** | 芯片丢 CONNECT/DISCONNECT 中断（快速复连）；或静默回收 Socket（peer FIN，无 DISCONNECT 中断） | 每 200ms 对在用 socket 回读芯片状态，修正三类失同步：① 本层 ESTABLISHED 而芯片已断 → 按断开处理；② 本层 LISTENING 而芯片已握手 → 补 accept；③ 本层 LISTENING 而芯片监听消失 → 重建 | 周期 200ms；**连续 2 次失配**才动手（去抖 ≈400ms）+ 动手后 **1s 冷却**（防"刚 open 未生效"瞬态重建风暴） | -| **Trap 23 排渣隔离** | 异常释放（芯片 TIMEOUT，如客户端中止上传）：在途数据落进 RX 缓冲，直接复监听 → 下条连接把 ~2048B 残渣当自己的数据读走（上传静默截断） | 复监听前隔离：持续排空 RX 残渣 + 主动 close + 排空中断，等芯片回 CLOSED/TCP_CLOSED 才 open+listen；到期强制放行 | 隔离 400ms 起 / **800ms 上限（必须 < 2s 时限**，否则监听被放弃）；仅异常路径生效，正常 FIN 路径零改动 | +| **Trap 22 周期对账** | 芯片丢 CONNECT/DISCONNECT 中断（快速复连）；或静默回收 Socket（peer FIN，无 DISCONNECT 中断） | 每 200ms 对在用 socket 回读芯片状态，修正**两类**失同步：① 本层 ESTABLISHED 而芯片已断 → 按断开处理；② 本层 LISTENING 而芯片已握手 → 补 accept（③④ 已移交 pump） | 周期 200ms；**连续 2 次失配**才动手（去抖 ≈400ms）+ 动手后 **1s 冷却**（防"刚 open 未生效"瞬态重建风暴） | +| **N-32 监听器 pump**（**唯一重建入口**） | 监听型 fd 的芯片状态与本层不一致（会话结束待重建 / 本层状态滞后） | 每 100ms 检查监听型 fd：芯片失位即重建（`net_listener_try`）；本层 CLOSED 而芯片**正在** LISTEN 时**只做状态重同步**、不发芯片命令 | 周期 100ms；连续 2 次失配（≈200ms）+ 动手后 1s 冷却；其它位置只置事实、不做重建动作 | +| **Trap 23 排渣隔离** | 异常释放（芯片 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 时限**，否则监听被放弃） | **行为结论**：监听器恢复从"一次性事件"变为"登记 → 到点重试"过程： @@ -1009,11 +1011,12 @@ Socket 已创建或已绑定时可用；port 为 0（动态分配）时返回已 void net_process_messages(void); ``` -处理其他任务投递的请求（send/recv/connect/accept/close/**resync-listen / relisten**）。每次调用先跑 3 个**非阻塞** tick，再取队列消息（0 超时出队）： +处理其他任务投递的请求（send/recv/connect/accept/close/**resync-listen / relisten**）。每次调用先跑 4 个**非阻塞** tick，再取队列消息（0 超时出队）： -1. **D10 重监听重试**：断连后监听器恢复的到点重试（30ms 间隔 / 2s 时限，§3.6） -2. **L3 挂起 recv 完成检查**：按 ①数据 ②到点 ③断连 检查每个挂起请求并通知调用方（看门狗 1s） -3. **Trap 22 芯片/本层对账**：200ms 周期修正三类失同步（§3.6） +1. **D10 重监听重试**（`net_listener_retry_tick`）：断连后监听器恢复的到点重试（30ms 间隔 / 2s 时限，§3.6） +2. **L3 挂起 recv 完成检查**（`net_pending_tick`）：按 ①数据 ②到点 ③断连 检查每个挂起请求并通知调用方（看门狗 1s） +3. **Trap 22 芯片/本层对账**（`net_reconcile_tick`）：200ms 周期修正**两类**失同步（①②，§3.6） +4. **N-32 监听器 pump**（`net_listener_pump`）：100ms 周期，**唯一重建入口**（③④；本层 CLOSED 而芯片在听时只重同步，不发芯片命令，§3.6） > `net_msg_t.timeout_ms`：L3 分片预算（`net_recv_to()`），0=默认 `NET_RECV_TIMEOUT_MS`（30s）。消息类型含 `NET_MSG_RESYNC_LISTEN`（仅 MCU 侧状态）与 `NET_MSG_RELISTEN`（芯片侧重监听）。 @@ -1394,13 +1397,13 @@ CH395F 底层驱动返回的状态码（`ch395f_get_cmd_status()` 或 `ch395f_po 需要回传请用调用方提供的指针，或复用通知值。（2026-09-21 实证：曾按"加 `msg.err` 字段"方式修错误码， 结果 `ui_net_sink` 每次空轮询都拿到栈垃圾 → 误判为"真错误" → 连上即 `net_close`。） -### 12.10 监听器自愈行为与排渣（D10 / Trap 09、Trap 22、Trap 23） +### 12.10 监听器自愈行为与沉降/隔离（D10 / Trap 09、Trap 22、Trap 23 / N-32） -**默认行为**（无需应用代码）：断连 → `auto_relisten` 重开监听；重开失败 → 30ms 节奏重试（2s 时限）；芯片丢中断/静默回收 → 200ms 对账自愈；中止复连首上传 → 排渣隔离。全在 netTask 内，应用只需保证 `net_poll()` + `net_process_messages()` 主循环在跑。 +**默认行为**（无需应用代码）：断连 → `auto_relisten` 重开监听；重开失败 → 30ms 节奏重试（2s 时限）；芯片丢中断/静默回收 → 200ms 对账 + 100ms 监听器 pump 自愈；中止复连首上传 → 沉降/隔离。全在 netTask 内，应用只需保证 `net_poll()` + `net_process_messages()` 主循环在跑。 | 场景 | 修复前症状 | 机制 | 生产验证（2026-09-23） | |---|---|---|---| -| **Trap 22** 快速复连丢中断 → 监听静默死亡 | 待机后 UI `:7003` 快速复连 2/10 且**永久**拒连；FTP `:21` 100ms 间隔自第 29 轮死亡；设备日志**无报错**（状态静默滞留） | 周期对账 `net_reconcile_tick()`（200ms，三类失同步）+ 去抖（连续 2 次）+ 冷却（1s）；`handle_disconnect_event` LISTENING 分支改为"已不可监听即重建" | `:7003` 10/10；`:21` 100ms/0ms/600ms 各 50/50；UI 20/20；FTP 正常 10/10（SHA-256）；中止 RST/FIN 5/5 + 5/5；零重建风暴 | +| **Trap 22** 快速复连丢中断 → 监听静默死亡 | 待机后 UI `:7003` 快速复连 2/10 且**永久**拒连；FTP `:21` 100ms 间隔自第 29 轮死亡；设备日志**无报错**（状态静默滞留） | 周期对账 `net_reconcile_tick()`（200ms，①②）+ 监听器 pump `net_listener_pump()`（100ms，**唯一重建入口**，N-32）+ 去抖（连续 2 次）+ 冷却（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；零重建风暴 | | **Trap 23** 中止后首笔复连上传被静默截断 ≤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 全匹配 | | **Trap 21**（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 | @@ -1412,6 +1415,7 @@ CH395F 底层驱动返回的状态码（`ch395f_get_cmd_status()` 或 `ch395f_po | 日期 | 变更 | |------|------| +| 2026-10-12 | **N-32 监听生命周期模块化 + 单一所有者**：监听生命周期抽为 `net_listener.c`（§2.2 文件表新增该行，真机专属）；主循环自愈 tick 由 3 个增至 **4 个**（新增 `net_listener_pump`，100ms，**唯一重建入口**）；`net_reconcile_tick` 对账收窄为 ①②，③④ 移交 pump；`handle_disconnect_event` / `handle_timeout_event` 改为 `net_listener_settle(GRACEFUL 100ms / QUARANTINE 400ms)` **只置事实**、不再自行重建；§3.3 / §3.6（四层自愈 → **五层**）/ §12.10 同步。权威设计见 `docs/子系统设计/网络Socket监听生命周期设计说明.md` §10 | | 2026-10-10 | 新增 **`net_can_accept()` / `net_can_read()` 就绪门控 API**（§10.1）：纯 RAM 读控制块、**不走消息队列、不等 netTask 回执**，供实时性敏感任务在发 RPC 前判断"有没有活"（动因 = `ui_net_sink_poll()` 每 10 ms 一次 `net_accept` 把 uiTask 拖成最坏 ≈50 ms；原拟登记 N-19 / C7，当日结案不入登记簿；设计与实测见 `docs/子系统设计/看门狗设计说明.md` §11（原分析文档已并入该节））；§3.5 补"netTask 运行要求"例外条；⚠ 记录两条使用约束——**不可作为唯一判据**（`readable` 只由 RECV_OK 中断置位，须保留低频兜底 recv）与**模拟器后端恒返 1**（`net_socket_sim.c`，Winsock 无 RPC 成本） | | 2026-09-23 | 同步 L3 pending 化、D10 非阻塞重监听、Trap 22 对账、Trap 23 排渣隔离后的现状：新增 `net_recv_to` / `net_sock_state` / `net_resync_listen` / `net_relisten`（§10.1）及 `net_getsockname`；§3 新增 3.6（对账与自愈四机制）、3.3/3.5 改写（recv 挂起模型、队列语义、netTask 运行要求）；§4/§5 示例更新（监听由就绪屏障后服务任务建立、`net_sock_state` 轮询）；§10.2 改述 `net_process_messages()` 每轮节奏（重监听重试 → 挂起 recv 完成 → 200ms 对账 → 队列），补 `timeout_ms`/新消息类型说明；新增 §11.2 分片阻塞读（`net_recv_to`）；§12.1/12.3/12.4/12.9 更新，新增 §12.10（自愈行为数据与排障判据，含 Trap 21 结案） | | 2026-09-21 | **修正公开 API 的错误码回传**：`net_msg_t` 按值拷入队列 → netTask 对消息的写入调用方不可见，改用 `xTaskNotify()` 通知值回传具体错误码（负值），公开 API 恢复 errno 后统一返回 -1（此前被覆盖成 `NET_ERR`，使 `net_get_errno() != NET_ERR_WOULDBLOCK` 的"空轮询"判断恒成立 → `ui_net_sink` 连上即 `net_close`）；§12.4 补单连接模型断开处理（EOF 时不得 `net_close` 监听 socket）；§12.9 补错误码回传约束 | diff --git a/docs/网络/BSD_Socket_API_函数调用关系.md b/docs/网络/BSD_Socket_API_函数调用关系.md index 2100e955..250763f8 100644 --- a/docs/网络/BSD_Socket_API_函数调用关系.md +++ b/docs/网络/BSD_Socket_API_函数调用关系.md @@ -3,8 +3,10 @@ > **定位**：本文档是 `docs/网络/BSD_Socket_API_使用指南.md`（下称"使用指南"）的**内部视图**伴读文档。 > 使用指南回答"**上层该怎么调**"（公开语义 / 示例 / 常见问题）；本文回答"**内部函数各自做什么、互相怎么调用、为什么这么设计**"（调用关系 / 设计意图 / 踩坑）。 > -> **范围**：MCU 端 `Drivers/BSP/NET/net_socket.c`（约 2870 行，全部函数）。 +> **范围**：MCU 端 `Drivers/BSP/NET/net_socket.c`（约 3670 行）+ 其拆出的 +> `Drivers/BSP/NET/net_listener.c`（约 550 行，**监听生命周期**，N-32 §10 模块化）。 > 模拟器端后端 `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_socket.c` include**（内部头，不进公开 `net_socket.h`），模拟器零依赖、不编译；其设计依据见 `docs/子系统设计/网络Socket监听生命周期设计说明.md` §10。 > > **交叉引用约定**：机制标 Trap 号 → `docs/问题记录/CH395F_Trap_Records.md`；用法语义引用使用指南 §；关键参数值与 `net_config.h` / `net_socket.c` 内宏一致。 @@ -12,7 +14,7 @@ ## 1. 一句话架构 -**一切芯片（CH395F）操作收敛到唯一执行者 netTask 串行完成**；其他任务通过"入队消息 + 任务通知"表达请求，结果只经**任务通知值**回传；阻塞等待**不独占 netTask**（挂起登记 + 主循环节拍完成）；监听器**常驻**（`auto_relisten` + D10 非阻塞重试 + Trap 22 周期对账 + Trap 23 排渣隔离，四层自愈）。 +**一切芯片（CH395F）操作收敛到唯一执行者 netTask 串行完成**；其他任务通过"入队消息 + 任务通知"表达请求，结果只经**任务通知值**回传；阻塞等待**不独占 netTask**（挂起登记 + 主循环节拍完成）；监听器**常驻**（`auto_relisten` + D10 非阻塞重试 + Trap 22 周期对账 + Trap 23 排渣隔离 + **N-32 监听器 pump（唯一重建入口）**，五层自愈）。 --- @@ -20,7 +22,7 @@ | 执行域 | 运行位置 / 节奏 | 允许的操作 | 典型调用者 | |---|---|---|---| -| **netTask 主循环** | 独立 FreeRTOS 任务，1ms/tick | **唯一**可碰芯片（SPI2）的地方；3 个非阻塞 tick；队列分派；事件处理器；用户回调 | `net_poll` / `net_process_messages` 及其下游全部 `_locked` / `_tick` / `handle_*` | +| **netTask 主循环** | 独立 FreeRTOS 任务，1ms/tick | **唯一**可碰芯片（SPI2）的地方；4 个非阻塞 tick（D10 重试 / L3 挂起 / Trap 22 对账 / N-32 pump）；队列分派；事件处理器；用户回调 | `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 独占芯片） | @@ -43,11 +45,12 @@ flowchart TB XN["xTaskNotify / xTaskNotifyWait
（结果回传的唯一通道）"] subgraph NT["netTask 主循环 — 1ms/tick；芯片操作唯一执行者"] - NPM["netProcessMessages
先跑 3 个 tick，再排空队列分派"] + NPM["netProcessMessages
先跑 4 个 tick，再排空队列分派"] NP["netPoll
INT# GPIO 轮询 → 全局中断 → 各 Socket SINT → 每轮一批"] - T1["① netRelistenRetryTick
D10 重监听重试：30ms / 2s 时限"] + T1["① netListenerRetryTick
D10 重监听重试：30ms / 2s 时限"] T2["② netPendingTick
L3 挂起 recv：①数据 ②到点 ③断连 ④看门狗 1s"] - T3["③ netReconcileTick
Trap 22 对账：200ms / 去抖 2 次 / 冷却 1s"] + T3["③ netReconcileTick
Trap 22 对账：200ms / 去抖 / 冷却（只剩①②）"] + T4["④ netListenerPump
N-32 唯一重建入口：100ms / 去抖 / 冷却"] DISP["队列分派 switch
SEND · RECV · CLOSE · CONNECT · LISTEN
ACCEPT · RESYNC_LISTEN · RELISTEN"] subgraph LK["_locked / 内部分派目标（仅 netTask 上下文）"] LL["netListenLocked
初次监听（3×500ms 阻塞重试）"] @@ -56,10 +59,11 @@ flowchart TB LR["netRecvLocked
快路径 / DONTWAIT / 登记挂起"] LA["netAcceptLocked
先 netPoll + 状态判定"] LC["netCloseLocked
了结挂起 + close + 等 CLOSED + 排空中断"] - RLS["netRelistenTry → netRelistenLocked
单次尝试 + Trap 23 排渣隔离"] + RLS["netListenerTry → netRelistenLocked
单次尝试 + Trap 23 排渣隔离"] RSY["RESYNC 分支：改状态 + 取消挂起
（不发芯片命令）"] end EV["事件处理器
handleConnect · handleDisconnect
handleRecv · handleSend · handleTimeout"] + ST["netListenerSettle
只置沉降/隔离事实（100ms / 400ms）"] FE["fireEvent → 用户回调"] PR["s_net_pending
（每 fd 至多一个挂起）"] CH[("ch395f.* 驱动
SPI2 串行事务")] @@ -68,16 +72,16 @@ flowchart TB PUB -->|入队| MQ MQ --> DISP DISP --> LL & LN & LS & LR & LA & LC & RLS & RSY - NPM --> T1 & T2 & T3 & NP + NPM --> T1 & T2 & T3 & T4 & NP T1 --> RLS T3 -->|"① 已断"| EV T3 -->|"② 补 accept"| EV - T3 -->|"③ 重建监听"| RLS + T4 -->|"①② 芯片失位即重建"| RLS NP --> EV EV --> FE FE -.-> CB - EV -->|"LISTENING：监听丢失"| RLS - EV -->|"TIMEOUT：置隔离"| RLS + EV -->|"断连/超时：只置事实"| ST + ST -.->|"事实 → 由 pump 统一重建"| T4 LR -->|无数据+阻塞| PR PR --> T2 T2 -->|xTaskNotify| XN @@ -91,9 +95,10 @@ flowchart TB **读图要点**： 1. 应用侧只有两种"等"：① 入队后 `xTaskNotifyWait` 等回执（同步语义）；② 挂起 recv 的等待（同一通道，只是"完成"由 `netPendingTick` 判定，不由 netTask 立即处理）。 -2. `net_process_messages()` 开头的 **3 个 tick 是网络层自愈主干**：没有任何应用消息时，监听恢复 / 挂起完成 / 状态对账照常运转——"断连后即使没人发消息，监听器也能自己活过来"靠的就是它们。 -3. 事件处理器**只由 `net_poll` 驱动**，例外是 `net_reconcile_tick`（带 2 次去抖 + 1s 冷却）可再入 `handle_disconnect_event` / `handle_connect_event` / `net_relisten_try`——对账是丢中断的唯一自愈通道（Trap 22）。 +2. `net_process_messages()` 开头的 **4 个 tick 是网络层自愈主干**：没有任何应用消息时，重试 / 挂起完成 / 状态对账 / 监听重建照常运转——"断连后即使没人发消息，监听器也能自己活过来"靠的就是它们。 +3. 事件处理器**只由 `net_poll` 驱动**，例外是 `net_reconcile_tick`（带 2 次去抖 + 1s 冷却）可再入 `handle_disconnect_event` / `handle_connect_event`——对账是丢中断的自愈通道（Trap 22）。**注意职责边界（N-32 P2）**：对账与事件处理器**只置事实**（置 CLOSED / 登记沉降），**重建监听的动作统一由 `net_listener_pump` 做**（本层唯一重建入口）——"谁先看到 DISCONNECT 就谁重建"的竞争在结构上消失。 4. 回调 `event_cb` 在 **netTask 上下文**执行：回调内不得阻塞、不得发网络操作。 +5. **模块归属**：`T1`（D10 重试）/ `T4`（pump）/ `RLS` 的 `net_listener_try` / `ST`（settle）在 `net_listener.c`（真机专属、模拟器不编译）；其余 tick 与 `_locked` 在 `net_socket.c`。 --- @@ -112,7 +117,7 @@ flowchart TB | 函数 | 设计作用 | 主要调用 | 意图 / 注意 | |---|---|---|---| | `net_poll()` | 事件泵：GPIO 轮询 INT#（低=有待处理）→ `GET_GLOB_INT_STATUS_ALL`（读=清）→ 按位图逐 Socket 读 SINT → 分派 5 类事件 | `HAL_GPIO_ReadPin` → `ch395f_get_glob_int_status_all` → `ch395f_get_sock_int_status` ×n → `handle_connect/disconnect/recv/send/timeout_event` | **RECV 中断是电平触发**：每次调用**只处理一批**（do-while(0)），处理完立即返回，否则主循环（echo/应用逻辑）饿死（Trap 08）；SENBUF_FREE 只置 `send_ready` 不记事件 | -| `net_process_messages()` | 队列入口 + 自愈 tick 宿主：每轮**先**跑 3 个非阻塞 tick，再排空队列逐条分派，结果 `xTaskNotify` 回传 | `net_relisten_retry_tick` → `net_pending_tick` → `net_reconcile_tick` → `osMessageQueueGet`(0 超时) ×n → switch 分派 → `xTaskNotify` | ① tick 放在队列**之前**：断连后即使没有任何应用消息，监听器也能自主恢复、挂起 recv 也能完成；② RECV 若返回 `NET_PENDING_REGISTERED`（哨兵 0x70000000）则**不发即时回执**（`do_notify=0`），完成时才通知；③ 失败结果把 `s_net_errno`（具体负错误码）压入通知值——调用方恢复 errno 后对外统一 -1（BSD 语义）；④ 通知值**整个 32 位**都是结果（不压位域标签，否则 32768 这类大字节数会溢出为负） | +| `net_process_messages()` | 队列入口 + 自愈 tick 宿主：每轮**先**跑 4 个非阻塞 tick，再排空队列逐条分派，结果 `xTaskNotify` 回传 | `net_listener_retry_tick` → `net_pending_tick` → `net_reconcile_tick` → `net_listener_pump` → `osMessageQueueGet`(0 超时) ×n → switch 分派 → `xTaskNotify` | ① tick 放在队列**之前**：断连后即使没有任何应用消息，监听器也能自主恢复、挂起 recv 也能完成；② RECV 若返回 `NET_PENDING_REGISTERED`（哨兵 0x70000000）则**不发即时回执**（`do_notify=0`），完成时才通知；③ 失败结果把 `s_net_errno`（具体负错误码）压入通知值——调用方恢复 errno 后对外统一 -1（BSD 语义）；④ 通知值**整个 32 位**都是结果（不压位域标签，否则 32768 这类大字节数会溢出为负）；⑤ **pump 置于对账之后**：对账①可能刚把会话置 CLOSED，pump 紧接着就能看到并重建 | ### 4.3 经队列的公共 API 及其 netTask 侧实现 @@ -121,20 +126,20 @@ flowchart TB | 公共 API | 消息 | netTask 侧实现 | 关键芯片命令 | 返回语义 | 设计意图 / 注意 | |---|---|---|---|---|---| | `net_listen` | `NET_MSG_LISTEN` | `net_listen_locked` | `set_proto_type` + `set_sour_port` + `open_socket`（**3×500ms 阻塞重试**）+ `tcp_listen` + 清全部中断状态 | 0 / -1 | **初次**监听允许阻塞重试（启动期无竞争）；成功后置 `auto_relisten=1`——监听常驻的源头；启动前清空各 Socket/全局中断状态，防历史残留误触发事件 | -| `net_accept` | `NET_MSG_ACCEPT` | `net_accept_locked` | 无（先 `net_poll` 泵一次 + 状态判定） | 监听 fd 自身（单连接）/ -1（WOULDBLOCK） | 单连接：监听 Socket 在 CONNECT 后**自身即数据通道**，返回的就是它；CLOSED + auto_relisten 时触发**非阻塞** `net_relisten_try`；**accept 路径不做自愈**——单次状态读会误判"刚 listen 未生效"致重建风暴（2026-09-23 实测），统一交给对账 | +| `net_accept` | `NET_MSG_ACCEPT` | `net_accept_locked` | 无（先 `net_poll` 泵一次 + 状态判定） | 监听 fd 自身（单连接）/ -1（WOULDBLOCK） | 单连接：监听 Socket 在 CONNECT 后**自身即数据通道**，返回的就是它；CLOSED + auto_relisten 时触发**非阻塞** `net_listener_try`；**accept 路径不做自愈**——单次状态读会误判"刚 listen 未生效"致重建风暴（2026-09-23 实测），统一交给 `net_listener_pump`（N-32 单一重建入口） | | `net_connect` | `NET_MSG_CONNECT` | `net_connect_locked` | `set_proto_type` + `open_socket`（3×500ms 重试）+ 清残留中断 + `set_sour_port` / `set_des_ip`（大端数组）/ `set_des_port` + `tcp_connect` | 0 = 请求已发出（**异步**）/ -1 | open **先于**寄存器写入（open 会复位寄存器）；open 后清残留 DISCONNECT，防新连接秒断（Trap 14/17）；目的 IP 字节序写反 = CONNECT TIMEOUT（Trap 16）；返回 0 ≠ 已建立——调用方以 `net_sock_state` 轮询等 ESTABLISHED | | `net_send` | `NET_MSG_SEND` | `net_send_locked` | `ch395f_write_send_buf`（分块）+ 等 SENBUF_FREE（`net_poll` 轮询） | 实际字节数 / -1 | 分块 ≤ `NET_SEND_CHUNK_MAX` = 1KB（**硬件发送 FIFO 硬上限**，Trap 20：写穿 FIFO = 数据错位）；`send_ready` 门控用 `net_poll` 轮询而非 osDelay；短写**必须**告警——静默截断会让对端永久等待剩余字节（2026-09-21 实证：UI 推流应答截断 → 客户端失联） | | `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 / TIMEDOUT / CONNRESET） | 快路径：数据已在 → 立即读出返回（允许部分读）；无数据 + 阻塞 → **登记挂起后立即返回**（L3，netTask 零占用）；DONTWAIT + CLOSED → EOF + 触发重监听 | | `net_recv_to` | `NET_MSG_RECV`（timeout>0） | `net_recv_locked` | 同上 | >0 / 0 / -1 / **-2（本片超时无数据）** | E-02 头阻塞修复配套：调用方把长等待切成有界片（如 5ms/剩余预算），**总超时语义不变、单次占用有界**；`timeout_ms=0` 直接拒（会被解释成默认 30s，恰是长阻塞）；超时**只凭 -2 判定、不得依赖 errno**（`s_net_errno` 是跨任务共享全局量，随时被别的任务覆盖） | | `net_close` | `NET_MSG_CLOSE` | `net_close_locked` | `close_socket` + 等 CLOSED（5ms 节奏 / ≤500ms）+ 排空 Socket/全局中断 | 0 / -1 | **先**了结本 fd 挂起 recv（排空/取消 + 必通知，关不得让等待者悬挂）；关后排空残留 DISCONNECT（Trap 14/17：否则下一连接被"刚建立就断开"秒断）；控制块整体清零 | -| `net_relisten` | `NET_MSG_RELISTEN` | `net_relisten_try` → `net_relisten_locked` | `set_proto_type` + `set_sour_port` + `open_socket` + `tcp_listen`（单次尝试；隔离期另有 `close` + `get_socket_status` + 排空） | 0 / -1 | 无条件芯片侧重建：芯片侧已在监听 → 首次 open 失败 → close 重建（短暂中断 ~1s）；失败**不阻塞**，登记 D10 重试；用途 = 代次变化后显式重建 / 判死后确定性重建；**-1 = "恢复中"**（重试轮询接管），不是永久失败 | +| `net_relisten` | `NET_MSG_RELISTEN` | `net_listener_try` → `net_relisten_locked` | `set_proto_type` + `set_sour_port` + `open_socket` + `tcp_listen`（单次尝试；沉降期另有 `close` + `get_socket_status` + 排空） | 0 / -1 | 无条件芯片侧重建：芯片侧已在监听 → 首次 open 失败 → close 重建（短暂中断 ~1s）；失败**不阻塞**，登记 D10 重试；用途 = 代次变化后显式重建 / 判死后确定性重建；**-1 = "恢复中"**（重试轮询接管），不是永久失败 | | `net_resync_listen` | `NET_MSG_RESYNC_LISTEN` | 分派内直接处理（**无芯片命令**） | 无 | 0 / -1 | D14 静默回收场景：芯片已自行把 Socket 回收回监听且**不发 DISCONNECT 中断** → 本层滞留 ESTABLISHED。只修 MCU 侧（state → LISTENING + 取消该 fd 挂起 recv）；**严禁**发芯片 close/重监听——会摧毁芯片侧健康监听器 → 连接永拒（run8 实证 170s 拒绝）。非 ESTABLISHED 时视为已一致，返回 0 | ### 4.4 直调 API（不经队列） | 函数 | 设计作用 | 主要调用 | 意图 / 注意 | |---|---|---|---| -| `net_socket(domain,type)` | 分配空闲控制块（`alloc_socket` 线性扫描 `in_use=0`）→ CREATED | `alloc_socket` + `net_relisten_clear` + `net_pending_clear` | 新 fd 不得继承上一次的待重试/挂起状态（复用描述符的经典坑）；domain 仅 `NET_AF_INET` | +| `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` 再读数据 | | `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 实证） | @@ -152,53 +157,77 @@ flowchart TB | 函数 | 设计作用 | 主要调用 | 意图 / 注意 | |---|---|---|---| | `net_pending_register` | 登记挂起（`net_recv_locked` 的"无数据 + 阻塞"路径） | 写 `s_net_pending[fd]` | 每 fd 至多一个：**覆盖会丢失前调用方通知 = 永久挂死**；执行任务自身（netTask）发起的等待直接拒绝（自等自通知 = 死锁，netTask 内须用 DONTWAIT） | -| `net_pending_tick` | 完成检查（`net_process_messages` 每轮调用，非阻塞） | ① `get_recv_len` + `read_recv_buf` ② 到点 ③ `get_recv_len` 排空 + `net_relisten_try` ④ `net_pending_complete` | 按 **①数据 ②到点 ③断连** 顺序检查（逐项对齐旧自旋语义）；CONNECTING/LISTENING 等状态**保持等待**（CONNECT→ESTABLISHED 是合法迁移，不做状态推断取消，防误杀正在建链的等待）；**看门狗**：到点后 1s 仍未了结 = 完成逻辑缺位 → 强制了结 + 错误日志 | +| `net_pending_tick` | 完成检查（`net_process_messages` 每轮调用，非阻塞） | ① `get_recv_len` + `read_recv_buf` ② 到点 ③ `get_recv_len` 排空 + `net_listener_try` ④ `net_pending_complete` | 按 **①数据 ②到点 ③断连** 顺序检查（逐项对齐旧自旋语义）；CONNECTING/LISTENING 等状态**保持等待**（CONNECT→ESTABLISHED 是合法迁移，不做状态推断取消，防误杀正在建链的等待）；**看门狗**：到点后 1s 仍未了结 = 完成逻辑缺位 → 强制了结 + 错误日志 | | `net_pending_complete` | 所有完成/取消路径的公共出口 | `xTaskNotify(caller, result)` + 清 active | 通知值 = 结果原值（>0 字节 / 0 EOF / 负错误码，与消息分派同一回传通道）；失败结果同步 `s_net_errno`（netTask 上下文一致性）；无在位挂起时静默返回（防重复通知） | | `net_pending_settle_close` | close 前**了结**本 fd 挂起 | `get_recv_len` + `read_recv_buf` + `net_pending_complete` | 关闭不得丢已到达数据（芯片缓冲 close 前可读）：有数据 → 按字节数通知；无数据 → 取消（CONNRESET）；先于 `ch395f_close_socket` 执行 | | `net_pending_cancel` / `cancel_all` | 显式取消（**必通知**） | `net_pending_complete` | 取消路径：陈旧 resync（单 fd）/ 网络重建（全部，`net_init` 开头，早于控制块清零）——"取消不通知 = 调用方永久挂死" | | `net_pending_clear` | 清除**不通知** | 清 `active` | 仅用于"新 fd 不得继承"（`net_socket`）与 close 后幂等清理（`net_close_locked`）——这两处前驱通知已由 settle 路径发出 | -### 4.6 D10 非阻塞重监听重试子系统（监听器自愈） +### 4.6 D10 非阻塞重监听重试子系统（`net_listener.c`） -**模型**：重开失败 = **登记待重试**（30ms 节奏 / 2s 时限），`net_relisten_retry_tick` 到点重试——任何时刻不阻塞任务。旧实现 `osDelay(500)` 忙等：netTask 冻结 500ms（全网停摆）、实测恢复 588ms、期间重连被拒（M3 台架）。 +**模型**：重开失败 = **登记待重试**（30ms 节奏 / 2s 时限），`net_listener_retry_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_relisten_try` | 尝试一次；失败登记重试（**不阻塞**） | `net_relisten_locked` → 成功 `net_relisten_done` / 失败置 `s_relisten_wait/next/dead` | 已在重试队列 → 直接返回 -1（**不重置重试时刻**）：否则 10ms 一次的 accept 轮询会不断把重试时刻往后推 → 永不重试（饥饿） | -| `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 23 隔离门**：带隔离标记的 socket（异常释放 TIMEOUT，如中止上传）→ 持续排空 RX 残渣 + 主动 close + 排空中断 + 等芯片回 CLOSED/TCP_CLOSED，隔离满 400ms 才放行；**800ms 上限强制放行**（必须 < 2s 重试时限，否则隔离耗尽重试预算 → `relisten give up` 监听被弃——2026-09-23 实测修正）；③ 成功只置 state=LISTENING，**不 memset**（fd 与 `auto_relisten` 保留——BSD 风格监听常驻） | -| `net_relisten_retry_tick` | 每轮到点重试 | `net_relisten_locked` → `net_relisten_done` / 顺延 / 放弃 | **同 fd 有在途挂起 recv 时跳过**（重开 Socket 会摧毁在途连接，L3 保险）；到 2s 时限 → 清状态 + `relisten give up` 错误日志（应用可见） | -| `net_relisten_done` | 标记完成 | `net_relisten_clear` +（探针构建）恢复计时样本 | 恢复时延 = 首次尝试 → 完成（L3 探针 `relisten` 段） | -| `net_relisten_clear` | 取消该 fd 的待重试 | 清 wait/next/dead + **沉降/隔离状态** | 触发点：`net_socket`（新 fd 不继承）/ `net_close_locked`（关闭即取消）；隔离状态必须一并清，否则残留标记会污染下一次复监听 | +| `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）调用。**只置事实，动作交 pump/try**；越界 fd 静默忽略 | +| `net_listener_try` | 尝试重建一次；失败登记重试（**不阻塞**） | `net_relisten_locked` → 成功 `net_relisten_done` / 失败置 `s_relisten_wait/next/dead` | 已在重试队列 → 直接返回 -1（**不重置重试时刻**）：否则 10ms 一次的 accept 轮询会不断把重试时刻往后推 → 永不重试（饥饿） | +| `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 23 沉降门**：带沉降标记的 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_retry_tick` | 每轮到点重试（D10） | `net_relisten_locked` → `net_relisten_done` / 顺延 / 放弃 | **同 fd 有在途挂起 recv 时跳过**（重开 Socket 会摧毁在途连接，L3 保险）；到 2s 时限 → 清状态 + `relisten give up` 错误日志（应用可见） | +| `net_relisten_done` | 标记完成 | `net_listener_clear` +（探针构建）恢复计时样本 | 恢复时延 = 首次尝试 → 完成（L3 探针 `relisten` 段） | +| `net_listener_clear` | 取消该 fd 的待重试/沉降 | 清 `wait/next/dead` + `settle_dead/settle_start` + `quarantine` | 触发点：`net_socket`（新 fd 不继承）/ `net_close_locked`（关闭即取消）；沉降/隔离状态必须一并清，否则残留标记会污染下一次复监听 | | `net_drain_chip_rx` | 排空芯片 RX 残留（256B 分块，≤16 次 = 4KB 上限） | `get_recv_len` + `read_recv_buf` | Trap 23：中止/异常断开时芯片 RX 缓冲残留上一条连接的数据（实测 ~2048B），不排空会被下一条连接当自己的数据读走（静默截断）；分块读避免新增静态缓冲（内存预算紧张） | -### 4.7 Trap 22 周期对账（丢中断自愈） +### 4.7 监听器 pump（N-32 P2 单一重建所有者，`net_listener.c`） + +`net_listener_pump()`（`net_process_messages` 每轮调用；周期 **100ms**）： + +**设计意图（设计文档 §4 不变量 II）**：其它所有位置**只置事实**（会话结束 / 状态迁移 / 事件派发），**不做重建动作**——于是"谁先看到 DISCONNECT 就谁重建"这类**多所有者竞争在结构上消失**。本函数是**本层唯一**的周期性重建决策者。 + +**覆盖三种情形**（认领门槛：在用 + `auto_relisten` + TCP + 已绑端口）： + +| # | 本层状态 / 芯片状态 | 动作 | 来源 | +|---|---|---|---| +| ① | 本层 LISTENING 而芯片监听**已失位** | 重建（`net_listener_try`） | 原对账③ | +| ② | 本层 CLOSED（会话已结束）而芯片**不在** LISTEN | 重建（`net_listener_try`） | 原对账④ | +| ③ | 本层 CLOSED 而芯片**正在** LISTEN | **只做状态重同步**（CLOSED→LISTENING），**不发任何芯片命令** | U11 缺口 | + +情形③的理由：芯片监听器是**健康**的，重下发 open+listen 会因 `USE` 错误走进关闭分支、把正听着的 Socket 关掉（U12 同源事故）；只把本层状态收回 LISTENING 即可（与 `net_resync_listen` 同一纪律）。 + +**去抖 + 冷却**（沿用原对账③④ 实测结论，取值不变）：同一失配需**连续 2 次**（≈200ms）才动手；同一 Socket 动手后**冷却 1s**（防抖成风暴，2026-09-23 实证）。**周期取 100ms**（对账 200ms 的 1/2）：比它快、又不至于像 50ms 那样频繁 close/open 与消费者收发撞车（2026-10-12 台架实测 50ms 会把 uiTask 最坏单轮从 172ms 推到 1034ms）。 + +> `session_dead` **不在此清零**（与 `net_relisten_locked` 同一契约：重建监听 ≠ 应用已确认会话结束；清零只发生在 `handle_connect_event`）。 + +### 4.8 Trap 22 周期对账（丢中断自愈，`net_socket.c`） `net_reconcile_tick()`（`net_process_messages` 每轮调用；周期 200ms）： **问题**：芯片在快速复连场景会**丢 CONNECT/DISCONNECT 中断**（或静默回收 Socket 不发中断）；丢事件后纯事件驱动无法自愈——典型：对端连接一直占着单连接监听的"后备"（芯片 TCP 仍 ESTABLISHED），后续 SYN 全被拒，而应用因未收到 DISCONNECT 仍以为有客户端（永不调 accept）。 -**机制**：对每个在用 Socket（ESTABLISHED / LISTENING）回读 `GET_SOCKET_STATUS`，判定三类失同步并修正： +**机制**：对每个在用 Socket（**仅 ESTABLISHED / LISTENING**）回读 `GET_SOCKET_STATUS`，判定**两类**失同步并修正： | # | 失同步 | 动作 | 复用的实现 | |---|---|---|---| -| ① | 本层 ESTABLISHED 而芯片已无连接（sock/tcp = CLOSED） | 按断开处理 → CLOSED + 回调（应用读到 EOF 后自动重监听） | `handle_disconnect_event`（内置陈旧事件甄别） | +| ① | 本层 ESTABLISHED 而芯片已无连接（sock/tcp = CLOSED） | 按断开处理 → CLOSED + 回调（应用读到 EOF 后由 pump 重建监听） | `handle_disconnect_event`（内置陈旧事件甄别） | | ② | 本层 LISTENING 而芯片已完成握手（tcp = ESTABLISHED） | 补做 standalone accept 簿记 | `handle_connect_event` | -| ③ | 本层 LISTENING 而芯片监听已消失（异常关闭） | 重建监听 | `net_relisten_try`（D10 非阻塞重试） | + +> ⚠ **N-32 P2（2026-10-12）**：原③（本层 LISTENING 丢监听）与④（孤儿监听）已**整体移交 `net_listener_pump`**——本函数内**不再有任何重建动作**（单一所有者），认领门槛相应收窄为 ESTABLISHED/LISTENING（原为驱动④而多认领"CLOSED + auto_relisten + 已绑端口"）。 **去抖 + 冷却（缺一不可）**：单次状态读可能落在"刚 open/listen 尚未生效"的瞬态——**2026-09-23 实测**：无去抖的 accept 路径自愈把监听反复重建直至 `relisten give up`（三服务口全死、89 行 ERROR）。故：同一失配需**连续 2 次**（≈400ms）才动手；同一 Socket 动手后**冷却 1s**。开销：每 200ms 每在用 Socket 一条状态命令，可忽略。 -### 4.8 事件处理器（netTask 上下文；由 `net_poll` 驱动，对账 tick 可再入） +### 4.9 事件处理器（netTask 上下文；由 `net_poll` 驱动，对账 tick 可再入） | 函数 | 设计作用 | 主要调用 | 意图 / 注意 | |---|---|---|---| -| `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 的大端相反）——解析别抄反 | -| `handle_disconnect_event` | 状态机迁移 + 陈旧事件甄别 + 监听丢失重建 | `ch395f_get_socket_status` →（LISTENING：芯片已不可监听 → `net_relisten_try`，仍在监听 → 判陈旧丢弃）/（ESTABLISHED：芯片仍 ESTABLISHED → 判陈旧丢弃） | ① **陈旧 DISCONNECT 甄别**（D20）：同一 fd"关闭→重监听→再连接"循环复用，上一条连接的 FIN/ACK 可能在 fd 已复用时才上报 → 不甄别则新连接秒断（实测：FTP 同会话第二个数据连接必 425）；② LISTENING 分支**已不可监听即重建**（Trap 22 修复的一半）；③ 置 CLOSED 后**不立即关芯片 Socket**——留给 `net_recv_locked` 排空剩余数据（FIN 可能先于数据到达） | +| `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` →（LISTENING：芯片已不可监听 → **`net_listener_settle(GRACEFUL)`**，仍在监听 → 判陈旧丢弃）/（ESTABLISHED：芯片仍 ESTABLISHED → 判陈旧丢弃） | ① **陈旧 DISCONNECT 甄别**（D20）：同一 fd"关闭→重监听→再连接"循环复用，上一条连接的 FIN/ACK 可能在 fd 已复用时才上报 → 不甄别则新连接秒断（实测：FTP 同会话第二个数据连接必 425）；② 正常释放（FIN）→ **GRACEFUL 沉降 100ms**（只置事实，重建由 `net_listener_pump` 做，N-32 P1/P2）；③ 置 CLOSED 后**不立即关芯片 Socket**——留给 `net_recv_locked` 排空剩余数据（FIN 可能先于数据到达） | | `handle_recv_event` | 置 `readable` + 回调；**不读 recv_len** | `fire_event` | 不读长度是为了避免与 `net_recv_locked` 的 `ch395f_get_recv_len` 竞争（Trap 13：分批读会归零）；`readable` 供 `net_select` 无 SPI 访问判读 | | `handle_send_event` | 发送缓冲已空：触发回调（`send_ready` 由 SENBUF_FREE 前置位） | `fire_event` | — | -| `handle_timeout_event` | CONNECTING → CREATED（连接超时）；**ESTABLISHED → 置重监听隔离 + CLOSED**（Trap 23）；LISTENING → 仅记日志 | （隔离）写 `s_relisten_quarantine[fd]` + `fire_event` | TIMEOUT = 异常释放（如客户端中止上传）：对端在途数据随后落进 RX 缓冲 → 必须隔离后才许复监听；正常 FIN 释放走 disconnect 路径，**不走**隔离（零改动） | +| `handle_timeout_event` | CONNECTING → CREATED（连接超时）；**ESTABLISHED → 登记隔离 + CLOSED**（Trap 23）；LISTENING → 仅记日志 | **`net_listener_settle(fd, NET_LISTENER_SETTLE_QUARANTINE)`** + `fire_event` | TIMEOUT = 异常释放（如客户端中止上传）：对端在途数据随后落进 RX 缓冲 → 必须隔离（400ms）后才许复监听；正常 FIN 释放走 disconnect 路径（GRACEFUL 100ms），**不走**隔离 | | `fire_event` | 调用已注册回调 | `p_sock->event_cb` | **回调上下文 = netTask**：回调内不得阻塞、不得发网络操作（会自等死锁） | -### 4.9 工具函数 +### 4.10 工具函数 | 函数 | 设计作用 | |---|---| @@ -257,7 +286,7 @@ sequenceDiagram Note over N: close / 网络重建 / 陈旧 resync → 显式 settle/cancel（必通知） ``` -### 5.3 断连 → 自动重监听（含 Trap 23 隔离） +### 5.3 断连 → 自动重监听（含 Trap 23 沉降） ```mermaid sequenceDiagram @@ -268,19 +297,19 @@ sequenceDiagram Note over C: 客户端 FIN（正常）或 RST/无响应（异常） N->>C: net_poll 读 SINT alt DISCONNECT（正常） - N->>N: handle_disconnect_event：回读甄别 → CLOSED + 回调 + N->>N: handle_disconnect_event：回读甄别 → CLOSED + 回调
+ net_listener_settle(GRACEFUL 100ms) else TIMEOUT（异常，如中止上传） - N->>N: handle_timeout_event：置重监听隔离 + CLOSED + N->>N: handle_timeout_event：net_listener_settle(QUARANTINE 400ms) + CLOSED end - A->>N: 下一次 net_recv（无数据）/ net_accept - N->>C: net_relisten_try → net_relisten_locked - opt 隔离期内（Trap 23） + Note over N: 只置事实 —— 重建统一由 net_listener_pump（100ms）决定 + N->>C: net_listener_try → net_relisten_locked + opt 沉降期内（Trap 23） N->>C: 排空 RX 残渣（256B 分块）+ close + 排空中断 C-->>N: 未到 CLOSED/TCP_CLOSED → 返回（30ms 后重试轮询复检） end N->>C: set_proto_type + set_sour_port + open_socket + tcp_listen alt open 失败（Trap 09 沉降） - N->>N: 登记重试（30ms 节奏 / 2s 时限）→ 每轮到点重试 + N->>N: 登记重试（30ms 节奏 / 2s 时限）→ net_listener_retry_tick 到点重试 else 成功 N->>N: state = LISTENING（auto_relisten 保留） N-->>A: xTaskNotify（accept 返回 / recv 返回 0） @@ -288,7 +317,7 @@ sequenceDiagram Note over N: 2s 超限时 → 清状态 + "relisten give up"（错误日志，应用可感知） ``` -### 5.4 丢中断自愈（Trap 22 对账） +### 5.4 丢中断自愈（Trap 22 对账 + N-32 pump） ```mermaid sequenceDiagram @@ -305,7 +334,7 @@ sequenceDiagram Note over N: 连续 2 次失配（去抖 ≈400ms）且不在冷却期 → 动手 N->>N: handle_connect_event：补 accept 簿记 → ESTABLISHED N-->>A: 下一次 net_accept 返回客户端（连接不再"吞掉"） - Note over N: 另两类：① 本层 ESTABLISHED 而芯片已断 → handle_disconnect_event
③ 本层 LISTENING 而芯片监听消失 → net_relisten_try + Note over N: 另两类：① 本层 ESTABLISHED 而芯片已断 → handle_disconnect_event
③④ 本层 LISTENING 丢监听 / CLOSED 孤儿 → net_listener_pump（100ms，唯一重建入口） ``` ### 5.5 网络重建（IP 变更免重启） @@ -339,10 +368,11 @@ sequenceDiagram | 8 | **close 前先了结挂起 recv + 排空残留 DISCONNECT** | Trap 14/17/19：锁存的陈旧 DISCONNECT 秒断下一连接 | | 9 | **两段式等待防丢失通知**：零等待拾取 + 阻塞；清除掩码全 1；以 pdTRUE 判定 | run3~11：丢失通知 → 挂死 / 结果错位；0 结果误判"无通知" → 永久挂死 | | 10 | **网络重建先取消并通知全部挂起，再复位芯片** | 取消不通知 = 调用方永久挂死 | +| 11 | **监听重建只有一个所有者**（`net_listener_pump`）；其它位置**只置事实**（置 CLOSED / 登记沉降），不做重建动作 | N-32 P2 / B10：多所有者导致"谁先看到 DISCONNECT 就谁重建"的竞争与重建风暴 | --- -## 7. ch395f 驱动接口使用图（net_socket.c → 芯片命令） +## 7. ch395f 驱动接口使用图（`net_socket.c` / `net_listener.c` → 芯片命令） | 芯片命令 | 使用处 | 说明 | |---|---|---| @@ -355,13 +385,13 @@ sequenceDiagram | `ch395f_set_send_buf` / `ch395f_set_recv_buf` | `net_init`（8 Socket 布局）；`net_bind`(UDP)（Socket 4~7 兜底） | 每 Socket 收 4 块 + 发 2 块 | | `ch395f_get_glob_int_status_all` | `net_poll`；`net_listen_locked` / `net_connect_locked` / `net_close_locked` / `net_relisten_locked`（清残留） | **读 = 清**（中断清除机制） | | `ch395f_get_sock_int_status` | `net_poll`（逐 Socket SINT）；各 open 路径后清残留；事件处理器清 TIMEOUT | **读 = 清** | -| `ch395f_open_socket` / `ch395f_close_socket` | `net_bind`(UDP)、`net_listen_locked`、`net_connect_locked`、`net_close_locked`、`net_relisten_locked`（含隔离期主动 close） | Trap 09：close 后需沉降才能重开 | +| `ch395f_open_socket` / `ch395f_close_socket` | `net_bind`(UDP)、`net_listen_locked`、`net_connect_locked`、`net_close_locked`、`net_relisten_locked`（含沉降期主动 close） | Trap 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_sendto` | 单次 ≤1KB（硬件 FIFO 上限，Trap 20） | | `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_recv_event` **故意不读**（防竞争，Trap 13） | -| `ch395f_get_socket_status` | `net_reconcile_tick`、`handle_disconnect_event`（两处甄别）、`net_close_locked`（等 CLOSED）、`net_relisten_locked`（隔离门）、`net_connect_locked`（诊断回读） | 输出 **2 字节**（[0]=Socket 状态 [1]=TCP 状态），缓冲必须给 2 字节 | -| `ch395f_get_remot_ipp` | `handle_connect_event`、`net_connect_locked`（诊断） | **小端**输出（与 set_des_ip 相反） | +| `ch395f_get_socket_status` | `net_listener_pump`、`net_reconcile_tick`、`handle_disconnect_event`（两处甄别）、`net_close_locked`（等 CLOSED）、`net_relisten_locked`（沉降门）、`net_connect_locked`（诊断回读） | 输出 **2 字节**（[0]=Socket 状态 [1]=TCP 状态），缓冲必须给 2 字节 | +| `ch395f_get_remot_ipp` | `handle_connect_event`、`net_reconcile_tick`（幽灵甄别）、`net_connect_locked`（诊断） | **小端**输出（与 set_des_ip 相反） | | `ch395f_set_keepalive_enable` | `handle_connect_event`（client 连接成功时） | — | --- @@ -370,19 +400,20 @@ sequenceDiagram | 想改什么 | 先看哪些函数 | |---|---| -| 监听恢复策略（节奏/时限/隔离） | `net_relisten_try` / `net_relisten_locked` / `net_relisten_retry_tick`；常量 `NET_RELISTEN_*_MS`（`net_socket.c` 内） | +| 监听恢复策略（节奏/时限/沉降） | `net_listener_try` / `net_relisten_locked` / `net_listener_retry_tick` / `net_listener_pump`；常量 `NET_RELISTEN_*_MS` / `NET_LISTENER_PUMP_PERIOD_MS` / `NET_LISTENER_STABLE_N` / `NET_LISTENER_COOLDOWN_MS`（`net_listener.c` 内） | | 阻塞接收等待语义 | `net_pending_register` / `net_pending_tick` / `net_pending_complete`；常量 `NET_PENDING_WATCHDOG_MS` | -| 丢中断自愈策略 | `net_reconcile_tick`（周期/去抖/冷却三常量）+ `handle_disconnect_event` LISTENING 分支 | +| 丢中断自愈策略 | `net_reconcile_tick`（周期/去抖/冷却三常量，①②）+ `net_listener_pump`（③④，唯一重建入口）+ `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`（**勿加回传字段**） | -| 超时参数（收发/重试/对账） | `net_config.h`（收发/重传/KeepAlive）；`net_socket.c` 内 `NET_RELISTEN_*` / `NET_RECONCILE_*` / `NET_PENDING_WATCHDOG_MS` | +| 超时参数（收发/重试/对账） | `net_config.h`（收发/重传/KeepAlive）；`net_listener.c` 内 `NET_RELISTEN_*` / `NET_LISTENER_*`；`net_socket.c` 内 `NET_RECONCILE_*` / `NET_PENDING_WATCHDOG_MS` | --- ## 9. 相关文档 - `docs/网络/BSD_Socket_API_使用指南.md` —— 公开 API 语义、示例、常见问题（本文的上半部） +- `docs/子系统设计/网络Socket监听生命周期设计说明.md` —— **监听生命周期权威设计**（N-32：边沿→电平、单一所有者 pump、`net_listener.c` 模块化边界 §10） - `docs/问题记录/CH395F_Trap_Records.md` —— Trap 01~23 机制细节（本文引用处） - `docs/网络/Net层阻塞模型架构设计.md` —— 阻塞等待模型的现状架构设计（pending 请求模型 / 五路完成语义） - `docs/问题记录/错误码传播审计.md` —— E-02 头阻塞与错误码回传全审计 diff --git a/docs/网络/Net层阻塞模型架构设计.md b/docs/网络/Net层阻塞模型架构设计.md index e181ed8a..fd301095 100644 --- a/docs/网络/Net层阻塞模型架构设计.md +++ b/docs/网络/Net层阻塞模型架构设计.md @@ -43,7 +43,7 @@ netTask 是**全部 socket 操作的唯一执行者**——CH395F 的 SPI 总线 | 区域 | 内容 | |---|---| | **左栏 · 调用方任务** | `net_recv` → 判"数据已在？" → **是**走快速路径；**否**（`timeout > 0`）登记 pending 后在自己上下文睡任务通知 | -| **中栏 · netTask 主循环** | ~1ms 节拍：`net_poll`（刷新 readable）→ `net_pending_tick`（了结挂起）→ `net_relisten_retry_tick` → 排空消息队列 | +| **中栏 · netTask 主循环** | ~1ms 节拍：`net_poll`（刷新 readable）→ 4 个非阻塞 tick（`net_listener_retry_tick` D10 → `net_pending_tick` 了结挂起 → `net_reconcile_tick` Trap 22 对账 → `net_listener_pump` 监听重建唯一入口）→ 排空消息队列 | | **下带 · 五路判定** | 每轮对每个挂起 fd 按序判定：数据到达 / 到点 / EOF / 同 fd 后续操作 / 网络重建；含 1s 看门狗 | | **回环** | 判定完成经 `xTaskNotify` 唤醒调用方（结果 = 字节数 / 负错误码） | @@ -75,7 +75,7 @@ netTask 是**全部 socket 操作的唯一执行者**——CH395F 的 SPI 总线 `net_close_locked` 对 `net_sock_t` 做**整块 memset**。若挂起状态置于其中，`close` 会 静默抹掉 pending——调用方永远等不到通知，**永久挂死**。独立表把"跨时间状态"与 -socket 生命周期解耦，与 `net_relisten_retry_tick` 的重试表同构。 +socket 生命周期解耦，与 `net_listener_retry_tick` 的重试表同构。 ### 3.2 登记守卫（两条硬防线） @@ -144,7 +144,7 @@ CONNECT → ESTABLISHED 是合法迁移，推断取消会误杀正在建链的 | **ACCEPT 路径未覆盖** | accept 仍用轮询计时 | 需 pending 化（二期） | | **超时精度** | 随主循环节拍（~1ms），被长操作占用时顺延 | 一期文档化、不修；二期 SEND 化后该顺延面**收窄** | | **看门狗未接自检** | 强结算 + `DBG_ERROR`，未写 selftest | 二期补齐 | -| **模拟器不可建模** | `net_socket_sim.c` 单线程 Winsock 无法复现挂起模型 | 该路径在模拟器上零覆盖，只能硬件验证 | +| **模拟器不可建模** | `net_socket_sim.c` 单线程 Winsock 无法复现挂起模型 | 该路径在模拟器上零覆盖，只能硬件验证；**监听生命周期 `net_listener.c` 亦为真机专属**（内部头只被 `net_socket.c` include，CMakeLists 不编译） | **二期扩展设计**（ACCEPT / SEND 的挂起化、门禁清单、改动量）见 `docs/任务规划/基线与待确认.md` §2.1。 @@ -218,3 +218,4 @@ CONNECT → ESTABLISHED 是合法迁移，推断取消会误杀正在建链的 | 2026-09-26 | 调研文档退役，客观实施记录独立成文 | | 2026-09-29 | **改写为架构设计文档**：以"当前如何设计/为何如此"为主线重组织；历史演进与门禁实测降级为附录 A；迁入 `docs/网络/` | | 2026-10-03 | **网络重建失败恢复（P1-8 / A2）落地并真机验证**：首启组网失败 = 自检 `net init fail` + 30s 周期重试（1s 分片喂心跳，**不自驻留**）；重建（reconfig）失败 = 自检 `net reinit fail` + 30s 延迟重触发事件位（tick 回绕安全），成功即清零；PHY 链路超时仍走既有 `comms fault` 降级（语义不变）。真机：开机 `net init: OK` / `PHY: 100M FULL` / `netTask: started`，无 `init FAIL` / `retry in 30s` 误触发（**正常路径零回归**）；芯片级 `net_init` 失败分支 / 拔线负向场景待专项窗口（`待处理内容.md` N-16）。**执行判据见 `测试说明/实机测试实施指南.md` §7.1 / §10** | +| 2026-10-12 | **N-32 监听生命周期模块化 + 单一所有者**：监听生命周期抽为 `net_listener.c`（`net_listener_try` / `net_listener_clear` / `net_listener_retry_tick` / `net_listener_pump` / `net_listener_settle`，真机专属、模拟器不编译）；**重建动作收敛到唯一所有者 `net_listener_pump`**（100ms，去抖+冷却），对账 `net_reconcile_tick` 只剩①②；主循环自愈 tick 由 3 个增至 **4 个**。详见 `docs/子系统设计/网络Socket监听生命周期设计说明.md` §10 |