refactor(NET): 源码注释去阶段化 + 网络两份文档重构 + 不稳根因图更新

- 源码注释:删去自愈收敛阶段
1/1.5/3等 scaffolding 称谓,改为语义引用
  (E-02 收口 / F-NET-2/3/4 / docs/网络/网络自愈架构设计.md §5.2 E13);
  涉及 net_socket/.h、net_events、net_listener、net_pending、net_types、
  net_config、ch395f、time_sync、iec104_serv、ui_net_sink、lftpd、
  simulator/sim/net_socket_sim、board/host 测试与探针
- 文档重构:网络自愈架构设计.md 与 Net层阻塞模型架构设计.md 改为现状口径
  (删历史节与阶段叙事),NET/README.md、docs/README.md 同步
- 工具与配图:gen_net_instability_svg.py 与
  docs/images/网络不稳根因总览.svg 随源码口径一并更新
- 门禁:@build 0 错误 0 警告
This commit is contained in:
2026-10-14 22:05:53 +08:00
parent cea2b51efb
commit d770e36c7c
30 changed files with 574 additions and 682 deletions
+10 -10
View File
@@ -11,7 +11,7 @@
* 设计要点:
* 1. fd 采用与 MCU 端一致的"控制块索引"模型(0 ~ NET_MAX_SOCKETS-1)
* 2. Winsock 句柄创建即置非阻塞(ioctlsocket FIONBIO),阻塞语义在包装层
* 按控制块 blocking 属性模拟(自愈收敛阶段 1.5:模式归使用者——blocking=1
* 按控制块 blocking 属性模拟(模式归使用者——blocking=1
* 时 recv 轮询等待(Sleep(1)),=0 或 NET_MSG_DONTWAIT 立即 WOULDBLOCK),
* 使 net_recv / net_recv_nb / net_recv_to / net_accept 的语义与 MCU 端一致
* 3. 代次号在模拟器上恒为 0(无"网络重建"概念),net_get_generation 恒返回 0
@@ -215,7 +215,7 @@ int net_socket(int domain, int type) {
s_socks[idx].type = (uint8_t)type;
s_socks[idx].state = NET_SOCK_STATE_CREATED;
s_socks[idx].ch395_sock = (uint8_t)idx;
/* 自愈收敛阶段 1.5:阻塞模式默认 = 阻塞(与 MCU 端 net_socket 一致;
/* 阻塞模式默认 = 阻塞(与 MCU 端 net_socket 一致;
* Winsock 句柄仍恒非阻塞,阻塞语义由包装层按本属性模拟,见文件头要点 2) */
s_socks[idx].blocking = 1;
s_ws[idx] = ws;
@@ -334,7 +334,7 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen) {
s_socks[nidx].type = (uint8_t)NET_SOCK_STREAM;
s_socks[nidx].state = NET_SOCK_STATE_ESTABLISHED;
s_socks[nidx].ch395_sock = (uint8_t)nidx;
/* 自愈收敛阶段 1.5:accept 出的新连接同样默认阻塞模式(与 MCU 端一致) */
/* accept 出的新连接同样默认阻塞模式(与 MCU 端一致) */
s_socks[nidx].blocking = 1;
s_ws[nidx] = cws;
@@ -342,7 +342,7 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen) {
return nidx;
}
/* 自愈收敛阶段1(F-NET-4):net_can_accept 双端退役——监听 accept 门控统一用
/* F-NET-4:net_can_accept 双端退役——监听 accept 门控统一用
* net_listener_armed()(本文件同名实现保留恒 1 语义),recv 门控 net_can_read() 保留。 */
/*
@@ -517,7 +517,7 @@ static int recv_wait(int sockfd, void *buf, int len, int has_budget, unsigned lo
}
/*
* 函数功能:接收数据(TCP,**默认无限阻塞**——自愈收敛阶段 1.5 与 MCU 端语义对齐)
* 函数功能:接收数据(TCP,**默认无限阻塞**——与 MCU 端语义对齐)
* 入口参数:sockfd - socket 描述符
* buf - 接收缓冲区
* len - 缓冲区大小
@@ -542,12 +542,12 @@ int net_recv(int sockfd, void *buf, int len, int flags) {
if ((flags & NET_MSG_DONTWAIT) || s_socks[sockfd].blocking == 0U) {
return recv_once(sockfd, buf, len);
}
/* 阻塞:无限等待(无默认预算,自愈收敛阶段 1.5) */
/* 阻塞:无限等待(无默认预算) */
return recv_wait(sockfd, buf, len, 0, 0ULL);
}
/*
* 函数功能:接收数据(非阻塞具名入口,与 MCU 端同名 API 对齐——自愈收敛阶段 1.5)
* 函数功能:接收数据(非阻塞具名入口,与 MCU 端同名 API 对齐)
* 入口参数:sockfd / buf / len - 同 net_recv
* 返回值:>0 字节数;0 = 对端关闭;-1 = 无数据(WOULDBLOCK) 或错误
* 限定条件:socket 已建立
@@ -566,7 +566,7 @@ int net_recv_nb(int sockfd, void *buf, int len) {
}
/*
* 函数功能:接收数据(**显式预算**便捷入口,与 MCU 端同名 API 对齐——自愈收敛阶段 1.5)
* 函数功能:接收数据(**显式预算**便捷入口,与 MCU 端同名 API 对齐)
* 入口参数:sockfd / buf / len - 同 net_recv
* timeout_ms - 本次等待预算(ms,必须 >0;0 = 无限等待语义
* 属 net_recv 的职责,此处拒 INVAL,与 MCU 端一致)
@@ -709,7 +709,7 @@ int net_close(int sockfd) {
}
/*
* 函数功能:主动拆掉当前 TCP 会话、保留监听(与 MCU 端同名 API——自愈收敛阶段 3,E-02 收口)
* 函数功能:主动拆掉当前 TCP 会话、保留监听(与 MCU 端同名 API——E-02 收口)
* 入口参数:sockfd - socket 描述符
* 出口参数:无
* 返回值:0 成功(含幂等:无活动会话),-1 失败
@@ -766,7 +766,7 @@ int net_set_event_cb(int sockfd, net_event_cb_t cb, void *arg) {
}
/*
* 函数功能:设置 Socket 阻塞/非阻塞**模式属性**(与 MCU 端同名 API 对齐——自愈收敛阶段 1.5)
* 函数功能:设置 Socket 阻塞/非阻塞**模式属性**(与 MCU 端同名 API 对齐)
* 入口参数:sockfd - socket 描述符
* on - 1 = 阻塞(net_socket/net_accept 默认);0 = 非阻塞
* 返回值:0 成功;-1 失败(描述符无效/未占用)