112 lines
6.3 KiB
Markdown
112 lines
6.3 KiB
Markdown
# STM32F4-Base
|
||
|
||
> **编译验证：所有代码修改后必须执行 `@build` 验证编译通过（0 错误 0 警告），否则不要提交。**
|
||
|
||
## 构建
|
||
|
||
- **仅支持 Keil MDK-ARM v5 (ARMCC)**，无其他工具链
|
||
- 命令行编译：`@build`（自动执行 `MDK-ARM/build.bat`）
|
||
- 退出码：0 = 成功 | 1 = 有警告（不通过）| 2+ = 错误，查看 `MDK-ARM/build_log.txt`
|
||
|
||
## 硬件
|
||
|
||
| 外设 | 接口 | 引脚 |
|
||
|------|------|------|
|
||
| CH395F 以太网 | SPI2 | PB12 CS, PB13 SCK, PB14 SDO, PB15 SDI |
|
||
| GD5F2GQ5UE NAND | SPI1 | PE0 CS, PB3 SCK, PB4 MISO, PB5 MOSI, PB8 WP, PE1 HOLD |
|
||
| TPAFE5160 ADC | 并行16位 | PG0-PG15 数据, PD3 RD, PD4 CONVST, PD7 BUSY |
|
||
| USART1 | 串口 | PA9 TX, PA10 RX (115200bps) |
|
||
| 6x LED | GPIO | PC4, PC5, PB1, PB2, PF11, PF12（低电平点亮） |
|
||
|
||
MCU: STM32F407ZGTx @ 168MHz (HSE 8MHz → PLL M=4/N=168/P=2，见 `*.ioc`/`stm32f4xx_hal_conf.h`)
|
||
|
||
## 架构
|
||
|
||
```
|
||
Src/main.c → 外设初始化 → app_main_init → gd5f2gq5ue_init → tpafe5160_init
|
||
→ osKernelInitialize → MX_FREERTOS_Init → osKernelStart
|
||
→ [FreeRTOS tasks: defaultTask, netTask, ftpTask]
|
||
```
|
||
|
||
- **defaultTask**：FTL + FatFS 初始化测试（开机一次性）
|
||
- **netTask**：`net_init()` → `net_poll()` + `net_process_messages()` 每 10ms
|
||
- **ftpTask**：`lftpd_start("/", 21, &ftp)` 延迟 7s 后启动
|
||
|
||
### 任务栈
|
||
|
||
| Task | 栈大小 |
|
||
|---|---|
|
||
| defaultTask | 2048 |
|
||
| netTask | 4096 |
|
||
| ftpTask | 4096 |
|
||
|
||
## CH395F 设计原则
|
||
|
||
- **单连接 socket**：Socket 0 复用监听和数据通道，收到 CONNECT 后切换为数据通道，DISCONNECT/TIMEOUT 后重新 OPEN → LISTEN
|
||
- **中断统一处理**：所有 CH395F 中断在 `net_poll()` 中通过 `GET_GLOB_INT_STATUS` 集中读取并清除，不得在 ISR 或其他地方单独处理
|
||
|
||
## NET 网络层
|
||
|
||
- `net_socket.h/c` — BSD Socket API，多连接模式下 Socket 0 监听、Socket 1~7 数据
|
||
- `net_select.h/c` — select/poll I/O 多路复用
|
||
- 线程安全通过消息队列（`netMsgQueue`）实现，所有 CH395F 操作在 netTask 中串行处理
|
||
- 网络初始化顺序（多连接）：`ch395f_set_fun_para(0x02)` → `ch395f_init()` → 配置 Socket 1~7（缓冲区+端口+协议，不 OPEN）→ 配置 Socket 0（TCP LISTEN）
|
||
- **新文件需手动添加到 Keil MDK 工程**才能编译
|
||
|
||
## 关键文件
|
||
|
||
| 路径 | 说明 |
|
||
|---|---|
|
||
| `Src/main.c` | 入口，CubeMX 生成 + USER CODE 区域 |
|
||
| `Src/freertos.c` | FreeRTOS task 创建，CubeMX 生成 + USER CODE 区域 |
|
||
| `App/task/net_task.c` | netTask 主循环（网络初始化 + 轮询） |
|
||
| `Drivers/BSP/NET/` | BSD Socket API 网络抽象层 |
|
||
| `Drivers/BSP/CH395F/` | CH395F SPI 驱动 |
|
||
| `Drivers/BSP/GD5F2GQ5UE/` | NAND Flash 驱动 + dhara FTL + FatFS diskio |
|
||
| `Drivers/BSP/TPAFE5160/` | ADC 并行接口驱动 |
|
||
| `Drivers/BSP/SD2506/` | RTC 驱动 |
|
||
| `Drivers/BSP/RS485/` | RS-485 通信（UART5 + PD0 DE） |
|
||
|
||
## 驱动关键点
|
||
|
||
详见 `docs/` 目录：
|
||
- `CH395F_Trap_Records.md` — CH395F 已知陷阱
|
||
- `GD5F2GQ5UE_Trap_Records.md` — GD5F2GQ5UE 已知陷阱
|
||
- `CH395F_Test_Guide.md` — 网络测试说明
|
||
|
||
## 串口调试（serial-mcp-server MCP/CLI）
|
||
|
||
通过 **Adancurusul/serial-mcp-server** 自主读取/控制 **USART1 串口**（PA9 TX / PA10 RX，115200bps）的打印流。
|
||
|
||
- **串口端口单一配置源：`.opencode/serial_config.json`**（当前本机为 `COM6`）。端口变化只改这个文件。
|
||
- 用法、采集窗口模式、已知陷阱等详见 **`docs/测试说明/serial-mcp-server_串口调试.md`**
|
||
|
||
## 自动化测试（AI 迭代闭环）
|
||
|
||
改完代码后运行 **`@test`** 可自动执行完整闭环：**构建验证 → 串口捕获武装（serial-mcp-server 采集窗口）→ 烧录（`MDK-ARM/download.bat`，下载后 Reset & Run）→ 解析捕获 JSON → `test/verify_log.ps1` 标记校验 → PASS/FAIL 判定并迭代**。
|
||
|
||
- **推荐一键命令**：`test/run_boot_test.ps1` = 采集（含 EOF 重试）→ 烧录 → 提取日志 → verify 全流程，退出码 0=PASS/1=FAIL/2=错误
|
||
- 判定标准：`@test` 内部先 `@build`（0 错误 0 警告），再 `@download`（退出码 0），日志用 `verify_log.ps1` 校验（默认 Required：`App init OK`/`Network Init`/`net init: OK`；Forbidden：`FAIL`/`ERROR`/`HardFault`）
|
||
- **采集必须在烧录前武装**（采集进程先打开 COM 等 first-byte，烧录触发复位后才抓得到开机日志）；`run_boot_test.ps1` 的 `-FlashCmd` 分支已保证顺序
|
||
- 每次按模块定制标记（网络/存储/RTC/ADC/RS485）见 `docs/测试说明/自动化测试流程.md`
|
||
- UI（`App/task/ui_task.c`）当前无 DBG 打印，无法从串口自动验证；如需 UI 回归，先在固件加 `UI port init: OK` / `UI menu init: OK` 打印再纳入 Required
|
||
|
||
## 注意
|
||
|
||
- `Inc/` 和 `Src/` 中 CubeMX 生成的文件带有 `USER CODE BEGIN`/`END` 标记，自定义代码写在这些区域之间
|
||
- `Drivers/BSP/` 下的驱动文件为纯手工代码，不受 CubeMX 保护
|
||
- CH395F 每次 SPI 事务需用 `ch395f_spi_begin()` / `ch395f_spi_end()` 包裹
|
||
- CH395F SPI PCB设计问题，现在分频系数必须为 8，速度相对较低
|
||
- FreeRTOS V10.3.1 via CMSIS-RTOS V2，HAL 时基用 TIM7（非 SysTick）
|
||
- NVIC 优先级分组 4 位，外设中断优先级 ≥ 5（`configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY`）
|
||
|
||
## 源码编辑与编码安全（铁律）
|
||
|
||
本工程源码含大量中文注释，曾因错误的文本重写方式导致整文件乱码（`U+FFFD` 替换符，不可逆）。以下规则必须遵守：
|
||
|
||
- **绝不用 `Get-Content` / `Set-Content` / `cmd` 文本重写含中文的源码文件**。这类"整文件重写"会按系统默认编码重新解码再写回，多字节中文必被 `U+FFFD` 替换且不可逆。
|
||
- **改代码只用 Edit 工具**（精确子串替换，不重新编解码整个文件，安全）；批量替换用 Edit 的 `replaceAll`。
|
||
- 必须脚本级替换时，使用显式且一致的编码（如 Python `open(p, encoding="utf-8")` 同编码回写），并先确认工程编码（Keil 工程常用 GBK）——但**最稳的是别碰**，只用 Edit / git。
|
||
- **发现乱码先别急着 `git checkout`**：`git checkout` 会丢弃所有未提交工作，使损失扩大。先评估能否用 Edit 仅改坏掉的那几行。
|
||
- 验证是否真损坏用字节级检查（统计 `EF BF BD` 出现次数），不要依赖终端/Read 渲染判断。
|