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:
+1
-1
@@ -7,7 +7,7 @@
|
||||
|
||||
`Src/main.c`(CubeMX 初始化)→ `app_main_init`(本目录 `app/app_main.c`)→ `osKernelStart` →
|
||||
6 个 FreeRTOS 任务(见 `task/`)。**`osKernelStart` 之前全是内核启动前代码,禁止调用任何
|
||||
FreeRTOS/CMSIS-RTOS API**(见 `AGENTS.md`「平台约束」)。
|
||||
FreeRTOS/CMSIS-RTOS API**(本条与「就绪屏障位必须 `osFlagsNoClear`」的理由 → `docs/子系统设计/控制台单写者日志设计.md` §2.5 与 `docs/架构设计/项目启动顺序管理.md`)。
|
||||
|
||||
## 目录结构(按职责分层)
|
||||
|
||||
|
||||
+2
-2
@@ -194,8 +194,8 @@ uint32_t adc_cal_flags(adc_semantic_t sem);
|
||||
* 0 - 三路全 VALID(标定侧允许判据跑) uint8_t
|
||||
* 限定条件:任意上下文(纯读 `adc_cal_flags()`,与它同一条并发契约:int32 对齐
|
||||
* 字读写原子、cfg poll 重载 µs 级混窗设计接受);**现查,本层不留任何状态**
|
||||
* 函数说明:① **为什么恰好这三路**:V0.1 把 8 路电气量分给两片转换器(AGENTS
|
||||
* 「双转换器无共同采样触发」),UA/UN/IA = TPAFE 侧这三路是**唯一有效**
|
||||
* 函数说明:① **为什么恰好这三路**:V0.1 把 8 路电气量分给两片转换器(无共同
|
||||
* 采样触发,见 docs/硬件平台/ADC通道映射说明.md),UA/UN/IA = TPAFE 侧这三路是**唯一有效**
|
||||
* 的测量通道;UB/UC/IB/IC/IN 即使将来标定也另受 `CLIPPED` 品质约束
|
||||
* (M5 快照层处理),不掺进本闭锁源。
|
||||
* ② ⚠ **不得当「保护在跑」的总括用**:判据停走共四路来源,本函数只覆盖
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
#include <stddef.h>
|
||||
|
||||
#include "adc.h" /* hadc1:MX_ADC1_Init() 已配 9 通道 / 144 cycles / 软件触发 */
|
||||
#include "tpafe5160.h" /* tpafe5160_snapshot():临界区原子快照(AGENTS 铁律) */
|
||||
#include "tpafe5160.h" /* tpafe5160_snapshot():临界区原子快照(唯一许可取数面) */
|
||||
|
||||
/* STM32 ADC1 通道号上限(F4 上 ADC_CHANNEL_0..15 的宏值即通道号 0..15) */
|
||||
#define ADC_INPUT_STM32_CH_MAX 16U
|
||||
@@ -222,7 +222,8 @@ int adc_input_init(void) {
|
||||
|
||||
/* 挂**一次** DMA,之后不再重启:ADC 由 TIM3 TRGO 每拍触发一轮 9 通道转换,
|
||||
* DMA 在 CIRCULAR 模式下自动搬运、硬件自动重载 NDTR → 每 2 拍绕一圈(乒乓)。
|
||||
* 内核启动前调用安全:只碰寄存器/HAL,不创建任何 CMSIS 对象(AGENTS 铁律)。
|
||||
* 内核启动前调用安全:只碰寄存器/HAL,不创建任何 CMSIS 对象
|
||||
* (内核前编码约束 → docs/架构设计/项目启动顺序管理.md §7)。
|
||||
* 此刻 TIM3 尚未启动(app_main.c 步骤 6)→ 不会发生任何转换或搬运。 */
|
||||
if (HAL_ADC_Start_DMA(&hadc1, (uint32_t *)s_stm32_dma,
|
||||
ADC_INPUT_STM32_DMA_LEN) != HAL_OK) {
|
||||
|
||||
+2
-2
@@ -133,7 +133,7 @@ int app_main_init(void) {
|
||||
* 用途:/serial-boot-test 把"芯片里正在跑的镜像"和"刚编出来的镜像"对上号。此前开机标记
|
||||
* 全是固定串(App init OK / Network Init / ...),旧镜像也照样全中,于是
|
||||
* "反复重下载、芯片一直是旧镜像"这类事故在自动闭环里完全不可见
|
||||
* (AGENTS.md 烧录铁律记的正是它)。代价:1 条 DBG ≈ 90 B Flash + 30 B 常量。
|
||||
* (`.dsh/skills/serial-boot-test/SKILL.md` 镜像身份核对一节的由来)。代价:1 条 DBG ≈ 90 B Flash + 30 B 常量。
|
||||
* ⚠ 戳只在**本 TU 被重编**时才刷新(增量构建),故本文件必须 #include
|
||||
* "test_config.h":否则只切套件宏(TEST_SUITE_* / ENABLE_DESTRUCTIVE_TESTS)
|
||||
* 不重编本 TU,产品镜像与测试镜像顶着同一个戳,戳校验对"两种构建互换"失明
|
||||
@@ -182,7 +182,7 @@ int app_main_init(void) {
|
||||
* 为什么放这儿而不是 defaultTask 的存储 bring-up:
|
||||
* ① 这一步只做 1 次 I2C 读 + 至多 1 次 I2C 写,落在内核启动前——
|
||||
* 单线程、非 ISR、调度器还没跑(本函数不调任何创建类内核 API,
|
||||
* AGENTS「内核前禁调创建类 API」那条与此无关);
|
||||
* 「内核前禁调创建类 API」那条与此无关);
|
||||
* ② 保持介质是 RTC 用户 SRAM,不是文件系统:不必等 STORAGE_READY,
|
||||
* 也就不必在喂狗点上碰卷锁(这条链上根本没有卷操作可言);
|
||||
* ③ sd2506_init 失败时这里自然走"读不到"那一支:状态标成不可信、
|
||||
|
||||
@@ -51,7 +51,7 @@
|
||||
#include "ui_data_feed.h"
|
||||
|
||||
/* 日志锚点:本文件只在"点表点数与快照点数不等"这一条静默漂移上打一条一次性日志
|
||||
* (每条约 90 B Flash,见 AGENTS「日志不是免费的」——常规发布路径刻意一条都不加)。
|
||||
* (每条约 90 B Flash + 216 B 栈,见 docs/子系统设计/控制台单写者日志设计.md §7.1——常规发布路径刻意一条都不加)。
|
||||
* ⚠ DBG_TAG 必须在 include 之前定义:dbg_log.h 的 DBG_ERROR 是宏,漏 include 时
|
||||
* ARMCC 只把 DBG_ERROR 当隐式声明函数放过编译期,错误落在链接期(L6218E
|
||||
* Undefined symbol),比漏写头文件本身更难归因 */
|
||||
@@ -787,7 +787,7 @@ static void feed_fill_info(ui_data_info_t *p_snap, uint32_t tick_ms) {
|
||||
* 一次空队列判断(drain 无请求时只是一次计数比较);
|
||||
* 差值法吸收 tick 回绕(同 App/algo/adc_health.h 的 now_ms 口径)。
|
||||
* 写路径失败态(ERR_RANGE/ERR_LOCKED/ERR_BUSY)走屏上通道,不打日志
|
||||
* (每条 DBG 约 90 B Flash + 216 B 栈,AGENTS「日志不是免费的」)
|
||||
* (每条 DBG 约 90 B Flash + 216 B 栈,见 docs/子系统设计/控制台单写者日志设计.md §7.1)
|
||||
*/
|
||||
void ui_data_feed_tick(void) {
|
||||
uint32_t now;
|
||||
|
||||
+1
-1
@@ -115,4 +115,4 @@
|
||||
|
||||
- `docs/子系统设计/控制台单写者日志设计.md`
|
||||
- `docs/子系统设计/运行与自检记录设计.md`
|
||||
- FatFs 陷阱:`AGENTS.md`「平台约束」
|
||||
- FatFs 陷阱(`FA_WRITE|FA_OPEN_APPEND` 缺一即 `FR_DENIED`、短写须校验字节数、严格 8.3):`docs/架构设计/STM32F4-Base存储架构说明.md` §10 第 10/11 项
|
||||
|
||||
@@ -632,7 +632,7 @@ static int s_clear_try(syslog_id_t id) {
|
||||
if (rc != 0) {
|
||||
/* 一次用户动作至多一条留痕(失败不重试,见 s_clear_service),不会刷屏,
|
||||
* 所以这里不需要像 B/F 项那样另立节流位。
|
||||
* ⚠ 留这条的成本约 90 B Flash(AGENTS「日志与工具链」);留它的理由:
|
||||
* ⚠ 留这条的成本约 90 B Flash + 216 B 栈(见 docs/子系统设计/控制台单写者日志设计.md §7.1);留它的理由:
|
||||
* "清除失败但盘上还有记录"在串口之外没有任何可观测面(UI 只有一个整数状态)。 */
|
||||
DBG_ERROR("clear %s fail (%d)", s_paths[id], (int)fr);
|
||||
}
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
* 不触引擎任何写路径;内核前注册点 = app_main.c(「先注册后 load」契约,同
|
||||
* adc_cal_init / run_par_init)。App/protocol 零日志惯例保持——注册失败留痕
|
||||
* 由调用方 app_main.c 锚点负责,getter/setter 纯 RAM 不打日志(iec104Task
|
||||
* 深链省栈,AGENTS 日志成本口径)。 */
|
||||
* 深链省栈,日志成本见 docs/子系统设计/控制台单写者日志设计.md §7.1)。 */
|
||||
|
||||
/* RAM 副本(引擎原地更新;u16 半字对齐读原子,撕裂域 = 单字段新旧值) */
|
||||
typedef struct {
|
||||
@@ -156,7 +156,7 @@ uint8_t iec104_comm_dirty_peek(void) {
|
||||
* 同一调用点旁挂,每轮无条件
|
||||
* 函数说明:失败不打日志是刻意的(App/protocol 零日志惯例,本文件无 DBG):
|
||||
* cfg_file_save 自身已有 DBG_ERROR 留痕 + 脏位保留 = 屏上 ERR 的
|
||||
* 判定源,再打一条就是重复锚点(AGENTS 日志成本口径)
|
||||
* 判定源,再打一条就是重复锚点(日志成本见 docs/子系统设计/控制台单写者日志设计.md §7.1)
|
||||
*/
|
||||
int iec104_comm_store_save(void) {
|
||||
if (s_comm_dirty == 0u) {
|
||||
|
||||
+1
-1
@@ -14,7 +14,7 @@
|
||||
| `rs485_task.c/h` | (RS-485 任务) | — | 半双工 RS-485 协议通信 |
|
||||
| `../sync/time_sync.c` | timeSyncTask | Normal | 墙钟时间同步(实现不在本目录,见 [`../sync/README.md`](../sync/README.md)) |
|
||||
|
||||
> 上表栈大小/优先级以 `Src/freertos.c` 为准(`README.md`/`AGENTS.md` 的任务表由
|
||||
> 上表栈大小/优先级以 `Src/freertos.c` 为准(`README.md` 的任务表由
|
||||
> `scripts/gen_task_table.py` 生成,勿手抄)。
|
||||
|
||||
## 就绪屏障(重要)
|
||||
|
||||
+3
-2
@@ -5,7 +5,7 @@
|
||||
* (App/algo/sample_ring.c)→ 全周傅氏相量重算(App/algo/phasor.c)
|
||||
* + 帧统计(节拍由 TIM3 硬件定时器提供)
|
||||
* 状态说明:**B1 已落地(2026-10-10)**——本任务从空桩转为真实消费者:
|
||||
* 用 tpafe5160_snapshot() 原子取数(AGENTS 铁律),统计帧数/无新帧次数,
|
||||
* 用 tpafe5160_snapshot() 原子取数(唯一许可取数面),统计帧数/无新帧次数,
|
||||
* 并纳入看门狗 required_mask(TASK_WD_ADC)。
|
||||
* **采样节拍**:由 **TIM3 更新中断(1 kHz)** 硬件触发——
|
||||
* ISR 内调 tpafe5160_start_conv_irq()(Src/main.c 的
|
||||
@@ -22,7 +22,8 @@
|
||||
* V0.1 上只有 TPAFE 三路(UA/UN/IA)测量有效;本任务只取数,不做保护运算。
|
||||
* 接入前必读:取数只用 adc_input_raw() / tpafe5160_snapshot()(临界区原子快照,
|
||||
* 仅任务上下文;旧的 get_buf/data_ready/clear_ready 已删除);接消费者前的
|
||||
* 强制门禁见根 AGENTS.md「接 ADC / RS-485 消费者前的强制门禁」+ 建任务前后
|
||||
* 强制门禁见 docs/算法/继电保护功能复现规划.md 的取数契约,RS-485 侧
|
||||
* → docs/产品需求/产品需求设计文档.md §5.10「重启门禁」;建任务前后
|
||||
* 各跑 scripts/stack_report.py 做栈预算。
|
||||
* 适用平台:STM32F407ZGTx + TPAFE5160
|
||||
* 作者:王建锋
|
||||
|
||||
+2
-1
@@ -24,7 +24,8 @@ void adc_task_func(void *arg);
|
||||
/* 事件驱动消费的唤醒标志。
|
||||
* TIM3 1 kHz 更新中断触发 CONVST 后,用本标志唤醒 adcTask 消费一拍。
|
||||
* 线程标志在此是**命令位**(等待即消费),不是状态位 → 用 osFlagsWaitAny,
|
||||
* 不加 osFlagsNoClear(AGENTS「就绪屏障位必须 osFlagsNoClear」只约束状态位) */
|
||||
* 不加 osFlagsNoClear(「就绪位必须 osFlagsNoClear」只约束状态位,见
|
||||
* docs/架构设计/项目启动顺序管理.md §2) */
|
||||
#define ADC_WAKE_FLAG 0x0001U
|
||||
|
||||
/* ISR 入口:由 Src/main.c 的 HAL_TIM_PeriodElapsedCallback(TIM3 分支)调用。
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
*(保护功能清单见 docs/算法/继电保护功能复现规划.md)
|
||||
* 故障闭锁(`adc_health_flags()` 电平位 → 元件状态复位 + 本拍不判据)。
|
||||
* 判据本体在 `App/algo/prot_elm.c`(纯逻辑,主机侧纯逻辑单测已覆盖),本文件
|
||||
* 只做消费/编排(AGENTS 目录地图:task 不装算法)。
|
||||
* 只做消费/编排(目录归属:算法进 App/algo/,task 不装算法)。
|
||||
* 线程约定:仅本任务调 prot_elm_run / prot_set_selfcheck(prot_elm.h 线程约定);
|
||||
* prot_set 写在 P4 前无第二写者(104 定值写经 pts→prot_set,见注)。
|
||||
* 创建日期:2026-10-12(B5)
|
||||
|
||||
Reference in New Issue
Block a user