Files
STM32F4-Base/Drivers/BSP/README.md
T
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

48 lines
3.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Drivers/BSP/ — 板级支持包(纯手工自研代码)
> **本目录全部为手工编写的板级驱动与中间层**(非 CubeMX 生成、非第三方库、非 ST HAL)。
> 每个芯片/子模块一个子目录。改驱动前**必读对应模块的 Trap Records**(见下)。
## 子模块一览
| 目录 | 芯片/模块 | 接口 | 职责 | 关键文档 |
|---|---|---|---|---|
| `CH395F/` | CH395F 以太网控制器 | SPI2 | 以太网 MAC/PHY 控制器底层驱动 | `docs/问题记录/CH395F_Trap_Records.md` |
| `GD5F2GQ5UE/` | GD5F2GQ5UE SPI NAND | SPI1 | NAND 驱动 + FTL(`nand_ftl.c`) | `docs/问题记录/GD5F2GQ5UE_Trap_Records.md` |
| `TPAFE5160/` | TPAFE5160 高精度 ADC | 并行 16 位 | ADC 采样驱动(CONVST/BUSY 时序) | — |
| `SD2506/` | SD2506 RTC | I2C | 实时时钟驱动 | `docs/问题记录/SD2506_Trap_Records.md` |
| `RS485/` | RS-485 半双工 | UART5 | 收发方向控制(DE 引脚)+ 时序 | — |
| `NET/` | BSD Socket 网络抽象层 | — | Socket API + select + 轻量 FTP 服务器 | `docs/网络/`(含 `Net层阻塞模型架构设计.md`) |
| `NETCFG/` | 网络配置 | — | `/config.ini` 网络段的加载/保存 | `docs/子系统设计/网络配置说明.md` |
| `UI/` | LVGL UI 组件 | — | 菜单/内容页/组件/中文字体 | `docs/UI设计/` |
## 根级文件
| 文件 | 作用 |
|---|---|
| `dbg_log.h` | **调试日志宏**(`DBG_INFO` 等),编译期开关 |
| `dbg_cfg.h` | 调试配置项 |
| `app_assert.h` | **模块级轻量断言宏**(`APP_ASSERT`):编译期两态裁剪(默认关闭 = 零符号零开销;打开态与 `configASSERT` 共用同一个失败钩子)。试点见 `Drivers/BSP/NET/net_socket.c` |
## 子模块 README
- [`NET/README.md`](NET/README.md) — 网络抽象层(Socket / select / FTP)
- [`UI/README.md`](UI/README.md) — LVGL UI 组件
## ⚠️ 改驱动前必读(踩坑速查)
| 模块 | 陷阱 |
|---|---|
| CH395F | SPI 事务须 `ch395f_spi_begin()/end()` 包裹;分频系数**必须为 8**(PCB 约束,勿"优化");快速复连会因事件被读清消费致监听死亡(TRAP-NET-17 已修,E14 复核:非芯片丢事件);上传中止后首笔复连截断(TRAP-NET-18 已修) |
| GD5F2GQ5UE | FatFs 移植版打开模式陷阱(`FA_OPEN_APPEND` 不含写位);文件名严格 8.3 短名、不得以点开头;`f_write` 簇分配失败返 `FR_OK` + 短写,须校验字节数 |
| NET | 就绪屏障位必须 `osFlagsNoClear`;`s_net_errno` 已按任务隔离(勿改回全局) |
| 通用 | 自研代码**禁用 C 库堆分配**(MicroLIB 堆仅 512 B),动态内存只用 `pvPortMalloc/vPortFree` |
> 完整平台约束的落点:隔离与错误码语义 → `.dsh/roles/network-specialist.md`(网络)/ `.dsh/roles/storage-specialist.md`(存储);中断与吞吐细节 → `docs/网络/网络自愈架构设计.md`、`docs/架构设计/STM32F4-Base存储架构说明.md`;C 库堆禁令 → `docs/门禁说明/coding-standard.md`。另见各模块的 Trap Records。
## 相关文档
- 架构全景:`docs/架构设计/项目架构总览.md`
- 存储栈:`docs/架构设计/STM32F4-Base存储架构说明.md`
- 测试指南:`docs/测试说明/板级测试/*_Test_Guide.md`