fix(net): 建立网络 fd 失效值契约,杜绝零初始化误判
根因:静态 fd 零初始化为 0,而 0 是合法 socket 句柄;判据用 >=0 会把"未初始化"误判成"有效",关闭时误伤他人 fd。本次把该修复 契约化、机械化,而不是再补一个点。 - 新增 net_fd.h 定义唯一失效值 NET_FD_INVALID(-1),全仓零依赖复用 - fd 判据只用 ==/!= NET_FD_INVALID,禁 >=0/<0/数值形态/if(fd) - 网络层内部用 NET_FD_IN_RANGE 做范围校验,上界不外泄 - 主机 fake 改 0 基并跟踪已分配 fd,补冷启动回归(变异测试可捕获) - 新增 net-handle 静态门禁(钩子 53)+ 契约文档 + 审计 + 最小加固 验证:net-handle 487 文件 0 违规;8 个主机套件全绿;Keil 0 错误 0 警告; 审计 3 确认/5 疑似/35 安全,无第二处生产误判。
This commit is contained in:
@@ -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 与失败读法、新代码接入八条自查清单 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 <tree>` 取补丁 → `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 <hook-id> --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 <id> --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 <UTF-8 无 BOM 文件>` 并自查最长行;或先老实提交一次让 `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 <hook-id>`,一次一个 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 <hook-id>`,一次一个 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 检测脚本 |
|
||||
|
||||
@@ -47,10 +47,10 @@ dhara 失败类 +84;RO 另 +208,全是该失败类名表)→ `ER_IROM1`
|
||||
<!-- MEM_SNAPSHOT:BEGIN generated by scripts/check_mem_numbers.py -->
|
||||
| 区域 | 用量 | 容量 | 占比 |
|
||||
|---|---|---|---|
|
||||
| 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%** |
|
||||
<!-- MEM_SNAPSHOT:END -->
|
||||
|
||||
各区的容量与常量来源:
|
||||
|
||||
@@ -15,10 +15,10 @@
|
||||
<!-- MEM_BUDGET:BEGIN generated by scripts/ram_baseline.py -->
|
||||
| 区域 | 用量 | 容量 | 占比 | 门禁(≤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) | 现值 | 配额 | 状态 |
|
||||
|---|---|---|---|
|
||||
|
||||
@@ -45,6 +45,7 @@
|
||||
| 非阻塞模式 | `O_NONBLOCK` / `MSG_DONTWAIT` | `net_setblocking(fd, 0)`(模式属性)/ `net_recv_nb()` / `NET_MSG_DONTWAIT`(单次) |
|
||||
| 错误码 | errno | `net_get_errno()` |
|
||||
| 头文件 | `<sys/socket.h>` | `"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 字节)
|
||||
|
||||
@@ -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] <file>: 第 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` |
|
||||
+18
-16
@@ -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 <hook-id>`
|
||||
(**一次只能给一个 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 篇)。
|
||||
|
||||
@@ -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 的口径同步,不要只改一处。
|
||||
@@ -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 · 驱动关键点速查(细节以对应条目为准)
|
||||
|
||||
Reference in New Issue
Block a user