e4981aa2f6
AGENTS.md stopped being the store of record for build steps, Python env, hardware pins, doc conventions, log cost and task ownership. Those facts already live in docs, skills and role files; the entry file now only points at them. This commit moves every reference that used to name the entry file to the authoritative landing point, so a reader who follows a link arrives at the fact instead of at a sentence that no longer exists. What changed is links and prose, not behaviour. Code, scripts and tests only have comment and docstring lines touched; the only non-comment edit in the whole changeset is one note string inside the generated pin table JSON, and its generator was changed in the same step so the two stay byte-identical. New landing points created before the references were retargeted: - The console single-writer log design doc, section 7.1, is now the single authority for log cost: about 90 B flash and 216 B stack per DBG_ line, and the rule that deep call chains must predefine DBG_LINE_BUF_MAX. It also carries the full list of the twelve translation units that have tightened it, plus the grep command that decides the truth if the list and the code ever disagree. - The document writing standard, section 2, now holds the BOM list. - keil-build skill gains an exit code table: 0 success, 1 build failure, 2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief that was never actually written down anywhere: exit 2 does not simply mean environment error, argparse also exits 2 and the wrapper script was remapped so the two no longer collide. Regenerated and checked byte for byte: - The end-to-end architecture SVG in docs/images from its generator. - tools/netlist_semantics/pinout_kb.json from gen_kb.py. Both are idempotent; running the generators again produces no diff. Deliberately not touched, because machines read them: - scripts/check_bom_drift.py joins every line containing BOM and asserts four paths are present, so the entry file BOM line must stay one line. - scripts/gen_task_table.py reads the TASK_TABLE anchors directly. - scripts/rename_maps and scripts/archive keep their historical wording; they describe what happened, not what is true now. Verified: doc links report the same six pre-existing findings as the base commit and no new ones, generated-fresh passes, bom drift is clean across 101 files, and AGENTS.md itself is unchanged in this commit.
14 KiB
14 KiB
test/host/ — 主机端测试脚本
PC 侧的测试驱动与判读脚本(Python,跑在开发机上,经串口/网络与目标板交互)。
文件一览
流程与判读
| 脚本 | 作用 |
|---|---|
run_boot_test.py |
/serial-boot-test 一键闭环:开串口+清日志 → 烧录 → wait-idle → verify_log 校验(退出码 0=PASS) |
verify_log.py |
日志标记校验:Required / Forbidden 标记 → PASS / FAIL;可选 --require-suite-summary 校验套件汇总行(=== <名称>: N/M PASSED (failed=0) === 且 N>0),抓"没跑到汇总行/断言数为 0"的盲区 |
网络 / FTP
| 脚本 | 作用 |
|---|---|
ch395f_socket_test.py |
Socket 通信测试(回显服务器 / 文件收发) |
ftp_test.py |
FTP 基本功能测试 |
ftp_up_dl_test.py |
FTP 上传下载测试 |
ftp_speed_test.py |
FTP 传输速度测试 |
ftp_capture.py |
FTP 流量抓取 |
ftp_regression.py |
FTP 回归套件 |
ftp_abort_probe.py |
FTP 中止场景探针(TRAP-NET-18;RST→450 / FIN→226,--check-abort;2026-10-13 自 MDK-ARM/ 迁入) |
ftp_integrity_test.py |
FTP 上传 SHA-256 完整性多轮回归 |
n30_repro.py |
背靠背 STOR 复现器(TRAP-NET-20 常备回归腿) |
relisten_stress.py |
监听快速复连压力(TRAP-NET-17 / E1:--port --n --gap-ms [--hold-ms]) |
e11_keepalive_probe.py |
keepalive 黑洞判死探针(E11) |
e6_soak.py |
E6 24h 挂机驱动(常态 + 每小时/每 4h E1 压测注入;判据读串口 U15 probe 计数) |
pasv_probe.py |
PASV 数据通道时序探针 |
ch395f_reuse_host.py |
Socket 复用/中止形态 PC 对端(bench 配套) |
ftp_auth_bench.py |
FTP 鉴权/锁定台架腿 |
iec104_master.py |
IEC 60870-5-104 主站客户端(台架复测/保护定值持久化):连设备 :2404(工厂默认,--port 可指别的)跑 STARTDT → 总召(actcon/四组背景扫描/actterm)→ 经 C_SE 两段写临时压低 OC1 定值确定性触发 YX16 变位(COT=3)→ 恢复 → YK11 两段式 → C_RD 读回;保护定值持久化模式 --b7-pre/--b7-post/--b7-mark/--b7-check(中间 ST-LINK 复位):YK12 两段投退→保护退出/联动、定值与压板态跨复位保持(含非默认 7.5 往返);纯标准库,输出纯 ASCII 可直接重定向归档为台架证据(判据 exit 0/1/2) |
cal_fit.py |
N 点最小二乘标定参数求解(全仓唯一实现,v2.2 起固件侧拟合已删除)(3~8 点,推荐 5 点):--selftest 跑金标向量回归(原 C 侧 r_q16=39322000 / b=12 + 4 条拒绝路径,exit 0 全过 / 1 有失败,改动算法后必跑);--from-doc 直接读执行卡 §3 CALDATA 长表(每行一个点:路 | 序号 | 屏上读数 | 注入已知量)按路分组拟合,输出合并 WRITE-ALL 命令;单路 --sem/--x/--y 亦可(--x = meas: 行 mV/mA 原样、--y = V/A 内部 ×1000,--r-old/--b-old 指读数采集时的设备参数);执行卡 docs/测试说明/专项验证/ADC多点标定执行流程.md §3;exit 0 可写 / 2 拒绝(入参越界 bad argument、点数越界、点位没拉开、单调性反转、斜率非正、r/b 越带、残差 >2%、表还是旧 6 列)或未填 |
cal_write.py |
标定参数写入器(库层复用 iec104_master.py):C_SE 两段写下发定值段 0x8050~(变比 r)/0x8048~(零点 b,落笔置 VALID),C_RD 读回复核;每路先 r 后 b,输出纯 ASCII 可归档;执行卡 docs/测试说明/专项验证/ADC多点标定执行流程.md §4;exit 0 全过 / 1 有失败 / 2 连接或协议错误 |
时间 / 时延
| 脚本 | 作用 |
|---|---|
latency_peer.py |
链路时延测试的 PC 对端(peer) |
原
time_sync_server.py(:8888 推送对时源)已随 :8888 退役删除(2026-11-04,#78); 对时改为板端 SNTP 客户端出向(墙钟说明 §16),台架用真实/私有 NTP 源即可。
主机侧单元测试(纯逻辑,无硬件)
| 文件 | 作用 |
|---|---|
common/unit_test_harness.py |
通用单测 harness(主机侧纯逻辑单测):探测 MSVC → 拼 INCLUDE/LIB → 编译 → 运行 → 判定退出码。各模块运行器只做声明式配置(TestBuild),不含工具链细节 |
watchdog/run_unit_test.py |
看门狗判定状态机单测:声明 TestBuild 后调 harness,用 MSVC 离线编译真实 App/util/task_watchdog.c(可观测桩驱动),39 用例穷举边界。零硬件、秒级(退出码 0=PASS/1=FAIL/2=环境错误) |
watchdog/watchdog_test.c |
测试单元本体(#include 生产源码 + 平台钩子桩) |
watchdog/stub/ |
桩头文件(main.h/iwdg.h/dbg_log.h),覆盖 MCU 版以在 PC 上编译 |
sys_clock/run_unit_test.py |
系统时钟换算单测:离线编译真实 App/util/sys_clock.c,以可控时钟 + 阴影 RTC 桩驱动,100 断言点覆盖闰年/月末/世纪/2038 上限/星期/30 天惰性再基准化/RTC 故障降级 |
sys_clock/sys_clock_test.c |
测试单元本体(#include 生产源码 + 强符号桩;不改生产代码) |
sys_clock/stub/ |
桩头文件(main.h/FreeRTOS.h/task.h/dbg_log.h),覆盖 MCU 版以在 PC 上编译 |
cfg_file/run_unit_test.py |
配置引擎单测:离线编译真实 App/cfg/cfg_file.c,以内存虚拟文件系统桩驱动,149 断言点覆盖 INI 解析/四种值类型编解码/段注册校验/load-save-poll 契约/超长守卫/故障注入 |
cfg_file/cfg_file_test.c |
测试单元本体(#include 生产源码 + cfg_store_* 内存 FS 后端桩;不改生产代码) |
cfg_file/stub/ |
桩头文件(dbg_log.h),覆盖 MCU 版以在 PC 上编译 |
phasor/run_unit_test.py |
相量层(L2)单测:离线编译真实 App/algo/phasor.c + sample_ring.c(无需任何桩,纯算法),57 用例覆盖傅氏系数表 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区原子交换 |
phasor/phasor_test.c |
测试单元本体(#include 两个生产源码 + 合成任意波形) |
adc_input/run_unit_test.py |
ADC 输入层(L1)单测:离线编译真实 App/algo/adc_input.c,103 用例给每个 Rank 注入互异码值逐通道钉死映射,并覆盖 DMA 挂载失败 / 乒乓半区选择(撕裂帧防线) / 超拍丢帧 / 停摆 / HAL 回调句柄守卫 / 停摆拍陈旧帧 / 参数错等真机难复现分支 |
adc_input/adc_input_test.c |
测试单元本体(#include 生产源码 + HAL / TPAFE 可注入桩) |
adc_input/stub/ |
桩头文件(adc.h / tpafe5160.h) |
vol_lock/run_unit_test.py |
卷锁单测:离线编译真实 App/fs/vol_lock.c,33 断言点覆盖创建 / 获取 / 释放契约(fail-open 不变量:创建失败仍返回 1 且零阻塞)/ 幂等 / 超时透传 |
vol_lock/vol_lock_test.c |
测试单元本体(#include 生产源码 + CMSIS 互斥桩) |
vol_lock/stub/ |
桩头文件(cmsis_os.h) |
time_sync/run_unit_test.py |
时间同步任务载体单测(v2.0):离线编译真实 App/sync/time_sync.c,33 断言点覆盖分片喂狗延时 / 就绪屏障(100 ms 分片、osFlagsNoClear、永不就绪不挂死)/ SNTP 节拍驱动与网络代次当轮交接 / 未出网守门(:8888 退役后任务即纯校时节拍宿主) |
time_sync/time_sync_test.c |
测试单元本体(#include 生产源码 + 网络 / 事件 / RTOS 可脚本化桩 + longjmp 跳出 for(;;) 任务循环) |
time_sync/stub/ |
桩头文件(FreeRTOS.h / task.h / cmsis_os2.h / net_socket.h(裁剪至 net_get_generation,编译期绊线:生产码若再引监听类 API 立刻炸)/ sys_events.h) |
iec104/run_unit_test.py |
IEC 60870-5-104 协议栈单测(IEC 104 上行):离线编译真实 App/protocol/iec104/ 三模块 + 数据源(prot_set/prot_elm/phasor/sample_ring),82 用例覆盖 CP56 往返 / APCI 半帧·粘帧·坏帧 / STARTDT 握手 / 总召分片+RBT / COV 死区 / k=12 窗满 / w=8 触发 S / t1·t2·t3 / N(R) 倒退判故障 / 遥控·定值两段式与 PN / C_CS / 未知类型·地址错误应答 |
nand_port/run_unit_test.py |
dhara NAND 移植层单测:离线编译真实 Drivers/BSP/GD5F2GQ5UE/nand_ftl.c + 真实 Lib/dhara/{journal,map}.c,以 RAM 假芯片驱动,149 断言覆盖 is_free 整页扫描 / 六个 HAL 入口的越界守卫 / 故障注入 / dhara map"写入 → 重新 resume"场景 |
nand_port/nand_port_test.c |
测试单元本体(#include 生产源码 + RAM 假芯片;内联一份"只看页首 64 B"的旧算法对照,证明断言能咬人) |
nand_port/stub/ |
桩头文件(gd5f2gq5ue.h 芯片几何与 SPI 原语声明 / dbg_log.h 日志宏计数) |
详见
docs/测试说明/单元测试/看门狗单元测试说明.md、docs/测试说明/单元测试/系统时钟单元测试说明.md、docs/测试说明/单元测试/配置文件单元测试说明.md、docs/测试说明/单元测试/ADC输入层单元测试说明.md、docs/测试说明/单元测试/相量层单元测试说明.md、docs/测试说明/单元测试/卷锁单元测试说明.md、docs/测试说明/单元测试/时间同步单元测试说明.md; harness 用法见common/README.md。 已挂 pre-commit 钩子(各模块同名*-unit-test,共 22 个;逐个说明见docs/代码规范/pre-commit使用说明.md§2.2 与docs/门禁说明/host-unit-tests.md)。
nand_port —— dhara NAND 移植层为什么能在 PC 上测
一句话:移植层是纯逻辑 + 假芯片,能钉死真机极难复现的越界/误判路径。
nand_ftl.c 的 dhara HAL 六个入口只做地址算术与边界判定,芯片侧全部经 11 个 SPI
原语打交道——把它们换成一块 RAM 假芯片,整层即可离线跑。而它要防的两类缺陷恰恰是
板端拿不到观测面的:
is_free旧实现只看页首 64 B,"页首 0xFF、后段有数据"的已编程页被误判 空闲 → dhara 往已编程页再编程 = 静默数据丢失。真机要恰好撞上那种页形态才发作, 发作后只表现为"某次复位后丢数据"。假芯片把双编程做成可数事件(违规计数), 测试还内联一份旧算法做对照:同一页旧算法答"空闲"、新实现答"非空"。- 越界页/块号(含
DHARA_PAGE_NONE哨兵)旧会被地址位截断成真实页 → 静默读写/搬走无辜数据。真机上没有任何路径会主动喂进越界号。假芯片记录全部 访问次数,于是"越界 → 返回 -1 +DHARA_E_CORRUPT_MAP且零芯片访问、零标坏块" 可机械断言。
运行方式
# /serial-boot-test 一键闭环(推荐,需真机)
& '.venv\Scripts\python.exe' .dsh/skills/serial-boot-test/scripts/run_boot_test.py
# 测试套件构建的回归:要求套件跑到汇总行且断言数 > 0
& '.venv\Scripts\python.exe' .dsh/skills/serial-boot-test/scripts/run_boot_test.py `
--required "=== Storage Tests:" --forbidden "ERROR;HardFault;[ERR]" `
--require-suite-summary "Storage Tests"
# 看门狗判定状态机单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/watchdog/run_unit_test.py
# 系统时钟换算单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/sys_clock/run_unit_test.py
# 配置引擎单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/cfg_file/run_unit_test.py
# 相量层(L2)单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/phasor/run_unit_test.py
# ADC 输入层(L1)单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/adc_input/run_unit_test.py
# 卷锁单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/vol_lock/run_unit_test.py
# 时间同步单测(纯逻辑,无需真机)
& '.venv\Scripts\python.exe' test/host/time_sync/run_unit_test.py
# dhara NAND 移植层单测(纯逻辑 + RAM 假芯片,无需真机)
& '.venv\Scripts\python.exe' test/host/nand_port/run_unit_test.py
串口端口配置在
.serialtest/config.json(单一配置源,当前 COM6/115200)。
⚠️ 注意
- PYTHONPATH/路径敏感:脚本按仓库根相对路径读写,从仓库根执行
- 本目录被 pre-commit 门禁的 cppcheck / 代码规范排除(
test/豁免); 但各模块的run_unit_test.py自身作为独立钩子参与门禁(见上,共 22 个) - 台架探针族分工(2026-10-13 起):自愈/Trap 常备回归腿在本目录(
relisten_stress/ftp_abort_probe/n30_repro/e6_soak等;e02_probe已随 :8888 退役删除,2026-11-04);MDK-ARM/*.py只余被文档当作 可信判据引用过的三件(ftp_freeze_probe/tcp_reconnect_probe/bench_verdict)—— 2026-10-22 清掉了一批既无人引用、又因设备侧启用鉴权而再也登录不上的历史一次性探针 (MDK-ARM/ftp_retr_abort_probe.py与整个MDK-ARM/bench_diag/(4 个诊断脚本)),需要时从 git 历史取回;ftp_freeze_probe.py因被 Trap 记录当复现配方而保留,已改用设备账号登录。 - 全部主机侧单测(16 个模块目录,含本目录新增的
nand_port/)都需要本机装有 MSVC (VS2019/2022/2026 的 C++ 工具链);无则脚本报环境错误(退出码 2)
相关文档
docs/测试说明/流程与规范/自动化测试流程.md—/serial-boot-test细节与失败模式docs/测试说明/流程与规范/测试开发标准流程.md— 测试分层与门禁docs/测试说明/单元测试/看门狗单元测试说明.md— 主机侧单测(用例 / 平台层 / 扩展方法)docs/测试说明/单元测试/系统时钟单元测试说明.md— 系统时钟换算单测(用例 / 桩 / Zeller 缺陷记录)docs/测试说明/单元测试/配置文件单元测试说明.md— 配置引擎单测(内存 FS 桩 / 抓出的 P0)docs/测试说明/单元测试/ADC输入层单元测试说明.md— ADC 输入层单测(逐 Rank 钉死映射)docs/测试说明/单元测试/相量层单元测试说明.md— 相量层单测(傅氏系数 / 双区交换)docs/测试说明/单元测试/卷锁单元测试说明.md— 卷锁单测(fail-open 不变量)docs/测试说明/单元测试/时间同步单元测试说明.md— 时间同步任务载体单测 v2.0(SNTP 节拍 / 代次交接 / 未出网守门)docs/测试说明/板级测试/CH395F_Test_Guide.md、FTP_Test_Guide.md