docs(net): 修正 FUN_PARA bit3 口径注释 + 补必要性论证

N-32 / B10 残余 P0 阶段:零风险的纯注释与文档口径修正。

net_socket.c:3627 / :3641 两处函数头注释写"CH395F 在 DISCONNECT
后自动关闭 Socket(FUN_PARA 默认)",与本仓 net_init 实际下发的
0x08(bit3 SOCKET_CLOSE=1,芯片不关、不清缓冲)相反。这类注释
会误导维护者跳过显式 close,是 U12 的观念源头。

新增设计文档 §2.4 回答"bit3=1 必要性大吗、如何安全处理":
- bit3=0 时芯片当场清缓冲,FTP「发完即 FIN」尾部数据必被硬件
  擦除且不可补救;bit3=0 也挡不住丢中断(Trap 22),孤儿态
  照样有。故保持 0x08,改在软件层收口(结论并入 D4)。
- 安全处理 = 把契约落到不变量 I(session_dead 电平化)与
  不变量 II(单一所有者 pump)+ 补 U12 的 close 对称。

验证:@build 0 错 0 警(Code=197084 与改前一致,纯注释);
pre-commit 全绿(cppcheck / doc-links / C 规范)。
This commit is contained in:
2026-10-12 12:36:18 +08:00
parent e4134a4723
commit 0d084e6ec9
2 changed files with 61 additions and 4 deletions
+6 -2
View File
@@ -3624,7 +3624,11 @@ static void handle_connect_event(net_sock_t *p_sock) {
* 出口参数:无
* 返回值:无
* 限定条件:net_poll() 检测到 DISCONNECT 中断后调用;netTask 上下文
* 函数说明:1. CH395F 在 DISCONNECT 后自动关闭 Socket(FUN_PARA 默认),需重新 OPEN + LISTEN
* 函数说明:1. ⚠ FUN_PARA bit3=1(本仓 net_init 置 0x08):DISCONNECT/TIM_OUT 后芯片
* **不**关 Socket、**不清**缓冲(停 0x05/0x00)——残留数据须由本层读出后,再由
* 本层 ch395f_close_socket 关闭;芯片不代劳(§5.52② / §5.23)。旧注释写"CH395F 在
* DISCONNECT 后自动关闭 Socket(FUN_PARA 默认)"与实际 0x08 相反,2026-10-12 修正:
* 它会误导维护者跳过显式 close(= U12 的成因之一)。之后需重新 OPEN + LISTEN
* 2. 单连接:置 CLOSED,交由 net_recv_locked 排空剩余数据后再关
* 3. 触发 NET_EVENT_DISCONNECTED 回调
*/
@@ -3638,7 +3642,7 @@ static void handle_disconnect_event(net_sock_t *p_sock) {
/* 监听态:DISCONNECT 落在监听器上 */
if (p_sock->state == NET_SOCK_STATE_LISTENING) {
/* Trap 22 / N-6:监听态收到 DISCONNECT——芯片断开后自动关闭该 Socket(FUN_PARA 默认),不重开则监听永久死亡(此后所有 SYN 被拒);
/* Trap 22 / N-6:监听态收到 DISCONNECT——bit3=1(0x08)下芯片**不**关该 Socket(停 0x05/0x00,芯片 TCP 侧已 CLOSED);不重开则此后所有 SYN 全被拒 = 监听永久死亡;
* 触发 = 断连后 <~1s 快速复连时 CONNECT 中断未上报(控制块滞留 LISTENING)后该连接断开(2026-09-23 生产固件复现);
* → 回读芯片状态:监听已失位即重建(D10 非阻塞重试),仍在监听判陈旧丢弃 */
/* 回读缓冲(芯片状态 2 字节) */