# STM32F4-Base 软件架构与运行时规格

> **文档定位**：全仓**系统运行时架构（软件侧）**与**工具链 / 工程约束**的权威表档。
> 来源链：`docs/产品需求/产品需求设计文档.md` v1.9 原 §3/§4 → 《系统架构与硬件规格》
> →（2026-10-30 按"软件 / 硬件不混排"拆分）本档 = 软件侧；硬件侧见
> [`硬件规格与能力边界.md`](硬件规格与能力边界.md)。需求与验收口径仍在需求档。
> 与 [`docs/架构设计/项目架构总览.md`](项目架构总览.md) 的分工：总览是**叙述性全景**，
> 本档是**完整口径表**——就绪屏障位表（bit0~8）、线程间通信机制表、启动时序图以
> **本档为准**，两处冲突以本档为准并回改总览。
> **版本**：v1.0　**日期**：2026-10-30

## 1. 六层分层架构

![STM32F4-Base 项目分层架构](../images/项目架构总览.svg)

> 上图由 `tools/arch_diagram/gen_arch_svg.py` 生成（手绘 SVG，零连线交叉）；改架构后编辑脚本顶部
> `ROWS` 数据重跑即可，源数据与下表一致。

分层原则：**上层只依赖相邻下层（单向）**；**① 业务层为顶层**（仅 `net_cfg`，被 UI 与基础服务共用），
**② UI 层与 ③ 基础服务层同级并列**。

| 层 | 目录 | 职责 | 关键模块 |
|---|---|---|---|
| ① 业务层 | `Drivers/BSP/NETCFG/` | 顶层共享配置（被 UI 与基础服务共用） | `net_cfg` |
| ② UI 层 | `Drivers/BSP/UI/` | LVGL 界面（与 PC 模拟器共用源码） | `ui_port` `ui_menu` `ui_menu_view` `ui_menu_tab` `ui_content_page` `ui_page_*` `ui_net_sink` `ui_font_cn_12` `ui_deco` |
| ③ 基础服务层 | `App/`、`Drivers/BSP/NET/lftpd/` | 应用侧服务、采集算法与协议编排 | `app_main` `sys_events` `app_cfg` `task/*` `algo/*`（语义取数与有效性~保护判据）`protocol/iec104/*` `log/soe_store` `lftpd` `time_sync` |
| ④ 中间件层 | `Drivers/BSP/NET/`、`Lib/`、`App/util/` | 通用库 / 协议栈 | `net_socket` `net_select` `FatFs` `nand_ftl`(dhara) `LVGL` `sys_clock` |
| ⑤ 驱动层 | `Drivers/BSP/{CH395F,GD5F2GQ5UE,TPAFE5160,SD2506,RS485}/` | 芯片寄存器 / 时序 / 中断 | `ch395f` `gd5f2gq5ue` `tpafe5160` `sd2506` `rs485` |
| ⑥ 内核 / HAL | `Middlewares/`、`Drivers/STM32F4xx_HAL_Driver/`、`Drivers/CMSIS/` | 任务调度、外设 HAL、启动 | FreeRTOS V10.3.1 · STM32 HAL · CMSIS |
| ⑦ 硬件 | — | STM32F407ZGTx @168MHz | SPI1 / SPI2 / I2C1 / UART4 / USART1 / DMA / GPIO / TIM7 |

> 表中硬件行只到"层"口径；**器件与引脚级规格见 [`硬件规格与能力边界.md`](硬件规格与能力边界.md)**。

## 2. 运行时任务模型

**九个** FreeRTOS 任务（`Src/freertos.c` 创建，任务体在 `App/task/`、`App/sync/`）：

| 任务 | 栈（words / B） | 优先级 | 职责 |
|---|---|---|---|
| `defaultTask` | 1280 / 5120 | Normal | FatFS 挂载（无卷 `f_mkfs`）→ 卷健康探针/自愈 → `net_cfg_load` + 定值/运行参数/通讯参数装载（**配置引擎属主**）→ 置 `STORAGE_READY` → 日志落盘（唯一写者）+ 2 s 配置轮询 + 各模块脏位落盘（`prot_set` / `run_par` / `comm`）+ SOE 排空 + LED 闪烁 + 栈水位观测 + **看门狗唯一喂狗者** |
| `netTask` | 960 / 3840 | Normal | 等存储 → `net_stack_bring_up()` → 置 `NET_READY` → `net_poll` 轮询 + CH395F 操作串行化（消息队列执行者） |
| `ftpTask` | 1024 / 4096 | Normal | 等网络**且**存储（`WaitAll`）→ `lftpd_start("/", 21)` → 单客户端会话循环 |
| `testTask` | 2048 / 8192 | BelowNormal | 测试套件入口（`test/board/test_config.h` 选择）。**产品构建不创建**（未选套件时立即 `vTaskDelete` 回收其 8 KB CCM 栈） |
| `uiTask` | 4096 / 16384 | BelowNormal | 等网络 → `ui_port_init`/`ui_menu_init`/`ui_standby_init`（空闲 60 s 切待机屏）/`ui_net_sink` → 10 ms 刷新 + 数据注入 |
| `timeSyncTask` | 640 / 2560 | Normal | 等网络 → TCP :8888 收 PC 推送时间 → 写 RTC |
| `adcTask` | 640 / 2560 | AboveNormal | **采集主线唯一消费者**：每拍 `adc_input_poll()`（TPAFE 快照 + ADC1 DMA 帧）→ `adc_health` 有效性 → `phasor_run()` 相量 → `freq_run()` 测频 → 每 200 ms `meas_tick()` 发布遥测快照 |
| `iec104Task` | 640 / 2560 | Normal | 等网络 → TCP 工厂默认 :2404 监听 → 104 链路状态机（总召/变位/周期/遥控/定值/对时）+ 断链重听 + 网络代次自愈 |
| `protectTask` | 512 / 2048 | Normal | **20 ms 判据节拍**：采样故障闭锁判定 → 定值校验和巡检 → `prot_elm_run()` 元件判据 → 动作边沿投递 SOE（**不做 NAND I/O**） |

> `idle`（128 words）/ `timer`（256 words）由 FreeRTOS 内核创建。所有任务栈从 **56 KB** `heap_4` 堆
> （CCM）分配；CCM 水位 87.9%（<92% 门禁）。
> 任务表与 `Src/freertos.c` 的 `osThreadAttr_t` 一致，由 `scripts/gen_task_table.py` 生成并门禁校验；
> **栈配置与实测余量**见 `../产品需求/产品需求设计文档.md` §7.3，改栈前后必须重跑 `scripts/stack_report.py`。
>
> ⚠ **节拍同源**：TIM3 更新事件（1 kHz）同时触发 TPAFE `CONVST` 与（经 TRGO）ADC1 一轮 9 通道扫描，
> 并在 ISR 内唤醒 `adcTask`——采集节拍与任务唤醒**不允许**各自计时。
> ⚠ **ADC1 必须在挂 DMA 的瞬间处于关闭态**：`app_main_init()` 步骤 4b-pre 的 `adc1_disable()` 不可删、不可后移，
> 否则 DMA 乒乓缓冲整体旋转 2 格（表象与"映射表写错"一致）。证据见
> [`docs/子系统设计/ADC采样节拍设计说明.md`](../子系统设计/ADC采样节拍设计说明.md) §4.5。

## 3. 就绪屏障（Event Flags）

![就绪屏障（Event Flags）](../images/就绪屏障.svg)

用 CMSIS-RTOS2 Event Flags（`sys_evtHandle`）表达"子系统就绪"，取代魔法延时与全局标志轮询。
生产者与消费者互不知晓，只经事件组解耦；新增子系统只需定义新 bit + 各自 wait/set。

| 位 | 名称 | 类型 | 语义 |
|---|---|---|---|
| bit0 | `SYS_EVT_NET_READY` | 状态位 | netTask：`net_init` + PHY 稳定完成 |
| bit1 | `SYS_EVT_STORAGE_READY` | 状态位 | defaultTask：FTL/FatFS 挂载 + 配置就绪 |
| bit2 | `SYS_EVT_FTP_READY` | 状态位 | ftpTask：`lftpd_start` 完成 |
| bit3 | `SYS_EVT_TIMESYNC_READY` | 状态位 | timeSyncTask：首次时间同步完成 |
| bit4 | `SYS_EVT_NET_RECONFIG` | 命令位 | UI：请求立即应用新网口配置 |
| bit5 | `SYS_EVT_CFG_SAVE` | 命令位 | UI：网口配置保存请求（defaultTask 消费并写盘） |
| bit6 | `SYS_EVT_CONSOLE_TX` | 命令位 | 控制台单写者：生产者入环形缓冲后置位 |
| bit7 | `SYS_EVT_PROT_SET_SAVE` | 命令位 | 保护定值落盘请求：104 检测到定值脏后置位，defaultTask 原子写 `/prot_set.bin` |
| bit8 | `SYS_EVT_RUN_PAR_SAVE` | 命令位 | 运行参数段落盘请求：104 写运行参数后置位，defaultTask 整档外科保存 |

> ⚠️ **铁律**：状态位（bit0~3）表达**持久状态**，任何消费者都**不许消费**——必须
> `osFlagsWaitAny|osFlagsNoClear`。命令位（bit4~8）表达"请做一件事"，必须**恰好被消费一次**（消费型等待）。
> 历史事故：就绪位被先到的等待者消费，导致 `ftpTask` 的 `WaitAll(bit0|bit1)` 永不成立、21 端口从未监听（静默）。

## 4. 启动时序

```mermaid
sequenceDiagram
    autonumber
    participant M as main
    participant A as app_main_init
    participant K as osKernelStart
    participant D as defaultTask
    participant N as netTask
    participant S as adcTask / protectTask
    participant F as ftpTask
    participant U as uiTask
    participant I as iec104Task / timeSyncTask

    M->>M: HAL_Init + CubeMX 外设初始化<br/>(SPI1/SPI2/I2C1/UART4/USART1/DMA/GPIO/TIM3/TIM7)
    M->>A: app_main_init()
    Note over A: 时间子系统优先，使后续日志带时间戳
    A->>A: sd2506_init() → sys_clock_init()（墙钟基准）
    A->>A: rs485_init() → gd5f2gq5ue_init()（BBT 扫描）
    A->>A: tpafe5160_init() → adc_input_init()（语义映射自检）
    A->>A: 配置段注册（adc_cal / run_par / prot_set / comm）→ 定值/元件初始化
    A->>A: adc1_disable() → ADC1 挂 DMA（4b-pre，顺序不可变）→ 启动 TIM3 1 kHz 节拍
    A-->>M: "App init OK"
    M->>K: osKernelStart()
    K->>D: 调度
    D->>D: f_mount（无卷则 f_mkfs FAT32）→ 卷探针/自愈 → 配置装载<br/>→ 定值整表原子装载（损坏则保出厂默认 + 自检留痕）
    D-->>N: set SYS_EVT_STORAGE_READY
    S->>S: adcTask：等 TIM3 节拍 → 采集 → 相量/测频 → 200 ms 遥测快照
    S->>S: protectTask：20 ms 判据（未标定/采样故障则停走）
    N->>N: wait STORAGE_READY（Any|NoClear）→ net_init(ip,mask,gw,mac)<br/>→ PHY 强制 100M 全双工 → 等链路 ≤3s
    N-->>F: set SYS_EVT_NET_READY
    F->>F: wait NET_READY|STORAGE_READY（All|NoClear）→ lftpd_start("/", 21)
    U->>U: wait NET_READY（Any|NoClear）→ ui_port_init → ui_menu_init → ui_net_sink_start(7003)
    I->>I: wait NET_READY（Any|NoClear）→ TCP listen :2404（默认）/ :8888
```

> **顺序铁律**：① 配置段注册必须**先于** `cfg_file_load`（否则 FTP 上传的段不生效）；
> ② `adc1_disable()` 必须在挂 DMA 之前；③ `osKernelStart` 之前禁调任何内核 API（含 `osDelay` / 队列）。

## 5. 线程间通信

| 机制 | 对象 | 用途 |
|---|---|---|
| Event Flags | `sys_evtHandle` | 启动就绪屏障 + 命令位（§3） |
| Message Queue | `netMsgQueue`（深度 8，`net_msg_t`） | 所有 CH395F 操作经队列**串行化**到 netTask 执行，保证 SPI 单线程访问 |
| 双区 + 序号（无锁） | `phasor` 相量区、`meas` 遥测快照 | 写侧填满计算区后单字节翻转活跃索引；读者先取索引再整份拷贝，`seq` 判"是否换帧" |
| SPSC 环（无锁） | `soe_store`（深度 8） | protectTask 只投递动作边沿，defaultTask 排空落盘——**保护路径零 NAND I/O** |
| 脏位 + 事件位 | `prot_set` / `run_par` / `comm` | 写入方置脏；104 侧 peek 后投递事件位，配置属主（defaultTask）落盘，失败保留脏位下轮重试 |
| 单字请求标志 | `prot_elm_request_reset()` | 跨上下文复归请求（104 遥控 YK11 在 iec104Task 落请求，protectTask 下一拍消费） |

## 6. 工具链与工程约束

> 本节收**构建与运行环境事实**。SDIO 无能力属硬件事实，见
> [`硬件规格与能力边界.md`](硬件规格与能力边界.md) §5 的 H5。

### 6.1 运行时与工具链

| 项 | 值 | 说明 |
|---|---|---|
| RTOS | FreeRTOS V10.3.1（CMSIS-RTOS2） | HAL 时基 TIM7，tick = 1 ms；NVIC 4 位抢占，外设中断优先级 ≥5 |
| 工具链 | Keil MDK-ARM v5（ARMCC v5） | 工程锁 `uAC6=0`，**不支持 armclang** |
| CubeMX | 6.17.0 + STM32Cube FW_F4 V1.28.3 | 与 `.ioc` 记录一致，再生成须用此组合 |

### 6.2 工程约束

| 约束 | 内容 |
|---|---|
| **CubeMX 生成文件** | `Inc/`、`Src/` 中带 `USER CODE BEGIN/END` 标记；自定义代码**只能**写标记区内 |
| **生成区外的定制** | 仅限 `Src/iwdg.c` 延后启动、4 个 Fault Handler 实体（`scripts/check_cubemx_survival.py` 审计兜底） |
| **`osKernelStart` 前** | 禁止任何 FreeRTOS / CMSIS-RTOS API 调用 |
| **BOM / 编码** | 部分源文件带 BOM（`Drivers/BSP/UI/*`、`App/task/ui_task.c`、`App/cfg/cfg_file.c`、`Lib/lv_conf.h`），被工具改写丢 BOM 会导致 ARMCC 按 CP936 解码、中文字面量编译失败 |
| **新源文件** | 必须双端注册（Keil `.uvprojx` + `simulator/CMakeLists.txt`），否则不参与编译 |

---

> **编号换算（原《系统架构与硬件规格》合档 → 本档）**：旧档号记裸号、不带 § 以免与本档编号混淆——
> 1.1→§1、1.2→§2、1.3→§3、1.4→§4、1.5→§5；旧 2.1 的 RTOS / 工具链 / CubeMX 三行与旧 2.5 五条工程约束
> （除 SDIO 行）并入 §6。全仓旧号引用已按本表重定向；换算只留此注，正文不再出现旧号。