STM32F4-Base/AGENTS.md

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 — 网络测试说明

注意

• 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 渲染判断。