refactor(docs): point entry-file references at their new homes
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.
This commit is contained in:
@@ -16,7 +16,7 @@
|
||||
| `net_test_task.c/h` | 网络层测试 |
|
||||
| `net_latency_test.c/h` | 链路时延探针(DWT CYCCNT 时基,MCU 专属) |
|
||||
|
||||
## ⚠️ 构建约束(`AGENTS.md` 详述)
|
||||
## ⚠️ 构建约束(详见本节与 `test_config.h`)
|
||||
|
||||
- **套件互斥**:`test_config.h` 的 `TEST_SUITE_CH395F/STORAGE/GD5F/RTC` 一次只能启用一个
|
||||
(违反则 `#error`);**全部注释 = 产品构建**
|
||||
@@ -41,5 +41,5 @@
|
||||
## 相关文档
|
||||
|
||||
- 测试指南:`docs/测试说明/板级测试/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md`
|
||||
- 套件配置:`AGENTS.md`「测试与验证」章
|
||||
- 套件配置:本节「构建约束」+ `board-test-suite` skill(套件互斥、破坏性开关代价、跑后恢复产品构建)
|
||||
- 容量恢复:`docs/测试说明/专项验证/存储维护与容量恢复.md`
|
||||
|
||||
@@ -46,7 +46,7 @@ extern "C" {
|
||||
#define LAT_VERDICT_FAIL 2
|
||||
|
||||
/*
|
||||
* 采样保存上限:静态数组容量(自研代码禁用 C 库堆,见 AGENTS.md)。
|
||||
* 采样保存上限:静态数组容量(自研代码禁用 C 库堆 → docs/门禁说明/coding-standard.md §2)。
|
||||
* n 可超过该值(min/max/spikes 仍对全量累计;med/p95 按已保存样本计算)。
|
||||
*/
|
||||
#define LAT_MAX_SAMPLES 128
|
||||
|
||||
@@ -261,7 +261,7 @@ static void storage_test_badblock(void)
|
||||
* 非法名字 f_open 必返 FR_INVALID_NAME(纯 RAM 名字判定、不碰盘);合法但
|
||||
* 不存在的名字返 FR_NO_FILE。本测试断言两类严格可区分——一旦哪天有人把
|
||||
* FR_INVALID_NAME 误归入"卷损坏"自愈集合,这条测试就是最后的机械防线。
|
||||
* (详见 docs/问题记录/GD5F2GQ5UE_Trap_Records.md TRAP-GD5F-05 / AGENTS.md)
|
||||
* (详见 docs/问题记录/GD5F2GQ5UE_Trap_Records.md TRAP-GD5F-05)
|
||||
*/
|
||||
static void storage_test_name_validation(void)
|
||||
{
|
||||
|
||||
+1
-1
@@ -79,7 +79,7 @@
|
||||
> `docs/测试说明/单元测试/时间同步单元测试说明.md`;
|
||||
> harness 用法见 [`common/README.md`](common/README.md)。
|
||||
> 已挂 pre-commit 钩子(各模块同名 `*-unit-test`,共 **22** 个;逐个说明见
|
||||
> `docs/代码规范/pre-commit使用说明.md` §2 与 AGENTS.md 门禁条)。
|
||||
> `docs/代码规范/pre-commit使用说明.md` §2.2 与 `docs/门禁说明/host-unit-tests.md`)。
|
||||
|
||||
### nand_port —— dhara NAND 移植层为什么能在 PC 上测
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
*
|
||||
* 必须复刻的两条芯片怪癖(不复刻就等于把被测代码的坑假件掉):
|
||||
* 1. ch395f_get_sock_int_status() 是**整体读即清**、芯片没有按位清除手段。本假件
|
||||
* 返回该 socket 的挂起位图并同步清零。AGENTS 模块约定里 B3 的实证坑("顺手
|
||||
* 返回该 socket 的挂起位图并同步清零。模块约定 B3 的实证坑("顺手
|
||||
* 全量清一遍"把别的在用 Socket 的门焊死)靠这条才照得出来。
|
||||
* 2. *_cached 系列返回的是**缓存值**而不是现场值:open 状态与 TCP 状态分开、且
|
||||
* "监听还活着"的判据是 (open != CLOSED && tcp_state == LISTEN)。测试据此能构造
|
||||
@@ -80,7 +80,7 @@
|
||||
*
|
||||
* 必须复刻的第三条芯片怪癖(前两套测不到、net_socket.c 却是主路):
|
||||
* 3. GET_GLOB_INT_STATUS_ALL(0x19,2 字节)**整体读即清**,且它是全局寄存器
|
||||
* (含全部 Socket 事件位)。AGENTS 模块约定 B3:唯一读者只能是 net_poll。
|
||||
* (含全部 Socket 事件位)。模块约定 B3:唯一读者只能是 net_poll。
|
||||
* 假件按调用序号返回预置值,并单独计数,让"别处偷偷读全局"成为可断言的事。
|
||||
* 4. sock_reset 复位机(E4 定案四步:读空 RX → CLOSE → 排空事件(quiescent) →
|
||||
* 等 byte0=00H,含 LISTEN 态二段 CLOSE 补发)。这里做**契约等价**实现:
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
|
||||
退出码:0=PASS / 1=测试失败 / 2=环境错误。
|
||||
|
||||
设计依据:docs/子系统设计/*104* 设计文档、AGENTS.md 模块约定(单连接 socket 断开语义、
|
||||
设计依据:docs/子系统设计/*104* 设计文档、docs/网络/网络自愈架构设计.md §4.10(单连接 socket 断开语义、
|
||||
错误码经任务通知值回传)、docs/测试说明/单元测试/主机单测覆盖率口径.md §9
|
||||
创建日期:2026-10-23
|
||||
"""
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
/*
|
||||
* 模块名称:主机侧单测桩 - dbg_log.h(net_events 模块专用)
|
||||
* 模块功能:DBG_* 计数。注意 net_events.c 在 include 本头之前把 DBG_LINE_BUF_MAX
|
||||
* 抬到 128U(AGENTS:深调用链模块必须抬,否则最长日志行会被截断),
|
||||
* 抬到 128U(深调用链模块必须抬,否则最长日志行会被截断 →
|
||||
* docs/子系统设计/控制台单写者日志设计.md §7.1),
|
||||
* 本桩不关心缓冲大小,只数条数。
|
||||
* ⚠ 仅供主机侧单测使用,不参与 MCU 构建。
|
||||
* 创建日期:2026-10-23
|
||||
|
||||
@@ -25,7 +25,7 @@
|
||||
* 关不掉时,代码**不能放弃请求**,也不能每 30ms 刷一条日志。真机上验证一次要等
|
||||
* 到真断线,主机侧把 tick 做成显式量后,1399ms 与 1400ms 的差别就是一行断言。
|
||||
* 3. GET_SOCK_INT_STATUS 是**整体读即清**,"顺手全量清一遍"会把别的在用 socket 的
|
||||
* 门焊死(AGENTS 模块约定 B3 实证坑)。假芯片必须复刻读即清,本文件用调用顺序
|
||||
* 门焊死(模块约定 B3 实证坑)。假芯片必须复刻读即清,本文件用调用顺序
|
||||
* 日志钉住"只读自己这一路"的时序。
|
||||
*
|
||||
* 覆盖点:
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
* 可控"芯片此刻还有多少字节可读";dbg_log 计数;net_set_errno 记录。
|
||||
*
|
||||
* 为什么要主机侧单测(而不是只靠台架):
|
||||
* 1. AGENTS 模块约定写着:net_* 公开 API 的错误码经**任务通知值**回传,因为 net_msg_t
|
||||
* 1. 模块约定:net_* 公开 API 的错误码经**任务通知值**回传,因为 net_msg_t
|
||||
* 是**按值拷入队列**的,netTask 改的是自己那份副本,调用方永远看不到;也**勿给
|
||||
* net_msg_t 加回传字段**(加了只会让调用方读到栈垃圾)。这条契约在真机上表现为
|
||||
* "偶发拿到 0 或正数却不知道为什么",日志无痕;在 PC 上必须把 xTaskNotify 做成
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
|
||||
退出码:0=PASS / 1=测试失败 / 2=环境错误。
|
||||
|
||||
设计依据:AGENTS.md 模块约定(错误码经任务通知值回传)、
|
||||
设计依据:模块约定(错误码经任务通知值回传,见 docs/网络/网络自愈架构设计.md §4.10)、
|
||||
docs/网络/Net层阻塞模型架构设计.md、docs/测试说明/单元测试/主机单测覆盖率口径.md §9
|
||||
创建日期:2026-10-23
|
||||
"""
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
* 模块名称:主机侧单测桩 - net_socket.h(NET 域共享形态,见 net_listener 同名文件)
|
||||
* 模块功能:net_pending.c 需要 net_set_errno() 与 NET_ERR_RETURN_1()(写法照抄真实
|
||||
* net_socket.h:528/532);socket 状态与错误码常量取**真实** net_types.h。
|
||||
* 本模块**不用** net_get_sock——tick 收的是 net_sock_t 表数组(AGENTS 模块
|
||||
* 本模块**不用** net_get_sock——tick 收的是 net_sock_t 表数组(模块
|
||||
* 约定:net_get_sock 对未用槽位返回 NULL,而 tick 必须读 in_use==0 兜底)。
|
||||
* ⚠ 仅供主机侧单测使用,不参与 MCU 构建。
|
||||
* 创建日期:2026-10-23
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
* 的假件:xTaskNotify 把 (目标句柄, 通知值) 记进日志,
|
||||
* xTaskGetCurrentTaskHandle 返回一个固定的"属主任务"句柄。
|
||||
* ⚠ 仅供主机侧单测使用,不参与 MCU 构建。
|
||||
* 为什么这两个假件是重点:AGENTS 模块约定写着"net_msg_t 是按值拷入队列的,
|
||||
* 为什么这两个假件是重点:模块约定写着"net_msg_t 是按值拷入队列的,
|
||||
* netTask 改的是自己那份副本,调用方永远看不到 → 错误码必须搭通知值回来",
|
||||
* 还写着"勿给 net_msg_t 加回传字段"。这条契约只有把 xTaskNotify 做成可观测的,
|
||||
* 才能在主机侧被验证(否则"调用方拿到错误码"这件事在 PC 上根本无法发生)。
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
* recv 快路径与 EOF vs WOULDBLOCK、connect 命令被拒的回滚、accept 的
|
||||
* closed-with-readable 排空接受、close 的先结算再关芯片。
|
||||
*
|
||||
* ⚠ 断言只钉**真实契约**(AGENTS 模块约定 + docs/网络/网络自愈架构设计.md §4.10 +
|
||||
* ⚠ 断言只钉**真实契约**(docs/网络/网络自愈架构设计.md §4.10 +
|
||||
* 源码注释里的定案编号),不钉假件规则:凡"因为假件这么做所以断言这么做"的一律不写。
|
||||
*
|
||||
* 入口:int main(void),返回 0=PASS / 1=FAIL。跑法见同目录 run_unit_test.py。
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
* 分片 3:跨上下文消息面(net_process_messages 全分派 + 结果经任务通知值回传)
|
||||
* 前置:net_socket_test.c 已纳入生产源与假内核/假芯片/兄弟模块桩(同一 TU)。
|
||||
*
|
||||
* 这一片是整套里最值钱的部分,钉的是 AGENTS 模块约定的两条硬契约:
|
||||
* 这一片是整套里最值钱的部分,钉的是模块约定的两条硬契约:
|
||||
* A.「所有 net_* socket 操作经 netMsgQueue 在 netTask 串行执行」
|
||||
* B.「net_* 公开 API 的错误码经任务通知值回传:net_msg_t 是按值拷入队列的,
|
||||
* netTask 改的是自己那份副本,调用方永远看不到 → 错误码搭 xTaskNotify 通知值回来;
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
/*
|
||||
* 分片 4:net_poll 中断分派、监听/可读闸门、close 与 drop_conn 的拆除序列
|
||||
*
|
||||
* 这一片钉的是 AGENTS 模块约定里**没有文档就无法发现**的那条芯片约束:
|
||||
* 这一片钉的是模块约定里**没有文档就无法发现**的那条芯片约束:
|
||||
* 所有 CH395F 中断在 net_poll() 内经 GET_GLOB_INT_STATUS 集中读取并清除,不得在
|
||||
* ISR 或其他地方单独处理。全局寄存器整体读即清、芯片无按位清除手段,而 net_poll
|
||||
* 只在全局位为 1 时才读该 Socket 的 SINT → 顺手全量清一遍等于把别的在用 Socket 的
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
* - 本分片只测**队列化之后**新增或变化的决策:出参经 per-fd 槽回传、挂起 recv、
|
||||
* 截断排空、模式切换、以及"任何一条出口都必须通知调用方"。
|
||||
*
|
||||
* ⚠ 断言只钉真实契约(AGENTS 模块约定 + docs/芯片手册/CH395F.md §9.2.4 +
|
||||
* ⚠ 断言只钉真实契约(docs/网络/网络自愈架构设计.md §4.10 + docs/芯片手册/CH395F.md §9.2.4 +
|
||||
* docs/问题记录/CH395F_Trap_Records.md),不钉假件规则。
|
||||
*
|
||||
* 创建日期:2026-11-03
|
||||
@@ -506,7 +506,7 @@ static void tc_udp8_pending_cancel(void)
|
||||
reset_all();
|
||||
}
|
||||
|
||||
/* ================= UDP-9 出参互斥与泄漏(AGENTS 禁止的回传字段,本改造的替代面) ================= */
|
||||
/* ================= UDP-9 出参互斥与泄漏(禁止的回传字段,本改造的替代面) ================= */
|
||||
|
||||
static void tc_udp9_outparam_slot(void)
|
||||
{
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
为什么要主机侧单测(而不是只用台架):
|
||||
net_socket.c 是本产品**唯一的 SPI 串行化点**:所有 net_* 公开 API 把请求按值拷进
|
||||
消息队列,由 netTask 串行执行,结果只能经 xTaskNotify 的 32 位通知值回来
|
||||
(net_msg_t 是按值入队的,netTask 改自己那份副本,调用方永远看不到——AGENTS
|
||||
(net_msg_t 是按值入队的,netTask 改自己那份副本,调用方永远看不到——模块
|
||||
模块约定明写"勿给 net_msg_t 加回传字段")。这条链的正确性取决于两个任务的
|
||||
交错时序,真机上"通知丢了"表现为永久挂死并被看门狗复位,日志里只剩一条
|
||||
[ERR];而错误码本身还按任务隔离,跨任务覆写只会让排障读到别人的码。
|
||||
|
||||
@@ -4,7 +4,8 @@
|
||||
* 同名文件)。net_socket.c 有 11 条 DBG_ERROR + 6 条 DBG_INFO,其中
|
||||
* 「短写必留痕」「版本门控拒置 bit3 必 [ERR]」「open 失败必 [ERR]」
|
||||
* 「close 复位没成也放行仍要留痕」这四条本身就是可断言的契约。
|
||||
* 本模块在 include 本头之前把 DBG_LINE_BUF_MAX 设为 128U(AGENTS 深调用链纪律),
|
||||
* 本模块在 include 本头之前把 DBG_LINE_BUF_MAX 设为 128U(深调用链纪律 →
|
||||
* docs/子系统设计/控制台单写者日志设计.md §7.1),
|
||||
* 桩不关心缓冲大小,只数条数。
|
||||
* ⚠ 仅供主机侧单测使用,不参与 MCU 构建。
|
||||
* 创建日期:2026-10-24
|
||||
|
||||
Reference in New Issue
Block a user