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:
@@ -823,7 +823,7 @@ void net_process_messages(void) {
|
||||
}
|
||||
/* ===== UDP 数据面(2026-11-03 队列化改造)=====
|
||||
* 芯片事务全部在 netTask 里执行;源地址出参不搭 net_msg_t(按值拷贝,
|
||||
* AGENTS 禁止加"回传用"字段),而是经 net_udp.c 的 per-fd 槽写回调用方
|
||||
* 禁止加"回传用"字段),而是经 net_udp.c 的 per-fd 槽写回调用方
|
||||
* 内存,通知值只带结果码。执行体定义见 net_udp.c。 */
|
||||
case NET_MSG_UDP_BIND: {
|
||||
/* 打开芯片侧 Socket(恒服务器模式);端口 0 = 由执行体取动态游标 */
|
||||
@@ -1244,7 +1244,7 @@ int net_listen_locked(int sockfd) {
|
||||
* Socket 的 SINT(见 :469 门控)→ 全量清等于把别的在用 Socket 的门一并
|
||||
* 焊死,其 CONNECT/DISCONNECT 等边沿事件永久丢失(RECV 属条件位,下轮
|
||||
* 可补回,见 TRAP-NET-08)。
|
||||
* 全局寄存器交 net_poll 集中读清(AGENTS 模块约定:所有 CH395F 中断经
|
||||
* 全局寄存器交 net_poll 集中读清(模块约定:所有 CH395F 中断经
|
||||
* net_poll 集中读取并清除);本 Socket 残留的全局位被 net_poll 读到时
|
||||
* SINT 已为 0,自然收尾。TRAP-NET-12/-18 指定的两级预清落在
|
||||
* net_connect_locked / net_close_locked / relisten 隔离段,均为单 Socket,
|
||||
@@ -2561,7 +2561,7 @@ int net_close(int sockfd) {
|
||||
* -1 - 失败(BADF/INVAL/入队失败) int
|
||||
* 限定条件:1. 必须在【非 netTask】上下文调用(同其它 net_* API,netTask 内会自等死锁)
|
||||
* 2. 场景=应用放弃会话(对时 30s 预算耗尽、协议超时);EOF 路径**不要**调
|
||||
* (net 层 auto_relisten 已接管,见 AGENTS 单连接断开语义)
|
||||
* (net 层 auto_relisten 已接管 → docs/网络/网络自愈架构设计.md §4.10)
|
||||
* 函数说明:1. 单连接模型下挂起但 TCP 仍活的客户端会永久占住监听(keepalive
|
||||
* 被 PC 内核自动 ACK 判不死,《网络自愈架构设计》§5.2 E13);应用不得
|
||||
* net_close 监听 fd → 本 API 拆连接不拆监听
|
||||
@@ -2894,7 +2894,7 @@ int net_udp_get_mode(int sockfd) {
|
||||
* 返回值:字节数(> 0);<= 0 为**原始码**(NET_ERR_* 或 NET_ERR),errno 由公开入口写 int
|
||||
* 限定条件:参数已由本函数校验
|
||||
* 函数说明:1. 源地址回传不占 net_msg_t 字段——先在本任务上下文把出参登记进
|
||||
* net_udp 的 per-fd 槽(AGENTS:net_msg_t 按值拷贝,禁止加回传字段),
|
||||
* net_udp 的 per-fd 槽(net_msg_t 按值拷贝,禁止加回传字段),
|
||||
* netTask 执行时按槽写回调用方内存,通知值只带结果码。
|
||||
* 同一 fd 上槽位互斥:并发收包在数据报语义下无法区分归属,直接 BUSY。
|
||||
* 2. 本函数不碰 errno:超时与错误都以原始码返回,由 net_recvfrom /
|
||||
|
||||
@@ -48,7 +48,7 @@ typedef enum {
|
||||
* NET_MSG_UDP_RECVFROM - buf/len=载荷 + timeout_ms=等待预算 + flags
|
||||
* ⚠ 源地址出参(src_addr / addrlen 两个指针)**不走本结构**:结构按值拷入
|
||||
* 队列,指针若在 int 字段里过桥,64 位主机单测构建会被截断,且违反
|
||||
* AGENTS「勿给 net_msg_t 加回传用字段」。改走 net_udp.c 的 per-fd 挂起槽
|
||||
* 禁止给 net_msg_t 加回传用字段。改走 net_udp.c 的 per-fd 挂起槽
|
||||
* (调用方在入队前登记自己的指针,netTask 完成后写进调用方内存 + 通知值回码),
|
||||
* 与 TCP 挂起 recv 把数据直接写进调用方 buf 是同一个模型。
|
||||
* 详见 docs/网络/BSD_Socket_API_使用指南.md §6 */
|
||||
@@ -366,7 +366,7 @@ int net_recv_to(int sockfd, void *buf, int len, uint32_t timeout_ms);
|
||||
* netTask 内直接执行不入队——自投递给自身 = 死锁)
|
||||
* 函数说明:1. 目的地址是**入参**,按值拷进 net_msg_t.addr 随消息进 netTask,
|
||||
* 与 net_connect 传地址同一条通道;结果(已发字节数/错误码)
|
||||
* 搭任务通知值回来(AGENTS「勿给 net_msg_t 加回传字段」)。
|
||||
* 搭任务通知值回来(勿给 net_msg_t 加回传字段)。
|
||||
* 2. 带显式目的地址 = 芯片 DesIP/DesPort 切到该对端 → 本 Socket 记账进入
|
||||
* **UDP 客户端形态**(p_sock->udp_mode = NET_UDP_MODE_CLIENT):此后
|
||||
* `dest_addr = NULL` 的发送就发往它。**收包帧格式不受影响**——信息头是
|
||||
@@ -506,7 +506,8 @@ int net_close(int sockfd);
|
||||
* 见函数说明 2;含幂等:无活动会话),-1 失败
|
||||
* 限定条件:非 netTask 上下文(经消息队列委托,同其它 net_* API)
|
||||
* 函数说明:1. 适用场景=应用层放弃会话(对时 30s 预算耗尽、协议超时等):
|
||||
* 单连接模型禁止对监听 fd net_close(连监听一起毁,AGENTS 约定),
|
||||
* 单连接模型禁止对监听 fd net_close(连监听一起毁 →
|
||||
* docs/网络/网络自愈架构设计.md §4.10),
|
||||
* 而挂起但 TCP 仍活的客户端会永久占住单连接监听(PC 内核自动
|
||||
* ACK keepalive,芯片僵尸判不死——《网络自愈架构设计》§5.2 E13 定案缺口)
|
||||
* 2. 实现(2026-10-25 探针窗口心跳缺口修复起):auto_relisten fd = 登记 QUARANTINE 隔离
|
||||
|
||||
@@ -204,7 +204,7 @@ typedef struct {
|
||||
* 头里取源地址;此处 CLIENT 的对端簿记(复用 remote_ip_arr[4] + remote_port,
|
||||
* 与 TCP 同一对字段)只用于发送去向与不足 8 字节残包的源地址兜底。
|
||||
* 位置选择:紧接 in_use 之后,落在 type/in_use 之后原有的 2 字节填充里
|
||||
* (本结构 8 个实例,净增 RAM = 0,见 AGENTS RAM 红线)。 */
|
||||
* (本结构 8 个实例,净增 RAM = 0;预算核对见 docs/内存管理/RAM预算台账.md)。 */
|
||||
uint8_t udp_mode;
|
||||
uint16_t local_port; /* 本地端口(主机序) */
|
||||
uint16_t remote_port; /* 远端端口(主机序) */
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
* net_recvfrom_to / net_udp_set_peer / net_udp_get_mode)住在
|
||||
* net_socket.h,那边只负责参数校验、装消息入队、等通知值回结果。
|
||||
* 为什么单独成模块:源地址(src_addr/addrlen)是**出参指针**,不能塞进按值拷入
|
||||
* 队列的 net_msg_t(AGENTS 明文「勿给 net_msg_t 加回传用字段」;
|
||||
* 队列的 net_msg_t(明文禁止「给 net_msg_t 加回传用字段」;
|
||||
* 指针过 int 桥在 64 位主机单测构建还会被截断)。所以出参走本模块的
|
||||
* per-fd 槽:调用方入队前登记自己的指针,netTask 结算时把源地址写进
|
||||
* 调用方内存、错误码/字节数搭任务通知值回去——与 TCP 挂起 recv 把数据
|
||||
|
||||
Reference in New Issue
Block a user