Files
STM32F4-Base/test/host/iec104_netmcu/MATRIX.md
T
wandering1 90cc9a7d99 feat(iec104): 把 104 骨架完整迁到 MCU 板端并在台架跑通总召
把 IEC104 从模拟器端整体搬到板端:协议栈原先由独立 iec104Task 驱动,
现在改为 netTask 单 owner 的 threadless 驱动,退役独立任务。

驱动与后端:
- 新增 iec104_net_mcu.c/.h,实现 IEC104_Net.h 的 11 个 ABI 函数,
  用槽表加单调句柄映射 net_socket 的单 fd 模型;CLIENT 拆除只走
  net_drop_conn_locked,绝不 net_close 监听 fd。
- net_socket 增 5 个 owner-only 接口(net_accept_locked、
  net_drop_conn_locked、net_pending_bytes、net_send_try、
  net_mono_now_ms)。
- iec104_serv.c 重写为 iec104_serv_net_tick(),在 netTask 1ms 主循环
  里驱动 core;无 osDelay/阻塞调用,喂狗是第一句。
- Src/freertos.c 删除 iec104Task 三件套,对应栈水位探针表项同步删除。

内存:目标板 192KB SRAM 装不下 vendor 默认容量档,按实测裁剪到
skeleton 档(TCP 缓冲、业务池、SOE 256->128、值槽密集化),
RW_IRAM1 118,408 B / 90.3%,留 2,178 B 余量。

台架修复(只在真硬件暴露):
- SNTP s_ctx.fd 零初始化后为 0,而 net fd 0 是合法槽位下标,
  首次代次变化时误 net_close(0) 关掉 ftpTask 的监听槽,导致 104
  连接被 FTP 的 220 banner 抢走;改为显式 .fd = -1。
- Accept 幂等:单 fd 模型下 vendor 每轮重试 Accept 会拿到同一 fd,
  后端改为会话在役时返 WOULD_BLOCK,Close 不再清槽。

验证:
- Keil 全量重建 0 error 0 warning,uvprojx 零抖动。
- 模拟器真实 TCP 13/13、transport 10/10。
- netmcu 后端单测 13/13(新增 N12)。
- 台架 serial-boot-test required 全中;板端 2404 总召 129 帧收到
  59 遥信(53 有源、全 IV)+ 16 双点 + 30 遥测(PT1 三相非零、
  UN/频率/温度按未标定置 IV)、遥控选择执行全否定、校时 COT 7。
- 期间顺带修正 UI 漂移自检文案、.serialtest required 陈旧项、
  coding-standard 对 vendor 与外部 ABI 名字的排除口径。
2026-11-18 10:29:18 +08:00

97 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 板端 IEC104 Net 后端隔离契约测试矩阵
## 交接说明(最终交付状态)
- **这组测试证明什么**:针对 `App/protocol/iec104/iec104_net_mcu.c`(被测 SHA256 `08ca22b9d61ec86181973ab97d7fab68ec8f0ecbf944bfd758e1546a80dc8b35`)的真实后端,在 fake net 层上证明 IEC104 Net ABI 契约:同 fd 语义下 Close 不毁监听、Pending_Input 精确/降级有界续收、Send 短写且不借用 buffer、Now_Ms 跨 32 位 tick 回绕单调、网络代次与句柄失效、断链重连、非 owner 入口拒绝、两句柄模型下代次重建后的监听存活(armed==1)与无 ABA、以及单 fd 会话的 Accept 一次性语义(已有 CLIENT/CLIENT_EOF 槽时 WOULD_BLOCK、零芯片事务、Close 后释放;旧语义"re-Accept 再发新句柄"已实测导致板端拆活连接,2026-11-18 台架)。最终实测:文本级静态 2/2、静态 checker 变异自测 `real_rc=0 mutant_rc=1`、动态 12/12(`real backend passed 12/12`)。
- **这组测试不证明什么**:fake net 层只是按产品头语义实现,不是真实 CH395F 驱动或板端电路;**CH395F 板端行为未验**(同 fd 语义待板端确认);**core / TcpServer 集成未验**(完整 STARTDT 建链为 NOT_RUN);netTask 队列/临界区与板端时序未验;MCU WCET / 性能未测;真实后端编译期坏变体未做,历史 TEST DOUBLE B1~B7 仅证明 harness 有效性;S1/S2 是文本级静态检查,不覆盖宏展开或函数指针间接调用。禁止据此写“板端已验证”。
- **一条命令复现**(仓库根执行):`python test/host/iec104_netmcu/check_static_selftest.py && python test/host/iec104_netmcu/check_static.py && python test/host/iec104_netmcu/run_netmcu_tests.py && git diff --check -- test/host/iec104_netmcu`
- **产物在哪里**:本目录 `test/host/iec104_netmcu/`;最终动态证据 `results/real/{build.log,run.log,report.json}`,静态证据 `results/static/report.json`,静态 checker 变异自测 `results/static_mutant/{report.json,selftest.txt,iec104_net_mcu_BAD.c}`,历史 TEST DOUBLE 证据 `results/report.json` 与 `results/{good,B1..B7}/`。所有文件未提交、未改产品/供应商源码;第二步 serv 重写后待命做 `iec104_serv_net_tick` 针对性核查。
## 状态与边界
- 被测对象:`App/protocol/iec104/iec104_net_mcu.c`(真实板端 Net 后端,net-cutover 所有)对 `IEC104_Net.h` 的实现。
- 测试替身:`net_socket_fake.{h,c}` 按产品 `Drivers/BSP/NET/net_socket.h` 声明模拟 `net_*` owner 出口(包括 `net_send_try` / `net_pending_bytes` / `net_mono_now_ms` / `net_accept_locked` / `net_drop_conn_locked` / `net_ctx_is_owner_task` 等),并受控注入单连接同 fd、短写 / WOULD_BLOCK / BUSY / RETRY_LATER、EOF / RST、网络代次变化、句柄非复用、芯片接收队列长度与 32 位 tick 回绕。绝不调用真实 CH395F 或 Windows socket。
- **CH395F 同 fd 语义(fake 已如实建模,板端仍待验证)**:`net_accept` / `net_accept_locked` 返回**监听 socket 自身**(`net_socket_fake.c:629-643` 的 `return sockfd;`),并为同一 fake fd 置 `established=1`;`net_close` 对监听 fd 会**真实销毁监听**并递增 `listen_closed_attempts`(`net_socket_fake.c:760-777`),而 `net_drop_conn` 只拆会话、保留监听(`net_socket_fake.c:779-797`)。因此 fake 不是 Winsock 式独立 fd 语义,N1/N8 断言的“Close 不毁监听”确实在同 fd 规则下判定;但这只是 fake 忠实模拟,**CH395F 实际行为仍待板端验证**。
- 本目录不进 `MDK-ARM/*.uvprojx`,不碰产品构建;只在主机侧用 MSVC 编译运行。
- 证据边界:这是 **真实后端 + fake net 层** 的 Net ABI 隔离证据,不等于完整 `iec104_core` / `TcpServer` 链路,不等于板端 CH395F / netTask 时序,也不是 MCU WCET。完整 STARTDT 建链流程仍为 NOT_RUN。
- Lead 三条口径:① `Now_Ms` = N-2(owner 周期采样),只测回绕后单调,不测“不调用也不漏记”;② `Pending_Input` 精确:RX=7 报 7、RX=0 报 0,不谎报 1/0;③ `Send` 返回后不借用 buffer:每次用不同源 buffer,返回即覆写,再断言 fake 内核中字节未被破坏。
- 已知平台偏离:CH395F 无 `setsockopt`,`App/protocol/iec104/iec104_net_mcu.h` 注释已入档;恒无 Nagle 视作平台事实,**不以 NODELAY 作为 OK 条件**。plan.md 的入档由 net-cutover 负责。
## 静态源码检查(先于动态用例)
| 编号 | 检查 | 判据 | 实测 |
|---|---|---|---|
| S1 | `IEC104_Net_Close` 的 CLIENT/CLIENT_EOF 分支不含 `net_close_sock` | 花括号范围机械匹配,非肉眼 | PASS,源文件 582-588 行 |
| S2 | `IEC104_Net_Recv` 的 `rc==0` EOF 分支只改角色,不含任何 close/drop 调用 | 花括号范围机械匹配 | PASS,源文件 408-414 行 |
静态检查源文件 SHA256:`08ca22b9d61ec86181973ab97d7fab68ec8f0ecbf944bfd758e1546a80dc8b35`;`results/static/report.json` 记录逐项 `source_lines` / `evidence` / `passed`。
**S1/S2 覆盖面(重要)**:这是**文本级**静态检查——用花括号范围匹配特定分支,断言其中不出现 `net_close_sock` 等标识符;它覆盖直接调用形态,**不做语法树/控制流分析**,宏展开、函数指针或间接调用形态不在覆盖范围。不得把 S1/S2 PASS 表述为“所有关监听路径均不存在”。
静态判据自身有效性有降级证据:`check_static_selftest.py` 在 `results/static_mutant/iec104_net_mcu_BAD.c` 中把 `net_close_sock` 注入真实 Close 的 CLIENT 分支,断言 `check_static.py` 对该副本返回 `passed 1/2`(S1 失败)且 RC≠0,同时对真实源文件仍 `2/2` RC0。实测:`static-checker selftest: real_rc=0 mutant_rc=1`;证据 `results/static_mutant/{report.json,selftest.txt,iec104_net_mcu_BAD.c}`。产品源文件未改。
## 动态用例矩阵
共 **12 个命名用例**(N2 拆为 N2a/N2b 两个 case,但同属一个 N2 测试函数;`report.json` 的 `case_count=12`、`case_names` 与 `case_count_basis` 与此一致)。
| 编号 | 用例 | 关键断言 | 实测 |
|---|---|---|---|
| N1 | Close 会话不影响监听 | 逻辑 client handle ≠ listener handle;Close(client) 后 `listen_closed_attempts==0`、`drop_conn_calls>=1`,同一 listener 可再 Accept | PASS |
| N2a | Pending_Input 精确值 | RX=7 → `available==7`;排空后 RX=0 → `available==0` | PASS |
| N2b | 接收队列查询降级/报小不藏数据 | 300B 在哨兵/报小模式下仍全部交付,不死循环、不提前结束 | PASS |
| N3 | Send 短写推进 + 零借用 | 20B 分多次推进;20 个不同源 buffer 返回后均涂 `0xEE`;fake 内核仍为涂改前 `0x41..0x54` | PASS |
| N4 | Now_Ms 跨 32 位回绕单调 | tick `0xFFFFFFF0 → 0xFFFFFFFF → 0`;64 位值严格递增,回绕差值 1ms | PASS |
| N5 | 网络代次变化使旧句柄失效 | 旧 client 的 Send/Recv/Pending/Accept 均 ERROR/BADF;旧 client Close 幂等 OK 且 `hardware_calls` 零增长;无 Init 的新 Listen 可用 | PASS |
| N6 | fd 复用 / 陈旧句柄不串味 | Close 后旧 client handle 读写 ERROR、重复 Close 幂等;新 client handle 不同且可收发;监听从未被关 | PASS |
| N7 | 断链重连(Net 层) | RST → Recv ERROR → Close(client) → listener 仍活 → 新 client handle → Send OK;**完整 STARTDT 仍 NOT_RUN** | PASS(Net 层) |
| N8 | Close 后同一 listener 再 Accept | 第二次 Accept 成功;`listen_closed_attempts==0` 机器断言;listener fd 仍活 | PASS |
| N9 | 非 netTask 上下文拒绝 | 所有入口 `ERROR + NET_ERR_INVAL`;`available` / `ready_events` 输出不变;`hardware_calls` 零增长、无死锁 | PASS |
| N10 | 代次切换的两句柄模型(戊+不变量) | h_client ≠ h_listener;代次推进后两句柄均失效;旧 client Close 幂等 OK 且 `hardware_calls` 不增、`listen_closed_attempts==0`;代次推进后旧 listener 已失效(`armed==0`),**重建 Listen 后 `net_fake_listener_armed()==1` 正向断言**;不调 Init 重建 h3 严格 >旧句柄(无 ABA);新 client Send OK | PASS |
| N11 | 单 fd 会话的 Accept 一次性语义(2026-11-18 台架事故修复证据) | 已有 CLIENT 槽时第 2 次 Accept 返回 `IEC104_NET_WOULD_BLOCK`、client 出参不变;`drop_conn_calls` / `hardware_calls` 均**不增**(闸为纯 RAM,零芯片事务);`listen_closed_attempts==0`;`armed==1`;**H1 正向证明**:库手里的首个 client 句柄仍能命中 CLIENT 槽并 Send OK、会话 fd 不变且与监听槽同 fd(旧代码 memset 旧槽会让 H1 悬空 → BADF → Drop_Client,这是"STARTDT 无回应 + 20~33ms EOF"的第一击);Close 旧 client 后新 Accept 成功(无永久静默拒连) | PASS |
| N12 | 会话在役时 Wait 不报假 ACCEPT(重复 Accept 引擎闸) | 无会话时 `IEC104_Net_Wait(ACCEPT)` 报 READY;会话在役后 `ready_events` **不含** `IEC104_NET_EVENT_ACCEPT`(`net_listener_armed` 对 ESTABLISHED 恒返 1,不挡则库每轮误判可接入、重复调 Accept);Close 后恢复报 READY(非永久静默拒接) | PASS |
> 两句柄模型(net-cutover 第三轮定案):LISTEN 槽 handle 在监听生命周期内不变,Accept 另起 CLIENT 槽与新 handle;不再翻转监听槽 role。这正是 N8 / N10 / N11 的判据来源。
> N11 原语义("re-Accept 再发新句柄、只 memset 旧槽")已实测导致板端拆活连接,两层伤害:① 第 2 次 Accept 的 `memset(client_slot)` 清掉库仍持有的 H1 槽 → `slot_by_handle(H1)` 失败 → STARTDT_ACT 的 Send 报 BADF → Drop_Client(第一击,解释了 STARTDT 无回应 + 20~33ms EOF);② 即便不清槽而另开 H2,库仍在 `IEC104_TcpServer.c:1606` Close(client) 把与监听同 fd 的会话拆掉(第二击)。现行语义 = Accept 一次性硬闸(已有当前代次 CLIENT/CLIENT_EOF 槽一律 WOULD_BLOCK,含 EOF 收尾窗口,先纯 RAM 判后碰芯片)+ Wait 侧 ACCEPT 就绪闸(N12),Close 后自动释放。这是防止同根因复发的行为证据。
## 坏变体与注入有效性
- **TEST DOUBLE 阶段(历史 harness-validity 证据,不是产品证据)**:`netmcu_stub_test.c` + `stub_iec104_netmcu.c` 的 B1~B7 全部变红:`good 7/7`;`B1..B7 red 7/7`。注入点:B1 Close 误用 net_close、B2 Pending 降级谎报 0、B3 Send 借用 buffer、B4 tick 强转、B5 忽略代次、B6 陈旧 Close 误关、B7 重连沿用 startup_ack。原始逐变体日志保留在 `results/good/` 与 `results/B1/`~`results/B7/`。
- **真实后端阶段**:B1~B7 宏依赖 TEST DOUBLE,不适用于真实后端,标记 **NOT_RUN**;真实后端的文本级静态面由 S1/S2 + `check_static_selftest.py` 覆盖,行为面由 N1~N12 覆盖。不得把 TEST DOUBLE 的 7/7 红当成真实后端坏变体结果。
## 测试发现的问题(独立验收追溯)
| 时间 | 后端 SHA256 | 发现 | 处置 |
|---|---|---|---|
| 2026-11-17 23:20+ | `bc7154e5…`(第三轮两句柄初版,620 行) | 首次真实后端跑 N9:`Recv/Pending_Input/Send/Wait` 四入口缺 owner 闸,非 owner + 无效句柄返回 BADF/OK 而非 `ERROR+NET_ERR_INVAL` | net-cutover 补 owner 闸(最终 `08ca22b9…`,620 行),复测 PASS |
| 2026-11-17 23:22+ | `08ca22b9…` 前夕 | N10 初版断言暴露:重建 Listen 若走 `Init` 会重置句柄计数,产生 ABA 风险;测试改为**不调 Init** 的 `listen_only()` 并断言 h3 严格大于旧句柄 | 后端保持单调递增句柄实现,复测 PASS |
| 2026-11-17 23:26+ | `08ca22b9…` | 按 protocol-review/lead 补 A7 正向断言时发现 fake 的 `generation_inc` 会清掉旧监听 armed(芯片复位语义),“stale 后、重建前 armed==1”不成立;断言改为 stale 后 armed==0、重建后 armed==1 | 测试口径修正,非后端缺陷;复测 PASS |
## 复现命令与最终实测输出
仓库根执行(最终后端 SHA256 `08ca22b9d61ec86181973ab97d7fab68ec8f0ecbf944bfd758e1546a80dc8b35`):
```
python test/host/iec104_netmcu/check_static.py
python test/host/iec104_netmcu/check_static_selftest.py
python test/host/iec104_netmcu/run_netmcu_tests.py
```
实测输出:
```
static source sha256=08ca22b9d61ec86181973ab97d7fab68ec8f0ecbf944bfd758e1546a80dc8b35
S1: Close CLIENT/CLIENT_EOF branch contains no net_close_sock 582-588 passed=True
S2: Recv EOF branch only changes role; no close/drop call 408-414 passed=True
static passed 2/2
static-checker selftest: real_rc=0 mutant_rc=1
real: build_rc=0 run_rc=0 note= failed_cases=[]
real backend passed 12/12
```
`git diff --check -- test/host/iec104_netmcu` 无输出(RC0)。`results/real/build.log` / `results/real/run.log` 是逐条原始日志,`results/real/report.json` 记录被测源文件哈希、测试源文件哈希、case count = 13、失败用例列表、NOT_RUN 项与已知偏离。`results/static/report.json` 与 `results/static_mutant/report.json` 记录静态正向/变异结果。
## 证据口径
- 动态 13/13 + 文本级静态 2/2 + 静态 checker 变异自测 1 red 只证明:真实 Net 后端在 fake net 层上的 ABI 契约、两个文本级静态不变量,以及 N11 单 fd Accept 一次性语义(WOULD_BLOCK + 零芯片事务 + H1 仍有效 + Close 后释放)与 N12 Wait 侧 ACCEPT 就绪闸(会话在役不报假 ACCEPT、Close 后恢复)。
- 未证明 / NOT_RUN:完整 IEC104 STARTDT 业务链路、真实 CH395F 同 fd 行为(fake 忠实模拟但板端未验)、netTask 队列/临界区、板端时序与 MCU WCET、真实后端编译期坏变体、宏/函数指针间接调用形态的静态覆盖。不得写“板端已验证”。