为自建代码目录补齐 README,建立目录级导航体系

- 新增 26 份目录 README:App/(+log,task,util,protocol)、Drivers/BSP/(+8子系统)、
  Src/、Inc/、scripts/、tools/(+6子工具)、test/、MDK-ARM/、simulator/(+sim,tests)
- 每份含:定位、文件清单表、关键约束/陷阱、指向 docs 权威文档
- 第三方库与生成代码目录排除(CMSIS/HAL/Middlewares/Lib/SDL2)
- docs/文档规范.md 新增 §1.1b 代码目录 README 约定;根 README 目录结构加入说明
This commit is contained in:
2026-09-26 12:25:36 +08:00
parent 8d86fb1149
commit 39bd06adea
31 changed files with 1149 additions and 0 deletions
+49
View File
@@ -0,0 +1,49 @@
# App/ — 应用层
> **自研代码**(非 CubeMX 生成、非第三方库)。本目录是项目的**应用层**:任务编排、业务逻辑、
> 日志与配置引擎、工具函数。所有文件遵循 `docs/代码规范/嵌入式C语言代码规范_V1.0.md`。
## 职责
`Src/main.c`(CubeMX 初始化)→ `app_main_init`(本目录 `app_main.c`)→ `osKernelStart` →
6 个 FreeRTOS 任务(见 `task/`)。**`osKernelStart` 之前全是内核启动前代码,禁止调用任何
FreeRTOS/CMSIS-RTOS API**(见 `AGENTS.md`「平台约束」)。
## 文件一览
| 文件 | 作用 |
|---|---|
| `app_main.c/h` | 应用初始化入口 `app_main_init`:时间子系统优先 → RS485 → NAND → ADC → 诊断 |
| `app_cfg.h` | **功能模块编译开关**(裁剪测试套件/模块用) |
| `sys_events.h` | 系统就绪事件定义(Event Flags:`SYS_EVT_NET_READY` 等就绪屏障) |
| `time_sync.c/h` | 时间同步任务(等待网络就绪后与时间源同步) |
| `cfg_file.c/h` | **配置引擎**(`/config.ini` 解析 + 持久化 + 旧档迁移),属主为 defaultTask |
| `cfg_file_store.h` | 配置存储后端抽象接口(MCU=FreeRTOS 堆 / 模拟器=宿主堆,共享核心零分配) |
| `cfg_file_store_mcu.c` | 配置存储的 MCU 端后端实现(`cfg_store_alloc/free` → FreeRTOS 堆) |
| `log/` | 日志子系统(见下) |
| `task/` | FreeRTOS 任务实现(见下) |
| `util/` | 工具函数(见下) |
| `protocol/` | 通信协议(预留,当前为空) |
## 子目录
| 目录 | 内容 | README |
|---|---|---|
| `log/` | syslog(`/log/run.log`·`selftest.log` 定长记录)+ 控制台单写者日志 | [`log/README.md`](log/README.md) |
| `task/` | 6 个 FreeRTOS 任务实现 | [`task/README.md`](task/README.md) |
| `util/` | CRC / 环形缓冲 / 墙钟时间 | [`util/README.md`](util/README.md) |
| `protocol/` | 通信协议(预留) | — |
## 关键约束
- **配置引擎单任务收敛**:`cfg_file` 为静态态、属主是 defaultTask;UI 保存请求经
`SYS_EVT_CFG_SAVE` 事件唤醒,netTask/uiTask **不得直接触碰**配置引擎
- **syslog 唯一写者**:`/log/*` 只由 defaultTask 写入
- 新增任务/缓冲/栈前**必须先核算 RAM 余量**(`docs/内存管理/`)
## 相关文档
- 架构全景:`docs/架构设计/项目架构总览.md`
- 启动顺序:`docs/架构设计/项目启动顺序管理.md`
- 配置引擎:`docs/子系统设计/配置文件设计说明.md`
- 日志:`docs/子系统设计/控制台单写者日志设计说明.md`、`docs/子系统设计/运行与自检记录设计说明.md`