e4981aa2f6
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.
37 lines
4.2 KiB
Markdown
37 lines
4.2 KiB
Markdown
# Drivers/BSP/TPAFE5160/ — TPAFE5160 高精度 ADC 驱动
|
||
|
||
> TPAFE5160 是**并行 16 位**接口的高精度 ADC。本目录为寄存器级驱动:
|
||
> 转换启动(CONVST)、忙信号(BUSY)、数据读取(RD)时序管理。
|
||
|
||
## 文件一览
|
||
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `tpafe5160.c/h` | ADC 初始化、转换启动(轮询 + 中断)、16 位并行数据读取 |
|
||
|
||
## 硬件接口
|
||
|
||
- **并行 16 位**:PG0–PG15 数据总线 / **PC8 RD**(读选通)/ **PC9 CONVST**(转换启动)/ **PC7 BUSY**(转换中)/ **PC6 FRSTDATA**(首通道标记,板上 R24 4.7k 上拉)/ **PA12·PA11·PA8 = OS0·OS1·OS2**(过采样选择)——V0.1 网表口径(V0.0 曾为 PD3/PD4/PD7,已作废)
|
||
- 部分引脚为 GPIO 模拟时序(非硬件 SPI/FSMC)
|
||
|
||
## 关键点
|
||
|
||
- **周期重触发由 TIM3 更新事件(1 kHz)驱动**(2026-10-10):`app_main_init` 末尾 `HAL_TIM_Base_Start_IT(&htim3)` 启动节拍,`Src/main.c` 的 `HAL_TIM_PeriodElapsedCallback` 在 TIM3 分支内调 `tpafe5160_start_conv_irq()`(ISR 内仅两次 GPIO 写)。ADC 采集链路 阶段曾由 `adcTask` 每 1 ms 软触发(已改)。⚠ **节拍源必须是 TIM3 而非 TIM6**:TIM3 的同一个更新事件还经 **TRGO** 硬件触发 STM32 ADC1,两片转换器由此同源对齐;F4 上 TIM6/TIM7 的 TRGO 只接 DAC,喂不到 ADC1
|
||
- **取数只用 `tpafe5160_snapshot(int16_t *dst, uint8_t count)`**(**仅任务上下文**,内部临界区原子拷贝;返回 1=新帧 / 0=无新帧 / -1=参数无效)。配套的 `tpafe5160_frame_seq()` 给帧序号、`tpafe5160_frstdata_err()` 给"FRSTDATA 无跳变"帧计数
|
||
- ⚠️ **不要用缓冲区指针取数**:旧的 `get_buf()` / `data_ready()` / `clear_ready()` 已于 2026-10-10 **删除**——`get_buf` 只给指针、任务再逐通道拷,中间被 BUSY EXTI 抢占就拷回**两帧混合**数据;`s_ready` 电平标志在 `start_conv_irq` 里被清 0,等于**用重触发去丢帧**。现由**帧序号**(只增不清)+ **临界区快照**取代
|
||
- **`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/内存管理/`);接消费者前的强制门禁 = 取数契约(只用 `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)→ **禁止**跨转换器做相位/功率/功率因数类运算
|
||
|
||
## 已知问题
|
||
|
||
- `docs/问题记录/TPAFE5160.md` 有 **16 张图片断链**(文档引用了但图从未入库)——已登记,暂缓处理
|
||
|
||
## 相关文档
|
||
|
||
- 芯片手册转录:`docs/芯片手册/TPAFE5160.md`(注:其配图有断链)
|
||
- 任务实现:`App/task/adc_task.c`
|
||
- 硬件引脚:根 `README.md`「外设接口」
|