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 把数据
|
||||
|
||||
@@ -38,7 +38,7 @@
|
||||
| NET | 就绪屏障位必须 `osFlagsNoClear`;`s_net_errno` 已按任务隔离(勿改回全局) |
|
||||
| 通用 | 自研代码**禁用 C 库堆分配**(MicroLIB 堆仅 512 B),动态内存只用 `pvPortMalloc/vPortFree` |
|
||||
|
||||
> 完整平台约束见根 `AGENTS.md`「平台约束」章,以及各模块的 Trap Records。
|
||||
> 完整平台约束的落点:隔离与错误码语义 → `.dsh/roles/network-specialist.md`(网络)/ `.dsh/roles/storage-specialist.md`(存储);中断与吞吐细节 → `docs/网络/网络自愈架构设计.md`、`docs/架构设计/STM32F4-Base存储架构说明.md`;C 库堆禁令 → `docs/门禁说明/coding-standard.md`。另见各模块的 Trap Records。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
- **`tpafe5160_init()` 做首帧有效性自检**:完整跑一帧转换+读取,若整帧读下来 FRSTDATA **没有发生任何跳变**(芯片没在驱动并行总线;板上上拉会把它钉死为高)→ 返回 `BSP_ERR_NO_DEVICE`(旧 `TPAFE5160_FRSTDATA_ERR(-3)`,2026-10-23 收编)并打 `[ERR] Init FRSTDATA no-toggle`。判据刻意不锁死"哪个 RD 边沿拉高/拉低"(手册只给"RD 下降沿 → FRSTDATA 高/低"两个跳变,本板未实测边沿次序),只要求"一帧内必须跳变" → 既抓死芯片,也不会因极性假设错误误杀好芯片
|
||||
- 采样数据的消费者 `App/task/adc_task.c` **已实现**(ADC 采集链路,2026-10-10:`tpafe5160_snapshot()` 原子取数 + 帧统计;`adcTask` 在 `Src/freertos.c` 的 `USER CODE` 区创建)。**v2.2(2026-10-10)**:采样节拍改由定时器更新中断硬件触发,本任务退化为纯消费者;**v2.8(2026-10-10)**:节拍源改 TIM3(同时经 TRGO 触发 ADC1 + DMA),STM32 侧改为消费 DMA 乒乓缓冲,单拍耗时 122 µs → **8 µs**
|
||||
- CONVST→BUSY→RD 三段时序对**建立/保持时间敏感**,改动需对照芯片手册
|
||||
- ⚠️ 本项目 ADC 相关功能**新增任务/缓冲前须核算 RAM**(见 `docs/内存管理/`);接消费者前的强制门禁见根 `AGENTS.md`「接 ADC / RS-485 消费者前的强制门禁」
|
||||
- ⚠️ 本项目 ADC 相关功能**新增任务/缓冲前须核算 RAM**(见 `docs/内存管理/`);接消费者前的强制门禁 = 取数契约(只用 `tpafe5160_snapshot()`/`adc_input_poll()`,见 `docs/算法/继电保护功能复现规划.md`)+ 建任务前后各跑一次 `scripts/stack_report.py`;RS-485 侧的重启门禁 → `docs/产品需求/产品需求设计文档.md` §5.10
|
||||
- ⚠️ **通道语义不是通道号**:`buf[i]` 对应哪个电气量必须查 `docs/硬件平台/ADC通道映射说明.md`(`buf[2]=IA`、`buf[5]=UN`、`buf[6]=UA`);V0.1 上 8 路电气量分属两片转换器属硬件缺陷(`docs/任务规划/硬件改版登记.md` §1)→ **禁止**跨转换器做相位/功率/功率因数类运算
|
||||
|
||||
## 已知问题
|
||||
|
||||
@@ -404,7 +404,7 @@ typedef struct {
|
||||
* (状态与队列都不动:调用方的编程错误不该落成屏上的"越界") int
|
||||
* 限定条件:uiTask 上下文(页面按键钩子);与 drain 同上下文 → 无锁
|
||||
* 函数说明:本函数**不**校验值域(越界与否是执行侧事实,在 drain 里整批预检),
|
||||
* 也不碰 prot_set、不碰文件系统(落盘归 defaultTask,AGENTS 模块约定)
|
||||
* 也不碰 prot_set、不碰文件系统(落盘归 defaultTask 的模块约定)
|
||||
*/
|
||||
int ui_data_param_request(const ui_data_param_req_t *a_req);
|
||||
|
||||
|
||||
@@ -7,8 +7,8 @@
|
||||
* 差异见下方"落地差异"。
|
||||
* 落地差异(相对早期示意稿,均为有意):
|
||||
* 1. 断言点**不再额外发一条 DBG_ERROR**:钩子本身就打印 file:line(断言唯一有
|
||||
* 价值的现场信息),而每条 DBG_* 调用点约 90 B Flash + 216 B 栈(AGENTS
|
||||
* 「日志不是免费的」);断言点又常处在"内核状态已不可信"的现场,走裸控制台
|
||||
* 价值的现场信息),而每条 DBG_* 调用点约 90 B Flash + 216 B 栈(见
|
||||
* docs/子系统设计/控制台单写者日志设计.md §7.1);断言点又常处在"内核状态已不可信"的现场,走裸控制台
|
||||
* 比走日志行缓冲更稳。
|
||||
* 2. 本头落在 Drivers/BSP 根目录(与 dbg_log.h、bsp_err.h 同级),不是示意稿写的
|
||||
* App/util:它是纯宏叶子能力(无状态、无数据、不依赖任何上层服务),BSP 与
|
||||
@@ -120,7 +120,7 @@ extern void vApplicationAssertFailed(const char *file, long line);
|
||||
* 4. 断言条件**不得带副作用**:关闭态不求值、打开态才求值,带副作用等于让行为
|
||||
* 随开关漂移——这是本宏唯一真正危险的误用形态。
|
||||
* 5. 台架口径:MCU 钩子打印以 [ERR] 开头 → 真机上断言一旦触发,/serial-boot-test 必然判本次
|
||||
* 失败,这是刻意的(AGENTS「Forbidden 标记含 [ERR]」/ 出现 Fault 即不通过)。
|
||||
* 失败,这是刻意的(Forbidden 标记含 [ERR] / 出现 Fault 即不通过)。
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
|
||||
@@ -90,7 +90,7 @@ typedef int bsp_err_t;
|
||||
* 三、自旋圈数型超时不许叫 *_TIMEOUT_MS,命名须含 LOOP/COUNT 且注释写明非时间量;
|
||||
* 返回码一律不许叫 *_TIMEOUT,改返回 BSP_ERR_TIMEOUT。
|
||||
*
|
||||
* ⚠ 两条硬纪律(AGENTS 铁律,这里只复述到最近的使用点):
|
||||
* ⚠ 两条硬纪律(这里只复述到最近的使用点,完整条文见 docs/门禁说明/coding-standard.md):
|
||||
* · 内核启动前不得传 BSP_WAIT_FOREVER:osKernelInitialize 之前任何阻塞调用都会挂;
|
||||
* · 长等待与重试循环必须在循环内喂看门狗(本仓 IWDG 有 required_mask 机制)。
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user