Commit Graph

5 Commits

Author SHA1 Message Date
wandering1 e4981aa2f6 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.
2026-11-16 19:38:27 +08:00
super_agent_bot 0d469a835a test(net/udp): 主机单测按真机改写 UDP-4/17/22/24,补残包组 UDP-26(#73)
剥头判据改了,测试就得跟着改——但这一条提交里真正值钱的是"为什么会错到":
UDP-4 当时写的是"客户端形态整包都是载荷、源地址取对端记账",UDP-24 的 240 轮
定种子随机长跑也照同一个模型脚本报假件。**随机长跑全绿恰恰不能证明模型对**:
它扫的是我自己写的那套模型,模型错了它一样绿。只有真机那次 48→56 的读数把这件事
钉死。

- UDP-4 改写为"客户端形态同样剥头",源地址来自信息头(脚本里特意让头里的源
  `119.28.220.215` ≠ 记账对端 `119.28.220.214`,这样"取错地方"就必然失败),
  并补 UDP-4h 断言 `addrlen`/family 与服务器形态一字不差——一条读路径就该一个契约。
- UDP-17h/m、UDP-22c、UDP-24 的客户端轮同样按定案重写(先 `reset_recv_len` 再
  宣布长度,假件的收包脚本必须可重排,这是长跑教过的第二条)。
- 改完判据后覆盖率门禁照出 `net_udp_src_from_peer()` 一行没人走了。**没有把基线
  调低**,而是补 UDP-26(9 条)钉住"`<8` 字节残包"那一侧:整包原样交付、一个字
  节都不许剥、源地址退到对端记账;没记账时交出全零这个"我不知道",而不是包里的
  字节——它是记账那本账如今唯一的读者。

全套 **677/677 绿**(改造前 470);`net_udp.c` 回到 237/239 行、14/14 函数,
`net_socket.c` 966/969 行、59/59 函数,全仓 8372/9290(90.1 %)、47/47 套,
`scripts/test_coverage_baseline.json` 与改动前一字未变(即无回退)。
2026-11-04 09:15:52 +08:00
super_agent_bot 1b5e5d424c test(net/udp): 主机单测补 UDP-25 两条 socket 并存的隔离(#73)
CI / 静态门禁 (pre-commit) (push) Failing after 45s
CI / 主机侧单测 (MSVC) (push) Failing after 50s
CI / 静态门禁 (pre-commit) (pull_request) Failing after 45s
CI / 主机侧单测 (MSVC) (pull_request) Failing after 45s
前 24 组全都只用一条 UDP socket,漏掉的正是队列化真正要保的那半句承诺:
**等待是一条 socket 自己的事**——串行的是命令,不是等待者。

UDP-25 用 13 条断言钉住两条并存 socket 的四件事:fdB 来包不得结算也不得通知
fdA 的 parked 收包(连它的调用缓冲都不许被写一个字节);fdA 自己的包到达时按
自己那一包的表头结算并恰好通知一次;fdB parked 时 fdA 自己 recvfrom 照常拿到
数据;关停在等的 fdB 必须当场结算、槽位与出参槽都不残留。

写这组时踩到假件的一个真坑,值得记下来:假件的 get_recv_len 是"每次读消耗一格、
最后一格永远重复"的脚本队列,本组前面给同一 fd 留过旧长度,不清就会拿**旧长度配
新内容**(现象是 UDP-25j 读出 12 字节而不是 7 字节),所以每条用例前用
ch395f_fake_reset_recv_len(fd) 归零再宣布——这是测法问题,不是被测代码的问题。

全套 667/667 绿(改造前 470,本次 +13);net_udp.c 仍 237/239 行 14/14 函数,
net_socket.c 966/969 行 59/59 函数,模块级覆盖率无回退。
2026-11-04 01:28:01 +08:00
super_agent_bot 9608b7a8ea test(net/udp): 加 240 轮定种子随机长跑 UDP-24,配套假件补可重排收包脚本(#73)
CI / 静态门禁 (pre-commit) (push) Failing after 45s
CI / 主机侧单测 (MSVC) (push) Failing after 44s
CI / 静态门禁 (pre-commit) (pull_request) Failing after 46s
CI / 主机侧单测 (MSVC) (pull_request) Failing after 44s
真机台架被断电和断线卡住,这一段只推进纯软件侧:把 UDP 数据面的随机序列
扫起来,并修掉随机长跑逼出的两条"测法自误"。

- ns_s7_udp.c 新增 UDP-24:固定种子 20261104 的 240 轮随机交互,每轮随机
  载荷长度 1~112(112 = 假件收包流 128 B 上限减 8 字节信息头)、源端口、
  源 IP、SERVER/CLIENT 形态、显式对端 sendto 与按记账对端 sendto,每 17 轮
  close + 重 bind 一次。断言收在六族不变量上(长度等于芯片宣布值、既不吞
  信息头也不丢真字节、源地址按形态分别取自表头/对端记账、udp_mode 与命令
  一致、close/重 bind 后出参槽与挂起槽不残留、每次 sendto 交给芯片恰好 len
  字节),并要求 ≥90% 轮次端到端干净(实测 240/240)。
- 长跑逼出的两处都是测法问题,不是被测码 bug,但只有长跑才逼得出:
  1) 连续 sendto 不注入 SENBUF_FREE 时,第二次发送会合法转挂起,而本套的
     挂起 send 替身从不完成,于是 FATAL 掐死整套件(连汇总行都没有)。改法
     照 440i/440j:set_sint_sticky(SENBUF_FREE) + push_glob + g_ns_int_pin_set=0,
     注释点名 TRAP-NET-04,背靠背发送的真机面留给 TC-NET-1609。
  2) 假件 ch395f_get_recv_len 是"按调用序号取、耗尽后重复最后一个"的脚本且
     容量有限,240 轮只追加不清空,序号撞满容量后每轮读到同一个陈旧长度
     (症状:len 在随机而 n 恒为 28,前 24 轮全绿,最容易误判成产品 bug)。
     补加法助手 ch395f_fake_reset_recv_len(sock),只归零该 sock 的脚本长度与
     序号,既有单轮用例不调用它、行为一字未变。
- 覆盖率口径第 4 轮同步:用例面记到 24 组、全套 654/654(改造前 470),
  新增一条"随机长跑逼出两条测法自误"的教训(长跑对假件的第一要求是
  状态可重排,不是能追加)。

验证:net_socket 套件 654/654 绿;全量覆盖率 47/47 退出码 0,net_udp.c
237/239 行 99.2%、14/14 函数,net_socket.c 966/969 行 99.7%、59/59 函数,
总行 8372/9290(90.1%),无 REGRESS;cppcheck(--hook-stage manual)退出码 0;
check_doc_links --all 通过(213 个文档,无法判定 0);pre-commit 对本批文件
全绿。基线 JSON 无变化(本轮只加测试,未动生产码),故不随本提交改动。
2026-11-04 00:46:08 +08:00
super_agent_bot fff961d803 feat(net/udp): UDP 数据面并入 netMsgQueue 串行执行(#73)
CI / 静态门禁 (pre-commit) (push) Failing after 49s
CI / 主机侧单测 (MSVC) (push) Failing after 30s
CI / 静态门禁 (pre-commit) (pull_request) Failing after 45s
CI / 主机侧单测 (MSVC) (pull_request) Failing after 44s
前置来自 #57 SNTP 调研:旧 net_sendto / net_recvfrom 由调用方直调
SPI 且无限自旋收包,既违约「netTask 是芯片唯一访问者」,又把 IWDG
预算吃在自旋里。

改造面
- 新增 Drivers/BSP/NET/net_udp.c/.h(真机专属,模拟器不编译):
  bind/set_peer/sendto/recvfrom 四条执行体 + 挂起收包表 + tick;
  net_msg_type_t 加四型,公开 API 一律「入队 → 睡在通知上」。
- 源地址出参不搭 net_msg_t(按值拷贝,AGENTS 禁加回传字段):改住
  net_udp.c 的 per-fd 槽,netTask 就地写回调用方内存,通知值只带
  结果码;每条出口都清槽,泄漏 = 该 fd 永久 BUSY。
- 发送复用 net_send_locked,不写第二份分块逻辑;「会话是否已死」
  收成一条判据 net_send_state_down()(TCP 看 ESTABLISHED、UDP 看
  UDP_OPEN),原先 4 处各写一遍。
- 顺带修掉真缺陷(新条 TRAP-NET-22):旧 sendto 把 DesIP 写成具体
  IP,芯片静默切 UDP Client,而旧 recvfrom 无条件剥 8 字节 → SNTP
  这类 48 B 应答丢载荷前 8 字节并交出垃圾源地址。加 udp_mode(塞进
  原有 padding,sizeof 不变)、bind 恒 SERVER、显式对端 sendto 切
  CLIENT、set_peer(fd, NULL) 轻量回 SERVER,仅 SERVER 且 avail >= 8
  才剥头。
- 截断定案:一次调用交付一个数据报,buf 装不下的尾巴用 64 B 栈上
  scratch 排空(不用 clear_recv_buf——它连后面已到达的包一起丢)。
- 取消点接齐:net_init 重建 cancel_all、net_socket 分配 fd clear、
  net_close settle_close + clear、重 bind 前先结算等包者,
  net_process_messages 第 5 个 tick 位挂 net_udp_tick。
- 收紧两处契约(原实现无生产调用者):UDP 未 bind 一律 -5;
  net_recv / _nb / _to 拒 DGRAM(绕过剥头就是静默吃 8 字节);
  NET_ERR_NOT_IN_NETTASK(-12) 退役为历史常量并写明原因。

验证
- 主机单测 test/host/net_socket 全套 616/616 绿(改造前 470):新
  分片 ns_s7_udp.c 20 组,改写 440 / 555 / 560 组;覆盖率
  net_udp.c 234/236(99.2%)、net_socket.c 956/969(98.7%),
  scripts/test_coverage_baseline.json 随本提交登记新文件。
- 测试抓到 4 个被测码真 bug:自等守卫误用调用侧谓词、芯片长度被读
  两次、槽指针取在 fd 合法性检查之前、重 bind 静默作废等待者。
- Keil ARMCC 0 Error(s) 0 Warning(s);net_udp.o Code 1,358 / ZI 224
  (8 fd × 28 B,其余模块零增长),全仓 RW_IRAM1 72.2%;内存台账
  受管区按门禁提示用 --write / --update 机器回填,未手改数字。
- pre-commit 全量钩子(含 doc-links、coding-standard、mem-budget、
  generated-fresh、bsp-err、registration、nested-comment)全绿。

限度
- 本轮无板子:真机回归 5 条(两端互通、set_peer(NULL) 能否恢复收
  广播、截断排空后下一包完整性、挂起 recv 期间 IWDG 余量、bind 写
  DesIP 与 open 先后的真芯片效果)已写进覆盖率口径「台架必验」。
- scripts/stack_report.py 退出码 1 是 10-26 起挂在账上的 iec104Task
  栈债(margin 1,016 < 1,024,见 docs/代码规范/pre-commit使用说明.md:
  122);本轮只让 net_bind 的 UDP 分支多一层静态帧(1,544 → 1,600),
  netTask margin 1,888 与 timeSyncTask 1,152 不受影响。抬栈要过
  mem-budget 台账,不在本分支自行处理。
- 登记簿销项按仓库约定留给主工作树,本分支不动 docs/任务规划/**。
2026-11-03 18:44:01 +08:00