diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b95c6d59..c67ffd5d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -196,7 +196,8 @@ repos: docs/芯片手册/ ) # mermaid 图:围栏内确定性语法预检(2026-10-30 加;当日口径 51 → 52、提交期实跑 48 → 49, - # 2026-11-17/18 摘 `iec104-unit-test` + 加 `iec104-tcp` 后收敛为 52 / 47 / 48)。 + # 2026-11-17/18 摘 `iec104-unit-test` + 加 `iec104-tcp` 后为 52 / 47 / 48, + # 同日再加 `net-handle` 后当前为 **53 / 48 / 49**)。 # 为什么要有:屏板链路设计.md §1 的 flowchart 里 `-.|"文字"|`(`-.` 直接跟管道,不是任何合法 # 箭头 token)让 mermaid 渲染 `Syntax error in text`——该图 2026-10-29 落库、期间 doc-links 等 # 全绿:文档门禁查链接与章节,**从不查围栏内图表语法**,这是它们的共同盲区。 @@ -514,10 +515,11 @@ repos: # 新板端网络后端的等价验证是 test/host/iec104_netmcu/(fake net 层 + 自定义 # runner,不是 run_unit_test.py 形态,硬套进这里只会得到一个跑不起来的钩子), # 由 scripts/ci_local.py 与人工运行,不进提交门禁。 - # ⚠ 计数口径(2026-11-18 两笔合并后实测):本条摘除使 YAML 解析条目 52 → 51、 + # ⚠ 计数口径(2026-11-18 三笔合并后实测):本条摘除使 YAML 解析条目 52 → 51、 # 提交期实跑 49 → 48;同日新增的 `iec104-tcp`(下面 12b 条,manual 阶段)再把 - # 声明数加回 **52**、manual 根数 3 → **4**、manual 阶段枚举行数 50 → **51**。 - # ⇒ 终态:**声明 52 / pre-commit 阶段 47 / 一次 git commit 实跑 48 / manual 4**。 + # 声明数加回 52、manual 根数 3 → 4、manual 阶段枚举行数 50 → 51;同日再加 + # `net-handle`(下面 13 条,pre-commit 阶段)。 + # ⇒ 当前:**声明 53 / pre-commit 阶段 48 / 一次 git commit 实跑 49 / manual 4**。 # 须与 AGENTS.md 的「共 N 个钩子」、docs/门禁说明/README.md §2 标题、 # docs/代码规范/pre-commit使用说明.md 三处同批改(勿在别处另立字面量)。 @@ -879,7 +881,30 @@ repos: language: system types: [c] - # ─── SKILL.md 体积与 reference/ 指针门禁(第 52 条,2026-10-29 加)───────────────────── + # ─── 网络句柄失效值契约门禁(第 52 条,2026-11-18 加,声明数 52 → 53)────────────────── + # 为什么要有:板端 104 连不上的真因不是"漏了一个 -1",而是"未打开的 fd"由 C 零初始化 + # 成 0,而本项目 net 层 fd 域是 0~7(0 是**合法**描述符)——失效值恰好落在合法值域, + # 再被 `fd >= 0` 这类数值形态判据当成"持有 fd";网络代际切换后它去关 fd 0,把别的 + # 服务的监听槽(FTP)关掉,最终 104 建链拿到 FTP 的 220 banner。修好一处只是治标, + # 本闸把契约(Drivers/BSP/NET/net_fd.h 的 NET_FD_INVALID)搬到提交期机械判定: + # R1 fd 形标识符与整数字面量比较;R2 文件作用域 static fd 无初始化/`{0}`/缺 fd 成员; + # R3 memset 含 fd 成员的结构体后 5 行内不回填;R4 `if (fd)` / `if (!fd)`; + # R5 契约头文件存在且被 net_socket.h include。 + # 白名单不是漏判:`Drivers/BSP/NET/` 是契约的层内实现者(C4 允许 `0 <= fd < 上界` + # 区间校验,fd 槽数组清零即"释放",套 R1~R4 会把正经实现判红);`test/host/` 的假 + # 对象按 C7 从 0 基分配,断言语域不同。两者的契约合规性由 R5 + 独立验收复核。 + # 自证:`--selftest` 42 条断言(每个 R 都有"故意写错必须抓到"与"正确写法不误报", + # 含注释里的反面教材不误报、白名单不误伤、整数组清零不误报)。 + # 全树扫不只看变更文件(files 只当触发):R5 要判契约文件本身,且"当前树 0 违规" + # 才是可复核的口径。判据、盲区与豁免写法 → docs/门禁说明/net-handle.md。 + - id: net-handle + name: "网络 fd 失效值契约(NET_FD_INVALID:数值判据 / 零初始化 / memset 后不回填)" + entry: scripts/gate_python.py scripts/check_net_handle.py + language: system + files: ^(.*\.(c|h)|scripts/check_net_handle\.py|\.pre-commit-config\.yaml)$ + pass_filenames: false + + # ─── SKILL.md 体积与 reference/ 指针门禁(第 53 条,2026-10-29 加)───────────────────── # 为什么要有:dsh-mnemon 插件对技能正文有 65536 字节的**写侧**硬上限(validateSkillContent), # 但**加载侧不查**——超限的 SKILL.md 照常可读、照常进技能目录,只有一件事会坏:自进化每次 # 「生成草案」都在落盘那一步被拒,那一行永久卡在「生成中」、界面只剩转圈、连「忽略」都不出现 diff --git a/AGENTS.md b/AGENTS.md index 26d3481c..55df0822 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,7 +54,7 @@ ## 提交门禁(pre-commit) -共 **52 个钩子**(提交期实跑 47 根 + `gitlint` = 一次 commit 48 根,4 根慢钩子由远端 CI 与 `ci_local.py` 承担)。任一失败即拦截;提交信息标题 ≤100 字符、正文每行 ≤80,长说明用 `git commit -F <文件>`。**每种门禁一篇详解 → `docs/门禁说明/README.md`**;通用机制 → `docs/代码规范/pre-commit使用说明.md`;CI 只跑静态门禁 + 主机侧单测、**不跑 `/keil-build`** → [`docs/CI/README.md`](docs/CI/README.md)。 +共 **53 个钩子**(提交期实跑 48 根 + `gitlint` = 一次 commit 49 根,4 根慢钩子由远端 CI 与 `ci_local.py` 承担)。任一失败即拦截;提交信息标题 ≤100 字符、正文每行 ≤80,长说明用 `git commit -F <文件>`。**每种门禁一篇详解 → `docs/门禁说明/README.md`**;通用机制 → `docs/代码规范/pre-commit使用说明.md`;CI 只跑静态门禁 + 主机侧单测、**不跑 `/keil-build`** → [`docs/CI/README.md`](docs/CI/README.md)。 ## 平台约束 diff --git a/App/protocol/iec104/iec104_net_mcu.c b/App/protocol/iec104/iec104_net_mcu.c index 3dd685b2..a33d237c 100644 --- a/App/protocol/iec104/iec104_net_mcu.c +++ b/App/protocol/iec104/iec104_net_mcu.c @@ -53,12 +53,20 @@ typedef enum { typedef struct { uintptr_t handle; /* 0 = 空闲;非 0 单调,不复用 */ - int fd; /* net 层 fd,同 fd 模型下 LISTEN/CLIENT 相同 */ + int fd; /* net 层 fd(0 合法;失效值只认 NET_FD_INVALID) */ uint32_t net_gen; /* 成功 Listen 时的网络代次,跨代旧句柄一律失效 */ uint8_t role; /* slot_role_t */ } slot_t; -static slot_t s_slots[IEC104_MCU_MAP_SIZE]; +/* 槽位初值:fd 必须显式写成契约失效值,禁止依赖静态零初始化(0 是合法 fd)。 + * 条目数必须等于 IEC104_MCU_MAP_SIZE(8)。 */ +#define IEC104_SLOT_INIT { .handle = 0U, .fd = NET_FD_INVALID, \ + .net_gen = 0U, .role = SLOT_FREE } + +static slot_t s_slots[IEC104_MCU_MAP_SIZE] = { + IEC104_SLOT_INIT, IEC104_SLOT_INIT, IEC104_SLOT_INIT, IEC104_SLOT_INIT, + IEC104_SLOT_INIT, IEC104_SLOT_INIT, IEC104_SLOT_INIT, IEC104_SLOT_INIT, +}; static uintptr_t s_next_handle = 1U; static uint8_t s_inited; @@ -174,6 +182,7 @@ static void client_slot_drop(slot_t *slot) /* 代次自锁:跨代槽的 fd 号可能已被复用,绝不能对它做任何硬件读取/拆除。 */ if (slot->net_gen != net_get_generation()) { memset(slot, 0, sizeof(*slot)); + slot->fd = NET_FD_INVALID; return; } state = net_sock_state(slot->fd); @@ -185,6 +194,7 @@ static void client_slot_drop(slot_t *slot) } /* 只清客户端槽;监听槽的 handle/fd/net_gen/role 原地不动。 */ memset(slot, 0, sizeof(*slot)); + slot->fd = NET_FD_INVALID; } /* 函数功能:分配一个新句柄值(单调递增、永不复用),必要时先整表作废重启。 @@ -198,6 +208,9 @@ static uintptr_t handle_new(void) uintptr_t h = s_next_handle; if (h >= (uintptr_t)(UINTPTR_MAX - IEC104_MCU_MAP_SIZE)) { memset(s_slots, 0, sizeof(s_slots)); + for (uint32_t i = 0U; i < IEC104_MCU_MAP_SIZE; ++i) { + s_slots[i].fd = NET_FD_INVALID; + } h = 1U; } s_next_handle = h + 1U; @@ -214,6 +227,9 @@ IEC104_NetResult_t IEC104_Net_Init(int *native_error) * 这里只清后端映射表、不向任何旧 fd 发 net_close_sock——fd 号可能已被 * 复用,误关会打掉新会话。不变量见本文件头。 */ memset(s_slots, 0, sizeof(s_slots)); + for (uint32_t i = 0U; i < IEC104_MCU_MAP_SIZE; ++i) { + s_slots[i].fd = NET_FD_INVALID; + } s_next_handle = 1U; s_rx_bytes = 0U; s_inited = 1U; @@ -235,7 +251,8 @@ IEC104_NetResult_t IEC104_Net_Listen( const char *bind_address, uint16_t port, IEC104_NetSocket_t *listener, uint16_t *bound_port, int *native_error) { - int fd, rc, addrlen; + int fd = NET_FD_INVALID; + int rc, addrlen; uint32_t i; uint32_t ip; struct net_sockaddr_in addr; @@ -259,6 +276,7 @@ IEC104_NetResult_t IEC104_Net_Listen( for (i = 0U; i < IEC104_MCU_MAP_SIZE; ++i) { if (s_slots[i].handle != 0U && s_slots[i].net_gen != gen) { memset(&s_slots[i], 0, sizeof(s_slots[i])); + s_slots[i].fd = NET_FD_INVALID; } } } @@ -268,7 +286,7 @@ IEC104_NetResult_t IEC104_Net_Listen( return result(IEC104_NET_ERROR, NET_ERR_INVAL, native_error); } fd = net_socket(NET_AF_INET, NET_SOCK_STREAM); - if (fd < 0) { + if (fd == NET_FD_INVALID) { return result(IEC104_NET_ERROR, net_get_errno(), native_error); } memset(&addr, 0, sizeof(addr)); @@ -635,6 +653,7 @@ IEC104_NetResult_t IEC104_Net_Close( } } memset(slot, 0, sizeof(*slot)); + slot->fd = NET_FD_INVALID; return result(IEC104_NET_OK, 0, native_error); } diff --git a/App/sync/time_sntp.c b/App/sync/time_sntp.c index ab480a86..945ac2ca 100644 --- a/App/sync/time_sntp.c +++ b/App/sync/time_sntp.c @@ -77,15 +77,16 @@ static struct { SntpTimestamp_t t1; /* 本轮请求时间(serializer 要求跨收发保存) */ uint8_t pkt[SNTP_PACKET_BASE_SIZE]; /* 请求报文(48B,静态省栈) */ } s_ctx = { - /* fd 必须显式初始化成 -1:net 层的 fd 0 是**合法**描述符,零初始化的 0 - * 会被 s_socket_close() 的 `fd >= 0` 判据当成"已打开的 socket", + /* fd 必须显式初始化成 NET_FD_INVALID(契约 C1):net 层的 fd 0 是**合法** + * 描述符,零初始化的 0 会被历史判据 `fd >= 0` 当成"已打开的 socket", * 于是在 SNTP 从未开过 socket 时对 fd 0 发 net_close(0),关掉别的服务 * (实测 2026-11-18 台架:网卡起来第一轮代次变化即把 ftpTask 刚 listen * 的槽 0 关掉,随后 104 的 net_socket() 又复用 fd 0,两个监听器抢同一 * 芯片 Socket,表现为 104 连接立刻收到 FTP 的 220 banner)。 * 教训:本项目 net fd 是"槽位下标",0 完全合法,任何"用 0 表示未打开" - * 的写法都是错的。 */ - .fd = -1, + * 的写法都是错的;判据只允许与 NET_FD_INVALID 比较。 + * 契约全文 → docs/网络/网络句柄失效值契约.md */ + .fd = NET_FD_INVALID, }; static uint32_t s_rng; /* xorshift32:散布/防欺骗随机数(非密钥用途) */ @@ -249,10 +250,10 @@ static void s_ts_now(SntpTimestamp_t *p_ts) { */ static int s_socket_open(uint32_t gen) { struct net_sockaddr_in addr; - int s; + int s = NET_FD_INVALID; s = net_socket(NET_AF_INET, NET_SOCK_DGRAM); - if (s < 0) { + if (s == NET_FD_INVALID) { DBG_ERROR("net_socket FAIL errno=%d", net_get_errno()); return -1; } @@ -277,9 +278,9 @@ static int s_socket_open(uint32_t gen) { * 返回值:无 */ static void s_socket_close(void) { - if (s_ctx.fd >= 0) { + if (s_ctx.fd != NET_FD_INVALID) { net_close(s_ctx.fd); - s_ctx.fd = -1; + s_ctx.fd = NET_FD_INVALID; } } @@ -476,7 +477,7 @@ static void s_send_round(uint32_t net_gen, uint32_t now) { } s_ctx.no_srv_logged = 0u; - if (s_ctx.fd < 0) { + if (s_ctx.fd == NET_FD_INVALID) { if (s_socket_open(net_gen) != 0) { s_fail_backoff(now); return; diff --git a/Drivers/BSP/CH395F/ch395f.c b/Drivers/BSP/CH395F/ch395f.c index d0ce22cb..bd59878b 100644 --- a/Drivers/BSP/CH395F/ch395f.c +++ b/Drivers/BSP/CH395F/ch395f.c @@ -1414,8 +1414,35 @@ void ch395f_get_unreach_info(uint8_t *p_buf) { /* 每 Socket 状态缓存(刷新点:主动回读 ch395f_get_sock_state; * 以及 net_poll 每轮对在用 Socket 各刷一次——E2 实测 18.1us/次, - * 4 监听 ~72us 远小于 1ms 轮询周期) */ -static ch395f_sock_state_t g_sock_state[8]; + * 4 监听 ~72us 远小于 1ms 轮询周期) + * + * 初值**必须显式写**,不能靠零初始化:本类型的不变量是「open != OPEN 时 + * tcp_state == CH395F_SOCK_STATE_NONE(无意义)」(ch395f.h 类型注释),而零初始化 + * 给的是 {CLOSED, TCP_CLOSED(0x00)}——TCP=00 是一个**合法**取值(二段关闭的 05/00 + * 中间态,TC-NET-1501 台架实证),于是"从未回读过"与"回读到已关闭"无法区分。 + * 显式给 NONE 后不变量从启动第一刻就成立,未刷新时的读取一律落在"无意义"上。 + * 行为不变(9 处生产消费点,逐处可 grep 坐实,分两档): + * 7 处先判 open 再看 tcp_state —— 本文件 ch395f_sock_is_listening、 + * ch395f_cmd_done(DONE_LISTEN)、复位状态机 WAIT_CLOSE;net_events 的 + * chip_listening(AND)、形态①"连接已失"OR 门(第一支 open==CLOSED 已短路)、 + * 形态⑤"静默回收"(AND);net_listener 的"芯片已在听"(AND)。 + * 2 处只比较 tcp_state、不判 open —— net_events 的 net_lost_connect_probe + * (目标值 ESTABLISHED=0x04)与 reconciler 的 LISTENING 分支 + * (目标值 ESTABLISHED=0x04);其目标值与 0x00(TCP_CLOSED) 和 + * 0xFF(NONE) 都不相交,故改前改后同样早退、同样不进。 + * 而 open 的初值本来就是 CLOSED、不受本次改动影响,故仅"open=CLOSED 时的 + * tcp_state"由 0x00 变 0xFF,判定结果无一处改变。代价:16B 从 ZI 移入 RW-data + * (RAM 占用不变,Flash 初始化镜像 +16B)。 */ +static ch395f_sock_state_t g_sock_state[8] = { + { CH395F_SOCKET_CLOSED, CH395F_SOCK_STATE_NONE }, + { CH395F_SOCKET_CLOSED, CH395F_SOCK_STATE_NONE }, + { CH395F_SOCKET_CLOSED, CH395F_SOCK_STATE_NONE }, + { CH395F_SOCKET_CLOSED, CH395F_SOCK_STATE_NONE }, + { CH395F_SOCKET_CLOSED, CH395F_SOCK_STATE_NONE }, + { CH395F_SOCKET_CLOSED, CH395F_SOCK_STATE_NONE }, + { CH395F_SOCKET_CLOSED, CH395F_SOCK_STATE_NONE }, + { CH395F_SOCKET_CLOSED, CH395F_SOCK_STATE_NONE }, +}; /* sock_reset 非阻塞状态机槽位(每 Socket 一个;t0 用 16 位 tick 差值, * 各阶段超时 <=2s,远小于 65535ms 回绕窗) */ diff --git a/Drivers/BSP/NET/lftpd/lftpd.c b/Drivers/BSP/NET/lftpd/lftpd.c index df22c78b..b9215c01 100644 --- a/Drivers/BSP/NET/lftpd/lftpd.c +++ b/Drivers/BSP/NET/lftpd/lftpd.c @@ -380,13 +380,14 @@ static int cmd_dele(lftpd_client_t *client, const char *arg) static int cmd_epsv(lftpd_client_t *client, const char *arg) { - if (client->data_socket >= 0) { + if (client->data_socket != NET_FD_INVALID) { lftpd_inet_close(client->data_socket); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; } - int listener_socket = lftpd_inet_listen(0); - if (listener_socket < 0) { + int listener_socket = NET_FD_INVALID; + listener_socket = lftpd_inet_listen(0); + if (listener_socket == NET_FD_INVALID) { send_simple_response(client->socket, 425, STATUS_425); return -1; } @@ -414,19 +415,20 @@ static int cmd_feat(lftpd_client_t *client, const char *arg) static int cmd_list(lftpd_client_t *client, const char *arg) { - if (client->data_socket == -1) { + if (client->data_socket == NET_FD_INVALID) { send_simple_response(client->socket, 425, STATUS_425); return -1; } send_simple_response(client->socket, 150, STATUS_150); - int data_sock = lftpd_inet_accept_timeout(client->data_socket, 5000); - if (data_sock < 0) { + int data_sock = NET_FD_INVALID; + data_sock = lftpd_inet_accept_timeout(client->data_socket, 5000); + if (data_sock == NET_FD_INVALID) { lftpd_log_peer("%s data accept failed (peer gone?), sk=%d", __func__, client->data_socket); send_simple_response(client->socket, 425, STATUS_425); lftpd_inet_close(client->data_socket); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; return -1; } @@ -435,7 +437,7 @@ static int cmd_list(lftpd_client_t *client, const char *arg) * 不关会让客户端一直读到超时(曾试"优雅断开+复用监听器"方案,因该语义限制 * 与芯片行为未能稳定工作,见 链路延迟测试说明.md §8.2)。 */ lftpd_inet_close(data_sock); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; if (err == 0) { send_simple_response(client->socket, 226, STATUS_226); @@ -447,19 +449,20 @@ static int cmd_list(lftpd_client_t *client, const char *arg) static int cmd_nlst(lftpd_client_t *client, const char *arg) { - if (client->data_socket == -1) { + if (client->data_socket == NET_FD_INVALID) { send_simple_response(client->socket, 425, STATUS_425); return -1; } send_simple_response(client->socket, 150, STATUS_150); - int data_sock = lftpd_inet_accept_timeout(client->data_socket, 5000); - if (data_sock < 0) { + int data_sock = NET_FD_INVALID; + data_sock = lftpd_inet_accept_timeout(client->data_socket, 5000); + if (data_sock == NET_FD_INVALID) { lftpd_log_peer("%s data accept failed (peer gone?), sk=%d", __func__, client->data_socket); send_simple_response(client->socket, 425, STATUS_425); lftpd_inet_close(client->data_socket); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; return -1; } @@ -468,7 +471,7 @@ static int cmd_nlst(lftpd_client_t *client, const char *arg) * 不关会让客户端一直读到超时(曾试"优雅断开+复用监听器"方案,因该语义限制 * 与芯片行为未能稳定工作,见 链路延迟测试说明.md §8.2)。 */ lftpd_inet_close(data_sock); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; if (err == 0) { send_simple_response(client->socket, 226, STATUS_226); @@ -518,15 +521,16 @@ static int cmd_pass(lftpd_client_t *client, const char *arg) static int cmd_pasv(lftpd_client_t *client, const char *arg) { - if (client->data_socket >= 0) { + if (client->data_socket != NET_FD_INVALID) { lftpd_inet_close(client->data_socket); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; } /* 原 3×200ms 应用层重试已删(lftpd_inet_listen 单次化)—— * 失败直接 425,FTP 客户端自带传输重试语义;服务端不再叠阻塞重试 */ - int listener_socket = lftpd_inet_listen(0); - if (listener_socket < 0) { + int listener_socket = NET_FD_INVALID; + listener_socket = lftpd_inet_listen(0); + if (listener_socket == NET_FD_INVALID) { send_simple_response(client->socket, 425, STATUS_425); return -1; } @@ -578,19 +582,20 @@ static int cmd_quit(lftpd_client_t *client, const char *arg) static int cmd_retr(lftpd_client_t *client, const char *arg) { - if (client->data_socket == -1) { + if (client->data_socket == NET_FD_INVALID) { send_simple_response(client->socket, 425, STATUS_425); return -1; } send_simple_response(client->socket, 150, STATUS_150); - int data_sock = lftpd_inet_accept_timeout(client->data_socket, 5000); - if (data_sock < 0) { + int data_sock = NET_FD_INVALID; + data_sock = lftpd_inet_accept_timeout(client->data_socket, 5000); + if (data_sock == NET_FD_INVALID) { lftpd_log_peer("%s data accept failed (peer gone?), sk=%d", __func__, client->data_socket); send_simple_response(client->socket, 425, STATUS_425); lftpd_inet_close(client->data_socket); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; return -1; } @@ -601,7 +606,7 @@ static int cmd_retr(lftpd_client_t *client, const char *arg) * 不关会让客户端一直读到超时(曾试"优雅断开+复用监听器"方案,因该语义限制 * 与芯片行为未能稳定工作,见 链路延迟测试说明.md §8.2)。 */ lftpd_inet_close(data_sock); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; if (err == 0) { lftpd_log_info("DOWNLOAD '%s' OK", path); @@ -646,19 +651,20 @@ static int cmd_stor(lftpd_client_t *client, const char *arg) return 0; } - if (client->data_socket == -1) { + if (client->data_socket == NET_FD_INVALID) { send_simple_response(client->socket, 425, STATUS_425); return -1; } send_simple_response(client->socket, 150, STATUS_150); - int data_sock = lftpd_inet_accept_timeout(client->data_socket, 5000); - if (data_sock < 0) { + int data_sock = NET_FD_INVALID; + data_sock = lftpd_inet_accept_timeout(client->data_socket, 5000); + if (data_sock == NET_FD_INVALID) { lftpd_log_peer("%s data accept failed (peer gone?), sk=%d", __func__, client->data_socket); send_simple_response(client->socket, 425, STATUS_425); lftpd_inet_close(client->data_socket); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; return -1; } @@ -669,7 +675,7 @@ static int cmd_stor(lftpd_client_t *client, const char *arg) * 不关会让客户端一直读到超时(曾试"优雅断开+复用监听器"方案,因该语义限制 * 与芯片行为未能稳定工作,见 链路延迟测试说明.md §8.2)。 */ lftpd_inet_close(data_sock); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; if (err == 0) { uint32_t size = 0; @@ -798,9 +804,9 @@ static int handle_control_channel(lftpd_client_t *client) cleanup: /* 数据监听器在复用模式下会跨命令保留,会话结束必须显式释放(否则每次会话泄漏一个 Socket) */ - if (client->data_socket >= 0) { + if (client->data_socket != NET_FD_INVALID) { lftpd_inet_close(client->data_socket); - client->data_socket = -1; + client->data_socket = NET_FD_INVALID; } /* 控制通道不得 close:单连接模型下它即监听器(fd 与监听一体),EOF/断连时 * net 层已 auto_relisten 回 LISTEN;此处 close 会连监听一起毁掉并触发 @@ -815,7 +821,7 @@ int lftpd_start(const char *directory, int port, lftpd_t *lftpd) lftpd->directory = directory; lftpd->port = port; - lftpd->server_socket = -1; /* memset 清零后显式置"无监听器"(0 是合法 fd) */ + lftpd->server_socket = NET_FD_INVALID; /* memset 清零后显式置"无监听器"(0 是合法 fd) */ /* 出厂默认口令在用告警(台架锚点;改了 [ftp] pwd_hash 即消失) */ if (ftp_cfg_is_default_pwd() != 0) { @@ -824,10 +830,10 @@ int lftpd_start(const char *directory, int port, lftpd_t *lftpd) while (true) { lftpd_task_wd_beat(); /* 看门狗:事件循环每轮喂心跳(ftpTask 主循环节拍点) */ - if (lftpd->server_socket < 0) { + if (lftpd->server_socket == NET_FD_INVALID) { /* 首次启动 / 网络重建后:全量创建监听器(socket+bind+listen) */ lftpd->server_socket = lftpd_inet_listen(port); - if (lftpd->server_socket < 0) { + if (lftpd->server_socket == NET_FD_INVALID) { lftpd_log_error("error creating listener"); /* 看门狗:3s 重试等待拆短片喂心跳(单次 3s 挂起超 IWDG 最坏窗 * ~1.7s → 误复位;与 time_sync.c 监听重试同模式) */ @@ -848,11 +854,12 @@ int lftpd_start(const char *directory, int port, lftpd_t *lftpd) lftpd_log_info("waiting for connection..."); - int client_socket = lftpd_inet_accept(lftpd->server_socket); - if (client_socket < 0) { + int client_socket = NET_FD_INVALID; + client_socket = lftpd_inet_accept(lftpd->server_socket); + if (client_socket == NET_FD_INVALID) { lftpd_log_peer("listener rebuilt (reason logged by accept layer)"); lftpd_inet_close(lftpd->server_socket); - lftpd->server_socket = -1; /* 监听器已不可用(网络重建):下轮重建 */ + lftpd->server_socket = NET_FD_INVALID; /* 监听器已不可用(网络重建):下轮重建 */ continue; } @@ -876,12 +883,15 @@ int lftpd_start(const char *directory, int port, lftpd_t *lftpd) } } - static lftpd_client_t client; /* static: off-stack session context (single session) */ + static lftpd_client_t client = { /* static: off-stack session context (single session) */ + .socket = NET_FD_INVALID, + .data_socket = NET_FD_INVALID, + }; memset(&client, 0, sizeof(client)); strncpy(client.directory, directory, sizeof(client.directory) - 1); client.directory[sizeof(client.directory) - 1] = '\0'; client.socket = client_socket; - client.data_socket = -1; + client.data_socket = NET_FD_INVALID; lftpd->client = &client; handle_control_channel(&client); @@ -894,7 +904,7 @@ int lftpd_start(const char *directory, int port, lftpd_t *lftpd) int lftpd_stop(lftpd_t *lftpd) { - if (lftpd->server_socket >= 0) { + if (lftpd->server_socket != NET_FD_INVALID) { lftpd_inet_close(lftpd->server_socket); } if (lftpd->client) { diff --git a/Drivers/BSP/NET/lftpd/lftpd.h b/Drivers/BSP/NET/lftpd/lftpd.h index 136fd857..a6494756 100644 --- a/Drivers/BSP/NET/lftpd/lftpd.h +++ b/Drivers/BSP/NET/lftpd/lftpd.h @@ -4,6 +4,8 @@ typedef struct { char directory[256]; + /* 两个 fd 均遵循 NET_FD_INVALID 契约:0 是合法 fd,失效值只认 NET_FD_INVALID + * (docs/网络/网络句柄失效值契约.md);对象 memset 后必须在 5 行内重置 */ int socket; int data_socket; /* FTP 鉴权会话态(每会话 memset 0 = 未登录;跨会话锁定计数在 @@ -16,7 +18,7 @@ typedef struct { typedef struct { const char *directory; int port; - int server_socket; + int server_socket; /* 监听 fd;无监听器 = NET_FD_INVALID(0 是合法 fd) */ lftpd_client_t *client; } lftpd_t; diff --git a/Drivers/BSP/NET/lftpd/lftpd_inet.c b/Drivers/BSP/NET/lftpd/lftpd_inet.c index 66a128d8..addb164b 100644 --- a/Drivers/BSP/NET/lftpd/lftpd_inet.c +++ b/Drivers/BSP/NET/lftpd/lftpd_inet.c @@ -37,10 +37,11 @@ int lftpd_inet_listen(int port) * 监听交给 FTP 客户端自身的重试语义(主流 FTP 服务器 passive listen 失败 * 亦直接 425,不在服务端叠应用层阻塞重试) */ lftpd_task_wd_beat(); /* 看门狗:入口喂心跳 */ - int s = net_socket(NET_AF_INET, NET_SOCK_STREAM); - if (s < 0) { + int s = NET_FD_INVALID; + s = net_socket(NET_AF_INET, NET_SOCK_STREAM); + if (s == NET_FD_INVALID) { DBG_ERROR("create socket"); - return -1; + return NET_FD_INVALID; } struct net_sockaddr_in addr; @@ -51,7 +52,7 @@ int lftpd_inet_listen(int port) if (net_bind(s, (struct net_sockaddr *)&addr, sizeof(addr)) < 0) { DBG_ERROR("bind port %d", port); net_close(s); - return -1; + return NET_FD_INVALID; } if (net_listen(s) >= 0) { @@ -60,7 +61,7 @@ int lftpd_inet_listen(int port) DBG_ERROR("listen port %d failed", port); net_close(s); - return -1; + return NET_FD_INVALID; } int lftpd_inet_get_socket_port(int socket) @@ -83,14 +84,15 @@ int lftpd_inet_accept(int socket) uint32_t gen = net_get_generation(); while (1) { - int s = net_accept(socket, NULL, NULL); - if (s >= 0) { + int s = NET_FD_INVALID; + s = net_accept(socket, NULL, NULL); + if (s != NET_FD_INVALID) { return s; } if (net_get_generation() != gen) { /* 运维改 IP 的正常后果,不是缺陷 → info(级别划分见存储架构说明 §10.3) */ DBG_INFO("network re-init: abort accept, relisten"); - return -1; + return NET_FD_INVALID; } lftpd_task_wd_beat(); /* 看门狗:自旋轮次喂心跳(无限等待,可能长时间无客户端) */ vTaskDelay(pdMS_TO_TICKS(100)); @@ -102,8 +104,9 @@ int lftpd_inet_accept_timeout(int socket, int timeout_ms) int elapsed = 0; while (elapsed < timeout_ms) { - int s = net_accept(socket, NULL, NULL); - if (s >= 0) { + int s = NET_FD_INVALID; + s = net_accept(socket, NULL, NULL); + if (s != NET_FD_INVALID) { return s; } /* M2 镜像门控退役(自愈专项实验 2026-10-12;沉降门失效族收口, @@ -115,7 +118,7 @@ int lftpd_inet_accept_timeout(int socket, int timeout_ms) /* **故意留 error**:控制连接还活着、我方数据监听却已不在服役 → * 这是本侧异常,不是对端行为 */ DBG_ERROR("data listener disarmed, accept aborted"); - return -1; + return NET_FD_INVALID; } lftpd_task_wd_beat(); /* 看门狗:每轮喂心跳(数据连接等待最长 5s) */ vTaskDelay(pdMS_TO_TICKS(100)); @@ -124,7 +127,7 @@ int lftpd_inet_accept_timeout(int socket, int timeout_ms) /* 客户端连上控制通道却没来建数据连接(中止/被防火墙拦)= 对端行为 → info */ DBG_INFO("accept timeout (%dms) - peer never opened data channel", timeout_ms); - return -1; + return NET_FD_INVALID; } int lftpd_inet_read_line(int socket, char *buffer, size_t buffer_len) diff --git a/Drivers/BSP/NET/net_config.h b/Drivers/BSP/NET/net_config.h index 7cfbbe28..85dd9b42 100644 --- a/Drivers/BSP/NET/net_config.h +++ b/Drivers/BSP/NET/net_config.h @@ -26,6 +26,8 @@ extern "C" { #endif +#include "net_fd.h" /* NET_FD_INVALID:fd 失效值契约(零依赖头) */ + /* * 最大支持的 Socket 数量(CH395F 支持 0~7) */ @@ -33,6 +35,13 @@ extern "C" { #define NET_MAX_SOCKETS 8 #endif +/* + * fd 区间校验(**net 层内部专用**,契约 C4):0 号是合法句柄,NET_FD_INVALID + * 与一切越界值均无效。上界只在本头 / net 层内部出现,应用层判"是否持有 fd" + * 一律只与 NET_FD_INVALID 比较(docs/网络/网络句柄失效值契约.md)。 + */ +#define NET_FD_IN_RANGE(fd) (((fd) > NET_FD_INVALID) && ((fd) < NET_MAX_SOCKETS)) + /* * 超时时间配置(毫秒) * 0 = 无限等待(阻塞模式) diff --git a/Drivers/BSP/NET/net_events.c b/Drivers/BSP/NET/net_events.c index 551572ec..cd200416 100644 --- a/Drivers/BSP/NET/net_events.c +++ b/Drivers/BSP/NET/net_events.c @@ -282,9 +282,9 @@ void handle_disconnect_event(net_sock_t *p_sock) { * +100ms 沉降落在窗内不可见。沉降窗口同时让残渣 DISCONNECT 在 state==CLOSED * (无害、仅留痕)时被消费,断开"杀下一条 → 新拆链 → 再杀"的繁殖链 */ { - /* fd 取自 uint8_t ch395_sock → 恒非负,只需上界门 */ + /* fd 取自 uint8_t ch395_sock → 恒为有效值,此处只复核 fd 域上界 */ int qfd = (int)p_sock->ch395_sock; - if (qfd < NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(qfd) != 0) { /* 登记优雅沉降(NET_RELISTEN_SETTLE_GRACEFUL) */ net_listener_settle(qfd, NET_LISTENER_SETTLE_GRACEFUL); } @@ -374,9 +374,9 @@ void handle_timeout_event(net_sock_t *p_sock) { /* TRAP-NET-18:异常释放(TIMEOUT,例如客户端中止上传)→ 复监听前隔离, * 等对端在途数据落尽并排空 RX 残渣(详见 net_relisten_locked 区块注释) */ { - /* fd 取自 uint8_t ch395_sock → 恒非负,只需上界门 */ + /* fd 取自 uint8_t ch395_sock → 恒为有效值,此处只复核 fd 域上界 */ int qfd = (int)p_sock->ch395_sock; - if (qfd < NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(qfd) != 0) { /* 登记异常释放隔离(重监听前等待在途数据落尽 + RX 排空) */ net_listener_settle(qfd, NET_LISTENER_SETTLE_QUARANTINE); } diff --git a/Drivers/BSP/NET/net_fd.h b/Drivers/BSP/NET/net_fd.h new file mode 100644 index 00000000..cfc03013 --- /dev/null +++ b/Drivers/BSP/NET/net_fd.h @@ -0,0 +1,28 @@ +/* + * 模块名称:Network Socket 句柄失效值契约 + * 模块功能:定义网络 socket 句柄的**唯一**失效值 NET_FD_INVALID,供 MCU 侧、 + * PC 模拟器与主机单测 stub 共用。 + * 适用平台:STM32F4 系列(CH395F 以太网芯片) / PC 模拟器 + * 作者:王建锋 + * 创建日期:2026-11-18 + * 修改记录: + * + * 契约要点(全文 → docs/网络/网络句柄失效值契约.md): + * 1. net_socket() 成功返回 0 .. NET_MAX_SOCKETS-1,**0 是合法 fd**; + * 失败返回 NET_FD_INVALID。 + * 2. 任何"持有 fd"的变量/结构体成员,声明处必须显式初始化为 NET_FD_INVALID, + * 不得依赖 C 的零初始化(零值恰好是合法 fd 0)。 + * 3. 判"是否持有 fd"只允许与 NET_FD_INVALID 比较(== / !=), + * 禁止 >= 0、< 0、== -1 之类的数值形态判据。 + * + * ⚠ 本头文件刻意**零依赖**(不 include net_config.h / net_types.h): + * 主机单测的 stub 目录里没有 net_config.h,而 stub 的 net_socket.h 同样要 + * include 本文件取失效值。不得在此引入任何其它头文件或 NET_MAX_SOCKETS。 + */ +#ifndef NET_FD_H +#define NET_FD_H + +/* 网络 socket 句柄失效值("未持有 / 已关闭 / 申请失败") */ +#define NET_FD_INVALID (-1) + +#endif /* NET_FD_H */ diff --git a/Drivers/BSP/NET/net_listener.c b/Drivers/BSP/NET/net_listener.c index f2fe9aba..acb5b44b 100644 --- a/Drivers/BSP/NET/net_listener.c +++ b/Drivers/BSP/NET/net_listener.c @@ -237,7 +237,7 @@ static int net_relisten_locked(int sockfd) { * 函数说明:只置事实、不做动作(动作只在 net_listener_tick 一处发生);越界静默忽略。 */ void net_listener_settle(int sockfd, net_listener_settle_t level) { - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } s_relisten_quarantine[sockfd] = (uint8_t)level; @@ -252,7 +252,7 @@ void net_listener_settle(int sockfd, net_listener_settle_t level) { * 上一轮的 400/800ms 等待(跨轮残留);上限留痕标志漏清则下一生成静默无声。 */ void net_listener_clear(int sockfd) { - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } s_relisten_req[sockfd] = 0U; @@ -292,7 +292,7 @@ static void net_relisten_done(int sockfd) { * 3. 非阻塞:实际重建发生在下一轮 tick;越界静默忽略。 */ void net_listener_request(int sockfd, net_listener_req_t reason) { - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } if (s_relisten_req[sockfd] != 0U) { /* 已在请求中:保持既有节奏(防重试饥饿) */ diff --git a/Drivers/BSP/NET/net_pending.c b/Drivers/BSP/NET/net_pending.c index 694f03d7..8eea1a89 100644 --- a/Drivers/BSP/NET/net_pending.c +++ b/Drivers/BSP/NET/net_pending.c @@ -80,7 +80,7 @@ static void net_pending_complete(int sockfd, int result) { net_pending_t *p; /* 描述符越界:静默返回(防重复通知) */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } /* 取挂起请求 */ @@ -122,7 +122,7 @@ int net_pending_register(int sockfd, void *buf, int len, uint32_t now; /* 描述符越界 → BADF */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } /* 取挂起请求 */ @@ -318,7 +318,7 @@ void net_pending_tick(net_sock_t *p_socks) { */ int net_pending_active(int sockfd) { /* 描述符越界:视为无挂起 */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return 0; } return (s_net_pending[sockfd].active != 0U) ? 1 : 0; @@ -335,7 +335,7 @@ int net_pending_active(int sockfd) { */ void net_pending_clear(int sockfd) { /* 描述符越界:直接返回 */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } /* 挂起状态清零(静默,不发通知) */ @@ -390,7 +390,7 @@ void net_pending_settle_close(int sockfd, net_sock_t *p_sock) { int avail; /* 描述符越界或无在位挂起:静默返回 */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } if (s_net_pending[sockfd].active == 0U) { @@ -447,7 +447,7 @@ static void net_send_pending_complete(int sockfd, int result) { net_send_pending_t *p; /* 描述符越界:静默返回(防重复通知) */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } /* 取挂起请求 */ @@ -479,7 +479,7 @@ int net_send_pending_register(int sockfd, const void *buf, int len, int sent, uint32_t now; /* 描述符越界 → BADF */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } /* 参数非法(缓冲无效 / 长度非正 / 进度越界)→ INVAL */ @@ -632,7 +632,7 @@ void net_send_pending_tick(net_sock_t *p_socks) { */ void net_send_pending_clear(int sockfd) { /* 描述符越界:直接返回 */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } /* 挂起状态清零(静默,不发通知) */ @@ -654,7 +654,7 @@ void net_send_pending_cancel(int sockfd, int err) { const net_send_pending_t *p; /* 描述符越界:静默返回 */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } /* 取挂起请求 */ @@ -698,7 +698,7 @@ void net_send_pending_cancel_all(int err) { */ int net_send_pending_active(int sockfd) { /* 描述符越界:视为无挂起 */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return 0; } return (s_net_send[sockfd].active != 0U) ? 1 : 0; diff --git a/Drivers/BSP/NET/net_select.c b/Drivers/BSP/NET/net_select.c index fb0f8354..d11b993f 100644 --- a/Drivers/BSP/NET/net_select.c +++ b/Drivers/BSP/NET/net_select.c @@ -184,7 +184,7 @@ int net_poll_events(net_pollfd_t *fds, int nfds, int timeout) { fds[i].revents = 0; /* 检查 fd 有效性 */ - if ((fds[i].fd < 0) || (fds[i].fd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(fds[i].fd) == 0) { fds[i].revents |= NET_POLLNVAL; ready++; continue; @@ -324,7 +324,7 @@ static int check_socket_error(int sockfd) { const net_sock_t *p_sock; /* 无效 fd 视为错误 */ - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return 1; } diff --git a/Drivers/BSP/NET/net_socket.c b/Drivers/BSP/NET/net_socket.c index e46ad111..32d60633 100644 --- a/Drivers/BSP/NET/net_socket.c +++ b/Drivers/BSP/NET/net_socket.c @@ -951,7 +951,8 @@ static int net_wait_result(const char *kind, int sockfd) { * 入口参数:domain - 地址族,仅支持 NET_AF_INET int * type - SOCK_STREAM(TCP) 或 SOCK_DGRAM(UDP) int * 出口参数:无 - * 返回值:Socket 描述符 (0~7),失败返回 -1 int + * 返回值:Socket 描述符 (0~NET_MAX_SOCKETS-1,首个成功值为 0), + * 失败返回 NET_FD_INVALID int * 限定条件:net_init() 已调用成功;s_net_initialized == 1 * 函数说明:自动分配一个空闲的 Socket 控制块(in_use=0),初始化为 CREATED 状态 */ @@ -963,15 +964,17 @@ int net_socket(int domain, int type) { /* 参数检查:地址族仅支持 NET_AF_INET */ if (domain != NET_AF_INET) { - /* 不支持的地址族 → INVAL */ - return NET_ERR_RETURN_1(NET_ERR_INVAL); + /* 不支持的地址族 → INVAL(保留 errno 副作用;返回值为契约失效值) */ + (void)NET_ERR_RETURN_1(NET_ERR_INVAL); + return NET_FD_INVALID; } /* 分配空闲控制块(in_use=0 的槽位) */ sockfd = alloc_socket(); - if (sockfd < 0) { - /* 无空闲控制块 → NOMEM */ - return NET_ERR_RETURN_1(NET_ERR_NOMEM); + if (sockfd == NET_FD_INVALID) { + /* 无空闲控制块 → NOMEM(保留 errno 副作用;返回值为契约失效值) */ + (void)NET_ERR_RETURN_1(NET_ERR_NOMEM); + return NET_FD_INVALID; } /* 初始化控制块:芯片侧 Socket 编号与描述符一一对应 */ @@ -1038,7 +1041,7 @@ int net_bind(int sockfd, const struct net_sockaddr *addr, int addrlen) { const struct net_sockaddr_in *p_addr_in; /* 参数检查:描述符范围 */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { /* 越界 → BADF */ return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -1289,7 +1292,7 @@ int net_listen(int sockfd) { net_msg_t msg; /* 描述符越界 → BADF */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -1332,7 +1335,7 @@ int net_listen(int sockfd) { * 入口参数:sockfd - 监听 Socket 描述符 int * 出口参数:addr - 输出:客户端地址结构体指针 struct net_sockaddr *(可为 NULL) * addrlen - 输入输出:地址结构体长度 int *(可为 NULL) - * 返回值:新连接的 Socket 描述符,失败返回 -1 int + * 返回值:新连接的 Socket 描述符,失败返回 NET_FD_INVALID int * 限定条件:Socket 处于 LISTENING 状态 * 函数说明:单连接:监听 Socket 自身在 CONNECT 后已转为 ESTABLISHED */ @@ -1357,7 +1360,7 @@ int net_listen(int sockfd) { * 入口参数:sockfd - 监听 Socket 描述符 int * 出口参数:addr - 输出:客户端地址结构体指针 struct net_sockaddr *(可为 NULL) * addrlen - 输入输出:地址结构体长度 int *(可为 NULL) - * 返回值:新连接的 Socket 描述符,失败返回 -1 int + * 返回值:新连接的 Socket 描述符,失败返回 NET_FD_INVALID int * 限定条件:Socket 处于 LISTENING 状态 * 函数说明:1. 单连接:监听 Socket 自身在 CONNECT 后已转为 ESTABLISHED * 2. 等待期叠加芯片状态轮询探针(CONNECT 事件未收到自愈,TRAP-NET-20) @@ -1443,7 +1446,7 @@ int net_accept_locked(int sockfd, struct net_sockaddr *addr, int *addrlen) { * 入口参数:sockfd - 监听 Socket 描述符 int * 出口参数:addr - 输出:客户端地址结构体指针 struct net_sockaddr *(可为 NULL) * addrlen - 输入输出:地址结构体长度 int *(可为 NULL) - * 返回值:新连接的 Socket 描述符,失败返回 -1 int + * 返回值:新连接的 Socket 描述符,失败返回 NET_FD_INVALID int * 限定条件:Socket 处于 LISTENING 状态;net_init() + MX_FREERTOS_Init() 已执行;非 netTask 上下文 * 函数说明:将接受请求放入消息队列,阻塞等待 netTask 处理完毕 */ @@ -1452,7 +1455,7 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen) { net_msg_t msg; /* 描述符越界 → BADF */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -1613,7 +1616,7 @@ int net_connect(int sockfd, const struct net_sockaddr *addr, int addrlen) { net_msg_t msg; /* 描述符越界 → BADF */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -1688,7 +1691,7 @@ static int net_connect_locked(int sockfd, const struct net_sockaddr *addr, int a uint8_t status; /* 参数检查:描述符范围 */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { /* 越界 → BADF */ return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -2232,7 +2235,7 @@ int net_drop_conn_locked(net_sock_t *p_sock) { /* * 函数功能:发送数据(线程安全版本,通过消息队列委托给 netTask) - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * buf - 待发送数据缓冲区指针(调用返回前须保持有效,本函数不拷贝数据) const void * * len - 数据长度(字节),> 0 int * flags - 标志位,当前实现忽略(保留 BSD send 接口兼容) int @@ -2256,7 +2259,7 @@ int net_send(int sockfd, const void *buf, int len, int flags) { net_msg_t msg; /* ---- 1. 参数合法性检查 ---- */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { /* 描述符越界 */ return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -2309,7 +2312,7 @@ int net_send(int sockfd, const void *buf, int len, int flags) { /* * 函数功能:接收数据(线程安全版本,通过消息队列委托给 netTask; * **默认无限阻塞**,30s 默认预算已删) - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * buf - 接收缓冲区指针 void * * len - 缓冲区大小 int > 0 * flags - 标志位,0=按 socket 阻塞属性等待,NET_MSG_DONTWAIT=单次非阻塞 int @@ -2333,7 +2336,7 @@ int net_recv(int sockfd, void *buf, int len, int flags) { net_msg_t msg; /* 描述符越界 → BADF */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -2387,7 +2390,7 @@ int net_recv(int sockfd, void *buf, int len, int flags) { /* * 函数功能:接收数据(非阻塞具名入口——原 NET_MSG_DONTWAIT 路径转正, * 对齐 BSD recv(MSG_DONTWAIT) / Python recv 非阻塞模式的"名如其义") - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * buf - 接收缓冲区指针 void * * len - 缓冲区大小 int > 0 * 出口参数:buf - 填充接收到的数据 @@ -2407,7 +2410,7 @@ int net_recv_nb(int sockfd, void *buf, int len) { * 函数功能:接收数据(带调用方指定超时的阻塞版,用于分片有界读; * 为**显式预算**便捷入口,等价 Python settimeout, * 不再有隐藏默认值) - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * buf / len - 接收缓冲与容量 void * / int > 0 * timeout_ms - 单次占用 netTask 的最长等待(毫秒,>0) uint32_t * 出口参数:无 @@ -2425,7 +2428,7 @@ int net_recv_to(int sockfd, void *buf, int len, uint32_t timeout_ms) { net_msg_t msg; /* ---- 1. 参数合法性检查 ---- */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { /* 描述符越界 */ return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -2504,7 +2507,7 @@ int net_recv_to(int sockfd, void *buf, int len, uint32_t timeout_ms) { /* * 函数功能:关闭 Socket(线程安全版本,通过消息队列委托给 netTask) - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * 出口参数:无 * 返回值:0 - 关闭成功 int * -1 - 关闭失败 int @@ -2517,7 +2520,7 @@ int net_close(int sockfd) { net_msg_t msg; /* 描述符越界 → BADF */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -2557,7 +2560,7 @@ int net_close(int sockfd) { /* * 函数功能:主动拆掉当前 TCP 会话、保留监听(线程安全版本,经消息队列委托 netTask) - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * 出口参数:无 * 返回值:0 - 成功(含幂等:无活动会话直接 0) int * -1 - 失败(BADF/INVAL/入队失败) int @@ -2576,7 +2579,7 @@ int net_drop_conn(int sockfd) { net_msg_t msg; /* 描述符越界 → BADF */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -2615,7 +2618,7 @@ int net_drop_conn(int sockfd) { /* * 函数功能:发送 UDP 数据报(含目标地址) - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * buf - 待发送数据缓冲区指针 const void * * len - 数据长度 int > 0 * flags - 标志位,通常为 0 int @@ -2658,7 +2661,7 @@ int net_sendto(int sockfd, const void *buf, int len, int flags, (void)flags; /* 参数检查:本批检查全部留在守卫/队列之前,参数错误先报参数错误 */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { /* 描述符越界 → BADF */ return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -2729,7 +2732,7 @@ int net_sendto(int sockfd, const void *buf, int len, int flags, } /* * 函数功能:接收 UDP 数据报(含源地址)——无限等待形态 - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * buf - 接收缓冲区指针 void * * len - 缓冲区大小 int > 0 * flags - NET_MSG_DONTWAIT = 本次非阻塞,其余按 0 处理 int @@ -2770,7 +2773,7 @@ int net_recvfrom(int sockfd, void *buf, int len, int flags, /* * 函数功能:接收 UDP 数据报(含源地址),带显式等待预算 - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * buf - 接收缓冲区指针 void * * len - 缓冲区大小 int > 0 * timeout_ms - 等待预算(毫秒,**> 0**;无限等待请用 net_recvfrom) uint32_t @@ -2818,7 +2821,7 @@ int net_udp_set_peer(int sockfd, const struct net_sockaddr_in *peer) { /* 执行结果 */ int result; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } if (s_net_socks[sockfd].in_use == 0U) { @@ -2911,7 +2914,7 @@ static int net_recvfrom_impl(int sockfd, void *buf, int len, int flags, int result; /* 参数检查(顺序与改造前一致:BADF → INVAL → 出参容量) */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_BADF; } if (s_net_socks[sockfd].in_use == 0U) { @@ -3048,7 +3051,7 @@ int net_close_sock(net_sock_t *p_sock) { } /* * 函数功能:注册 Socket 事件回调函数 - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * cb - 回调函数指针 net_event_cb_t(可为 NULL 取消注册) * arg - 用户自定义参数指针 void * * 出口参数:无 @@ -3064,7 +3067,7 @@ int net_set_event_cb(int sockfd, net_event_cb_t cb, void *arg) { net_sock_t *p_sock; /* 参数检查 */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { /* 描述符越界 → BADF */ return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -3088,7 +3091,7 @@ int net_set_event_cb(int sockfd, net_event_cb_t cb, void *arg) { /* * 函数功能:设置 Socket 阻塞/非阻塞**模式属性**(模式挂控制块属性, * 对齐 BSD O_NONBLOCK / Python setblocking) - * 入口参数:sockfd - Socket 描述符 int >= 0 && < NET_MAX_SOCKETS + * 入口参数:sockfd - Socket 描述符 int 有效 fd * on - 1 = 阻塞(net_socket 默认);0 = 非阻塞 int * 出口参数:无 * 返回值:0 - 设置成功 int @@ -3106,7 +3109,7 @@ int net_setblocking(int sockfd, int on) { net_sock_t *p_sock; /* 参数检查:描述符范围 */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { /* 描述符越界 → BADF */ return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -3153,7 +3156,7 @@ int net_get_errno(void) { */ int net_sock_state(int sockfd) { /* 描述符越界:返回 -1(不设错误码,只读查询) */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return -1; } /* 控制块未在用:返回 -1 */ @@ -3318,7 +3321,7 @@ uint32_t net_ntohl(uint32_t netlong) { * 函数功能:分配一个空闲的 Socket 控制块 * 入口参数:无 * 出口参数:无 - * 返回值:空闲 Socket 索引(0~NET_MAX_SOCKETS-1);-1 表示无空闲 Socket int + * 返回值:空闲 Socket 索引(0~NET_MAX_SOCKETS-1);NET_FD_INVALID 表示无空闲 int * 限定条件:s_net_socks 已定义 * 函数说明:1. 线性扫描 s_net_socks,返回首个 in_use == 0 的控制块索引 * 2. 调用方负责初始化该控制块 @@ -3336,8 +3339,8 @@ static int alloc_socket(void) { } } - /* 无空闲控制块:返回 -1 */ - return -1; + /* 无空闲控制块:返回契约失效值 */ + return NET_FD_INVALID; } @@ -3380,7 +3383,7 @@ static void parse_ip_string(const char *str, uint8_t *ip_arr) { /* * 函数功能:根据描述符获取 Socket 控制块指针(内部使用) - * 入口参数:sockfd - Socket 描述符 int 0 - NET_MAX_SOCKETS-1 + * 入口参数:sockfd - Socket 描述符 int 有效 fd * 出口参数:无 * 返回值:Socket 控制块指针;描述符越界或未分配时返回 NULL net_sock_t * * 限定条件:无 @@ -3389,7 +3392,7 @@ static void parse_ip_string(const char *str, uint8_t *ip_arr) { */ net_sock_t *net_get_sock(int sockfd) { /* 描述符越界:返回 NULL */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NULL; } @@ -3426,7 +3429,7 @@ net_sock_t *net_sock_raw(int sockfd) { */ int net_getsockname(int sockfd, struct net_sockaddr *addr, int *addrlen) { /* 描述符越界 → BADF */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -3477,7 +3480,7 @@ int net_getsockname(int sockfd, struct net_sockaddr *addr, int *addrlen) { */ int net_getpeername(int sockfd, struct net_sockaddr *addr, int *addrlen) { /* 描述符越界 → BADF */ - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } diff --git a/Drivers/BSP/NET/net_socket.h b/Drivers/BSP/NET/net_socket.h index e7298fc1..8aad5f95 100644 --- a/Drivers/BSP/NET/net_socket.h +++ b/Drivers/BSP/NET/net_socket.h @@ -15,6 +15,7 @@ extern "C" { #endif +#include "net_fd.h" /* NET_FD_INVALID:fd 失效值契约(0 是合法 fd) */ #include "net_types.h" /* @@ -155,9 +156,12 @@ int net_poll(void); * 函数功能:创建 socket * 入口参数:domain - 地址族,仅支持 AF_INET * type - SOCK_STREAM(TCP) 或 SOCK_DGRAM(UDP) - * 返回值:socket 描述符 (0~7),失败返回 -1 + * 返回值:socket 描述符 (0~NET_MAX_SOCKETS-1,**0 是合法句柄**,首个成功值为 0); + * 失败返回 NET_FD_INVALID(同时置 net_errno) * 限定条件:net_init() 已调用 - * 函数说明:自动分配空闲 Socket 控制块 + * 函数说明:自动分配空闲 Socket 控制块。句柄失效值契约见 net_fd.h / + * docs/网络/网络句柄失效值契约.md —— 判"是否持有 fd"只与 + * NET_FD_INVALID 比较,禁止 >= 0 / < 0 之类的数值形态判据。 */ int net_socket(int domain, int type); @@ -186,9 +190,9 @@ int net_listen(int sockfd); * 入口参数:sockfd - 监听 socket 描述符 * addr - 输出:客户端地址 * addrlen - 输入输出:地址长度 - * 返回值:新 socket 描述符,失败返回 -1 + * 返回值:新 socket 描述符,失败返回 NET_FD_INVALID * 限定条件:socket 正在监听 - * 函数说明:在非阻塞模式下,如果没有新连接,返回 -1 并设置 + * 函数说明:在非阻塞模式下,如果没有新连接,返回 NET_FD_INVALID 并设置 * net_errno 为 NET_ERR_WOULDBLOCK */ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen); diff --git a/Drivers/BSP/NET/net_udp.c b/Drivers/BSP/NET/net_udp.c index 7e740124..d763823a 100644 --- a/Drivers/BSP/NET/net_udp.c +++ b/Drivers/BSP/NET/net_udp.c @@ -41,6 +41,8 @@ #define NET_UDP_HDR_IP_OFF 4U /* 截断数据报的排空粒度(字节):读空不丢后续包,只在调用方缓冲偏小时走这条路 */ #define NET_UDP_DRAIN_CHUNK 64U +/* 上电芯片默认只给低位 Socket 分配收发缓冲;从该编号起须兜底重设(手册 §5.45) */ +#define NET_UDP_REBUF_FIRST 4 /* * 私有类型定义区 @@ -102,7 +104,7 @@ static void net_udp_req_complete(int sockfd, int result); * 拒绝比交错投递安全(TCP 挂起 recv 同一守卫,见 net_pending_register)。 */ int net_udp_outparam_arm(int sockfd, struct net_sockaddr *src_addr, int *addrlen) { - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NET_ERR_RETURN_1(NET_ERR_BADF); } @@ -129,7 +131,7 @@ int net_udp_outparam_arm(int sockfd, struct net_sockaddr *src_addr, int *addrlen * 调用方侧"消息没投出去"的清理,防槽位泄漏把该 fd 永久钉成 BUSY。 */ void net_udp_outparam_disarm(int sockfd) { - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } @@ -155,7 +157,7 @@ void net_udp_outparam_disarm(int sockfd) { * 调用方侧通知已在各 settle/cancel 路径发过,这里只做幂等归零。 */ void net_udp_clear(int sockfd) { - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } (void)memset(&s_net_udp[sockfd], 0, sizeof(s_net_udp[sockfd])); @@ -212,7 +214,7 @@ int net_udp_bind_exec(int sockfd, uint16_t local_port) { /* net_init 已为全部 8 个 Socket 分配缓冲;此处仅对 Socket 4~7 兜底重设, * 布局与 net_init 一致(固定 6 块/Socket,与 MSS 解耦) */ - if (sockfd >= 4) { + if (sockfd >= NET_UDP_REBUF_FIRST) { /* 每 Socket 块数 = 接收 + 发送 */ uint8_t blocks_per_socket = (uint8_t)(CH395F_RECV_BLOCKS + CH395F_SEND_BLOCKS); /* 本 Socket 接收缓冲起始块 */ @@ -548,7 +550,7 @@ void net_udp_settle_close(int sockfd, net_sock_t *p_sock) { /* 芯片侧可用字节 */ int avail; - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } p = &s_net_udp[sockfd]; @@ -585,7 +587,7 @@ static void net_udp_req_complete(int sockfd, int result) { /* 本 fd 接收槽 */ net_udp_req_t *p; - if ((sockfd < 0) || (sockfd >= NET_MAX_SOCKETS)) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return; } p = &s_net_udp[sockfd]; diff --git a/Drivers/BSP/UI/ui_net_sink.c b/Drivers/BSP/UI/ui_net_sink.c index cc9b8e8f..73ab1b2c 100644 --- a/Drivers/BSP/UI/ui_net_sink.c +++ b/Drivers/BSP/UI/ui_net_sink.c @@ -85,8 +85,8 @@ static uint8_t g_lcdmem_data[4 + UI_FB_SIZE]; /* LCDMEM 应答缓冲:4B 偏 static uint8_t g_status_data[32]; /* STATUS 应答缓冲:最大 28 B,见应答注释 */ static uint8_t g_rx[RM_RX_BUF]; /* 接收暂存区:整块 recv 后逐字节喂入状态机 */ -static int g_listen = -1; /* 监听 Socket fd(未启动或已停止时为 -1) */ -static int g_client = -1; /* 当前客户端 Socket fd(无连接时为 -1) */ +static int g_listen = NET_FD_INVALID; /* 监听 Socket fd(未启动或已停止时为失效值) */ +static int g_client = NET_FD_INVALID; /* 当前客户端 Socket fd(无连接时为失效值) */ static uint16_t g_port; /* 监听端口(网络重建 / 断线后重监听用) */ static uint32_t g_gen; /* 建立监听时的网络代次号(变化 = 网络已重建) */ static uint8_t s_send_fail_run; /* 连续发送失败计数(0 = 正常) */ @@ -192,7 +192,7 @@ static int remo_send(uint8_t cmd, const uint8_t *data, uint16_t len) { int total; int ret; - if (g_client < 0) { + if (g_client == NET_FD_INVALID) { return -1; } if (s_sink_blocked) { @@ -586,11 +586,11 @@ static void rm_parser_feed(uint8_t b) { * 函数说明:绑定 g_port 与任意本地地址并进入监听;成功后写回 g_listen */ static int bind_listen(void) { - int ls; + int ls = NET_FD_INVALID; struct net_sockaddr_in addr; ls = net_socket(NET_AF_INET, NET_SOCK_STREAM); - if (ls < 0) { + if (ls == NET_FD_INVALID) { return -1; } @@ -624,11 +624,11 @@ int ui_net_sink_start(uint16_t port) { g_port = port; if (bind_listen() < 0) { - g_listen = -1; + g_listen = NET_FD_INVALID; return -1; } - g_client = -1; + g_client = NET_FD_INVALID; g_gen = net_get_generation(); rm_parser_reset(); return 0; @@ -661,15 +661,15 @@ void ui_net_sink_poll(void) { /* 网络重建(代次变化):旧监听/客户端已随芯片复位失效,重建监听 */ if (net_get_generation() != g_gen) { - if (g_client >= 0 && g_client != g_listen) { + if (g_client != NET_FD_INVALID && g_client != g_listen) { net_close(g_client); } - if (g_listen >= 0) { + if (g_listen != NET_FD_INVALID) { net_close(g_listen); - g_listen = -1; + g_listen = NET_FD_INVALID; } sink_beat(); /* F3:重建前的一对 close 往返结束 */ - g_client = -1; + g_client = NET_FD_INVALID; rm_parser_reset(); s_send_fail_run = 0U; /* 网络重建:失败累计清零、解除推送阻断 */ s_sink_blocked = 0U; @@ -678,7 +678,7 @@ void ui_net_sink_poll(void) { return; } - if (g_listen < 0) { + if (g_listen == NET_FD_INVALID) { /* 尚未启动或启动失败:重试(成功则 g_listen 更新) */ (void)ui_net_sink_start(g_port); return; @@ -690,19 +690,19 @@ void ui_net_sink_poll(void) { * 内恒 0 → :7003 永不进 net_accept → net_lost_connect_probe 对该端口等于 * 从未运行(CONNECT 事件未收到时无第二信源);armed 放行后由 net_accept_locked * 的状态门自行裁决(含 RX 有数据的 closed-but-readable 接受) */ - if (g_client < 0) { + if (g_client == NET_FD_INVALID) { if (net_listener_armed(g_listen) == 0) { /* 监听器已不在服役(fd 消失 / 非监听型)→ 置 -1 交回上方 * g_listen < 0 分支重建监听。改前靠"每轮都 accept"撞出 BADF 来暴露, * 加了门控就必须显式兜这一条,否则端口永久不再接受新客户端 */ if (net_get_sock(g_listen) == NULL) { - g_listen = -1; + g_listen = NET_FD_INVALID; } return; } int c = net_accept(g_listen, NULL, NULL); sink_beat(); /* F3:accept 往返返回即喂(风暴期该往返实测 150ms 级) */ - if (c >= 0) { + if (c != NET_FD_INVALID) { g_client = c; rm_parser_reset(); s_send_fail_run = 0U; /* 新连接:失败累计清零、解除推送阻断 */ @@ -738,7 +738,7 @@ void ui_net_sink_poll(void) { if (g_client != g_listen) { net_close(g_client); /* 多连接后端(PC 模拟器):数据通道独立,需显式关闭 */ } - g_client = -1; + g_client = NET_FD_INVALID; rm_parser_reset(); /* 监听生命周期 P1 不变量 II:重建**不再**由本处自行 bind_listen。 * ① net_recv_locked 的 EOF 分支已触发 auto_relisten(D10 非阻塞重试); @@ -748,7 +748,7 @@ void ui_net_sink_poll(void) { * 仅当 fd 真消失(net_get_sock 返 NULL = 网络重建)才置 -1,交回上方 * 分支重新走 start → bind_listen */ if (net_get_sock(g_listen) == NULL) { - g_listen = -1; /* fd 真消失:交回主循环重试 */ + g_listen = NET_FD_INVALID; /* fd 真消失:交回主循环重试 */ } } else { /* n < 0:区分"暂无数据"(继续等待)与"真错误"(断开并视情况重建监听) */ @@ -762,13 +762,13 @@ void ui_net_sink_poll(void) { net_close(g_client); /* 多连接后端(PC 模拟器):数据通道独立,需显式关闭 */ } sink_beat(); /* F3:EOF/错误路径的 close 往返结束 */ - g_client = -1; + g_client = NET_FD_INVALID; rm_parser_reset(); /* 监听生命周期 P1 不变量 II:同 EOF 分支——不再自行 bind_listen, * 重建交回 net 层(recv 的错误分支同样会走 relisten)。仅 fd 真消失 * 时置 -1 交回主循环走 start */ if (net_get_sock(g_listen) == NULL) { - g_listen = -1; /* fd 真消失:交回主循环重试 */ + g_listen = NET_FD_INVALID; /* fd 真消失:交回主循环重试 */ } } } diff --git a/Drivers/BSP/UI/ui_page_clear.c b/Drivers/BSP/UI/ui_page_clear.c index d3128b92..d91f0200 100644 --- a/Drivers/BSP/UI/ui_page_clear.c +++ b/Drivers/BSP/UI/ui_page_clear.c @@ -64,10 +64,16 @@ static const uint8_t k_cl_id[CL_ROW_N] = { UI_W_REC_LOG_START, UI_W_REC_LOG_OPER, UI_W_REC_LOG_YK }; -static uint8_t s_confirm; /* 待确认行(第一次 ENTER 已按下),CL_NONE = 无 */ -static uint8_t s_note; /* 已投递、要显示清除结果的行,CL_NONE = 无 */ -static uint8_t s_err; /* 投递被拒的行,CL_NONE = 无 */ -static uint16_t s_sel_seen; /* 上一次绘制时的选中行(移开光标即收回三个锁存) */ +/* 三个锁存的失效值一律在声明处写死:行号 0 是合法行("运行记录"),零初始化等于 + * "行 0 上有结果",只能靠 pg_init 在开页时覆盖掉——把正确性押在调用顺序上。声明处 + * 给 CL_NONE 后,.bss 阶段即满足"无行",pg_init 仍照旧重设(幂等)。 */ +static uint8_t s_confirm = CL_NONE; /* 待确认行(第一次 ENTER 已按下),CL_NONE = 无 */ +static uint8_t s_note = CL_NONE; /* 已投递、要显示清除结果的行,CL_NONE = 无 */ +static uint8_t s_err = CL_NONE; /* 投递被拒的行,CL_NONE = 无 */ +/* 本变量不是"无行"锁存,而是"上次绘制时看到的选中行":零值=行 0(合法),且只在 + * pg_draw 里与当前选中行比较,三个锁存已有声明初值后它取任何初值都不影响安全, + * 故不套 CL_NONE(0xFF 不是合法行号,用了反而误导) */ +static uint16_t s_sel_seen; /* 上一次绘制时的选中行(移开光标即收回三个锁存) */ /* 函数定义区 */ diff --git a/docs/README.md b/docs/README.md index 68c8c445..00ae19ca 100644 --- a/docs/README.md +++ b/docs/README.md @@ -103,6 +103,7 @@ docs/ | [`网络/Net层阻塞模型架构设计.md`](网络/Net层阻塞模型架构设计.md) | **等待模型**:recv/send 挂起请求架构、数据结构与挂起槽状态机、recv 五路 + send 四路完成语义、模块接口契约(14 函数)、实现落点(20 集成点)、调用方契约、设计边界与性能特征 | | [`网络/IEC104_Net适配契约.md`](网络/IEC104_Net适配契约.md) | **104 板端 Net 后端契约**:直译 vendor `Close(client)` 会毁掉监听的**反例**、按槽 role 的映射规则、LISTEN 恒定 / CLIENT 每次新建的双句柄模型、代次不变式、单调不复用句柄、`NET_NO_OS` 编译期边界与已知缺口、证据边界(fake 12/12,CH395F 板端未证) | | [`网络/网络自愈架构设计.md`](网络/网络自愈架构设计.md) | **网络自愈架构 + 监听生命周期**:现状权威描述——根因三层证据与 A′ 出局、ioLibrary 代码级对照、设计原则(不变量 I1~I8)、分层职责与三 tick、reconciler 形态①~⑤ + M3 门、驱动原语、读即清信源审计、FUN_PARA bit3 契约、recv 语义、KeepAlive、参数表与 E 锚点速查、红线、编号发现速查、代码级事实清点、决策记录、`net_listener.c` / `net_events.c` 模块化边界、延后项;审计与实施过程已归档 | +| [`网络/网络句柄失效值契约.md`](网络/网络句柄失效值契约.md) | **fd 失效值契约(0 是合法句柄)**:220 banner 误导链、三层根因(失效值落合法域 / 数值形态判据 / 主机假 fd 域不同域)+「MISRA 9.1 与 cppcheck 为何抓不到」、契约条款 C1~C7 各带正反例、提交门禁 `net-handle` 的 R1~R5 与失败读法、新代码接入八条自查清单 | --- diff --git a/docs/代码规范/pre-commit使用说明.md b/docs/代码规范/pre-commit使用说明.md index 6b2ed8c7..2f9d419f 100644 --- a/docs/代码规范/pre-commit使用说明.md +++ b/docs/代码规范/pre-commit使用说明.md @@ -35,10 +35,10 @@ git commit └─ test-coverage 主机单测覆盖率总闸(47 套 + 回退台账) ``` -**阶段**:`pre-commit` 阶段拦截代码问题、`commit-msg` 阶段拦截格式问题,任一失败 → commit 中止;另有 `manual` 阶段(`stages: [manual]` 的慢钩子)**不随 `git commit` 跑**,由远端 CI 与 `scripts/ci_local.py` 的 manual 段承担(见下)。一次 `git commit` 实跑 **48** 根 = `pre-commit` 阶段 47 根 + `gitlint` 1 根。 +**阶段**:`pre-commit` 阶段拦截代码问题、`commit-msg` 阶段拦截格式问题,任一失败 → commit 中止;另有 `manual` 阶段(`stages: [manual]` 的慢钩子)**不随 `git commit` 跑**,由远端 CI 与 `scripts/ci_local.py` 的 manual 段承担(见下)。一次 `git commit` 实跑 **49** 根 = `pre-commit` 阶段 48 根 + `gitlint` 1 根。 > **CI 侧的同一套门禁(2026-10-01 起)**:Gitea Actions(`.gitea/workflows/ci.yml`)在 push / PR 时 -> 以 `pre-commit run --all-files` 复跑 **`pre-commit` 阶段的 47 根**(`mem-numbers` 在无 Keil `.map` 的 runner 上自适应跳过), +> 以 `pre-commit run --all-files` 复跑 **`pre-commit` 阶段的 48 根**(`mem-numbers` 在无 Keil `.map` 的 runner 上自适应跳过), > 再以「手动阶段门禁」步**逐根** `--hook-stage manual` 复跑 `cppcheck` / `test-cppcheck` / `test-coverage` 三根(本地还有第四根 `iec104-tcp`,需模拟器产物) > (`pre_commit run a b c` 不支持多 id,实测报 `unrecognized arguments`)。 > 本地提交前想跑同一套判定:`& '.venv\Scripts\python.exe' scripts/ci_local.py`。详见 `../测试说明/流程与规范/测试开发标准流程.md` §9。 @@ -93,7 +93,7 @@ git commit | 机制 | 口径 | |---|---| -| **三个阶段** | pre-commit 阶段 **47** 个钩子 + commit-msg 阶段 `gitlint`(= 一次 `git commit` 实跑 **48**)+ `manual` 阶段 4 根(`cppcheck` / `test-cppcheck` / `test-coverage` / `iec104-tcp`:`git commit` 不跑,只在远端 CI 的「手动阶段门禁」步与 `scripts/ci_local.py` 的 manual 段跑;前三根实测合计约 165 s ≈ 一次带代码提交耗时的三分之二,`iec104-tcp` 另需模拟器构建产物)→ 口径 = YAML 解析后的 hook 条目数 **52**;自查命令与「声明 / 文档 / 实跑」三数同源核对 → `docs/门禁说明/README.md` §2;`default_install_hook_types: [pre-commit, commit-msg]` 是显式声明的——换机后 `pre-commit install` 才会带上 commit-msg 钩子 | +| **三个阶段** | pre-commit 阶段 **48** 个钩子 + commit-msg 阶段 `gitlint`(= 一次 `git commit` 实跑 **49**)+ `manual` 阶段 4 根(`cppcheck` / `test-cppcheck` / `test-coverage` / `iec104-tcp`:`git commit` 不跑,只在远端 CI 的「手动阶段门禁」步与 `scripts/ci_local.py` 的 manual 段跑;前三根实测合计约 165 s ≈ 一次带代码提交耗时的三分之二,`iec104-tcp` 另需模拟器构建产物)→ 口径 = YAML 解析后的 hook 条目数 **53**;自查命令与「声明 / 文档 / 实跑」三数同源核对 → `docs/门禁说明/README.md` §2;`default_install_hook_types: [pre-commit, commit-msg]` 是显式声明的——换机后 `pre-commit install` 才会带上 commit-msg 钩子 | | **一根钩子在输出里出现两次** | 未声明 `stages:` 的钩子**默认属于所有阶段**,pre-commit 与 commit-msg 两遍都会列出它;第二遍的"文件"是提交信息文件,几乎必然 `(no files to check)Skipped`。**只看输出结尾会把"实跑通过"读成"没跑"**——判某钩子跑没跑要认它**第一次**出现的那行(实测 2026-10-24:只改 `.pre-commit-config.yaml` 的提交里 `test-coverage` 与 `bsp-err` 都是 Passed,尾巴那一遍是 Skipped) | | **stash 陷阱** | pre-commit 跑钩子前会 stash 未暂存改动,钩子看到的是"没有你中间状态"的树。**改代码 + 同时更新基线/受管区的,必须先 `git add` 再跑钩子**,否则会拿到假报警(本仓踩过,`docs/门禁说明/bsp-err.md` §4 记了现场)。**它藏不住什么,见下一行** | | **stash 覆盖面:只覆盖已跟踪文件的未暂存改动**(2026-10-26 读源码定案,**对所有钩子通用**) | 机制在 pre-commit 的 `staged_files_only._unstaged_changes_cleared()`:`git diff-index ` 取补丁 → `git checkout -- .` → 跑完 `git apply` 还原。所以「钩子实跑 = 只看到 HEAD + 本笔 staged」这句**对已跟踪文件成立、对未跟踪文件不成立**:未跟踪文件压根不在 `diff-index` 里,**不会被藏**;`git add -N`(intent-to-add)也救不了——pre-commit 只 `git rm --cached` 把它撤下索引(`_intent_to_add_cleared()`),**文件本体仍在盘上**。后果:别人写了尚未入库的文件(新页面实例 / 新单测目录 / 新文档)躺在树里时,**任何一笔碰到该文件所属钩子 `files:` 的提交都会被这份半成品拖红**——红的内容没错,但账不该记在这笔提交上。实测:`ui_page_clock.c`、`ui_page_reset.c` 处于未跟踪且未绑 `#page` 期间,`generated-fresh` 对**所有人**的 UI 提交都会 FAIL(现场日志 `docs/门禁说明/generated-fresh.md` §6 第 8 条)。三条结论:① 提交排序——会让全树变红的半成品要么先落地(绑引用 + 重跑生成器)要么先挪出工作树;② 凡「判定基准取工作区」的钩子(重跑比对类、全库统计类)在多人同树下必须配**静默窗口**;③ 真要 `--no-verify` 抢跑,正文必须点名是哪几个**未跟踪**文件拖的红,别让它被读成「钩子不可信」 | @@ -109,11 +109,11 @@ git commit - 提交前等价自查(静态门禁 + 提交信息门禁 + 主机侧纯逻辑单测):`scripts/ci_local.py`(用 `.venv` 解释器跑)。 - 单独跑某一条:`-m pre_commit run --files <改动的文件>`;全库:`--all-files`。 -- 临时跳过只在紧急情况,且必须在提交说明里写明跳过了什么、为什么、随后怎么补——**跳之前先跑 §2.4 自查表**(`--no-verify` 一次跳过 47 条,连 `gitlint` 一起跳 = 48 条,见 §2.2「三个阶段」行)。 +- 临时跳过只在紧急情况,且必须在提交说明里写明跳过了什么、为什么、随后怎么补——**跳之前先跑 §2.4 自查表**(`--no-verify` 一次跳过 48 条,连 `gitlint` 一起跳 = 49 条,见 §2.2「三个阶段」行)。 ### 2.4 抢跑自查表(`--no-verify` 之前自己跑一遍:只读、不 stash、别人正在写盘也安全) -`--no-verify` 跳过的不是「一条格式检查」,是**全部 47 条**(外加 commit-msg 阶段的 `gitlint`,共 48 条)。 +`--no-verify` 跳过的不是「一条格式检查」,是**全部 48 条**(外加 commit-msg 阶段的 `gitlint`,共 49 条)。 2026-10-26 本仓连着抢了三笔,放走三条本该被拦的真问题,都在提交正文里可复核: | 抢跑那笔 | 本该由谁拦下 | 后果什么时候才看得见 | @@ -163,7 +163,7 @@ git commit | **改写型钩子** `trailing-whitespace` / `end-of-file-fixer` | 它们会**改文件**。真提交里改的是 stash 之后的树;而手跑 `--files` **不 stash**(§2.2 那两行),直接落在工作区——**列了别人在飞的文件就等于替人改文件** | 只列自己的文件:`-m pre_commit run --files <自己的文件>`;或先用 A 组的一行式查出问题自己修,别让钩子替你动盘 | | **要靠 stash 才能正确归因**的判定:`mem-numbers` / `mem-budget`(读磁盘 `.map`)、`stack_report`(读磁盘 `.htm`)、`ui-golden` / `uinav-selftest`(要模拟器 exe 与台架锁)、`test-coverage`(会编译,可能撞别人的 `.obj`) | 磁盘上的 `.map` / `.htm` / `.exe` 属于**最后一次构建的人**,不是你的 ⇒ 手跑红常常是替别人背账(今天 `mem-budget` 就红在「台账与 `.map` 不同码」,因为 `.map` 里混着三条在飞源码道) | **照样要跑**(宁可多跑),但**红先归因**:`git status --porcelain` 看是谁在飞、`.htm` 的时间戳是哪次构建;确认不属本笔就在提交正文点名,**不要改基线数字去凑绿** | | **只有真提交才会碰到的面**:`gitlint`(commit-msg 阶段)与未声明 `stages:` 会跑两遍的钩子 | 手跑脚本查不到提交信息规范(标题 ≤100、**正文每行 ≤80**) | 提交信息一律 `git commit -F ` 并自查最长行;或先老实提交一次让 `gitlint` 说话,再改成 `--no-verify` | -| **`manual` 阶段的四根**(`cppcheck` / `test-cppcheck` / `test-coverage` / `iec104-tcp`) | `pre-commit run --all-files` 只跑 `pre-commit` 阶段(47 根),**不会碰它们**——漏跑不会报红,只会静默少一道门禁 | 抢跑时补:`& '.venv\Scripts\python.exe' -m pre_commit run --all-files --hook-stage manual `,一次一个 id(见 §2.2「三个阶段」行) | +| **`manual` 阶段的四根**(`cppcheck` / `test-cppcheck` / `test-coverage` / `iec104-tcp`) | `pre-commit run --all-files` 只跑 `pre-commit` 阶段(48 根),**不会碰它们**——漏跑不会报红,只会静默少一道门禁 | 抢跑时补:`& '.venv\Scripts\python.exe' -m pre_commit run --all-files --hook-stage manual `,一次一个 id(见 §2.2「三个阶段」行) | #### C. 抢跑之后(三条都来自今天的真事,不是设想) @@ -266,7 +266,7 @@ git commit -m "紧急修复" --no-verify SKIP=cppcheck git commit -m "紧急修复" ``` -> ⚠️ **不推荐**:`--no-verify` 一次跳过 47 条(连 `gitlint` 一起 = 48 条;manual 阶段四根本来不随提交跑),不是「跳过格式检查」。**跳之前必须先跑 §2.4 抢跑自查表** +> ⚠️ **不推荐**:`--no-verify` 一次跳过 48 条(连 `gitlint` 一起 = 49 条;manual 阶段四根本来不随提交跑),不是「跳过格式检查」。**跳之前必须先跑 §2.4 抢跑自查表** > (尤其 `stack_report.py`——它不在钩子清单里,只有人会跑;数字与安全边界类问题不会自己冒出来)。跳之后按 §2.4 C 组 > 补齐三件事:`git status` 对交付清单、正文点名「哪些没跑 / 为什么 / 谁在飞」、静默窗口补一次 `run --all-files`。 @@ -332,7 +332,7 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env | 文件 | 位置 | 说明 | |---|---|---| -| `.pre-commit-config.yaml` | 仓库根 | 钩子配置(**52 个钩子**声明数,一次 `git commit` 实跑 48 根 = pre-commit 阶段 47 + `gitlint`;口径 = YAML 解析后的 hook 条目数,自查命令 → `docs/门禁说明/README.md` §2。声明数与一次提交的实跑数分列,勿混写;计数改动的完整台账只记在 `docs/门禁说明/README.md` §2,本行不重述)。逐项详解在 `docs/门禁说明/`(索引 `docs/门禁说明/README.md`;主机侧单测 **21 根**合一篇,含各套件来历与「22 套无专属钩子」台账(套数为 2026-10-30 复点值) `docs/门禁说明/host-unit-tests.md` §6;UI 侧另有 `font-charset` 与 `ui-golden` 两篇) | +| `.pre-commit-config.yaml` | 仓库根 | 钩子配置(**53 个钩子**声明数,一次 `git commit` 实跑 49 根 = pre-commit 阶段 48 + `gitlint`;口径 = YAML 解析后的 hook 条目数,自查命令 → `docs/门禁说明/README.md` §2。声明数与一次提交的实跑数分列,勿混写;计数改动的完整台账只记在 `docs/门禁说明/README.md` §2,本行不重述)。逐项详解在 `docs/门禁说明/`(索引 `docs/门禁说明/README.md`;主机侧单测 **21 根**合一篇,含各套件来历与「22 套无专属钩子」台账(套数为 2026-10-30 复点值) `docs/门禁说明/host-unit-tests.md` §6;UI 侧另有 `font-charset` 与 `ui-golden` 两篇) | | `.gitlint` | 仓库根 | gitlint 规则(宽松,兼容中文) | | `.cubemx_survival_baseline.json` | 仓库根 | CubeMX 易失定制基线(哈希;`--write` 重建) | | `scripts/check_mojibake.py` | scripts/ | U+FFFD 检测脚本 | diff --git a/docs/内存管理/RAM使用分析与优化方案.md b/docs/内存管理/RAM使用分析与优化方案.md index 8a460409..72dc2237 100644 --- a/docs/内存管理/RAM使用分析与优化方案.md +++ b/docs/内存管理/RAM使用分析与优化方案.md @@ -47,10 +47,10 @@ dhara 失败类 +84;RO 另 +208,全是该失败类名表)→ `ER_IROM1` | 区域 | 用量 | 容量 | 占比 | |---|---|---|---| -| ER_IROM1 | 416,092 B (406.34 KB) | 1,048,576 B (1024 KB) | 39.7% | -| RW_IRAM1 | 118,408 B (115.63 KB) | 131,072 B (128 KB) | 90.3% | +| ER_IROM1 | 416,188 B (406.43 KB) | 1,048,576 B (1024 KB) | 39.7% | +| RW_IRAM1 | 118,416 B (115.64 KB) | 131,072 B (128 KB) | 90.3% | | RW_CCM | 57,376 B (56.03 KB) | 65,280 B (64 KB) | 87.9% | -| **Flash (ROM 合计)** | **418,380 B (408.6 KB)** | 1,048,576 B (1024 KB) | **39.9%** | +| **Flash (ROM 合计)** | **418,924 B (409.1 KB)** | 1,048,576 B (1024 KB) | **40.0%** | 各区的容量与常量来源: diff --git a/docs/内存管理/RAM预算台账.md b/docs/内存管理/RAM预算台账.md index 20447b68..f1e39a9d 100644 --- a/docs/内存管理/RAM预算台账.md +++ b/docs/内存管理/RAM预算台账.md @@ -15,10 +15,10 @@ | 区域 | 用量 | 容量 | 占比 | 门禁(≤92%) | |---|---|---|---|---| -| ER_IROM1 (Flash) | 416,092 B | 1,048,576 B | 39.7% | 参考 | +| ER_IROM1 (Flash) | 416,188 B | 1,048,576 B | 39.7% | 参考 | | RW_CCM | 57,376 B | 65,280 B | 87.9% | PASS | | UNINIT_CCM | 48 B | 256 B | 18.8% | 参考 | -| RW_IRAM1 | 118,408 B | 131,072 B | 90.3% | PASS | +| RW_IRAM1 | 118,416 B | 131,072 B | 90.3% | PASS | | 子系统(静态 RW+ZI;除 RTOS 堆在 CCM 外均在 SRAM1) | 现值 | 配额 | 状态 | |---|---|---|---| diff --git a/docs/网络/BSD_Socket_API_使用指南.md b/docs/网络/BSD_Socket_API_使用指南.md index 3c7525da..d58b77ed 100644 --- a/docs/网络/BSD_Socket_API_使用指南.md +++ b/docs/网络/BSD_Socket_API_使用指南.md @@ -45,6 +45,7 @@ | 非阻塞模式 | `O_NONBLOCK` / `MSG_DONTWAIT` | `net_setblocking(fd, 0)`(模式属性)/ `net_recv_nb()` / `NET_MSG_DONTWAIT`(单次) | | 错误码 | errno | `net_get_errno()` | | 头文件 | `` | `"net_socket.h"` | +| 描述符取值 | 非负整数(0 常被 stdin 占用,故 `fd > 0` 惯用) | 控制块索引 `0~7`,**0 是合法句柄**;失效值只认 `NET_FD_INVALID`(§2.3) | | 无限阻塞约束 | 无 | ⚠ IWDG `required_mask` 内任务**禁止**(嵌入式特有契约,§10.1) | --- @@ -82,7 +83,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`) | +| fd 模型 | 控制块索引 0~7(**0 合法**;失效值只认 `NET_FD_INVALID`) | 相同(并行数组 `s_ws[]` 存 Winsock 句柄,不侵入共享的 `net_sock_t`) | | 并发 / 阻塞 | 消息队列 + `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`) | @@ -94,6 +95,8 @@ PC 模拟器(`simulator/`,CMake + SDL2)与 MCU 端共用同一份上层网 > **模拟器端网络启动**(镜像 MCU 端上电流程:defaultTask 在就绪屏障前加载 `net_cfg`,见 `simulator/main.c`):`WSAStartup` → `net_cfg_load()`(网口配置 RAM 副本,失败回退工厂默认)→ `ui_net_sink_start(7003)`(RemoDispBus TCP 监听,与 MCU 端同端口)→ 主循环 `ui_net_sink_poll()`(非阻塞协议收发)+ `net_cfg_save_run()`(执行 UI 保存请求,主循环 = 配置引擎属主)。不调用 `net_init()`——WSA 初始化由 `net_socket_sim.c` 内部 `ensure_wsa()` 幂等保证,`net_init()` 仅为对齐 API 而保留(上层代码双端统一调用)。 +> **fd 域与失效值**:合法 fd 是 `0 ~ NET_MAX_SOCKETS-1`(`NET_MAX_SOCKETS` 是 CH395F 的 Socket 个数,定义在 `Drivers/BSP/NET/net_config.h`),**0 是能正常收发数据的合法句柄**;表示「未持有 / 已关闭 / 申请失败」的失效值只有 `NET_FD_INVALID`(`Drivers/BSP/NET/net_fd.h`)。因此判「有没有 fd」只能写 `x != NET_FD_INVALID` / `x == NET_FD_INVALID`,**禁止** `x >= 0`、`x < 0`、`x == -1`、`if (x)` 这类数值形态判据——零初始化的 0 会伪装成「持有 fd 0」。完整契约(初值、判据、memset 后回填、假对象域对齐)与提交门禁 `net-handle` 的规则 → `docs/网络/网络句柄失效值契约.md`。**⚠ 示例照抄警告**:本文 §4 与 §10 的部分早期示例仍沿用 `sock = -1` / `sock < 0` 的写法(历史遗留,为保留当时的上下文未逐段改写)。**这些示例照抄进新代码会直接复发本契约明令禁止的数值形态判据**(`< 0` / `= -1` 与「0 合法」冲突),复制时必须先按上面的具名判据改写。 + ### 2.4 Socket 状态机 ```mermaid @@ -914,7 +917,7 @@ int net_socket(int domain, int type); |------|------| | `domain` | 地址族,仅支持 `AF_INET` | | `type` | `SOCK_STREAM`(TCP) 或 `SOCK_DGRAM`(UDP) | -| 返回值 | socket 描述符 (0~7),失败返回 -1 | +| 返回值 | socket 描述符 (0~7),失败返回 `NET_FD_INVALID`(**0 合法**,判定同见 §2.3 的 fd 域说明) | #### net_bind - 绑定地址 @@ -1418,6 +1421,8 @@ static int read_time_frame(int conn_sock, uint8_t buf[FRAME_LEN]) { - TCP Client:最多 8 个 - UDP:最多 8 个 +注意索引 **0 是能真正收发数据的合法句柄**(首个 `net_socket()` 成功即返回 0),表示「没有 socket」只能用 `NET_FD_INVALID`;判据禁止 `>= 0` / `< 0` 写法(理由与全套规则 → `docs/网络/网络句柄失效值契约.md`)。 + ### 12.3 发送数据有什么限制? - 每次发送的数据长度不能超过 `NET_SEND_BUF_SIZE`(默认 4096 字节) diff --git a/docs/网络/网络句柄失效值契约.md b/docs/网络/网络句柄失效值契约.md new file mode 100644 index 00000000..efdd9c23 --- /dev/null +++ b/docs/网络/网络句柄失效值契约.md @@ -0,0 +1,321 @@ +# 网络句柄失效值契约 + +> **适用对象**:任何保存网络 socket 描述符(fd)的代码——`App/`、`Drivers/BSP/`、主机单测、PC 模拟器。 +> **一句话**:本项目的 fd 0 是**合法**句柄,所以「没打开」不能靠零初始化表达;初值、判据、 +> 清零后重置三处都必须显式指向 `NET_FD_INVALID`。 +> **配套**:常量定义 → `Drivers/BSP/NET/net_fd.h`;机械检查 → `scripts/check_net_handle.py` +> (提交钩子 `net-handle`,规则详解见 `docs/门禁说明/net-handle.md`)。 +> 驱动/NET 层其它实证陷阱 → `docs/问题记录/CH395F_Trap_Records.md`。 + +## 1. 我该干什么 + +写或改任何持有 socket 描述符的代码时,先做三件事:**声明处显式初始化成 `NET_FD_INVALID`**、 +**判「有没有 fd」只与 `NET_FD_INVALID` 比较**、**`memset` 清零后 5 行内回填**。 + +为什么必须这样:本项目的 fd 不是「操作系统分配的描述符」,而是芯片 Socket 的**槽位下标**, +取值 `0 .. NET_MAX_SOCKETS-1`——**0 号是能真正收发数据的句柄**(第一个 `net_socket()` 成功调用 +就返回 0)。而 C 语言会把文件作用域 `static` 对象、以及被 `memset(..., 0, ...)` 过的结构体 +填成 0。于是「从未打开」与「持有 fd 0」在数值上不可区分:判据一旦写成 `fd >= 0`,零初始化的 +0 就通过了,代码会去关一个它从来没申请过的句柄。 + +先把下面几个标识符认全,后文不再解释: + +| 名称 | 值 / 形态 | 是什么 | 定义处 | +|---|---|---|---| +| `NET_FD_INVALID` | `(-1)` | fd 的**唯一**失效值,同时表示「未持有 / 已关闭 / 申请失败」;全仓只有一处定义 | `Drivers/BSP/NET/net_fd.h` | +| `NET_MAX_SOCKETS` | `8` | CH395F 支持的 Socket 个数,故合法 fd 是 `0 .. 7` | `Drivers/BSP/NET/net_config.h` | +| `NET_FD_IN_RANGE(fd)` | 宏 | net 层**内部**用的区间校验(`fd > NET_FD_INVALID && fd < NET_MAX_SOCKETS`);消费者不用它,见 §4 的 C4 | `Drivers/BSP/NET/net_config.h` | +| `net_fd.h` | 零依赖头 | 刻意不 include 任何别的头(不引 `net_config.h`),好让主机单测的 stub 目录也能取到失效值 | — | + +「fd」在本文一律指这个槽位下标,不是 Linux 的文件描述符;「消费者」指 `Drivers/BSP/NET/` +之外的调用方(`App/`、`Drivers/BSP/UI/`、`Drivers/BSP/NET/lftpd/` 等)。 + +## 2. 现象:104 建链收到 FTP 的 220 banner + +这一节交代「不遵守契约会长成什么样」,读它是为了认出同类现场,不是为了复述历史。 + +板端现象是「104 连不上」,但抓包看到的是 104 建链后立刻收到 FTP 的 `220` 欢迎行——说明 104 +的 TCP 连接落到了 FTP 的监听槽上。误导链五步: + +1. 上电后 SNTP 从未开过 socket,`App/sync/time_sntp.c` 里文件作用域 `static` 的 `s_ctx.fd` + 由 C 零初始化成 `0`; +2. 网卡就绪后第一轮**网络代次变化**(`net_get_generation()` 与 `s_ctx.gen` 不同)触发 + `time_sntp_run()` 的代次分支,进而调 `s_socket_close()`; +3. 关闭判据写成 `if (s_ctx.fd >= 0)`,`0 >= 0` 成立 → 对「从未打开」的 fd 0 发 `net_close(0)`, + 而 fd 0 此刻正是 **ftpTask 刚 listen 的槽**; +4. ftpTask 发现监听没了,重建监听;104 侧 `net_socket()` 又分配到同一个空闲槽 0; +5. 两个监听器抢同一芯片 Socket:104 的链路实际连着 FTP 服务,于是收到 `220` banner。 + +关键点不在「关错一次」,而在**失效值与合法值同域**:只要 0 既可能是「没打开」又可能是 +「FTP 的监听槽」,任何数值形态的判据都必然在其中一侧出错。 + +## 3. 根因:三层叠加,外加一层「工具抓不到」 + +这一节解释为什么这类缺陷能长期存活,读完应当能判断「我这段代码是不是同类」。 + +### 3.1 失效值落在合法值域内 + +C 的零初始化语义给出 0,而 0 在本项目是合法 fd。失效值必须落在值域**之外** +(`NET_FD_INVALID` 取 `-1`,因为合法域下界是 0),这是契约的第一块基石。 + +### 3.2 判据用的是数值形态 + +即便初值写对了,判据若写成 `fd >= 0` / `fd < 0` / `fd == -1`,它就与「失效值具体是什么」 +脱钩:下一次有人把初值改成 `{0}`,或把失效值换成别的数,判据不会跟着变,缺陷立刻复发。 +初值与判据**同等重要**,二者都必须锚在同一个具名常量上。 + +### 3.3 主机测试的假 fd 域与生产不同,缺陷在主机侧恒绿 + +历史主机单测的假 `net_socket()` 从 **100** 起分配 fd(另一处从 3 / 9 起),而生产域是 `0..7`。 +两个域不相交,于是「零初始化 = 0」这件事在主机侧根本没有发生的机会,回归用例永远是绿的。 +这不是测试写得少,而是**假对象的域与生产不同域**:测试保真度缺陷会让整类问题在 CI 上隐形。 + +### 3.4 为什么 MISRA / cppcheck 这类工具抓不到 + +这一层要讲清楚,否则会有人以为「配好静态检查就够了」。 + +- **它不是「读未初始化对象」**。MISRA C:2012 Rule 9.1 的原文限定是 *automatic storage + duration*——只覆盖自动存储期对象。文件作用域 `static` 是 **static storage duration**, + C99 保证它在程序启动前零初始化完毕,所以 `static ctx_t s_ctx;`(无初始化器)是**完全合规**的写法。 + 缺陷不在「读了未初始化内存」,而在「零初始化出来的那个 0 恰好是业务上的合法值」——语义层的事, + 规则文本够不着。 +- **cppcheck 有同一个盲区**。本仓的 `cppcheck` 钩子以 `--enable=warning,performance,portability,style` + 运行,**未挂 `--addon=misra`**;其 `uninitvar` 与 MISRA 9.1 同构,同样只对自动变量报警。 + 而判据 `if (ctx.fd >= 0)` 在语法与类型层面**没有任何可疑之处**——`int` 与整数字面量比较, + 是这类工具里最普通、也最不该报警的形态。 +- **缺的是「域知识」**。通用工具无法判断「0 对这个变量合不合法」,因为合法性来自**外部契约**: + CH395F 单连接模型的 fd 就是芯片 Socket 下标 0~7。任何通用规则想抓这个类,必须先知道 + 「合法域 0~7、失效值必须在域外」这条只存在于项目接口约定里的知识。 + +结论:**「零初始化 + 失效值落在合法域」这类缺陷既不违反语言规则、也不违反任何通用检查项, +通用静态分析按设计抓不到它,必须用项目级契约 + 专属门禁兜底**(落地见 §5)。 + +### 3.5 同类还有多少(排查口径与结论) + +本轮做过一次全仓审计,按「哨兵/句柄/状态」与「零初始化默认值」对照,逐个回读**实际判据** +(不是只看 `#define`):确认缺陷 **3** 条(SNTP 生产误判 1 条 + 主机假对象域 2 条,均已在 +本次落地中修掉);疑似隐患 **5** 条(零值落在合法域,但当前有独立闸门或调用顺序兜住,顺序一变 +即成缺陷);安全 **35** 条(零值不可能是合法值,或有显式闸门)。**生产代码里没有发现第二处 +实际误判**——这也反过来解释了为什么单靠「遇一个修一个」治不住这个类。 + +## 4. 契约条款 + +这一节是可以逐条照抄的规则;C1~C7 是条款名(代码注释里以「契约 C1」这样的形式引用), +每条给一句话规则 + 正例 + 反例。 + +### C1 显式初始化 + +**规则**:任何保存 fd 的变量或结构体成员,声明处必须显式写成 `NET_FD_INVALID`; +结构体用 C99 指定初始化器 `.fd = NET_FD_INVALID`。 + +```c +/* 正例:文件作用域结构体——指定初始化器点明 fd */ +static sntp_ctx_t s_ctx = { + .fd = NET_FD_INVALID, /* 0 是合法 fd,不能靠零初始化 */ +}; + +/* 正例:局部变量同样显式给初值 */ +int fd = NET_FD_INVALID; +``` + +```c +/* 反例 */ +static sntp_ctx_t s_ctx; /* 零初始化 → fd == 0,看起来"已持有" */ +static sntp_ctx_t s_ctx = {0}; /* 同上,只是把 0 写得更显眼 */ +int fd; /* 局部变量:值不确定,判据随时可能为真 */ +``` + +### C2 具名判据 + +**规则**:判「是否持有 fd」只允许 `x != NET_FD_INVALID` / `x == NET_FD_INVALID`; +禁止 `x >= 0`、`x < 0`、`x == -1`、`x != -1`、`if (x)`、`if (!x)`。 + +```c +/* 正例 */ +if (s_ctx.fd != NET_FD_INVALID) { + net_close(s_ctx.fd); + s_ctx.fd = NET_FD_INVALID; /* 关完立刻回失效值,别留悬空句柄 */ +} +``` + +```c +/* 反例:四条判据在当前 fd 域下都可能给出错误结论 */ +if (s_ctx.fd >= 0) { ... } /* 0 通过 → 关掉别人的 fd 0 */ +if (s_ctx.fd == -1) { ... } /* 失效值写死,换常量即失配 */ +if (fd) { ... } /* 把 fd 0 当"没有" */ +if (!fd) { ... } /* 同上,取反 */ +``` + +### C3 清零后重置 + +**规则**:`memset` 清零一个含 fd 成员的结构体后,必须在**同一函数内、5 行以内**把 fd 显式置回 +`NET_FD_INVALID`;不允许「反正后面会赋值」这种口头保证。 + +```c +/* 正例:memset 之后紧接着回填(会话上下文每次重建都走这条) */ +memset(&client, 0, sizeof(client)); +strncpy(client.directory, dir, sizeof(client.directory) - 1); +client.socket = client_socket; +client.data_socket = NET_FD_INVALID; /* memset 之后的 5 行内,契约 C3 */ +``` + +```c +/* 反例:清完就直接进业务,读路径先看到的是 fd 0 */ +memset(&ctx, 0, sizeof(ctx)); +ctx.state = SNTP_ST_IDLE; +/* ……几十行之后才用到 ctx.fd */ +``` + +### C4 上界不外泄 + +**规则**:`Drivers/BSP/NET/` 内部做 `0 <= fd < NET_MAX_SOCKETS` 的区间校验是合法的 +(写 `NET_FD_IN_RANGE(fd)`);但**上界只属于 net 层**,消费者只判「是否等于失效值」。 + +```c +/* 正例(net 层内部):区间校验用宏,宏里复用 NET_FD_INVALID 与 NET_MAX_SOCKETS */ +if (NET_FD_IN_RANGE(sockfd) == 0) { + return NET_ERR_RETURN_1(NET_ERR_BADF); +} +``` + +```c +/* 反例(消费者):把层内上界抄进业务代码 */ +if (listen_fd < NET_MAX_SOCKETS) { ... } /* 既没排除 NET_FD_INVALID,也把上界变成了第二真相源 */ +``` + +### C5 返回值与首个成功值 + +**规则**:`net_socket()` 失败返回 `NET_FD_INVALID`;头文件注释与主机测试都断言 +**`net_socket()` 的第一个成功返回值是 0**——这条断言是「0 合法」的机器证据,别删。 + +```c +/* 正例 */ +fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM); +if (fd == NET_FD_INVALID) { + return -1; /* 返回值本身是函数级错误码,与 fd 失效值分开 */ +} +``` + +```c +/* 反例:把"分配失败"表达成一个随便的负数 */ +return -2; /* 调用方没有可比的具名常量,只能靠猜 */ +``` + +### C6 主人语义(谁申请谁关闭) + +**规则**:fd 只能由申请它的模块关闭;`net_close(fd)` 对越界或未分配的 fd **必须失败**(返回 -1)。 +主机假对象必须复刻这条语义(跟踪「已分配集合」),不能「随便传都成功」——否则「关了别人的 fd」 +永远测不出来。 + +```c +/* 正例(假对象复刻生产语义,同时把"关闭企图"计数,供回归用例断言) */ +int net_close(int sockfd) +{ + g_close_calls++; /* 无条件计数:失败企图也要看得见 */ + if (NET_FD_IN_RANGE(sockfd) == 0 || g_fd_alloc[sockfd] == 0) { + return -1; /* 未分配 → 失败 */ + } + g_fd_alloc[sockfd] = 0; + return 0; +} +``` + +```c +/* 反例:假对象放行一切,于是"误关他人 fd"在主机侧全绿 */ +int net_close(int sockfd) { (void)sockfd; return 0; } +``` + +### C7 假对象域对齐 + +**规则**:主机测试与模拟器的 fd 假对象必须从 **0** 开始分配、上限与 `NET_MAX_SOCKETS` 同量级, +禁止 100+ 之类的独立假域。 + +```c +/* 正例:最小空闲槽优先,与生产同域;全满返回契约失效值 */ +for (fd = 0; fd < T_NET_MAX_FD; fd++) { + if (g_fd_alloc[fd] == 0) { + g_fd_alloc[fd] = 1; + return fd; + } +} +return NET_FD_INVALID; +``` + +```c +/* 反例:假域与 0..7 不相交,"零初始化 = 0"这一幕永远演不出来 */ +static int g_sock_next_fd = 100; +int net_socket(int domain, int type) { (void)domain; (void)type; return g_sock_next_fd++; } +``` + +落地后的回归用例叫 `tc_cold_start_gen_change_no_close`(`test/host/sntp/sntp_test.c`): +先断言冷启动时 `fd == NET_FD_INVALID`,再清「关闭企图」计数、让网络代次跳变、跑一轮 +`time_sntp_run()`,最后断言**关闭企图为 0** 且仍未持有 fd。C5~C7 缺失时这条用例必失败。 + +## 5. 门禁怎么拦 + +这一节讲「写错了会在哪里被挡下」,读完应当知道失败信息怎么读、豁免面在哪。 +门禁本体是 `scripts/check_net_handle.py`,作为 `net-handle` 钩子挂在提交期(全仓 53 根钩子之一), +**变更文件只当触发信号,判定恒扫全树**。 + +| 规则 | 拦什么(一句话) | 典型失败示例 | +|---|---|---| +| **R1** | fd 形标识符(名字含 `fd` / `sock` / `socket` / `handle`,或结构体 fd 成员)与**整数字面量**比较 | `if (ctx.fd >= 0)`、`if (sockfd == -1)`、`if (-1 == fd)` | +| **R2** | 文件作用域 `static` 的 fd 标量 / 含 fd 成员的结构体:无初始化器、`= {0}`、指定初始化器缺 fd 成员、fd 成员不是 `NET_FD_INVALID` | `static ctx_t s_ctx;`、`static ctx_t s_ctx = {0};`、`.fd = -1` | +| **R3** | `memset(对象, 0, ...)` 作用于含 fd 成员的结构体后 5 行内没有回填 `= NET_FD_INVALID` | 清完直接进业务(见 C3 反例) | +| **R4** | `if (fd)` / `if (!fd)` 这种「数值真值」判据 | `if (!ctx.fd) { ... }` | +| **R5** | 契约存在性:`net_fd.h` 定义 `NET_FD_INVALID`,且 `net_socket.h` include 它 | 头文件被删 / 宏被改名 / include 被删 | + +失败信息长这样(原样给出规则号、文件、命中的表达式与改法): + +``` +FAIL [R1] : 第 N 行:`ctx.fd >= 0`——fd 形标识符与整数字面量比较; + 改用`ctx.fd == NET_FD_INVALID` / `ctx.fd != NET_FD_INVALID` + (数值形态判据会随 fd 域/失效值变化失真) +``` + +自查命令(本仓库统一用 `.venv` 解释器): + +```powershell +& '.venv\Scripts\python.exe' scripts/check_net_handle.py # 全树扫描,当前应为 0 违规 +& '.venv\Scripts\python.exe' scripts/check_net_handle.py --selftest # 逐条自证:正例放行 / 反例必抓 +``` + +三条必须知道的边界,否则会把「白名单」误读成「不用守契约」: + +- **白名单只针对 R1~R4,不针对契约**:`Drivers/BSP/NET/`(层内实现者,C4 允许区间校验)与 + `test/host/`(主机假对象,断言语域与生产不同)不被这四条规则判,但两处代码**照样要守 C1~C7**。 +- **`handle` 名字族是按规则分档,不是豁免**:104 的 `socket_handle` 是句柄发号器 + (从 1 起、0 永不合法),所以 `== 0U` 与「与具名常量比较」不判;但 `handle == -1` / `handle < 0` + 这种用数值形态表达失效的照判,`if (handle)` 也照判。 +- **没有存量基线**:接线当日即要求全树 0 违规,不接受「先记进基线以后还」;也不允许用 + `#pragma` / 注释标记 / 长期 `SKIP=net-handle` 绕过。细则(盲区清单、豁免理由、改判据的流程) + → `docs/门禁说明/net-handle.md` §6 与 §7。 + +门禁只做静态文本判定,**不判**「fd 是否由申请者关闭」(C6)与「假对象域是否 0 基」(C7)—— +那两条靠主机单测的语义建模 + 回归用例覆盖。 + +## 6. 新代码接入 checklist + +新增模块(或重构既有模块)保存 fd 时,逐条勾完再提交: + +- [ ] 只引 `net_socket.h`(它已 include `net_fd.h`),**不**在本模块重定义失效值,也不假设 `-1` 以外任何数 +- [ ] 每个保存 fd 的变量/结构体成员都在**声明处** `= NET_FD_INVALID`(结构体用 `.fd = NET_FD_INVALID`) +- [ ] 全文没有 `>= 0` / `< 0` / `== -1` / `!= -1` / `if (fd)` / `if (!fd)` 形式的 fd 判据 +- [ ] 所有 `memset` 清含 fd 结构体的位置,5 行内都有 `= NET_FD_INVALID` 回填 +- [ ] 关闭动作只针对自己申请的 fd;不替别的服务「顺手关一下」 +- [ ] 消费者不引用 `NET_MAX_SOCKETS` / `NET_FD_IN_RANGE()`(上界只在 net 层内部使用) +- [ ] 要写主机测试的话:假 `net_socket()` 从 0 起分配、复刻「未分配关闭失败」,并断言首个成功值是 0 +- [ ] `scripts/check_net_handle.py` 对本树 0 违规;若改了白名单目录(`Drivers/BSP/NET/`、`test/host/`), + 自行按 C1~C7 逐条自查(门禁不代劳) + +## 7. 相关文档 + +这一节只做导航,契约内容不在别处重复。 + +| 想知道什么 | 去哪 | +|---|---| +| 常量定义与「零依赖」为什么重要 | `Drivers/BSP/NET/net_fd.h` 文件头注释 | +| 门禁 R1~R5 的判定细节、盲区、豁免理由、怎么改判据 | `docs/门禁说明/net-handle.md` §1 与 §6、§7、§8 | +| BSD Socket API 层面怎么用(含 fd 域与失效值那一行) | `docs/网络/BSD_Socket_API_使用指南.md` §2.3 | +| 这类陷阱的现场判读(含 220 banner 误导链的精简版) | `docs/问题记录/CH395F_Trap_Records.md` 「网络 fd 失效值」节 | +| 监听生命周期与网络代次(为什么代次变化会触发批量关闭) | `docs/网络/网络自愈架构设计.md` | diff --git a/docs/门禁说明/README.md b/docs/门禁说明/README.md index 5a6bdbcb..a202e458 100644 --- a/docs/门禁说明/README.md +++ b/docs/门禁说明/README.md @@ -1,7 +1,7 @@ # 门禁逐项说明(每种门禁一篇) -> 本目录逐项说明各门禁:**声明的 52 个钩子到底在干什么、拦谁、放谁、什么时候会骗人**——其中 4 根慢钩子带 -> `stages: [manual]`,一次 `git commit` 只实跑 48 根(口径见下条)。 +> 本目录逐项说明各门禁:**声明的 53 个钩子到底在干什么、拦谁、放谁、什么时候会骗人**——其中 4 根慢钩子带 +> `stages: [manual]`,一次 `git commit` 只实跑 49 根(口径见下条)。 > 每个门禁一篇,八段固定结构:查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / > **限制与盲区** / 豁免与基线 / 改门禁本身要注意什么。**最后一节是这套文档存在的理由**—— > 一份只看"拦了什么"的门禁文档,会让人以为绿就是对的。 @@ -9,7 +9,7 @@ - 配置事实源:`.pre-commit-config.yaml`。**钩子数的唯一口径 = YAML 解析后的 hook 条目数**,不是文件里的文本行数。 自查(打印声明数;加/删一条钩子后,这个数要与 **AGENTS.md 的「共 N 个钩子」**、**本目录 §2 标题**同时对齐): `& '.venv\Scripts\python.exe' -c "import yaml; d=yaml.safe_load(open('.pre-commit-config.yaml', encoding='utf-8')); print(sum(len(r['hooks']) for r in d['repos']))"` - → **52**(2026-10-26:49 → 50 加 `generated-fresh`;2026-10-27:50 → 51 加 `nested-comment`; + → **53**(2026-10-26:49 → 50 加 `generated-fresh`;2026-10-27:50 → 51 加 `nested-comment`; 2026-10-28:51 → 52 加 `id-check-new`、随即 52 → 51 摘掉 `id-check`(退役全库语料审计);2026-10-29:51 → 52 加 `skill-size`(SKILL.md 写侧上限与 reference 指针,详见 [`skill-size.md`](skill-size.md)); 同日 52 → **51** 退役 `id-check-new`——只查新增行的编号门禁整体退场,脚本与白名单移入 `scripts/archive/id_gate/`,此后**编号形态没有机器面**(留档 [`id-check-new.md`](id-check-new.md)); @@ -17,50 +17,51 @@ 详见 [`mermaid-syntax.md`](mermaid-syntax.md)); 2026-11-17:52 → 51 摘掉 `iec104-unit-test`(旧自研协议层三源随 vendor 库接入整体删除,测试脚本 `test/host/iec104/run_unit_test.py` 已不存在(该目录已删除 2026-11-18)⇒ 死钩子,每次触发必 RC=2); - 2026-11-18:51 → **52** 加 `iec104-tcp`(IEC 104 真实回环 11 条 TCP 用例,`stages: [manual]`))。 - ⇒ **两笔合并后声明数仍是 52,但结构变了:pre-commit 阶段 48 → 47、manual 3 → 4。** + 2026-11-18:51 → **52** 加 `iec104-tcp`(IEC 104 真实回环 11 条 TCP 用例,`stages: [manual]`); + 同日 52 → **53** 加 `net-handle`(网络 fd 失效值契约:数值形态判据 / 零初始化 static / memset 后不回填 / + `if (fd)` / 契约头文件,详见 [`net-handle.md`](net-handle.md)))。 ⚠ **别用 `grep -c` 去数配置里的声明行**:该文件里有一条**注释掉的**候选钩子(clang-format,第 65 行), - 文本 grep 会多算 1(当前口径 52 会数成 53)——「声明比文档多 1 / 实跑又少一档」这种三个数不同源的争执就是这么来的。真要 grep, + 文本 grep 会多算 1(当前口径 53 会数成 54)——「声明比文档多 1 / 实跑又少一档」这种三个数不同源的争执就是这么来的。真要 grep, 用**锚定行首缩进**的模式(它天然跳过以 # 开头的注释行)2026-10-28 实测直接得 **51**(当时口径)、 - 2026-11-18 复测得 **52**,均与 YAML 口径一致; + 2026-11-18 复测得 **53**,均与 YAML 口径一致; 会多算 1(比口径多 1)的是**不锚定行首、按子串**匹配声明行的写法(那条被注释掉的候选也被它算进去)。 ⚠ 反过来的坑也真踩过(2026-10-27):在配置**注释里复述那个 grep 字面量**,会让文本 grep 再虚高 1—— 数数只认 YAML 解析,注释与文档里都别写出那个字面量(`docs/门禁说明/nested-comment.md` §8 记了现场)。 实跑侧口径:`scripts/ci_local.py` 的静态门禁汇总行 `[SUMMARY] …: pre-commit hooks -- passed=A failed=B skipped=C`(方括号里那一段是**层级名**,脚本输出与文档层的语义名正分头迁移 → 抓这行**按 `passed=` 字段匹配**,别把层级名前缀写死进字面量,否则会 grep 不到而误判「没有实跑数」), - `A+B+C` = **pre-commit 阶段**的钩子数(**47** = 52 − 4 根 `stages: [manual]` − `gitlint`;2026-11-17 摘 + `A+B+C` = **pre-commit 阶段**的钩子数(**48** = 53 − 4 根 `stages: [manual]` − `gitlint`;2026-11-17 摘 `iec104-unit-test` 前是 48,2026-10-30 加 `mermaid-syntax` 前该式子右侧是 51/47),再加 `gitlint` 1 条 (它声明在本配置的 `repo: jorisroovers/gitlint` 条目、`stages: [commit-msg]`(第 70 行), `--hook-stage commit` 的枚举不含它——**2026-11-18 实测**: - `--hook-stage commit` 枚举 **47 行** / `manual` 枚举 **51 行** / YAML 解析声明 **52**(47 + 4 + 1 = 52, + `--hook-stage commit` 枚举 **48 行** / `manual` 枚举 **52 行** / YAML 解析声明 **53**(48 + 4 + 1 = 53, 差的那个就是 `gitlint`;旧说法「gitlint 声明在上游清单、本配置里查不到」已于 2026-10-30 随 `stages:` 接线作废) - → 47 + 1 = **48 = 一次 `git commit` 实跑的钩子数**;再加 4 根 manual 阶段的慢钩子才是声明数 52,三数同源(2026-10-29 加 `skill-size` 之前这四个数是 51 / 47 / 48;2026-10-30 加 `mermaid-syntax` 后是 52 / 48 / 49;**2026-11-18 摘 `iec104-unit-test` 并加 `iec104-tcp` 后是 52 / 47 / 48**)。 + → 48 + 1 = **49 = 一次 `git commit` 实跑的钩子数**;再加 4 根 manual 阶段的慢钩子才是声明数 53,三数同源(2026-10-29 加 `skill-size` 之前这四个数是 51 / 47 / 48;2026-10-30 加 `mermaid-syntax` 后是 52 / 48 / 49;2026-11-18 摘 `iec104-unit-test` 并加 `iec104-tcp` 后是 52 / 47 / 48;**同日加 `net-handle` 后是 53 / 48 / 49**)。 枚举自查(不执行任何钩子,`SKIP` 列全部 id):`SKIP=<全部 id> -m pre_commit run --all-files --hook-stage commit` - 输出 47 行、`--hook-stage manual` 输出 51 行(47 常规 + 4 慢的)。 + 输出 48 行、`--hook-stage manual` 输出 52 行(48 常规 + 4 慢的)。 - **四根慢钩子在 manual 阶段**:`cppcheck`、`test-cppcheck`、`test-coverage`、`iec104-tcp` 带 `stages: [manual]` → `git commit` 阶段**不跑**(实测前三根合计约 165 s,占一次带代码提交耗时的约三分之二; `iec104-tcp` 另需模拟器构建产物、单跑约 14 s),只在**远端 CI 的「手动阶段门禁」步** (`.gitea/workflows/ci.yml`,逐根 `--hook-stage manual`;⚠ `iec104-tcp` **远端 CI 跑不了**——CI 不构建模拟器) 与 `scripts/ci_local.py` 的 **manual 段**里跑。 本地手工复跑:`& '.venv\Scripts\python.exe' -m pre_commit run --all-files --hook-stage manual ` - (**一次只能给一个 id**,多 id 实测报 `unrecognized arguments`)。声明数仍是 52,变的是「提交期实跑几根」。 + (**一次只能给一个 id**,多 id 实测报 `unrecognized arguments`)。声明数仍是 53,变的是「提交期实跑几根」。 - 通用机制(三个阶段 = `pre-commit` / `commit-msg` / `manual`、stash 陷阱、`always` 已废、增量拦截三段式、旧 §2.x 查号表): `docs/代码规范/pre-commit使用说明.md` §2。 -- 快速自查(不等提交):`& '.venv\Scripts\python.exe' scripts/ci_local.py`(静态段 47 根 + manual 段四根 + 提交信息门禁 + 体积门禁 + 主机侧纯逻辑单测;manual 段默认跑)。 +- 快速自查(不等提交):`& '.venv\Scripts\python.exe' scripts/ci_local.py`(静态段 48 根 + manual 段四根 + 提交信息门禁 + 体积门禁 + 主机侧纯逻辑单测;manual 段默认跑)。 ## 1. 三种拦截姿态(先分清这个,报错时才知道该干什么) | 姿态 | 含义 | 有哪些 | 失败时该做什么 | |---|---|---|---| | **改写型** | 不报错,直接改你的文件 | `trailing-whitespace`、`end-of-file-fixer` | 重新 `git add` 被改的文件再提交(它改的是工作区,不是索引) | -| **硬拦截** | 违反即失败,没有存量豁免 | `cppcheck`、`coding-standard`、`doc-links`、`no-mojibake`、`mem-budget`、`ui-golden`、`font-charset`、`lv-conf-sync`、`task-table`、`mem-numbers`、`registration-check`、`cubemx-survival`、`test-suite-switch`、`mermaid-syntax`(基线为空,先例是已退役的 `id-check-new`「零语料」;唯一排除面 = 外部资料目录,见其专篇 §7)、21 个主机单测、官方 5 个、`gitlint` | 只能改代码或改文档;**不要**找豁免开关 | +| **硬拦截** | 违反即失败,没有存量豁免 | `cppcheck`、`coding-standard`、`doc-links`、`no-mojibake`、`mem-budget`、`ui-golden`、`font-charset`、`lv-conf-sync`、`task-table`、`mem-numbers`、`registration-check`、`cubemx-survival`、`test-suite-switch`、`mermaid-syntax`(基线为空,先例是已退役的 `id-check-new`「零语料」;唯一排除面 = 外部资料目录,见其专篇 §7)、`net-handle`(基线为空,白名单见其专篇 §7)、21 个主机单测、官方 5 个、`gitlint` | 只能改代码或改文档;**不要**找豁免开关 | | **增量拦截** | 规则恒生效,但存量钉在基线/台账里,只许减不许增 | `layer-deps`(3 条,2026-10-25 还清 UI 记录 3 条)、`bsp-err`(38 条)、`generated-fresh`(5 处 `docs/images/` 配图存量,脚本内 `BASELINE`)、`nested-comment`(2 处主机侧假件头,`test/host/common/`,脚本内 `BASELINE`) | 报错先分清是**新增**还是**存量搬家**:`--verbose` 看归类,`--prune` 看已还清 | | **只查新增** | 只看本次改动的增量,没有存量基线,也没有台账 | ~~`id-check-new`~~(**2026-10-29 退役**,脚本在 `scripts/archive/id_gate/`;这一姿态已无现役门禁) | 手工复查时才谈得上:改成语义短语(门禁不再跑,行内 `[编号豁免]` 也随之失效) | ⚠ 增量拦截最容易误会的一点:**绿灯不等于没问题**,只等于"没有比上次更差"。 每个增量拦截门禁的基线数字都写进它自己的文档,读那篇时第一眼看的就是"现在在册多少条"。 -## 2. 索引(52 个 hook → 30 篇,其中 2 篇是已退役门禁的留档 + 2 根只有本表指针(专篇待补)+ 1 根详解在 docs/测试说明/) +## 2. 索引(53 个 hook → 31 篇,其中 2 篇是已退役门禁的留档 + 2 根只有本表指针(专篇待补)+ 1 根详解在 docs/测试说明/) > 带 `stages: [manual]` 的四根(`cppcheck` / `test-cppcheck` / `test-coverage` / `iec104-tcp`)**提交期不跑**,只在远端 CI 的 > 「手动阶段门禁」步与 `scripts/ci_local.py` 的 manual 段跑(⚠ `iec104-tcp` 远端 CI 跑不了,见该行说明);下表对应各行的「文档」列已标注。 @@ -81,6 +82,7 @@ | [`task-table.md`](task-table.md) | `task-table` | README/AGENTS 里的任务表是否与 `Src/freertos.c` 一致 | `README.md`、`AGENTS.md`、`Src/freertos.c` | 已写 | | [`registration-check.md`](registration-check.md) | `registration-check` | 新 `.c` 是否双端注册(Keil 工程 + 模拟器 CMake);UI 页面描述符表是否接线 | `.c`、`.uvprojx`、`CMakeLists.txt` | 已写 | | [`nested-comment.md`](nested-comment.md) | `nested-comment` | 块注释体内再出现 /*(ARMCC 9-D 嵌套注释;诱因是注释里写路径通配) | 全仓 `.c/.h`(第三方与生成物除外) | 已写 | +| [`net-handle.md`](net-handle.md) | `net-handle` | 网络 fd 失效值契约:数值形态判据 / 零初始化 static fd / memset 后不回填 / `if (fd)` / 契约头文件缺失(fd 0 是合法值,失效值必须 `NET_FD_INVALID`) | 全仓 `.c/.h`(第三方/生成物除外;`Drivers/BSP/NET/` 与 `test/host/` 为层内白名单) | 已写 | | [`skill-size.md`](`skill-size.md`) | `skill-size` | SKILL.md 不超插件写侧上限 65536 字节(**只在写侧校验、加载侧不查**:超限的技能照常能读、每次「生成草案」却被拒、永久卡在「生成中」)+ `reference/` 指针不悬空 + 不带 BOM | `.dsh/skills/**`(filenames 只当触发,判定始终全树扫) | 已写 | | [`generated-fresh.md`](generated-fresh.md) | `generated-fresh` | 生成器幂等性:把生成器重跑到**系统临时目录**,与工作区逐字节必须一致(不一致 = 生成物比生成器旧) | `tools/**`、UI 源码、`ui_menu_tree.txt`、`ui_cn_chars.txt`、`docs/images/*.svg`、两份注册表 | 已写 | | [`lv-conf-sync.md`](lv-conf-sync.md) | `lv-conf-sync` | 两份 `lv_conf.h`(MCU / 模拟器)的特性子集是否一致 | 两份 lv_conf 或脚本 | 已写 | @@ -114,7 +116,7 @@ ## 4. 现状与下一步 -- **本目录 30 篇已全部成文**(2026-10-30 加 `mermaid-syntax` 一篇 → 30;2026-10-29 加 `skill-size` 一篇 → 29;2026-10-27 实测当时 27 篇;2026-10-28 当时复核:`docs/门禁说明/` 下除 README 外 28 篇,与上表「文档」列 +- **本目录 31 篇已全部成文**(2026-11-18 加 `net-handle` 一篇 → 31;2026-10-30 加 `mermaid-syntax` 一篇 → 30;2026-10-29 加 `skill-size` 一篇 → 29;2026-10-27 实测当时 27 篇;2026-10-28 当时复核:`docs/门禁说明/` 下除 README 外 28 篇,与上表「文档」列 **一一对应**——「有页无行」与「有行无页」两个差集都是空集;一行覆盖多个 hook 的行(`cppcheck`+`test-cppcheck`、 22 个 `*-unit-test`)按行内列举计。上一句写「23 篇」是存量误差:2026-10-25 连加 `bom-guard` / `setview-check` / `uinav-selftest` 三根、本轮加 `generated-fresh` 都没同步它(本轮前实有 25 篇)。 diff --git a/docs/门禁说明/net-handle.md b/docs/门禁说明/net-handle.md new file mode 100644 index 00000000..a28517ae --- /dev/null +++ b/docs/门禁说明/net-handle.md @@ -0,0 +1,160 @@ +# 网络句柄失效值契约(net-handle)— fd 不得靠"零初始化 + 数值形态"表达"未打开" + +> 一句话:**只要你的模块保存网络 fd,就必须显式初始化成 `NET_FD_INVALID`,并且只能用 +> `== NET_FD_INVALID` / `!= NET_FD_INVALID` 判"有没有"**——因为本项目的 fd 0 是**合法**描述符, +> 零初始化的 0 会被误当成"已打开"。本钩子在提交期机械拦截四类错误写法 + 契约头文件缺失。 +> 脚本 `scripts/check_net_handle.py`(纯标准库、只读,2026-11-18 接线)。 +> 契约正文与代码正反例 → 网络子系统文档(`docs/网络/` 下的「网络句柄失效值契约」篇);常量定义 → `Drivers/BSP/NET/net_fd.h`。 + +## 1. 它在查什么 + +| 规则 | 判定 | 典型命中写法(必须改) | +|---|---|---| +| **R1** | fd 形标识符(名字含 `fd` / `sock` / `socket` / `handle`,或结构体 fd 成员)与**整数字面量**比较;名字含 `handle` 的走"句柄发号器"弱规则(见 §6) | `if (ctx.fd >= 0)`、`if (sockfd == -1)`、`if (-1 == fd)`、`if (slot_handle == -1)` | +| **R2** | 文件作用域 `static` 的 fd 标量 / 含 fd 成员的结构体:无初始化器、`= {0}`、指定初始化器缺 fd 成员、fd 成员不等于 `NET_FD_INVALID` | `static int fd;`、`static ctx_t s_ctx;`、`static ctx_t s_ctx = {0};`、`static ctx_t s_ctx = { .state = 0 };`、`.fd = -1` | +| **R3** | `memset(对象, 0, ...)` 作用于含 fd 成员的结构体后,**5 行内**没有回填 `= NET_FD_INVALID` | `memset(&s_ctx, 0, sizeof(s_ctx));` 之后直接 `s_ctx.state = ...;` | +| **R4** | `if (fd)` / `if (!fd)` 这种"数值真值"判据 | `if (fd) { ... }`、`if (!ctx.fd) { ... }` | +| **R5** | 契约存在性:`Drivers/BSP/NET/net_fd.h` 定义 `NET_FD_INVALID`,且 `net_socket.h` include 它 | 头文件被删 / 宏被改名 / include 被删 | + +正确写法(本钩子必须放行): + +```c +/* 文件作用域:显式初始化 + 指定初始化器 */ +static ctx_t s_ctx = { + .fd = NET_FD_INVALID, /* 0 是合法 fd,不能靠零初始化 */ + .state = 0, +}; + +/* 判据:与契约常量比较 */ +if (s_ctx.fd != NET_FD_INVALID) { + net_close(s_ctx.fd); + s_ctx.fd = NET_FD_INVALID; +} +``` + +## 2. 为什么要它 + +板端 104 连不上(收到 FTP 的 220 banner)的真因不是"漏了一个 `-1`": + +1. `static` 的 fd 由 C 零初始化为 `0`; +2. 本项目 net 层 fd 域是 `0 .. NET_MAX_SOCKETS-1`,**0 合法**——失效值恰好落在合法值域里; +3. 判据写成 `fd >= 0`,于是"从未打开"被当成"持有 fd 0"; +4. 网络代际切换时,SNTP 的关闭逻辑对 fd 0 发 `net_close(0)`,把 FTP 的监听槽关掉; + ftpTask 重建监听、104 建链,最终两个服务抢同一芯片 socket。 + +这不是一个文件的事:同一个语言语义缺口(零初始化 = 失效)+ 同一种判据形态(数值比较)会在 +任何保存 fd 的模块重演。本钩子把它变成机器判定,不靠人记性——**修好一处是治标,拦住一类才是治本**。 + +## 3. 触发面 + +- 配置:`files: ^(.*\.(c|h)|scripts/check_net_handle\.py|\.pre-commit-config\.yaml)$`, + `pass_filenames: false`——**变更文件只当触发信号,判定恒扫全树**。 + 理由:R5 要判契约文件本身(改 `net_fd.h` 时被改的可能不是它),且"当前树 0 违规"才是可复核口径。 +- 扫描面 = 全仓 `.c/.h`,**排除**:`Drivers/CMSIS/`、`Drivers/STM32F4xx_HAL_Driver/`、`Middlewares/`、 + `Lib/`、`Drivers/BSP/dhara/`、`IEC60870-Slave/`、`App/protocol/iec60870/`(逐字节钉在上游的第三方)、 + `MDK-ARM/`、`scripts/archive/`、`docs/`(无 C 源)、`simulator/build/`、`simulator/SDL2/`、 + `test/host/iec104_netmcu/results/`(变异体生成物,故意植入缺陷)。 +- **白名单(R1~R4 不判)**:`Drivers/BSP/NET/`、`test/host/`。这不是漏判,见 §7。 + +单独自查: + +```bash +& '.venv\Scripts\python.exe' scripts/check_net_handle.py # 全树 +& '.venv\Scripts\python.exe' scripts/check_net_handle.py --selftest # 自证 +& '.venv\Scripts\python.exe' scripts/check_net_handle.py --verbose # 打印被跳过的数组清零等 +``` + +## 4. 报错怎么读 + +``` +FAIL [R1] App/sync/time_sntp.c: 第 N 行:`s_ctx.fd >= 0`——fd 形标识符与整数字面量比较; + 改用`s_ctx.fd == NET_FD_INVALID` / `s_ctx.fd != NET_FD_INVALID`(数值形态判据会随 fd 域/失效值变化失真) +``` + +- 每条都带**规则号 + 文件 + 行号 + 命中的原表达式 + 改法**,照改即可; +- `R2` 会点明缺哪个 fd 成员(`补 .fd = NET_FD_INVALID`); +- `R3` 会给"memset 的对象 + 5 行内应出现的那条赋值"; +- `R5` 报的是契约文件本身(缺文件 / 缺宏 / 缺 include),照任务书 §1 的模板补。 + +常见"假报警": + +| 现象 | 说明 | +|---|---| +| 注释里写着 `fd >= 0` 也报? | 不会。脚本先剥注释/字符串/字符字面量再判;反面教材写在注释里是安全的。 | +| `NET_FD_INVALID == -1` 报吗? | 不会。全大写宏/常量不当句柄。 | +| `sock_ok` / `sock_state` 报吗? | 不会。带 `_ok/_flag/_ready/_valid/_state/_err/_count/...` 后缀的是"关于 socket 的标量",不是保存 fd 的变量。 | +| 104 的 `handle == 0U` 报吗? | 不会(见 §6 的 handle 分档)。`handle < 0` / `== -1` 这种负数码仍报。 | + +## 5. 好处 + +- 把"零初始化 = 失效"这个**隐含假设**变成编译前的硬约束; +- 把"fd 域变了但判据还是老数字"这类**跨模块漂移**在提交期暴露,而不是等台架出现 220 banner; +- 新模块接入时不用背契约:写错就被点名,报错里直接给正确写法。 + +## 6. 限制与盲区 + +本闸是文本启发式,不是编译器前端。以下都**可能漏判**(知道比不知道强): + +- **槽数组**:`static ctx_t s_tab[8];` 与 `memset(s_tab, 0, sizeof(s_tab));` 不判 R2/R3—— + 槽表的"清零 = 全部空闲"是合法语义,逐槽身份由 `role/handle/gen` 一类状态守卫;要求 + C99 指定初始化器逐个回填 8 个槽不现实(`[0 ... 7]` 是 GCC 扩展,ARMCC 不吃)。 +- **跨文件类型**:含 fd 成员的结构体必须在**同一份被扫的 .c/.h 里**能看到定义;定义在别处且 + 本文件没有 include 文本时,R3 的类型推断会放弃(跳过而非误报)。 +- **指针参数**:`memset(p, 0, ...)` 的 `p` 若无法从本文件声明里解析出类型,R3 跳过。 +- **带下标的成员表达式**(`s_slots[i].fd >= 0`)不被 R1 识别:判据正则里的成员链只吃 + `a.b.c` / `p->b` 形态。当前树无此写法(`Drivers/BSP/NET/` 的槽表本来就在白名单里), + 但新代码若在别处写"数组元素里的 fd",这条会漏——靠评审与 R2/R3 兜。 +- **多行/宏包裹的条件**:把判据折成宏(`#define FD_OK(x) ((x) >= 0)`)或拆到多行,R1 只看 + 同一表达式内的形态,可能漏;宏体内若保持单行仍会被抓到。 +- **其它真值形态**:`while (fd)`、三目 `fd ? a : b`、`switch (fd)`、`(void)fd` 不在 R4 面内。 +- **`handle` 分档 = 句柄发号器弱规则**:`handle` 是不透明会话令牌(104 的失效值是 + `IEC104_NET_INVALID_SOCKET`,槽里另有真正的 `int fd`)。名字里**同时**含 `socket` 与 + `handle` 的(如 104 的 `socket_handle`)按 handle 档处理:它是不透明令牌,不是文件描述符。 + 判据: + - 与具名常量比较(`IEC104_NET_INVALID_SOCKET` / `UINTPTR_MAX` 等)→ **不判**(正则只匹配数字面量); + - 与 `0` 比较(`== 0U` / `!= 0U`)→ **不判**——发号器从 1 起、0 永不合法,"没有句柄"就是 0; + - 与负数字面量比较(`== -1` / `< 0` / `>= 0`)→ **判**(用数值形态表达失效,正是本契约拦的那类); + - 真值判断 `if (handle)` / `if (!handle)` → 由 R4 **照判**。 + 这是"弱规则"不是"不检查":104 侧以后若写 `if (handle)` 或 `handle == -1`,照样红; + 也**没有**把 `App/protocol/iec104/` 整目录加白名单。R2 的 static 标量只认 fd/sock 档。 +- **R2 只看文件作用域**:函数内 `static int fd;`、局部变量、结构体成员本身不在此规则面内 + (它们是 C1 的写作要求,靠评审与 R3/R4 兜)。 +- 本闸**不判**"fd 是否由申请者关闭"(C6 主人语义)与假对象 fd 域是否 0 基(C7)——那需要 + 运行时/测试语义,由主机单测与独立验收覆盖。 + +## 7. 豁免与基线 + +- **没有存量基线**:接线当日全树实扫即要求 0 违规(同类先例:`nested-comment` 之外的硬拦截)。 + 因此不提供"在册 N 条"的台账,也不接受"先记进基线以后还"。 +- **唯一豁免面是脚本内的 `WHITELIST`**(`Drivers/BSP/NET/`、`test/host/`),理由: + - `Drivers/BSP/NET/` 是契约的**层内实现者**:C4 明确允许 `0 <= fd < NET_MAX_SOCKETS` 区间校验; + fd 槽数组以"槽下标"为身份,`memset(p_sock, 0, ...)` 正是释放动作。对它套 R1~R4 会把正经 + 实现判红,属于规则与语义冲突,不是"给个方便"。 + - `test/host/` 是主机假对象:按 C7 从 0 基分配 fd,断言语域与生产不同;假对象自身的契约 + 合规性由 sntp 回归用例与独立验收复核。 +- **`handle` 名字族不算豁免、算规则分档**:句柄发号器的 0 永不合法(`s_next_handle` 从 1 起), + 与 fd 槽位的"0 是合法描述符"**不同源**,故 R1 对它只判"负数形态表达失效",`== 0U` 与"与具名 + 常量比较"不判;R4 的真值判断照判。判据与理由见 §6,不要用"给 `App/protocol/iec104/` 加白名单" + 来消红——那会连 `if (handle)` 一起放过。 +- **不允许**用 `#pragma` / 注释标记 / `SKIP=net-handle` 长期豁免。临时 `SKIP` 只按 + `docs/代码规范/pre-commit使用说明.md` §2 的紧急流程走,并必须在提交说明里写清原因与补做计划。 +- 若要新增豁免面:改脚本 `WHITELIST` 并**在同一笔提交里**补进本节,写清"为什么规则在这里 + 与语义冲突";只写文件、不写理由的豁免视同削弱检查。 + +## 8. 改门禁本身 + +- **自测**:`--selftest` 逐条打印(当前 **42 条断言**),覆盖: + - R1:`ctx.fd >= 0` / `sockfd == -1` / 反向字面量 `-1 == fd` 必抓;`!= NET_FD_INVALID`、 + 注释里的反面教材、函数调用 `fd()`、白名单路径不误报;`handle < 0` 必抓、`handle == 0U` + 不误报;104 的 `IEC104_Net_Close()` 判据(句柄族 vs 具名常量/0)不误报,而 `slot_handle == -1` + 仍必抓(证明弱规则不等于放行)。 + - R2:无初始化器 / `{0}` / 缺 fd 成员 / `.fd = -1` / 匿名 struct 必抓;正确指定初始化器、 + 无 fd 成员的 static、函数声明、句柄发号器不误报。 + - R3:memset 后不回填必抓;回填 / 无 fd 成员 / 整数组清零不误报。 + - R4:`if (fd)` / `if (!ctx.fd)` 必抓;`!= NET_FD_INVALID` 与普通布尔不误报。 + - R5:缺文件 / 缺 include / 齐备三态。 +- **改判据时**:必须先加一条 `--selftest` 断言再改实现(先红后绿);误报的处置是**收窄判据 + + 在 §6 写下盲区**,不是加文件豁免。 +- **改名/移动**会影响:配置里的 `files:` 正则、本文件的命令、`docs/门禁说明/README.md` 索引行。 + 钩子 id `net-handle` 被 `SKIP=` 与 `ci_local.py` 的汇总按名引用,改名要同步。 +- 本文件与脚本的计数(42 条断言)若变动,按 `docs/门禁说明/README.md` §2 的口径同步,不要只改一处。 diff --git a/docs/问题记录/CH395F_Trap_Records.md b/docs/问题记录/CH395F_Trap_Records.md index 1c816547..9408af2c 100644 --- a/docs/问题记录/CH395F_Trap_Records.md +++ b/docs/问题记录/CH395F_Trap_Records.md @@ -321,6 +321,39 @@ CH395F 以太网驱动与 NET 层的实证陷阱:现象、定案根因、修 - 口径冲突:`Test_Guide.md:1135` 的 TRAP-NET-07 行仍写"卡 FIN_WAIT_2/`close_socket`(RST)"(与 TRAP-NET-07 定案冲突);`:45` 的"TC704 40/40"与 `:880` 的"`PHASE7_MULTI_COUNT` ≤5"矛盾(HEAD 宏值仍是 8);`Drivers/BSP/NET/README.md:35` 与 `net_socket.c` 的"正常 FIN 路径零改动"与 TRAP-NET-18 二阶段矛盾。 - 证据通则:`*.log` 在 `.gitignore` 内 → 本文所有台架计数(40/40、34/34、227 轮、4 轮 11/11、13/13…)**脚本在库、日志未入库 = 不可复核**;TRAP-NET-20 引用的实验分支 `n30-chip-bench`(tip `eddbede`)不含 bench 源文件与 uvprojx 注册,裸机芯片台架无法从任何已提交状态重建(主分支存档见 `test/board/ch395f_reuse_bench.c`)。 +## 网络 fd 失效值:0 是合法句柄,零初始化等于「拿着别人的 fd」 + +读这一节是为了认出「看不出错、但把别的服务的 socket 关掉」那类现场。契约正文(条款、正反例、 +自查清单)在 `docs/网络/网络句柄失效值契约.md`,这里只记现场判读与规则。 + +- **状态**:✅ 已闭环(生产误判由提交 `90cc9a7d` 修,判据形态与主机假对象域随后整体迁移, + 机械门禁 `net-handle` 已接线) +- **现象**:104 主站连不上设备,抓包却看到链路建立后立刻收到 **FTP 的 `220` 欢迎行**——104 的 + TCP 连接实际落在 FTP 的监听槽上,两个监听器抢同一个芯片 Socket。 +- **误导链**:SNTP 从未开过 socket,文件作用域 `static` 的 `s_ctx.fd` 被 C 零初始化成 `0` + → 网卡就绪后网络代次变化触发 `time_sntp_run()` 的代次分支 → `s_socket_close()` 的判据 + `if (s_ctx.fd >= 0)` 对 `0` 成立 → `net_close(0)` 关掉 ftpTask 的监听槽(0 号 Socket 正是 + 首个 `net_socket()` 成功返回值)→ ftpTask 重建监听、104 又分配到槽 0 → 收到 `220`。 +- **判据**:`fd` 是 **CH395F Socket 下标 `0~NET_MAX_SOCKETS-1`**,不是操作系统描述符,**0 合法**; + 失效值只有 `NET_FD_INVALID`(定义在 `Drivers/BSP/NET/net_fd.h`)。任何 `>= 0` / `< 0` / + `== -1` / `if (fd)` 这类数值形态判据都会在「0 = 没有」与「0 = FTP 的监听」之间必然错一侧。 + 同类还查出一条被掩盖的事实:主机单测的假 `net_socket()` 曾从 **100** 起分配 fd(另一处从 3 / 9 起), + 与生产的 `0~7` 不相交,「零初始化 = 0」这一幕在主机侧永远演不出来,所以这类缺陷在 CI 上**恒绿**。 +- **为什么静态检查抓不到**:MISRA C:2012 Rule 9.1 只覆盖 automatic storage duration,文件作用域 + `static` 是 static storage duration 且 C99 保证零初始化 → **写法合规**;本仓 cppcheck 未挂 + `--addon=misra`,其 `uninitvar` 同样只对自动变量报警;`if (ctx.fd >= 0)` 在语法与类型层毫无可疑。 + 缺的是「0 对这个变量合不合法」这条**域知识**——只能靠项目契约 + 专属门禁补。 +- **落地**:①失效值收成具名常量 `NET_FD_INVALID`(`Drivers/BSP/NET/net_fd.h`,零依赖头,主机 + stub 也能取);②生产代码判据全部改成 `== / != NET_FD_INVALID`;③主机假对象改为 **0 基**并复刻 + 「未分配的 fd 关闭必须失败」,新增回归用例 `tc_cold_start_gen_change_no_close` + (`test/host/sntp/sntp_test.c`:冷启动断言无 fd → 代次跳变跑一轮 → 断言**零次关闭企图**); + ④静态门禁 `scripts/check_net_handle.py`(钩子名 `net-handle`)按 R1~R5 拦「整数字面量比较 / + 零初始化或缺 fd 成员的 static / memset 后未回填 / 数值真值判据 / 契约常量缺失」,规则细节与 + 豁免面 → `docs/门禁说明/net-handle.md`。 +- **下次别再犯(硬规则)**:**任何持有 fd 的变量,初值与判据都必须锚在 `NET_FD_INVALID` 上; + 只要这个值域里 0 是合法的,「没打开」就绝不能用零初始化表达,也绝不能靠 `>= 0` 判断。** + 写主机假对象时先问一句:**它的 fd 域和生产是同一个域吗?不是就等于没测。** + --- # 附录 A · 驱动关键点速查(细节以对应条目为准) diff --git a/scripts/check_net_handle.py b/scripts/check_net_handle.py new file mode 100644 index 00000000..3ecd99cf --- /dev/null +++ b/scripts/check_net_handle.py @@ -0,0 +1,849 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""网络句柄失效值契约门禁(net-handle)。 + +为什么要有这根钩子(2026-11-18): + 板端 104 连不上的真因不是"漏了一个 -1",而是一个语言语义缺口被多种纪律叠出来: + 文件作用域 `static` 的 fd 由 C 零初始化为 0,而本项目 net 层 fd 域是 0~7(0 是**合法** + 描述符),于是"从未打开"被 `fd >= 0` 判据当成"持有 fd",网络代际切换后误关别的服务的 + 监听槽,最终 104 建链拿到 FTP 的 220 banner。契约见 `docs/网络/网络句柄失效值契约.md` + 与 `Drivers/BSP/NET/net_fd.h`;本脚本把契约里可机械判定的部分搬到提交期。 + +规则(对应任务书 §4;R1~R4 判 C 源文本,R5 判契约文件存在): + R1 fd 形标识符(名字含 fd / sock / socket / handle)与整数字面量比较。 + R2 文件作用域 `static` 的 fd 标量 / 含 fd 成员的结构体:无初始化器、`= {0}`、 + 或指定初始化器缺 fd 成员 / fd 成员不是 NET_FD_INVALID。 + R3 `memset(对象, 0, ...)` 作用于含 fd 成员的结构体后 5 行内没有回填 NET_FD_INVALID。 + R4 `if (fd)` / `if (!fd)` 这种"数值真值"判据。 + R5 `Drivers/BSP/NET/net_fd.h` 定义 NET_FD_INVALID,且 `net_socket.h` include 它。 + +白名单(为什么不是"漏判"): + `Drivers/BSP/NET/` 是契约的**层内**实现者:C4 明确允许它做 `0 <= fd < NET_MAX_SOCKETS` + 区间校验,且 fd 槽数组以"槽下标"为身份、清零即释放(`memset(p_sock, 0, ...)` 正是 + 回收动作),对它套 R1~R4 会把正经实现判成违规。`test/host/` 是主机假对象,fd 域按 + C7 从 0 起分配,同样需要按测试语域写断言。两者的契约合规性由 R5 + 独立验收复核。 + +用法: + python scripts/check_net_handle.py # 全仓扫描(钩子也是全仓扫描) + python scripts/check_net_handle.py --selftest # 自证:正例必抓、正确写法不误报 + python scripts/check_net_handle.py --verbose # 打印被跳过的路径与判定细节 + +退出码:0 = 0 违规;1 = 有违规;2 = 契约文件缺失或内部错误(与 pre-commit 环境错误同口径)。 +""" + +from __future__ import annotations + +import argparse +import os +import re +import sys + +REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + +NET_FD_H = "Drivers/BSP/NET/net_fd.h" +NET_SOCKET_H = "Drivers/BSP/NET/net_socket.h" +INVALID = "NET_FD_INVALID" + +# 第三方 / 生成物 / 归档:跳过(与 cppcheck、coding-standard 的排除面同口径 + 归档脚本)。 +SKIP_PREFIXES = ( + "Drivers/CMSIS/", + "Drivers/STM32F4xx_HAL_Driver/", + "Drivers/BSP/dhara/", + "Middlewares/", + "Lib/", + "MDK-ARM/", + "IEC60870-Slave/", + "App/protocol/iec60870/", + "scripts/archive/", + ".opencode/", + ".agents/", + ".git/", + ".venv/", + "ci-artifacts/", + "docs/", + "simulator/build/", + "simulator/SDL2/", + "test/host/iec104_netmcu/results/", # 变异体生成物(故意植入缺陷,不能当源码判) +) + +# R1~R4 的白名单(语义见文件头)。三者分开写,方便以后按需收窄。 +WHITELIST = { + "R1": ("Drivers/BSP/NET/", "test/host/"), + "R2": ("Drivers/BSP/NET/", "test/host/"), + "R3": ("Drivers/BSP/NET/", "test/host/"), + "R4": ("Drivers/BSP/NET/", "test/host/"), +} + +EXPR = r"[A-Za-z_]\w*(?:\s*(?:\.|->)\s*[A-Za-z_]\w*)*" +LITERAL = r"(?:-\s*)?\d+(?:[uUlL]+)?" +OP = r"(?:>=|<=|==|!=|>|<)" + +CMP_EXPR_FIRST = re.compile( + r"(?])(" + EXPR + r")\s*(" + OP + r")\s*(" + LITERAL + r")\b") +CMP_LITERAL_FIRST = re.compile( + r"(? str: + """把注释 / 字符串 / 字符字面量的内容替换成空格,保留换行与偏移。 + + 为什么必须做:本仓注释里大量写着 `fd >= 0` 这种**反面教材**(time_sntp.c 的 + 指针注释就是这么写的),不剥注释会把教材当违规。字符串里的 banner 同理。 + """ + out = [] + i = 0 + n = len(text) + state = "code" # code | line | block | str | chr + while i < n: + c = text[i] + nxt = text[i + 1] if i + 1 < n else "" + if state == "code": + if c == "/" and nxt == "/": + state = "line" + out.append(" ") + i += 2 + continue + if c == "/" and nxt == "*": + state = "block" + out.append(" ") + i += 2 + continue + if c == '"': + state = "str" + out.append(" ") + i += 1 + continue + if c == "'": + state = "chr" + out.append(" ") + i += 1 + continue + out.append(c) + i += 1 + continue + # 非 code 状态:吞掉内容(换行保留,块注释换行要留给行号) + if c == "\n": + out.append("\n") + i += 1 + continue + if state == "line": + out.append(" ") + i += 1 + if nxt == "": + state = "code" + continue + if state == "block": + if c == "*" and nxt == "/": + out.append(" ") + i += 2 + state = "code" + continue + out.append(" ") + i += 1 + continue + if state == "str": + if c == "\\": + out.append(" ") + i += 2 + continue + if c == '"': + state = "code" + out.append(" ") + i += 1 + continue + if state == "chr": + if c == "\\": + out.append(" ") + i += 2 + continue + if c == "'": + state = "code" + out.append(" ") + i += 1 + continue + return "".join(out) + + +def line_of(text: str, pos: int) -> int: + """偏移 -> 1 基行号。""" + return text.count("\n", 0, pos) + 1 + + +# ------------------------------------------------------------------ 名字判定 +def is_fd_name(name: str) -> bool: + """fd 形标识符:名字含 fd / sock / socket / handle(整词形态)。 + + 排除项都有实测理由: + - 全大写(`NET_MAX_SOCKETS`、`NET_FD_INVALID`)是宏/常量,不是"持有中的句柄"; + - `fd_bits` / `fd_mask` / `fd_set` 是位掩码,不是描述符; + - `handler` / `handled` 不是句柄(`handle` 只认整词与 `_handle` 结尾)。 + """ + if not name: + return False + if name.isupper(): + return False + low = name.lower() + # 状态/布尔/计数后缀:`sock_ok`(echo 是否成功)、`sock_state`、`sock_count` + # 这类名字带 sock 但不是句柄,按名字面判会误报(2026-11-18 在 test/board 实测到 + # `if (sock_ok)`)。它们是"关于 socket 的标量",不是"保存 fd 的变量"。 + if low.endswith(("_bits", "_mask", "_set", "_ok", "_flag", "_ready", "_valid", + "_state", "_err", "_count", "_num", "_idx", "_len", "_size")): + return False + if re.search(r"(^|_)fd(_|$)", low) or low.endswith("fd"): + return True + if "sock" in low: + return True + if re.search(r"(^|_)handle(s)?(_|$)", low): + return True + return False + + +def fd_name_kind(name: str) -> str | None: + """把 fd 形名字分成两档:'fd'(fd/sock,真实描述符)与 'handle'(不透明句柄)。 + + 为什么要分档(2026-11-18 实测):IEC 104 后端的 `handle` 是 uintptr_t 会话令牌, + 它自己的头文件写明失效值是 IEC104_NET_INVALID_SOCKET(UINTPTR_MAX),而槽里 + 同时还有真正的 `int fd`。对 `handle == 0U`("没有句柄值")要求改写成 + NET_FD_INVALID 会**改坏语义**;真正属于本契约那一类的是"用 -1 / <0 这种数值 + 形态表达失效"。故 handle 档只抓负数字面量(-1、< 0),fd/sock 档抓任何整数 + 字面量比较。 + + 命名含 `handle` 者一律归 handle 档(2026-11-18 实测):`socket_handle` 同时含 + socket 与 handle,但它是 104 的不透明会话令牌(uintptr_t),不是文件描述符; + 若按 socket 归到 fd 档,就会逼着把 `socket_handle == 0U` 改写成 + `== NET_FD_INVALID`,改坏语义。名字面里出现 handle 就说明持有者自认这是句柄。 + """ + if not is_fd_name(name): + return None + low = name.lower() + if re.search(r"(^|_)handle(s)?(_|$)", low): + return "handle" + if re.search(r"(^|_)fd(_|$)", low) or low.endswith("fd") or "sock" in low: + return "fd" + return "handle" + + +def is_fd_member(name: str) -> bool: + """结构体成员是否是"fd 成员":fd / sockfd / *_fd。比 R1 的名字面窄。""" + low = name.lower() + if low.endswith(("_bits", "_mask", "_set")): + return False + return bool(re.search(r"(^|_)fd(_|$)", low) or low.endswith("fd")) + + +def last_name(expr: str) -> str: + """取成员表达式最后一个标识符:`s_ctx.fd` -> fd;`p->sockfd` -> sockfd。""" + parts = re.split(r"->|\.", expr) + return parts[-1].strip() + + +# ------------------------------------------------------------------ struct 定义 +def _match_brace(code: str, open_pos: int) -> int: + """从 `{` 开始做括号配对,返回匹配的 `}` 下标;失败返回 -1。""" + depth = 0 + i = open_pos + while i < len(code): + if code[i] == "{": + depth += 1 + elif code[i] == "}": + depth -= 1 + if depth == 0: + return i + i += 1 + return -1 + + +def parse_members(body: str) -> list[str]: + """从 struct 体里取成员名(跳过函数指针、位域、嵌套块)。""" + names = [] + for chunk in body.split(";"): + c = chunk.strip() + if not c or "(" in c: + continue + c = c.split(":")[0].strip() + m = re.search(r"([A-Za-z_]\w*)\s*(?:\[[^\]]*\])?\s*$", c) + if m: + names.append(m.group(1)) + return names + + +def collect_struct_defs(code: str) -> dict[str, set[str]]: + """收集 typedef / 具名 struct 的类型名 -> 成员集合。""" + types: dict[str, set[str]] = {} + for m in re.finditer(r"\b(struct|union)\s*([A-Za-z_]\w*)?\s*\{", code): + open_pos = m.end() - 1 + close_pos = _match_brace(code, open_pos) + if close_pos < 0: + continue + body = code[open_pos + 1:close_pos] + members = set(parse_members(body)) + prefix = code[max(0, m.start() - 16):m.start()] + tail = code[close_pos + 1:close_pos + 200] + alias_m = re.match(r"\s*([A-Za-z_]\w*)\s*;", tail) + tag = m.group(2) + if "typedef" in prefix.split() or prefix.rstrip().endswith("typedef"): + if alias_m: + types[alias_m.group(1)] = members + if tag: + types[tag] = members + if alias_m and ("typedef" in prefix): + types[alias_m.group(1)] = members + return types + + +def fd_members(members: set[str]) -> set[str]: + """成员集合里的 fd 成员名。""" + return {x for x in members if is_fd_member(x)} + + +# ------------------------------------------------------------------ 文件作用域 static +def file_scope_statics(code: str) -> list[str]: + """返回文件作用域(大括号深度 0)的 static 声明语句文本。""" + stats = [] + depth = 0 + line_start = 0 + stmt_start = None + i = 0 + n = len(code) + while i < n: + c = code[i] + if depth == 0 and stmt_start is None and code.startswith("static", i) and ( + i == 0 or not (code[i - 1].isalnum() or code[i - 1] == "_")): + prev_nl = code.rfind("\n", 0, i) + lead = code[prev_nl + 1:i] + if lead.strip() == "": # 声明行行首(允许缩进) + stmt_start = i + if c == "{": + depth += 1 + elif c == "}": + depth -= 1 + elif c == ";" and depth == 0 and stmt_start is not None: + stats.append(code[stmt_start:i + 1]) + stmt_start = None + elif c == "\n" and depth == 0 and stmt_start is not None: + # 跨行声明继续;但函数定义 `static void f(...)` 的头行以 { 结束, + # 它会在 depth>0 处走到 ;(函数体内的分号),由 contains('(') 过滤。 + pass + i += 1 + return stats + + +def split_decl(decl: str) -> tuple[str, str | None, str | None]: + """拆 `static Type name = init;` -> (declarator, init, inline_struct_body)。""" + s = decl.strip() + s = re.sub(r"^static\b", "", s).strip() + s = s[:-1].strip() if s.endswith(";") else s + init = None + body = None + # 找顶层 '='(结构体体内可能有 '=',但 inline struct 的情况先按首个 '{' 处理) + brace = s.find("{") + is_inline_struct = brace >= 0 and re.search(r"\b(struct|union)\b", s[:brace]) + if is_inline_struct: + # inline struct: `struct { ... } name` / `struct {...} name = {...}` + close = _match_brace(s, brace) + if close > 0: + after = s[close + 1:] + body = s[brace + 1:close] + eq = after.find("=") + if eq >= 0: + init = after[eq + 1:].strip() + after = after[:eq] + return after.strip(), init, body + eq = s.find("=") + if eq >= 0: + init = s[eq + 1:].strip() + s = s[:eq].strip() + return s, init, body + + +def var_type_and_name(declarator: str) -> tuple[str | None, str | None]: + """从声明符里取 (类型名, 变量名);函数/函数指针/数组返回 (None, None) 或带标记。""" + if "(" in declarator: + return None, None + ids = re.findall(r"[A-Za-z_]\w*", declarator) + if not ids: + return None, None + name = ids[-1] + type_tokens = [t for t in ids[:-1] if t not in TYPE_QUALIFIERS] + # 指针星号不影响类型名;多维/数组由调用方用 '[' 判断 + return (type_tokens[0] if type_tokens else None), name + + +def check_static_stmt(stmt: str, types: dict[str, set[str]], rel: str, hits: list) -> None: + """R2:单条文件作用域 static 声明。""" + declarator, init, inline_body = split_decl(stmt) + if "[" in declarator.split("=")[0]: + return # 槽数组:清零即"全部空闲",逐槽身份由状态机守卫(§6 盲区) + type_name, name = var_type_and_name(declarator) + if name is None: + return + members: set[str] | None = None + if inline_body is not None: + members = set(parse_members(inline_body)) + elif type_name and type_name in types: + members = types[type_name] + fd_names = fd_members(members) if members else set() + + if fd_names: + if init is None: + hits.append((rel, "R2", "文件作用域 static 结构体 `%s` 含 fd 成员 %s 但无初始化器;" + "用指定初始化器 .%s = %s" + % (name, sorted(fd_names), sorted(fd_names)[0], INVALID))) + return + body = init.strip() + if re.fullmatch(r"\{\s*0[uUlL]*\s*\}", body): + hits.append((rel, "R2", "`%s` 用 `= {0}` 清零初始化,fd 成员落成 0(0 是合法 fd);" + "改用指定初始化器 .%s = %s" + % (name, sorted(fd_names)[0], INVALID))) + return + designated = dict(re.findall(r"\.\s*([A-Za-z_]\w*)\s*=\s*([^,}]+)", body)) + if not designated: + hits.append((rel, "R2", "`%s` 的初始化器不是指定初始化器,无法保证 fd 成员为 %s;" + "改用 .%s = %s" % (name, INVALID, sorted(fd_names)[0], INVALID))) + return + for fd in sorted(fd_names): + if fd not in designated: + hits.append((rel, "R2", "`%s` 的指定初始化器缺 fd 成员 `.%s`(零初始化 = 0 = 合法 fd);" + "补 .%s = %s" % (name, fd, fd, INVALID))) + elif designated[fd].strip().strip("()").strip() != INVALID: + hits.append((rel, "R2", "`%s.%s` 初始化为 `%s`,不是契约常量 %s" + % (name, fd, designated[fd].strip(), INVALID))) + return + + # 标量 fd(`static int fd;`):只认 fd/sock 档。`static uintptr_t s_next_handle` + # 是一句柄**发号器**(单调递增、0 保留),不是"持有中的 fd",见 fd_name_kind 说明。 + if fd_name_kind(name) == "fd": + if init is None: + hits.append((rel, "R2", "文件作用域 static fd 标量 `%s` 无初始化器(会落成 0 = 合法 fd);" + "改为 `static int %s = %s;`" % (name, name, INVALID))) + elif init.strip().strip("()").strip() != INVALID: + hits.append((rel, "R2", "文件作用域 static fd 标量 `%s` 初始化为 `%s`,不是契约常量 %s" + % (name, init.strip(), INVALID))) + + +# ------------------------------------------------------------------ 变量类型表 +def collect_var_types(code: str) -> dict[str, str]: + """粗粒度变量类型表(供 R3 用):名字 -> 类型名。后出现者覆盖先出现者。""" + vtypes: dict[str, str] = {} + decl_re = re.compile( + r"(?= 0`)→ 判(用数值形态表达失效,正是本契约拦的); +# - 真值判断 `if (handle)` / `if (!handle)` → 仍由 R4 判(弱规则不是"不检查")。 +HANDLE_FAMILY_CONSTANTS = ( + "IEC104_NET_INVALID_SOCKET", "IEC104_NET_INVALID_HANDLE", + "UINTPTR_MAX", "INTPTR_MAX", "SIZE_MAX", +) + + +def handle_family_kind(code: str) -> str | None: + """本文件是否声明/使用了某句柄族的具名失效常量;返回该常量名(用于修复建议)。""" + for name in HANDLE_FAMILY_CONSTANTS: + if re.search(r"\b" + re.escape(name) + r"\b", code): + return name + return None + + +def should_flag(kind: str, literal: str, op: str) -> bool: + """该名字档位 + 该操作数是否算违规(见 fd_name_kind 的理由)。 + + handle 档(句柄发号器,0 永不合法)只抓"用负数域表达失效":`== -1` / `< 0` / `>= 0`。 + `== 0U` 是"没有句柄值"的检查,不属于本契约的 fd 失效值类;与具名常量比较则根本不会 + 走到这里(正则只匹配整数字面量)。 + """ + if kind == "fd": + return True + lit = literal.strip() + if lit.startswith("-"): + return True + return lit.rstrip("uUlL") == "0" and op.strip() in ("<", ">=") + + +def named_hint(expr: str, code: str = "") -> str: + """按名字档位给修复建议,避免把 104 句柄引向 NET_FD_INVALID。 + + 句柄族(0 永不合法)如果本文件里已有具名失效常量,就直接点名它——让报错能照抄。 + """ + if fd_name_kind(last_name(expr)) == "handle": + fam = handle_family_kind(code) + if fam: + return "该句柄族的具名失效常量 `%s`(句柄发号器的 0 永不合法,与 fd 的 0 合法域不同源)" % fam + return ("该句柄族的具名失效常量(网络 fd 用 NET_FD_INVALID;" + "104 会话句柄用 IEC104_NET_INVALID_SOCKET)") + return "`%s == %s` / `%s != %s`" % (expr, INVALID, expr, INVALID) + + +# ------------------------------------------------------------------ 各规则扫描 +def scan_text(rel: str, raw: str, types: dict[str, set[str]] | None = None, + verbose: bool = False) -> list[tuple[str, str, str]]: + """扫一份 C 源文本,返回 [(rel, 规则, 说明)]。rel 用 posix 相对路径。""" + code = strip_nocode(raw) + own_types = collect_struct_defs(code) + all_types: dict[str, set[str]] = dict(types or {}) + all_types.update(own_types) + hits: list[tuple[str, str, str]] = [] + + def whitelisted(rule: str) -> bool: + return any(rel.startswith(p) for p in WHITELIST[rule]) + + # R1:fd 形标识符 vs 整数字面量 + if not whitelisted("R1"): + for m in CMP_EXPR_FIRST.finditer(code): + expr, op, lit = m.group(1), m.group(2), m.group(3) + name = last_name(expr) + kind = fd_name_kind(name) + if kind and not expr_has_call(code, m.start(1)) and should_flag(kind, lit, op): + hits.append((rel, "R1", "第 %d 行:`%s %s %s`——fd 形标识符与整数字面量比较;" + "改用%s(数值形态判据会随 fd 域/失效值变化失真)" + % (line_of(code, m.start()), expr.strip(), op, lit, + named_hint(expr.strip(), code)))) + for m in CMP_LITERAL_FIRST.finditer(code): + lit, op, expr = m.group(1), m.group(2), m.group(3) + name = last_name(expr) + kind = fd_name_kind(name) + if kind and should_flag(kind, lit, op): + hits.append((rel, "R1", "第 %d 行:`%s %s %s`——fd 形标识符与整数字面量比较;" + "改用%s(数值形态判据会随 fd 域/失效值变化失真)" + % (line_of(code, m.start()), lit, op, expr.strip(), + named_hint(expr.strip(), code)))) + + # R2:文件作用域 static + if not whitelisted("R2"): + for stmt in file_scope_statics(code): + check_static_stmt(stmt, all_types, rel, hits) + + # R3:memset 后 5 行内无 NET_FD_INVALID 回填 + if not whitelisted("R3"): + vtypes = collect_var_types(code) + for m in re.finditer(r"\bmemset\s*\(\s*([^,]+?)\s*,\s*(?:0[uUlL]*|'\\0')\s*,", code): + arg = m.group(1).strip() + base, elem_expr, indexed = memset_target(arg) + if base is None: + continue + if not indexed and is_array_decl(code, base): + if verbose: + print("[net-handle] 跳过数组清零 %s:%d(槽表清零 = 全部空闲)" + % (rel, line_of(code, m.start()))) + continue + type_name = vtypes.get(base) + if not type_name or type_name not in all_types: + continue + fds = fd_members(all_types[type_name]) + if not fds: + continue + start_line = line_of(code, m.end()) + window = code.splitlines()[start_line - 1:start_line + 4] # 后续 ≤5 行 + text_win = "\n".join(window) + missing = [fd for fd in sorted(fds) + if not re.search(re.escape(elem_expr) + r"\s*(?:\.|->)\s*" + re.escape(fd) + + r"\s*=\s*" + re.escape(INVALID) + r"\b", text_win)] + if missing: + hits.append((rel, "R3", "第 %d 行:memset 清零 `%s`(类型 %s)后 5 行内没有回填" + " `%s.%s = %s`;清零后的 0 是合法 fd" + % (line_of(code, m.start()), elem_expr, type_name, + elem_expr, missing[0], INVALID))) + + # R4:if (fd) / if (!fd) + if not whitelisted("R4"): + for m in IF_TRUTHY.finditer(code): + neg, expr = m.group(1), m.group(2) + if is_fd_name(last_name(expr)): + hits.append((rel, "R4", "第 %d 行:`if (%s%s)`——把 fd 当布尔值判;" + "改用 `%s %s %s`" + % (line_of(code, m.start()), + "!" if neg.strip() else "", expr.strip(), + expr.strip(), "!=" if neg.strip() else "==", INVALID))) + return hits + + +def expr_has_call(code: str, start: int) -> bool: + """表达式前若紧跟标识符且再往前是调用形态,说明是函数返回值(不判)。""" + j = start - 1 + while j >= 0 and code[j] in " \t": + j -= 1 + return j >= 0 and code[j] in ")]" + + +def is_array_decl(code: str, name: str) -> bool: + """name 是否是数组对象(声明处带 `[`)。""" + return bool(re.search(r"\b[A-Za-z_]\w*\s+" + re.escape(name) + r"\s*\[", code)) + + +def memset_target(arg: str) -> tuple[str | None, str, bool]: + """解析 memset 第一参数:返回 (基名, 展示表达式, 是否元素/成员表达式)。""" + expr = arg.strip() + if expr.startswith("&"): + expr = expr[1:].strip() + # 去掉强转 `(void *)` + expr = re.sub(r"^\([^)]*\)\s*", "", expr).strip() + m = re.fullmatch(r"([A-Za-z_]\w*)\s*(\[[^\]]*\])?", expr) + if not m: + return None, expr, False + base = m.group(1) + index = m.group(2) + if index is None: + return base, base, False # 裸名字:是数组还是单对象,由调用方查声明 + return base, expr, True # 数组元素:单个对象 + + +# ------------------------------------------------------------------ R5 +def check_contract(root: str) -> list[tuple[str, str, str]]: + """R5:契约文件存在、定义常量、被 net_socket.h include。""" + hits = [] + fd_path = os.path.join(root, NET_FD_H) + sock_path = os.path.join(root, NET_SOCKET_H) + if not os.path.isfile(fd_path): + hits.append((NET_FD_H, "R5", "契约头文件不存在;先按 ci-artifacts/net-fd-contract-brief.md §1 建它")) + return hits + with open(fd_path, "r", encoding="utf-8", errors="replace") as f: + fd_text = strip_nocode(f.read()) + if not re.search(r"^\s*#\s*define\s+" + INVALID + r"\b", fd_text, re.M): + hits.append((NET_FD_H, "R5", "没有 `#define %s`;失效值契约的唯一定义处必须在这里" % INVALID)) + if not os.path.isfile(sock_path): + hits.append((NET_SOCKET_H, "R5", "net_socket.h 不存在")) + return hits + with open(sock_path, "r", encoding="utf-8", errors="replace") as f: + sock_raw = f.read() + # include 行必须对**原文**判:strip_nocode 会把 "net_fd.h" 这个字面量一起抹掉。 + # 只认行首 `#include`,注释里的同形文本不会被行首锚点吃掉。 + if not re.search(r'^\s*#\s*include\s*[<"]net_fd\.h[>"]', sock_raw, re.M): + hits.append((NET_SOCKET_H, "R5", "没有 `#include \"net_fd.h\"`;消费者拿不到契约常量")) + return hits + + +# ------------------------------------------------------------------ 全仓扫描 +def iter_sources(root: str) -> list[str]: + """全仓 .c/.h 相对路径(posix),按 SKIP_PREFIXES 排除。""" + out = [] + for dirpath, dirnames, filenames in os.walk(root): + rel_dir = os.path.relpath(dirpath, root).replace(os.sep, "/") + if rel_dir == ".": + rel_dir = "" + else: + rel_dir += "/" + dirnames[:] = sorted(d for d in dirnames + if not any((rel_dir + d + "/").startswith(p) for p in SKIP_PREFIXES) + and d not in (".git", ".venv", "build", "__pycache__")) + for fn in sorted(filenames): + if fn.endswith((".c", ".h")): + rel = rel_dir + fn + if any(rel.startswith(p) for p in SKIP_PREFIXES): + continue + out.append(rel) + return out + + +def scan_tree(root: str, verbose: bool = False) -> tuple[list, int]: + files = iter_sources(root) + types: dict[str, set[str]] = {} + texts = {} + for rel in files: + with open(os.path.join(root, rel), "r", encoding="utf-8", errors="replace") as f: + texts[rel] = f.read() + types.update(collect_struct_defs(strip_nocode(texts[rel]))) + hits = [] + for rel in files: + hits.extend(scan_text(rel, texts[rel], types, verbose=verbose)) + hits.extend(check_contract(root)) + return hits, len(files) + + +# ------------------------------------------------------------------ selftest +def selftest() -> int: + """内置正例/反例逐条断言:故意写错必须抓到,正确写法不误报。""" + checks = [] # (说明, 实际, 期望) + + def expect(desc, hits, rule, want): + got = sum(1 for h in hits if h[1] == rule) + checks.append((desc, got, want)) + + # ---- R1 + bad = "void f(void)\n{\n if (ctx.fd >= 0) { close_it(); }\n}\n" + expect("R1 抓 `ctx.fd >= 0`", scan_text("App/x.c", bad), "R1", 1) + bad2 = "void f(void)\n{\n if (sockfd == -1) { return; }\n}\n" + expect("R1 抓 `sockfd == -1`", scan_text("App/x.c", bad2), "R1", 1) + bad3 = "void f(void)\n{\n if (-1 == fd) { return; }\n}\n" + expect("R1 抓反向字面量 `-1 == fd`", scan_text("App/x.c", bad3), "R1", 1) + good1 = "void f(void)\n{\n if (ctx.fd != NET_FD_INVALID) { use_it(); }\n}\n" + expect("R1 不误报 `!= NET_FD_INVALID`", scan_text("App/x.c", good1), "R1", 0) + good2 = "void f(void)\n{\n /* 反面教材:if (fd >= 0) 是错的 */\n int x = 0;\n (void)x;\n}\n" + expect("R1 不误报注释里的反面教材", scan_text("App/x.c", good2), "R1", 0) + good3 = "void f(void)\n{\n if (fd() >= 0) { return; }\n}\n" + expect("R1 不误报函数调用 `fd() >= 0`", scan_text("App/x.c", good3), "R1", 0) + bad4 = "void f(void)\n{\n if (handle < 0) { return; }\n}\n" + expect("R1 抓句柄用负数字面量表达失效 `handle < 0`", + scan_text("App/x.c", bad4), "R1", 1) + good4 = "void f(void)\n{\n if (handle == 0U) { return; }\n}\n" + expect("R1 不误报句柄的 0 值检查 `handle == 0U`(0 是该族自己的空闲值)", + scan_text("App/x.c", good4), "R1", 0) + good4b = "void f(void)\n{\n if (socket_handle == 0U) { return; }\n}\n" + expect("R1 不误报 `socket_handle == 0U`(名字含 handle 即句柄族,不按 socket 判 fd)", + scan_text("App/x.c", good4b), "R1", 0) + bad4b = "void f(void)\n{\n if (sockfd == 0) { return; }\n}\n" + expect("R1 抓真 fd 的数值形态 `sockfd == 0`(0 在本仓是合法 fd)", + scan_text("App/x.c", bad4b), "R1", 1) + # ---- 句柄发号器族(104 后端):0 永不合法,与 fd 槽位的"0 合法"不同源。 + # 弱规则 = 与具名失效常量/0 的比较不判,但真值判断与负数形态仍判(不是整目录白名单)。 + g_sig = ("IEC104_NetResult_t IEC104_Net_Close(IEC104_NetSocket_t socket_handle, int *native_error)\n" + "{\n if (socket_handle == IEC104_NET_INVALID_SOCKET || socket_handle == 0U) {\n" + " return ok;\n }\n return ok;\n}\n") + expect("R1 不误报句柄族与具名失效常量/0 的比较(IEC104_Net_Close 实测反例)", + scan_text("App/protocol/iec104/iec104_net_mcu.c", g_sig), "R1", 0) + bad_h = "void f(void)\n{\n if (slot_handle == -1) { return; }\n}\n" + expect("R1 仍抓句柄族的负数形态 `slot_handle == -1`(弱规则不是不查)", + scan_text("App/x.c", bad_h), "R1", 1) + bad_h2 = "void f(void)\n{\n if (socket_handle) { return; }\n}\n" + expect("R4 仍抓句柄族真值判断 `if (socket_handle)`", + scan_text("App/x.c", bad_h2), "R4", 1) + bad_h3 = "void f(void)\n{\n if (!slot_handle) { return; }\n}\n" + expect("R4 仍抓句柄族 `if (!slot_handle)`", + scan_text("App/x.c", bad_h3), "R4", 1) + good5 = "void f(void)\n{\n int32_t sock_ok = (n == 4);\n if (sock_ok) { use_it(); }\n}\n" + expect("R1/R4 不误报 socket 状态布尔 `sock_ok`", + scan_text("App/x.c", good5), "R4", 0) + # 宏 / 宏调用 / 函数实参:test/host 的 fd_set 风格(NET_FD_ZERO / NET_FD_SET / + # NET_FD_ISSET)把 fd 或字面量当**实参**传,不是"与字面量比较",一律不判。 + good6 = ("#define NET_FD_ZERO(set) memset((set), 0, sizeof(net_fd_set_t))\n" + "#define NET_FD_SET(set, fd) do { (void)(fd); } while (0)\n" + "void f(void)\n{\n NET_FD_SET(&set, 0);\n}\n") + expect("R1/R3 不误报 fd_set 宏定义与宏实参字面量", scan_text("App/x.c", good6), "R1", 0) + expect("R3 不误报宏定义里的 memset", scan_text("App/x.c", good6), "R3", 0) + good7 = "void f(void)\n{\n if (NET_FD_ISSET(fd, &set)) { use_it(); }\n}\n" + expect("R4 不误报宏调用 `if (NET_FD_ISSET(fd, &set))`", scan_text("App/x.c", good7), "R4", 0) + good8 = "void f(void)\n{\n if (NET_MAX_SOCKETS > 0) { return; }\n}\n" + expect("R1 不误报全大写常量 `NET_MAX_SOCKETS > 0`", scan_text("App/x.c", good8), "R1", 0) + good9 = "void f(void)\n{\n if (fd >= 0) { return; }\n}\n" + expect("R1 抓函数体内的真判据(对照组,证明上面的放行不是整体失灵)", + scan_text("App/x.c", good9), "R1", 1) + wl = "void f(void)\n{\n if (p->fd >= 0) { return; }\n}\n" + expect("R1 白名单 Drivers/BSP/NET/ 不报", scan_text("Drivers/BSP/NET/net_socket.c", wl), "R1", 0) + + # ---- R2 + t = "typedef struct {\n uint8_t state;\n int fd;\n} ctx_t;\n" + expect("R2 抓无初始化器 fd 标量", scan_text("App/x.c", "static int fd;\n"), "R2", 1) + expect("R2 抓 `= {0}`", scan_text("App/x.c", t + "static ctx_t s_ctx = {0};\n"), "R2", 1) + expect("R2 抓指定初始化器缺 fd 成员", + scan_text("App/x.c", t + "static ctx_t s_ctx = { .state = 0 };\n"), "R2", 1) + expect("R2 抓 `.fd = -1`(不是契约常量)", + scan_text("App/x.c", t + "static ctx_t s_ctx = { .fd = -1 };\n"), "R2", 1) + expect("R2 抓匿名 struct 无初始化器", + scan_text("App/x.c", "static struct {\n int fd;\n} s_ctx;\n"), "R2", 1) + expect("R2 不误报正确指定初始化器", + scan_text("App/x.c", t + "static ctx_t s_ctx = {\n .fd = NET_FD_INVALID,\n};\n"), "R2", 0) + expect("R2 不误报无 fd 成员的 static", + scan_text("App/x.c", "static uint32_t s_rng;\n"), "R2", 0) + expect("R2 不误报函数声明", + scan_text("App/x.c", "static void f(int fd);\n"), "R2", 0) + expect("R2 不误报句柄发号器 `static uintptr_t s_next_handle = 1U;`", + scan_text("App/x.c", "static uintptr_t s_next_handle = 1U;\n"), "R2", 0) + + # ---- R3 + r3_bad = (t + "void f(void)\n{\n static ctx_t s_ctx;\n" + " memset(&s_ctx, 0, sizeof(s_ctx));\n s_ctx.state = 1;\n}\n") + expect("R3 抓 memset 后不回填", scan_text("App/x.c", r3_bad), "R3", 1) + r3_good = (t + "void f(void)\n{\n static ctx_t s_ctx;\n" + " memset(&s_ctx, 0, sizeof(s_ctx));\n" + " s_ctx.fd = NET_FD_INVALID;\n s_ctx.state = 1;\n}\n") + expect("R3 不误报 memset 后回填", scan_text("App/x.c", r3_good), "R3", 0) + r3_other = ("typedef struct {\n uint32_t a;\n} plain_t;\n" + "void f(void)\n{\n static plain_t s;\n memset(&s, 0, sizeof(s));\n}\n") + expect("R3 不误报无 fd 成员结构体", scan_text("App/x.c", r3_other), "R3", 0) + r3_arr = (t + "static ctx_t s_tab[4];\nvoid f(void)\n{\n" + " memset(s_tab, 0, sizeof(s_tab));\n}\n") + expect("R3 跳过整数组清零(槽表语义)", scan_text("App/x.c", r3_arr), "R3", 0) + + # ---- R4 + expect("R4 抓 `if (fd)`", scan_text("App/x.c", "void f(void)\n{\n if (fd) { use_it(); }\n}\n"), "R4", 1) + expect("R4 抓 `if (!ctx.fd)`", + scan_text("App/x.c", "void f(void)\n{\n if (!ctx.fd) { open_it(); }\n}\n"), "R4", 1) + expect("R4 不误报 `if (ctx.fd != NET_FD_INVALID)`", + scan_text("App/x.c", "void f(void)\n{\n if (ctx.fd != NET_FD_INVALID) { return; }\n}\n"), "R4", 0) + expect("R4 不误报其它布尔", + scan_text("App/x.c", "void f(void)\n{\n if (s_ready) { return; }\n}\n"), "R4", 0) + + ok = True + print("=== net-handle selftest ===") + for desc, got, want in checks: + passed = got == want + ok = ok and passed + print(" [%s] %s(命中 %d,期望 %d)" % ("PASS" if passed else "FAIL", desc, got, want)) + + # ---- R5:契约文件的三态(用临时目录,不污染工作区) + r5_checks = [] + import tempfile + with tempfile.TemporaryDirectory() as tmp: + def write(rel, body): + path = os.path.join(tmp, rel) + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, "w", encoding="utf-8", newline="\n") as f: + f.write(body) + r5_checks.append(("R5 缺契约文件必报", len(check_contract(tmp)), 1)) + write(NET_FD_H, "#ifndef NET_FD_H\n#define NET_FD_H\n#define NET_FD_INVALID (-1)\n#endif\n") + r5_checks.append(("R5 有定义但 net_socket.h 缺失必报", len(check_contract(tmp)), 1)) + write(NET_SOCKET_H, '#include "net_fd.h"\n') + r5_checks.append(("R5 齐备时 0 违规", len(check_contract(tmp)), 0)) + write(NET_SOCKET_H, '#include "net_types.h"\n') + r5_checks.append(("R5 net_socket.h 未 include 契约必报", len(check_contract(tmp)), 1)) + for desc, got, want in r5_checks: + passed = got == want + ok = ok and passed + print(" [%s] %s(命中 %d,期望 %d)" % ("PASS" if passed else "FAIL", desc, got, want)) + + total = len(checks) + len(r5_checks) + print("SELFTEST: %s(%d 条断言)" % ("PASS" if ok else "FAIL", total)) + return 0 if ok else 1 + + +# ------------------------------------------------------------------ main +def main() -> int: + if hasattr(sys.stdout, "reconfigure"): + sys.stdout.reconfigure(encoding="utf-8", errors="replace") + ap = argparse.ArgumentParser(description="网络句柄失效值契约门禁(R1~R5)") + ap.add_argument("--selftest", action="store_true", help="自证:正例必抓、正确写法不误报") + ap.add_argument("--verbose", action="store_true", help="打印跳过路径与判定细节") + ap.add_argument("--root", default=REPO, help="仓库根(默认脚本所在仓库)") + args = ap.parse_args() + + if args.selftest: + return selftest() + + root = os.path.abspath(args.root) + hits, nfiles = scan_tree(root, verbose=args.verbose) + print("[net-handle] 扫描 %d 个 C/H 文件(跳过第三方/生成物/归档)" % nfiles) + if hits: + counts: dict[str, int] = {} + for rel, rule, msg in hits: + counts[rule] = counts.get(rule, 0) + 1 + print("FAIL [%s] %s: %s" % (rule, rel, msg)) + print("[net-handle] 违规 %d 条:%s" % ( + len(hits), " ".join("%s=%d" % (k, counts[k]) for k in sorted(counts)))) + print("[net-handle] 契约与正反例 → docs/门禁说明/net-handle.md;" + "豁免只允许写进本脚本的 WHITELIST 并在文档 §7 说明理由") + return 1 + print("[net-handle] PASS:R1~R5 全绿,0 违规") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/ram_baseline.tsv b/scripts/ram_baseline.tsv index 41c1b609..8192cce9 100644 --- a/scripts/ram_baseline.tsv +++ b/scripts/ram_baseline.tsv @@ -23,4 +23,4 @@ date code ro rw zi er_irom1 er_pct iram1 iram1_pct ccm ccm_pct top_rwzi 2026-11-11 256024 31760 2080 152368 287784 27.4 97024 74.0 57376 87.9 heap_4.o=57376;lv_mem_core_builtin.o=16384;nand_ftl.o=8288;lftpd.o=7884;ui_net_sink.o=6802;ui_port.o=6432;wave_ring.o=5332;sb_link.o=4376;ch395f.o=4162;console_log.o=4132 2026-11-13 256592 32036 2088 152584 288628 27.5 97248 74.2 57376 87.9 heap_4.o=57376;lv_mem_core_builtin.o=16384;nand_ftl.o=8288;lftpd.o=7884;ui_net_sink.o=6802;ui_port.o=6432;wave_ring.o=5332;sb_link.o=4376;ch395f.o=4162;console_log.o=4132 2026-11-15 256592 32036 2088 152584 288628 27.5 97248 74.2 57376 87.9 heap_4.o=57376;lv_mem_core_builtin.o=16384;nand_ftl.o=8288;lftpd.o=7884;ui_net_sink.o=6802;ui_port.o=6432;wave_ring.o=5332;sb_link.o=4376;ch395f.o=4162;console_log.o=4132 -2026-11-18 367488 48604 2288 173544 416092 39.7 118408 90.3 57376 87.9 heap_4.o=57376;lv_mem_core_builtin.o=16384;nand_ftl.o=8288;lftpd.o=7884;iec104_tcpserver.o=7656;ui_net_sink.o=6802;ui_port.o=6432;iec104_source.o=5944;wave_ring.o=5332;sb_link.o=4376 +2026-11-18 367584 48604 2736 173104 416188 39.7 118416 90.3 57376 87.9 heap_4.o=57376;lv_mem_core_builtin.o=16384;nand_ftl.o=8288;lftpd.o=7884;iec104_tcpserver.o=7656;ui_net_sink.o=6802;ui_port.o=6432;iec104_source.o=5944;wave_ring.o=5332;sb_link.o=4376 diff --git a/scripts/size_attestation.json b/scripts/size_attestation.json index 1f00f1e0..d5326612 100644 --- a/scripts/size_attestation.json +++ b/scripts/size_attestation.json @@ -1,17 +1,17 @@ { - "built_at": "2026-11-18T19:40:16+08:00", - "fingerprint": "ab2a2842d208dd3fc465d3a5fa346f423d826bffd5e5456f24aba4724c1aa7c6", - "fingerprint_files": 1583, + "built_at": "2026-11-18T22:01:16+08:00", + "fingerprint": "27c4be92b1f2096a195e449cefdc615860a572f3ed2caca9bbdcfa60084d4ade", + "fingerprint_files": 1584, "fingerprint_source": "git-index", "gated_regions": [ "RW_IRAM1", "RW_CCM" ], - "git_head": "6e0755f97152f62de724e9bde66ba9a83691de08", + "git_head": "50ee1b44021c7cc291f70fcad1c73f3385e15dc6", "map": "MDK-ARM/STM32F407-Demo/STM32F407-Demo.map", - "map_mtime": 1795001958, + "map_mtime": 1795010439, "pct": { - "ER_IROM1": 39.68, + "ER_IROM1": 39.69, "RW_CCM": 87.89, "RW_IRAM1": 90.34, "UNINIT_CCM": 18.75 @@ -19,7 +19,7 @@ "regions": { "ER_IROM1": { "max": 1048576, - "size": 416092 + "size": 416188 }, "RW_CCM": { "max": 65280, @@ -27,7 +27,7 @@ }, "RW_IRAM1": { "max": 131072, - "size": 118408 + "size": 118416 }, "UNINIT_CCM": { "max": 256, @@ -37,10 +37,10 @@ "schema": 2, "scope_note": "\u540c\u7801\u51ed\u8bc1\uff1a\u6307\u7eb9\u8986\u76d6\u56fa\u4ef6\u4f53\u79ef\u76f8\u5173\u6e90\u7801\uff0c\u53e3\u5f84\u89c1\u672c\u811a\u672c docstring", "sizes": { - "code": 367488, + "code": 367584, "ro_data": 48604, - "rw_data": 2288, - "zi_data": 173544 + "rw_data": 2736, + "zi_data": 173104 }, "threshold_pct": 92.0, "worktree_dirt_at_stamp": 0, diff --git a/simulator/sim/net_socket_sim.c b/simulator/sim/net_socket_sim.c index c1d8e917..69dca2a1 100644 --- a/simulator/sim/net_socket_sim.c +++ b/simulator/sim/net_socket_sim.c @@ -72,7 +72,7 @@ static int ensure_wsa(void) { * 函数功能:分配一个空闲 fd(控制块索引) * 入口参数:无 * 出口参数:无 - * 返回值:空闲索引(0 ~ NET_MAX_SOCKETS-1),-1 表示无空闲 + * 返回值:空闲索引(0 ~ NET_MAX_SOCKETS-1),NET_FD_INVALID 表示无空闲 * 限定条件:s_socks 已定义 * 函数说明:线性扫描,返回首个 in_use == 0 的控制块索引 */ @@ -84,7 +84,7 @@ static int alloc_fd(void) { return i; } } - return -1; + return NET_FD_INVALID; } /* @@ -173,7 +173,7 @@ int net_poll(void) { * 入口参数:domain - 地址族(仅 AF_INET) * type - NET_SOCK_STREAM(TCP) 或 NET_SOCK_DGRAM(UDP) * 出口参数:无 - * 返回值:socket 描述符(0 ~ NET_MAX_SOCKETS-1),失败 -1 + * 返回值:socket 描述符(0 ~ NET_MAX_SOCKETS-1),失败 NET_FD_INVALID * 限定条件:Winsock 已就绪 * 函数说明:分配空闲控制块,创建 Winsock SOCKET 并置非阻塞 */ @@ -187,13 +187,13 @@ int net_socket(int domain, int type) { if (ensure_wsa() != 0) { s_net_errno = NET_ERR; - return -1; + return NET_FD_INVALID; } idx = alloc_fd(); - if (idx < 0) { + if (idx == NET_FD_INVALID) { s_net_errno = NET_ERR; - return -1; + return NET_FD_INVALID; } is_udp = (type == NET_SOCK_DGRAM); @@ -201,13 +201,13 @@ int net_socket(int domain, int type) { is_udp ? IPPROTO_UDP : IPPROTO_TCP); if (ws == INVALID_SOCKET) { s_net_errno = NET_ERR; - return -1; + return NET_FD_INVALID; } if (ioctlsocket(ws, FIONBIO, &nb) != 0) { closesocket(ws); s_net_errno = NET_ERR; - return -1; + return NET_FD_INVALID; } memset(&s_socks[idx], 0, sizeof(net_sock_t)); @@ -238,7 +238,7 @@ int net_bind(int sockfd, const struct net_sockaddr *addr, int addrlen) { struct sockaddr_in wsaddr; int yes = 1; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -269,7 +269,7 @@ int net_bind(int sockfd, const struct net_sockaddr *addr, int addrlen) { * 函数说明:backlog 为 1(单客户端),监听 Socket 保持非阻塞 */ int net_listen(int sockfd) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -302,9 +302,9 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen) { int nidx; u_long nb = 1; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; - return -1; + return NET_FD_INVALID; } wslen = sizeof(wscli); @@ -313,7 +313,7 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen) { if (cws == INVALID_SOCKET) { int err = WSAGetLastError(); s_net_errno = (err == WSAEWOULDBLOCK) ? NET_ERR_WOULDBLOCK : NET_ERR; - return -1; + return NET_FD_INVALID; } if (addr != NULL && addrlen != NULL) { @@ -322,10 +322,10 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen) { } nidx = alloc_fd(); - if (nidx < 0) { + if (nidx == NET_FD_INVALID) { closesocket(cws); s_net_errno = NET_ERR; - return -1; + return NET_FD_INVALID; } ioctlsocket(cws, FIONBIO, &nb); @@ -357,7 +357,7 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen) { * (设计文档 D6:双模型分裂暂不消除),无此中间态,恒 1 即为正确语义。 */ int net_listener_armed(int sockfd) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { return 0; } return 1; @@ -372,7 +372,7 @@ int net_listener_armed(int sockfd) { * 上层门控在模拟器上不改变既有行为(含"每轮都 recv"的自愈特性) */ int net_can_read(int sockfd) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { return 0; } return 1; @@ -391,7 +391,7 @@ int net_can_read(int sockfd) { int net_connect(int sockfd, const struct net_sockaddr *addr, int addrlen) { struct sockaddr_in wsaddr; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -430,7 +430,7 @@ int net_connect(int sockfd, const struct net_sockaddr *addr, int addrlen) { int net_send(int sockfd, const void *buf, int len, int flags) { int r; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -529,7 +529,7 @@ static int recv_wait(int sockfd, void *buf, int len, int has_budget, unsigned lo * 无限等待还是立即 WOULDBLOCK;DONTWAIT 单次覆盖属性 */ int net_recv(int sockfd, void *buf, int len, int flags) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -554,7 +554,7 @@ int net_recv(int sockfd, void *buf, int len, int flags) { * 函数说明:等价 net_recv(sockfd, buf, len, NET_MSG_DONTWAIT),不改变 blocking 属性 */ int net_recv_nb(int sockfd, void *buf, int len) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -575,7 +575,7 @@ int net_recv_nb(int sockfd, void *buf, int len) { * 函数说明:模拟器以 GetTickCount64 + Sleep(1) 轮询兑现预算 */ int net_recv_to(int sockfd, void *buf, int len, uint32_t timeout_ms) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -616,7 +616,7 @@ int net_sendto(int sockfd, const void *buf, int len, int flags, struct sockaddr_in wsaddr; int r; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -664,7 +664,7 @@ int net_recvfrom(int sockfd, void *buf, int len, int flags, (void)flags; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -700,7 +700,7 @@ int net_recvfrom(int sockfd, void *buf, int len, int flags, * 函数说明:关闭 Winsock 句柄并释放控制块(in_use 清零,net_get_sock 转返回 NULL) */ int net_close(int sockfd) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -729,7 +729,7 @@ int net_close(int sockfd) { * 监听 fd 不受影响。无活动会话幂等返 0。 */ int net_drop_conn(int sockfd) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -763,7 +763,7 @@ int net_drop_conn(int sockfd) { * 函数说明:模拟器以非阻塞 I/O 直接感知事件,回调仅存储不主动触发 */ int net_set_event_cb(int sockfd, net_event_cb_t cb, void *arg) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -786,7 +786,7 @@ int net_set_event_cb(int sockfd, net_event_cb_t cb, void *arg) { * 语义与 MCU 端"模式挂控制块属性"一致 */ int net_setblocking(int sockfd, int on) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -920,7 +920,7 @@ uint32_t net_ntohl(uint32_t netlong) { * 函数说明:上层据此判断"监听 Socket 是否随客户端一同失效"(单连接模型) */ net_sock_t *net_get_sock(int sockfd) { - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS) { + if (NET_FD_IN_RANGE(sockfd) == 0) { return NULL; } if (s_socks[sockfd].in_use == 0) { @@ -943,7 +943,7 @@ int net_getsockname(int sockfd, struct net_sockaddr *addr, int *addrlen) { struct sockaddr_in wsaddr; int wslen; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } @@ -980,7 +980,7 @@ int net_getpeername(int sockfd, struct net_sockaddr *addr, int *addrlen) { struct sockaddr_in wsaddr; int wslen; - if (sockfd < 0 || sockfd >= NET_MAX_SOCKETS || s_socks[sockfd].in_use == 0) { + if (NET_FD_IN_RANGE(sockfd) == 0 || s_socks[sockfd].in_use == 0) { s_net_errno = NET_ERR_BADF; return -1; } diff --git a/test/board/net_test_task.c b/test/board/net_test_task.c index 384ad1b1..bbcf8d98 100644 --- a/test/board/net_test_task.c +++ b/test/board/net_test_task.c @@ -162,7 +162,7 @@ static uint32_t phase7_cksum(const uint8_t *p, uint32_t n) { static int32_t phase7_session(uint16_t local_port) { int32_t sockfd = net_socket(NET_AF_INET, NET_SOCK_STREAM); - if (sockfd < 0) { + if (sockfd == NET_FD_INVALID) { TEST_CHECK(0, "TC-NET-701 socket create"); return 0; } @@ -261,7 +261,7 @@ static int32_t phase7_session(uint16_t local_port) static void phase7_test_timeout(void) { int32_t sockfd = net_socket(NET_AF_INET, NET_SOCK_STREAM); - if (sockfd < 0) { TEST_CHECK(0, "TC-NET-703 socket create"); return; } + if (sockfd == NET_FD_INVALID) { TEST_CHECK(0, "TC-NET-703 socket create"); return; } struct net_sockaddr_in raddr; memset(&raddr, 0, sizeof(raddr)); @@ -866,7 +866,7 @@ void net_layer_test_main(void) int32_t addrlen = sizeof(client_addr); sockfd = net_socket(NET_AF_INET, NET_SOCK_STREAM); - if (sockfd < 0) { + if (sockfd == NET_FD_INVALID) { DBG_ERROR("Test task: net_socket failed"); return; } @@ -907,7 +907,7 @@ void net_layer_test_main(void) #endif ) { int32_t acc = net_accept(sockfd, (struct net_sockaddr *)&client_addr, &addrlen); - if (acc < 0) { + if (acc == NET_FD_INVALID) { /* 网络重建(代次变化)→ 旧监听随芯片复位失效,重建 8080 监听 */ if (net_get_generation() != gen) { struct net_sockaddr_in addr; @@ -917,7 +917,7 @@ void net_layer_test_main(void) memset(&addr, 0, sizeof(addr)); addr.sin_family = NET_AF_INET; addr.sin_port = net_htons(8080); - if (sockfd < 0 || + if (sockfd == NET_FD_INVALID || net_bind(sockfd, (struct net_sockaddr *)&addr, sizeof(addr)) < 0 || net_listen(sockfd) < 0) { DBG_ERROR("Test task: relisten failed"); @@ -1224,8 +1224,8 @@ static void udp_bench_peer_free_check(void) DBG_INFO("--- TC-NET-1610: peer-free self-check (no PC traffic needed) ---"); fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM); - TEST_CHECK(fd >= 0, "TC-NET-1610a: udp socket fd=%d", fd); - if (fd < 0) { + TEST_CHECK(fd != NET_FD_INVALID, "TC-NET-1610a: udp socket fd=%d", fd); + if (fd == NET_FD_INVALID) { return; } TEST_CHECK(net_udp_get_mode(fd) == NET_UDP_MODE_SERVER, @@ -1302,8 +1302,8 @@ static void udp_bench_peer_free_check(void) rc = net_close(fd); TEST_CHECK(rc == 0, "TC-NET-1610n: close rc=%d", rc); fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM); - TEST_CHECK(fd >= 0, "TC-NET-1610o: a socket allocated after close fd=%d", fd); - if (fd < 0) { + TEST_CHECK(fd != NET_FD_INVALID, "TC-NET-1610o: a socket allocated after close fd=%d", fd); + if (fd == NET_FD_INVALID) { return; } rc = net_bind(fd, (const struct net_sockaddr *)&sa, (int)sizeof(sa)); @@ -1355,8 +1355,8 @@ void net_layer_udp_bench_test_main(void) /* ---------- TC-NET-1601:socket + bind(服务端形态) ---------- */ DBG_INFO("--- TC-NET-1601: socket/bind -> server mode ---"); fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM); - TEST_CHECK(fd >= 0, "TC-NET-1601a: udp socket fd=%d", fd); - if (fd < 0) { + TEST_CHECK(fd != NET_FD_INVALID, "TC-NET-1601a: udp socket fd=%d", fd); + if (fd == NET_FD_INVALID) { TEST_REPORT("Phase 16"); return; } @@ -1465,8 +1465,8 @@ void net_layer_udp_bench_test_main(void) DBG_INFO("--- TC-NET-1608: close/rebind on a new port, first packet lands ---"); net_close(fd); fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM); - TEST_CHECK(fd >= 0, "TC-NET-1608a: fresh udp socket fd=%d", fd); - if (fd >= 0) { + TEST_CHECK(fd != NET_FD_INVALID, "TC-NET-1608a: fresh udp socket fd=%d", fd); + if (fd != NET_FD_INVALID) { (void)memset(&me, 0, sizeof(me)); me.sin_family = NET_AF_INET; me.sin_port = net_htons((uint16_t)UDP_BENCH_PORT2); diff --git a/test/host/iec104_netmcu/net_socket_fake.c b/test/host/iec104_netmcu/net_socket_fake.c index d9e44778..41c82144 100644 --- a/test/host/iec104_netmcu/net_socket_fake.c +++ b/test/host/iec104_netmcu/net_socket_fake.c @@ -79,6 +79,7 @@ static net_fake_stats_t stats; static fake_fd_t *fd_at(int fd) { + /* 测试代码:假对象域校验用裸区间判据(契约 C4/C6 允许),生产判据不得照抄 */ if (fd < 0 || fd >= FAKE_MAX_FD) { return NULL; } @@ -95,7 +96,7 @@ static int alloc_fd(void) return i; } } - return -1; + return NET_FD_INVALID; /* 契约 C5:分配失败返回失效值(不是随便一个负号) */ } void net_fake_reset(void) @@ -147,7 +148,7 @@ int net_fake_session_fd(void) return i; } } - return -1; + return NET_FD_INVALID; /* 契约 C5:无会话 = 失效值 */ } int net_fake_listen_fd(void) @@ -158,13 +159,13 @@ int net_fake_listen_fd(void) return i; } } - return -1; + return NET_FD_INVALID; } int net_fake_listener_armed(void) { int fd = net_fake_listen_fd(); - return (fd >= 0 && net_listener_armed(fd) != 0) ? 1 : 0; + return (fd != NET_FD_INVALID && net_listener_armed(fd) != 0) ? 1 : 0; } int net_fake_push_rx(const void *data, int len) @@ -357,6 +358,7 @@ net_sock_t *net_get_sock(int sockfd) net_sock_t *net_sock_raw(int sockfd) { + /* 测试代码:假对象域校验用裸区间判据(契约 C4),不是生产判据 */ if (sockfd < 0 || sockfd >= FAKE_MAX_FD) { return NULL; } @@ -542,7 +544,7 @@ int net_fake_copy_tx(uint8_t *data, int capacity) { int fd = net_fake_session_fd(); int n; - if (fd < 0) { + if (fd == NET_FD_INVALID) { return -1; } n = fds[fd].tx_pending; @@ -572,10 +574,10 @@ int net_socket(int domain, int type) return i; } } - return -1; + return NET_FD_INVALID; } fd = alloc_fd(); - if (fd >= 0) { + if (fd != NET_FD_INVALID) { sync_sock(fd); } return fd; @@ -769,7 +771,8 @@ int net_close(int sockfd) ++stats.close_calls; ++stats.hardware_calls; if (f == NULL) { - return -1; + /* 契约 C6:越界 / 未分配 fd 的关闭必须失败 */ + return NET_FD_INVALID; } if (f->is_listener) { /* 真实板端:单连接模型下对监听 fd 调 net_close 会连监听一起毁掉。 diff --git a/test/host/iec104_netmcu/results/report.json b/test/host/iec104_netmcu/results/report.json index 7351d563..bfeab168 100644 --- a/test/host/iec104_netmcu/results/report.json +++ b/test/host/iec104_netmcu/results/report.json @@ -1,10 +1,10 @@ { "scope": "REAL backend App/protocol/iec104/iec104_net_mcu.c + fake net layer; host-only isolation evidence, not full core/TcpServer/hardware", - "backend_sha256": "4d6b8d9e8ed3404372f274d99c16bc87a06fecbee8db0b30b044b24d0562d73d", + "backend_sha256": "7b787ec910fad31da3ea530089c0ca817bdbd62203d9fa1ae8223da64185112a", "sources": { "MATRIX.md": "e8c913cac2a852173f052ce806a3da101a272e2a4dff8751499fdcf39788deab", - "net_socket_fake.h": "d597375d1186b4801b4dc859401b6f3f0c9d1110efda37d0a9e73b810d7a8cd0", - "net_socket_fake.c": "8eb9ea5ed195b38e2f4993ac021ad19afa40464ff03de73628d3a795350a631e", + "net_socket_fake.h": "c7c712256b5ac4b5162fd445319296dd32ada4abc6efa0384e65e2635bba38c9", + "net_socket_fake.c": "3dbf75dcaf1d5159480a41c2783644bbf4892f102694de57f9816c1b9d402dd5", "netmcu_test.c": "09c203941c41fbb543580f45192c1604b984daaeb10135548756d4e42e8ebe02", "check_static.py": "8f08695a6c6bffec6047558b5b6d0aff0c7393665853357d1176f61b1aac1132" }, diff --git a/test/host/lftpd/lftpd_test.c b/test/host/lftpd/lftpd_test.c index 95883655..a25dd2f8 100644 --- a/test/host/lftpd/lftpd_test.c +++ b/test/host/lftpd/lftpd_test.c @@ -121,6 +121,21 @@ typedef struct { static lftp_net_t g_n; +/* 假 inet 层的 fd 分配集合(契约 C5/C6/C7):与生产同域的 0 基句柄, + * 未分配 / 越界的 lftpd_inet_close 必须失败(返回 NET_FD_INVALID)。 */ +#define LFTP_FAKE_MAX_FD 8 +static int g_n_fd_used[LFTP_FAKE_MAX_FD]; + +static int lftp_fake_fd_alloc(int fd) +{ + /* 测试代码:假对象域校验用的裸区间判据(契约 C6),非生产判据 */ + if (fd < 0 || fd >= LFTP_FAKE_MAX_FD || g_n_fd_used[fd] != 0) { + return NET_FD_INVALID; + } + g_n_fd_used[fd] = 1; + return fd; +} + int lftpd_inet_read_line(int socket, char *buffer, size_t buffer_len) { (void)socket; @@ -168,7 +183,10 @@ int lftpd_inet_listen(int port) { (void)port; g_n.listen_calls++; - return g_n.listen_rc; + if (g_n.listen_rc < 0) { + return NET_FD_INVALID; + } + return lftp_fake_fd_alloc(g_n.listen_rc); } int lftpd_inet_get_socket_port(int socket) @@ -188,13 +206,20 @@ int lftpd_inet_accept_timeout(int socket, int timeout_ms) (void)socket; (void)timeout_ms; g_n.accept_calls++; - return g_n.accept_to_rc; + if (g_n.accept_to_rc < 0) { + return NET_FD_INVALID; + } + return lftp_fake_fd_alloc(g_n.accept_to_rc); } int lftpd_inet_close(int socket) { - (void)socket; g_n.close_calls++; + /* 契约 C6:越界 / 未分配一律失败(假对象复刻生产主人语义) */ + if (socket < 0 || socket >= LFTP_FAKE_MAX_FD || g_n_fd_used[socket] == 0) { + return NET_FD_INVALID; + } + g_n_fd_used[socket] = 0; return 0; } @@ -379,11 +404,12 @@ static lftpd_client_t g_cli; static void reset_all(void) { (void)memset(&g_n, 0, sizeof(g_n)); + (void)memset(g_n_fd_used, 0, sizeof(g_n_fd_used)); (void)memset(&g_io, 0, sizeof(g_io)); g_n.string_rc = 0; - g_n.listen_rc = 20; + g_n.listen_rc = 1; /* 假 fd 域与生产对齐:0 基(契约 C5/C7) */ g_n.port = 5000; - g_n.accept_to_rc = 21; /* 默认数据通道能连上 */ + g_n.accept_to_rc = 2; /* 默认数据通道能连上 */ g_n.data_write_rc = 0; g_io.stat_rc = 0; g_io.is_dir = 1; @@ -408,8 +434,8 @@ static void reset_all(void) g_sockname_rc = 0; (void)memset(&g_cli, 0, sizeof(g_cli)); (void)strcpy(g_cli.directory, "/"); - g_cli.socket = 10; - g_cli.data_socket = -1; + g_cli.socket = 0; + g_cli.data_socket = NET_FD_INVALID; /* 不写死字段名:认证状态的结构由 lftpd_auth.h 定义,本模块只把它当黑盒清零 (口令/锁定逻辑有 test/host/ftp_auth 的 10 条专测,这里不重复验)。 */ (void)memset(&s_auth_state, 0, sizeof(s_auth_state)); @@ -479,10 +505,11 @@ static void tc_gates(void) "TC-LFTPD-005 if the welcome never got through (peer already gone) finish straight away instead of spinning on reads; that trace really is INFO"); reset_all(); - g_cli.data_socket = 33; /* 被动模式已开但客户端直接跑了 */ + g_cli.data_socket = 1; /* 被动模式已开但客户端直接跑了(假对象域内、已分配) */ + g_n_fd_used[1] = 1; feed("QUIT", NULL, NULL, NULL); (void)handle_control_channel(&g_cli); - CHECK((g_n.close_calls == 1) && (g_cli.data_socket == -1), + CHECK((g_n.close_calls == 1) && (g_cli.data_socket == NET_FD_INVALID), "TC-LFTPD-006 on exit the still-open data listener must be released (a single-socket chip must not be left with a dangling socket)"); reset_all(); @@ -495,7 +522,7 @@ static void tc_gates(void) g_cli.auth_logged_in = 1; g_io.opendir_rc = 0; g_io.readdir_n = 0; - g_n.listen_rc = 20; + g_n.listen_rc = 1; feed("LIST", NULL, NULL, NULL); (void)handle_control_channel(&g_cli); CHECK((rep_has("425 ") == 1) && (g_n.accept_calls == 0), @@ -513,7 +540,7 @@ static void tc_passive(void) 关掉(那正是 TC-LFTPD-006 要验的行为),这里要看的是 PASV 自己留下的状态。 */ (void)cmd_pasv(&g_cli, NULL); CHECK((strcmp(rep(0), "227 Entering Passive Mode (192,168,31,1,19,136).\r\n") == 0) && - (g_cli.data_socket == 20) && (g_n.listen_calls == 1), + (g_cli.data_socket == 1) && (g_n.listen_calls == 1), "TC-LFTPD-011 the 227 tuple: ip through htonl then high byte to low byte (dotted order), port high/low, and the passive listen handle is recorded"); reset_all(); @@ -522,7 +549,7 @@ static void tc_passive(void) feed("PASV", NULL, NULL, NULL); (void)handle_control_channel(&g_cli); CHECK((rep_has("425 ") == 1) && (g_n.close_calls == 1) && - (g_cli.data_socket == -1), + (g_cli.data_socket == NET_FD_INVALID), "TC-LFTPD-012 when the local ip is unavailable the listener just created must be closed (no half-passive mode left behind)"); reset_all(); @@ -534,12 +561,12 @@ static void tc_passive(void) reset_all(); g_cli.auth_logged_in = 1; - g_n.listen_rc = 20; + g_n.listen_rc = 1; g_n.accept_to_rc = -1; /* 对端一直不开数据通道 */ feed("PASV", "LIST", NULL, NULL); (void)handle_control_channel(&g_cli); CHECK((rep_has("150 ") == 1) && (rep_has("425 ") == 1) && - (g_cli.data_socket == -1) && (g_n.close_calls == 1), + (g_cli.data_socket == NET_FD_INVALID) && (g_n.close_calls == 1), "TC-LFTPD-014 a failed data accept reports 425 and closes and resets the listener instead of leaving it to the next command"); reset_all(); @@ -593,7 +620,7 @@ static void tc_transfer(void) reset_all(); g_cli.auth_logged_in = 1; g_cfg.write_en = 0u; - g_n.listen_rc = 20; + g_n.listen_rc = 1; feed("PASV", "STOR up.bin", NULL, NULL); (void)handle_control_channel(&g_cli); CHECK((rep_has("550 ") == 1) && (g_n.accept_calls == 0) && diff --git a/test/host/lftpd/stub/net_socket.h b/test/host/lftpd/stub/net_socket.h index 438854e2..f71945fe 100644 --- a/test/host/lftpd/stub/net_socket.h +++ b/test/host/lftpd/stub/net_socket.h @@ -9,6 +9,8 @@ #ifndef NET_SOCKET_H #define NET_SOCKET_H +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ + #include "FreeRTOS.h" #include "task.h" diff --git a/test/host/lftpd_inet/lftpd_inet_test.c b/test/host/lftpd_inet/lftpd_inet_test.c index c2d81cde..1edbaab1 100644 --- a/test/host/lftpd_inet/lftpd_inet_test.c +++ b/test/host/lftpd_inet/lftpd_inet_test.c @@ -62,6 +62,10 @@ int g_lfi_debug_count; /* ===================== 可控 socket 层 ===================== */ +/* 假 fd 域与生产对齐(契约 C5/C6/C7):0 基 + 已分配集合; + * net_close 对越界 / 未分配 fd 必须失败(返回 NET_FD_INVALID 并把 errno 置 BADF)。 */ +#define LFI_FAKE_MAX_FD 8 + typedef struct { int socket_rc; int bind_rc; @@ -100,11 +104,13 @@ typedef struct { } lfi_net_t; static lfi_net_t g_net; +static int lfi_fd_used[LFI_FAKE_MAX_FD]; /* 1 = 该 fd 已由假 net_socket/accept 分配 */ static void net_reset(void) { (void)memset(&g_net, 0, sizeof(g_net)); - g_net.socket_rc = 3; + (void)memset(lfi_fd_used, 0, sizeof(lfi_fd_used)); + g_net.socket_rc = 0; /* 契约 C5:首个成功 fd 是 0 */ g_net.bind_rc = 0; g_net.listen_rc = 0; g_net.getsock_rc = 0; @@ -131,6 +137,10 @@ int net_socket(int domain, int type) g_net.socket_calls++; g_net.last_domain = domain; g_net.last_type = type; + /* 测试代码:裸字面量判据属"假对象域校验"语义(契约 C6),非生产判据 */ + if (g_net.socket_rc >= 0 && g_net.socket_rc < LFI_FAKE_MAX_FD) { + lfi_fd_used[g_net.socket_rc] = 1; + } return g_net.socket_rc; } @@ -154,8 +164,12 @@ int net_listen(int sockfd) int net_close(int sockfd) { - (void)sockfd; g_net.close_calls++; + /* 测试代码:假对象域校验(契约 C6)——越界 / 未分配一律失败 */ + if (sockfd < 0 || sockfd >= LFI_FAKE_MAX_FD || lfi_fd_used[sockfd] == 0) { + return NET_FD_INVALID; + } + lfi_fd_used[sockfd] = 0; return 0; } @@ -275,18 +289,18 @@ static void tc_listen(void) (g_lfi_error_count == 1), "TC-LFTINET-003 a listen failure also closes the socket and logs it"); net_reset(); logs_clear(); - CHECK((lftpd_inet_listen(21) == 3) && (g_net.last_domain == NET_AF_INET) && + CHECK((lftpd_inet_listen(21) == 0) && (g_net.last_domain == NET_AF_INET) && (g_net.last_type == NET_SOCK_STREAM) && (g_net.last_bind_port_net == net_htons(21u)) && (g_net.listen_calls == 1), "TC-LFTINET-004 a stream listener whose port went through htons (sin_port is network order)"); net_reset(); logs_clear(); g_net.getsock_rc = -1; - CHECK((lftpd_inet_get_socket_port(3) == -1) && (g_lfi_error_count == 1), + CHECK((lftpd_inet_get_socket_port(0) == -1) && (g_lfi_error_count == 1), "TC-LFTINET-005 a failing getsockname returns -1 (never report a stale port as the result)"); net_reset(); logs_clear(); g_net.getsock_port_net = net_htons(8888u); - CHECK(lftpd_inet_get_socket_port(3) == 8888, + CHECK(lftpd_inet_get_socket_port(0) == 8888, "TC-LFTINET-006 the port comes back through ntohs into host order"); } @@ -296,14 +310,14 @@ static void tc_accept(void) { printf("-- TC-LFTINET-010..012 / 020..022 accept --\n"); net_reset(); logs_clear(); - g_net.accept_seq[0] = 9; g_net.accept_n = 1; - CHECK((lftpd_inet_accept(3) == 9) && (g_net.delay_calls == 0), + g_net.accept_seq[0] = 1; g_net.accept_n = 1; + CHECK((lftpd_inet_accept(0) == 1) && (g_net.delay_calls == 0), "TC-LFTINET-010 an immediate hit neither sleeps nor waits"); net_reset(); logs_clear(); - g_net.accept_seq[0] = -1; g_net.accept_seq[1] = -1; g_net.accept_seq[2] = 9; + g_net.accept_seq[0] = -1; g_net.accept_seq[1] = -1; g_net.accept_seq[2] = 1; g_net.accept_n = 3; - CHECK((lftpd_inet_accept(3) == 9) && (g_net.delay_calls == 2) && + CHECK((lftpd_inet_accept(0) == 1) && (g_net.delay_calls == 2) && (g_lfi_info_count == 0), "TC-LFTINET-011 every failed round yields the CPU (and feeds the watchdog in the same block) until it succeeds"); @@ -311,25 +325,25 @@ static void tc_accept(void) g_net.accept_seq[0] = -1; g_net.accept_seq[1] = -1; g_net.accept_seq[2] = -1; g_net.accept_n = 3; g_net.gen_flip_after = 3; /* 第 3 轮时网络重建 */ - CHECK((lftpd_inet_accept(3) == -1) && (g_lfi_info_count == 1) && + CHECK((lftpd_inet_accept(0) == -1) && (g_lfi_info_count == 1) && (g_net.accept_calls == 3), "TC-LFTINET-012 a generation change aborts accept immediately (otherwise the listener stays on the old generation after the new IP takes effect)"); net_reset(); logs_clear(); - g_net.accept_seq[0] = -1; g_net.accept_seq[1] = 9; g_net.accept_n = 2; - CHECK((lftpd_inet_accept_timeout(3, 5000) == 9) && (g_net.delay_calls == 1), + g_net.accept_seq[0] = -1; g_net.accept_seq[1] = 1; g_net.accept_n = 2; + CHECK((lftpd_inet_accept_timeout(0, 5000) == 1) && (g_net.delay_calls == 1), "TC-LFTINET-020 the data channel is accepted inside the timeout window"); net_reset(); logs_clear(); g_net.accept_seq[0] = -1; g_net.accept_seq[1] = -1; g_net.accept_n = 2; g_net.armed = 0; /* 监听门被撤(会话已放弃) */ - CHECK((lftpd_inet_accept_timeout(3, 5000) == -1) && (g_net.accept_calls == 1) && + CHECK((lftpd_inet_accept_timeout(0, 5000) == -1) && (g_net.accept_calls == 1) && (g_lfi_error_count == 1), "TC-LFTINET-021 lowering the listener gate gives up at once instead of burning the full 5 s on a dead listener"); net_reset(); logs_clear(); g_net.accept_seq[0] = -1; g_net.accept_n = 1; - CHECK((lftpd_inet_accept_timeout(3, 300) == -1) && (g_net.delay_calls == 3) && + CHECK((lftpd_inet_accept_timeout(0, 300) == -1) && (g_net.delay_calls == 3) && (g_lfi_info_count == 1), "TC-LFTINET-022 the peer never opens the data channel: step by 100ms to the limit and finish as INFO"); } @@ -437,8 +451,13 @@ static void tc_write_read(void) "TC-LFTINET-062 other negative values keep waiting until the 30 s budget is exhausted"); net_reset(); logs_clear(); - CHECK((lftpd_inet_close(3) == 0) && (g_net.close_calls == 1), - "TC-LFTINET-070 close only forwards to net_close"); + lfi_fd_used[0] = 1; /* 假对象:fd 0 已由假 net_socket 分配(与生产同域,0 基) */ + CHECK((lftpd_inet_close(0) == 0) && (g_net.close_calls == 1), + "TC-LFTINET-070 close only forwards to net_close (an allocated fd)"); + + net_reset(); logs_clear(); + CHECK((lftpd_inet_close(0) == NET_FD_INVALID) && (g_net.close_calls == 1), + "TC-LFTINET-071 closing an unallocated fd must fail (fake mirrors the owner semantics)"); } int main(void) diff --git a/test/host/lftpd_inet/stub/net_socket.h b/test/host/lftpd_inet/stub/net_socket.h index 78d15e81..272f54d6 100644 --- a/test/host/lftpd_inet/stub/net_socket.h +++ b/test/host/lftpd_inet/stub/net_socket.h @@ -11,6 +11,8 @@ #ifndef NET_SOCKET_H #define NET_SOCKET_H +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ + /* 真实 net_socket.h 会把 FreeRTOS.h / task.h 一起带给调用方, * lftpd_inet.c 正是靠那条链拿 TickType_t / vTaskDelay / pdMS_TO_TICKS, * 所以桩必须照做同样的 include(少一行就是 C2065 未声明)。 */ diff --git a/test/host/net_events/stub/net_socket.h b/test/host/net_events/stub/net_socket.h index 978960b2..9a4c93b9 100644 --- a/test/host/net_events/stub/net_socket.h +++ b/test/host/net_events/stub/net_socket.h @@ -9,6 +9,8 @@ #ifndef NET_SOCKET_H #define NET_SOCKET_H +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ + #include "net_types.h" net_sock_t *net_get_sock(int sockfd); diff --git a/test/host/net_listener/stub/net_socket.h b/test/host/net_listener/stub/net_socket.h index 8ec7ecf8..b942d0ae 100644 --- a/test/host/net_listener/stub/net_socket.h +++ b/test/host/net_listener/stub/net_socket.h @@ -11,6 +11,8 @@ #ifndef NET_SOCKET_H #define NET_SOCKET_H +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ + #include "net_types.h" net_sock_t *net_get_sock(int sockfd); diff --git a/test/host/net_pending/stub/net_socket.h b/test/host/net_pending/stub/net_socket.h index e56c6f49..1c72ea93 100644 --- a/test/host/net_pending/stub/net_socket.h +++ b/test/host/net_pending/stub/net_socket.h @@ -10,6 +10,8 @@ #ifndef NET_SOCKET_H #define NET_SOCKET_H +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ + #include "net_types.h" int net_set_errno(int err); diff --git a/test/host/net_select/stub/net_socket.h b/test/host/net_select/stub/net_socket.h index 4043291a..a092f42f 100644 --- a/test/host/net_select/stub/net_socket.h +++ b/test/host/net_select/stub/net_socket.h @@ -15,6 +15,8 @@ #ifndef NET_SOCKET_H #define NET_SOCKET_H +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ + #include "net_types.h" const net_sock_t *net_get_sock(int sockfd); diff --git a/test/host/net_socket/net_socket_test.c b/test/host/net_socket/net_socket_test.c index b05aa0cd..b579d538 100644 --- a/test/host/net_socket/net_socket_test.c +++ b/test/host/net_socket/net_socket_test.c @@ -346,8 +346,8 @@ static void tc_104_socket_no_inherit(void) p->session_dead == 0U && p->readable == 0U && p->send_ready == 1U && p->event_cb == NULL, "TC-NETSOCK-104j reusing the slot: no leftover field may carry over"); - /* 地址族不支持 → INVAL(在 alloc 之前,不占槽) */ - CHECK(net_socket(NET_AF_INET6, NET_SOCK_STREAM) == -1 && + /* 地址族不支持 → INVAL(在 alloc 之前,不占槽);返回值是契约失效值(C5) */ + CHECK(net_socket(NET_AF_INET6, NET_SOCK_STREAM) == NET_FD_INVALID && net_get_errno() == NET_ERR_INVAL && s_net_socks[1].in_use == 0U, "TC-NETSOCK-104k non-INET address family -> INVAL and no slot taken"); diff --git a/test/host/sntp/run_unit_test.py b/test/host/sntp/run_unit_test.py index 9d867d04..5771ed69 100644 --- a/test/host/sntp/run_unit_test.py +++ b/test/host/sntp/run_unit_test.py @@ -52,6 +52,7 @@ BUILD = TestBuild( os.path.join(ROOT, "App", "sync"), os.path.join(ROOT, "App", "cfg"), os.path.join(ROOT, "Drivers", "BSP", "NETCFG"), + os.path.join(ROOT, "Drivers", "BSP", "NET"), # net_fd.h(stub 先命中,仅补零依赖契约头) os.path.join(ROOT, "Lib", "coreSNTP"), os.path.join(ROOT, "Lib", "coreSNTP", "include"), HERE, diff --git a/test/host/sntp/sntp_test.c b/test/host/sntp/sntp_test.c index 0e0f4cfd..c15a5109 100644 --- a/test/host/sntp/sntp_test.c +++ b/test/host/sntp/sntp_test.c @@ -50,13 +50,16 @@ static syslog_id_t g_syslog_last_id; /* ---- net fake ---- */ #define SNTP_T_NET_SEND_MAX 8 #define SNTP_T_NET_RECV_MAX 8 +/* 假 fd 域与生产对齐(契约 C5/C7):0 基、上限 8,失效值 NET_FD_INVALID */ +#define SNTP_T_NET_MAX_FD 8 #define SNTP_T_NET_IP(o1,o2,o3,o4) { (o1), (o2), (o3), (o4) } static uint32_t g_gen; -static int g_sock_next_fd = 100; +/* 已分配 fd 集合(1 = 已分配)。net_close 对未分配 fd 必须失败——复刻生产 C6 */ +static int g_fd_alloc[SNTP_T_NET_MAX_FD]; static int g_sock_opens; -static int g_sock_close_calls; -static int g_last_close_fd = -1; +static int g_sock_close_calls; /* "关闭企图"次数(含对未分配 fd 的失败企图) */ +static int g_last_close_fd = NET_FD_INVALID; static int g_bind_calls; static int g_bind_ret; /* 脚本:0 成功 / -1 失败 */ static int g_errno_val; @@ -121,10 +124,10 @@ void syslog_post_quiet(syslog_id_t id, const char *desc) /* ---- net fake 实现 ---- */ static void sntp_t_net_reset(void) { - g_sock_next_fd = 100; + memset(g_fd_alloc, 0, sizeof(g_fd_alloc)); /* 假 fd 域:0 基,重置为空闲 */ g_sock_opens = 0; g_sock_close_calls = 0; - g_last_close_fd = -1; + g_last_close_fd = NET_FD_INVALID; g_bind_calls = 0; g_bind_ret = 0; g_errno_val = 0; @@ -164,10 +167,19 @@ static void sntp_t_push_recv(int kind, const uint8_t *data, int len, int net_socket(int domain, int type) { + int fd; + (void)domain; (void)type; g_sock_opens++; - return g_sock_next_fd++; + /* 与生产同域:最小空闲槽、0 基;全满返回契约失效值(不是"随便给个号") */ + for (fd = 0; fd < SNTP_T_NET_MAX_FD; fd++) { + if (g_fd_alloc[fd] == 0) { + g_fd_alloc[fd] = 1; + return fd; + } + } + return NET_FD_INVALID; } int net_bind(int sockfd, const struct net_sockaddr *addr, int addrlen) @@ -230,8 +242,16 @@ int net_recvfrom_to(int sockfd, void *buf, int len, uint32_t timeout_ms, int net_close(int sockfd) { + /* 无条件计数"关闭企图":旧实现(零初始化 fd=0)会来关未分配的 fd 0, + * 只有计数包含失败企图,回归用例才能看见这个动作(契约 C6 的另一面) */ g_sock_close_calls++; g_last_close_fd = sockfd; + /* 复刻生产语义:越界 / 未分配一律失败(测试代码,故与常量比较) */ + if ((sockfd < 0) || (sockfd >= SNTP_T_NET_MAX_FD) || (g_fd_alloc[sockfd] == 0)) { + g_errno_val = NET_ERR_BADF; + return -1; + } + g_fd_alloc[sockfd] = 0; return 0; } @@ -741,7 +761,7 @@ static void tc_recv_err_deadfd(void) g_errno_val = NET_ERR_CONNRESET; g_tick += 200u; time_sntp_run(g_gen); - CHECK(g_last_close_fd >= 100 && s_ctx.fd == -1, "recverr: dead fd closed"); + CHECK(g_last_close_fd == 0 && s_ctx.fd == NET_FD_INVALID, "recverr: dead fd closed"); CHECK(s_ctx.state == SNTP_ST_WAIT_DUE, "recverr: backoff"); /* 下一轮到点自动重开 socket */ for (t = 0; t < 12000u; t += 200u) { @@ -932,12 +952,36 @@ static void tc_offset_math(void) CHECK(exp == 5000LL, "off: (T2-T1+T3-T4)/2 == 5000ms exact"); } +/* + * 回归用例:冷启动 + 网络代次变化不得产生任何关闭企图的 net_close。 + * 抓的是板端 104 连不上的真因:s_ctx 是文件作用域 static,旧实现零初始化 → + * fd == 0(0 是合法 fd!),s_socket_close() 判据 `fd >= 0` 成立 → 对 fd 0 发 + * net_close,把别的服务(实测 FTP 监听槽 0)关掉。 + * + * 顺序要求(不可改用 s_case_reset):必须先清"关闭企图"计数,再让代次跳变; + * s_case_reset 把 g_gen++ 放在计数清零之前,会把这个证据擦掉。 + */ +static void tc_cold_start_gen_change_no_close(void) +{ + CHECK(s_ctx.fd == NET_FD_INVALID, + "coldstart: fd 显式初始化为 NET_FD_INVALID(0 是合法 fd)"); + + g_sock_close_calls = 0; + g_gen++; /* 冷启动首轮代次变化(等价上电后网卡就绪) */ + time_sntp_run(g_gen); + + CHECK(g_sock_close_calls == 0, + "coldstart: 代次变化不得产生 net_close 企图(旧实现会关未分配的 fd 0)"); + CHECK(s_ctx.fd == NET_FD_INVALID, "coldstart: 代次变化后仍无持有 fd"); +} + int main(void) { setvbuf(stdout, NULL, _IONBF, 0); printf("=== SNTP Client Tests ===\n"); #define TC(fn) do { printf("[" #fn "]\n"); fn(); } while (0) + TC(tc_cold_start_gen_change_no_close); TC(tc_poll_clamp); TC(tc_disabled_silent); TC(tc_first_send_window); diff --git a/test/host/sntp/stub/net_socket.h b/test/host/sntp/stub/net_socket.h index cf003048..b3f731c4 100644 --- a/test/host/sntp/stub/net_socket.h +++ b/test/host/sntp/stub/net_socket.h @@ -5,6 +5,8 @@ * 载荷/源地址/返回值由测试脚本注入(sntp_test.c 的 fake 实现)。 */ #ifndef SNTP_TEST_NET_SOCKET_H #define SNTP_TEST_NET_SOCKET_H + +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ #include "task.h" #include "net_types.h" diff --git a/test/host/time_sync/run_unit_test.py b/test/host/time_sync/run_unit_test.py index f59f1524..1225574e 100644 --- a/test/host/time_sync/run_unit_test.py +++ b/test/host/time_sync/run_unit_test.py @@ -48,6 +48,7 @@ BUILD = TestBuild( os.path.join(HERE, "stub"), os.path.join(ROOT, "App", "util"), os.path.join(ROOT, "App", "sync"), + os.path.join(ROOT, "Drivers", "BSP", "NET"), # net_fd.h(stub 先命中,仅补零依赖契约头) HERE, ], summary_marker="=== Time Sync Tests:", diff --git a/test/host/time_sync/stub/net_socket.h b/test/host/time_sync/stub/net_socket.h index 83fe36dd..bb357b59 100644 --- a/test/host/time_sync/stub/net_socket.h +++ b/test/host/time_sync/stub/net_socket.h @@ -18,6 +18,8 @@ #ifndef NET_SOCKET_H #define NET_SOCKET_H +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ + #include #include "FreeRTOS.h" diff --git a/test/host/ui_sink/run_unit_test.py b/test/host/ui_sink/run_unit_test.py index a824c52b..7334dcf4 100644 --- a/test/host/ui_sink/run_unit_test.py +++ b/test/host/ui_sink/run_unit_test.py @@ -40,6 +40,7 @@ BUILD = TestBuild( include_dirs=[ os.path.join(HERE, "stub"), os.path.join(ROOT, "Drivers", "BSP", "UI"), + os.path.join(ROOT, "Drivers", "BSP", "NET"), # net_fd.h(stub 先命中,仅补零依赖契约头) HERE, ], summary_marker="=== UI Sink Tests:", diff --git a/test/host/ui_sink/stub/net_socket.h b/test/host/ui_sink/stub/net_socket.h index ff3a44ac..7993c1aa 100644 --- a/test/host/ui_sink/stub/net_socket.h +++ b/test/host/ui_sink/stub/net_socket.h @@ -1,6 +1,8 @@ #ifndef NET_SOCKET_H #define NET_SOCKET_H +#include "net_fd.h" /* NET_FD_INVALID:与生产同一份契约(stub 不复制失效值) */ + /* * 主机侧桩(test/host/ui_sink):镜像真实 Drivers/BSP/NET/net_socket.h 中 * ui_net_sink.c 用到的 API 面(签名逐字一致),实现由测试文件提供假件。 @@ -11,6 +13,7 @@ #define NET_SOCK_STREAM 1 #define NET_INADDR_ANY 0u #define NET_ERR_WOULDBLOCK 11 +#define NET_ERR_BADF (-2) /* 与生产 net_types.h 同值:假 net_close 未分配关闭用 */ struct net_sockaddr { unsigned short sa_family; diff --git a/test/host/ui_sink/ui_sink_test.c b/test/host/ui_sink/ui_sink_test.c index 840be4b1..e4f4f039 100644 --- a/test/host/ui_sink/ui_sink_test.c +++ b/test/host/ui_sink/ui_sink_test.c @@ -18,6 +18,10 @@ int g_uisink_err_count = 0; /* ===================== 假件:net 层 ===================== */ +/* 假 fd 域与生产对齐(契约 C5/C7):0 基、上限 8;net_close 复刻 C6 的 + * "越界 / 未分配必须失败",未分配关闭返回 -1 并置 BADF。 */ +#define UI_SINK_FAKE_MAX_FD 8 +static int f_fd_used[UI_SINK_FAKE_MAX_FD]; /* 1 = 该 fd 已分配 */ static int f_rpc; /* 本轮已发生的 net RPC 次数 */ static int f_closes; static int f_accepts; @@ -39,7 +43,7 @@ static int rxq_len, rxq_pos; uint32_t net_get_generation(void) { return f_gen; } uint16_t net_htons(uint16_t v) { return (uint16_t)((v << 8) | (v >> 8)); } -int net_socket(int d, int t) { (void)d; (void)t; f_rpc++; return f_next_fd; } +int net_socket(int d, int t) { (void)d; (void)t; f_rpc++; if (f_next_fd >= 0 && f_next_fd < UI_SINK_FAKE_MAX_FD) { f_fd_used[f_next_fd] = 1; } return f_next_fd; } int net_bind(int fd, const struct net_sockaddr *a, int l) { (void)fd; (void)a; (void)l; f_rpc++; return 0; } int net_listen(int fd) { (void)fd; f_rpc++; return 0; } int net_accept(int fd, struct net_sockaddr *a, int *l) { @@ -48,6 +52,7 @@ int net_accept(int fd, struct net_sockaddr *a, int *l) { if (f_accept_next >= 0) { int c = f_accept_next; f_accept_next = -1; + if (c < UI_SINK_FAKE_MAX_FD) { f_fd_used[c] = 1; } return c; } f_errno_v = NET_ERR_WOULDBLOCK; @@ -75,7 +80,16 @@ int net_recv_nb(int fd, void *b, int n) { rxq_pos += take; return take; } -int net_close(int fd) { (void)fd; f_rpc++; f_closes++; return 0; } +int net_close(int fd) { + f_rpc++; f_closes++; + /* 测试代码:裸字面量判据在此是"假对象域校验"语义,非生产判据(契约 C6) */ + if (fd < 0 || fd >= UI_SINK_FAKE_MAX_FD || f_fd_used[fd] == 0) { + f_errno_v = NET_ERR_BADF; + return -1; + } + f_fd_used[fd] = 0; + return 0; +} int net_get_errno(void) { return f_errno_v; } void *net_get_sock(int fd) { (void)fd; return f_sock_alive ? (void *)&f_gen : (void *)0; } @@ -144,9 +158,10 @@ static void fresh(int hook) { memset(rxq, 0, sizeof(rxq)); rxq_len = rxq_pos = 0; f_rpc = 0; f_closes = 0; f_accepts = 0; + memset(f_fd_used, 0, sizeof(f_fd_used)); f_armed = 0; f_can_read = 0; f_accept_next = -1; f_recv_mode = 1; f_gen = 1; f_errno_v = 0; - f_next_fd = 3; f_sock_alive = 1; + f_next_fd = 0; f_sock_alive = 1; s_key_n = 0; s_lcdmem_calls = 0; g_uisink_err_count = 0; s_last_tx_len = 0; ui_net_sink_set_beat_cb(hook != 0 ? beat_cb : (void (*)(void))0); @@ -172,7 +187,7 @@ static void qframe(uint8_t cmd, const uint8_t *d, int len) { static void case_null_hook_full_protocol(void) { printf("case: unregistered hook runs the whole protocol path unchanged\n"); fresh(0); - f_armed = 1; f_accept_next = 3; /* MCU 单连接模型:client fd = listen fd */ + f_armed = 1; f_accept_next = 0; /* MCU 单连接模型:client fd = listen fd */ ui_net_sink_poll(); /* accept -> g_client=3 */ CHECK(s_beats == 0, "no hook: zero beat side effects"); f_armed = 0; /* 已建连后不再走 accept */ @@ -197,7 +212,7 @@ static void case_gated_zero_rpc(void) { fresh(1); for (int i = 0; i < 5; i++) { ui_net_sink_poll(); } /* armed=0,无监听活 */ CHECK(f_rpc == 0 && s_beats == 0, "listener unarmed: 5 rounds no RPC no beat"); - f_armed = 1; f_accept_next = 3; + f_armed = 1; f_accept_next = 0; ui_net_sink_poll(); /* 建连(1 RPC + 1 心跳) */ f_armed = 0; int b0 = s_beats; @@ -231,10 +246,10 @@ static void case_storm_chain_beats(void) { static void case_rebuild_beats(void) { printf("case: generation rebuild feeds after close pair and after re-listen\n"); fresh(1); - f_armed = 1; f_accept_next = 3; + f_armed = 1; f_accept_next = 0; ui_net_sink_poll(); /* client=3=listen */ int r0 = f_rpc; int b0 = s_beats; - f_gen = 2; f_next_fd = 9; + f_gen = 2; f_next_fd = 1; ui_net_sink_poll(); /* 代次变化:close+start */ CHECK(f_closes == 1 && f_rpc == r0 + 4, "rebuild does close x1 (client==listen guard) + socket/bind/listen"); @@ -247,7 +262,7 @@ static void case_rebuild_beats(void) { static void case_eof_keepalive(void) { printf("case: EOF (MCU model, client==listen) never closes the listen fd\n"); fresh(1); - f_armed = 1; f_accept_next = 3; + f_armed = 1; f_accept_next = 0; ui_net_sink_poll(); f_armed = 0; /* EOF 后无 accept 通路的静默形态 */ f_recv_mode = 2; f_can_read = 1;