101 lines
7.0 KiB
Markdown
101 lines
7.0 KiB
Markdown
# AGENTS.md
|
||
|
||
## 项目概述
|
||
|
||
本仓库是基于国民技术（Nations）**N32WB031 BLE SoC** 的嵌入式固件工程集合。N32WB031 是一颗 Cortex-M0 内核的低功耗蓝牙芯片（64MHz HSI，Flash 256KB，RAM 48KB）。
|
||
|
||
当前唯一的活跃工程是 **`mcm-ddc-04/`**：一个基于 N32WB03x SDK V2.0.0 从零搭建的裸工程，演示 UART 串口打印（printf 重定向 + DMA 发送 + RX 中断）、CLI 命令框架、FreeRTOS 多任务、GPIO 点灯。目标硬件为 **N32WB031_STB_V1.3 开发板**（NS-LINK 调试器，SWD 下载）。
|
||
|
||
仓库顶层目录：
|
||
|
||
- `mcm-ddc-04/` — 主工程（应用代码、MDK 工程文件、开发日志）
|
||
- `nations-tec/` — 厂商资源：SDK V2.0.0、DFP 器件包、STB 开发板资料（原理图/BOM/PCB）、官方 PDF 文档。**这些内容为只读参考资料，不要修改。**
|
||
- `app/`、`Boot/`、`docs/` — 顶层空目录，为后续规划预留的占位（当前无内容）
|
||
|
||
关键参考路径（相对仓库根）：
|
||
|
||
- SDK：`nations-tec/N32WB03x_SDK_V2.0.0`（固件库 `firmware/`、中间件 `middlewares/Nationstech/ble_library` 与 `middlewares/Third_Party/FreeRTOS`、官方例程 `projects/n32wb03x_EVAL/`、DFU 工具 `utilities/dfu`）
|
||
- 官方例程：USART printf `projects/n32wb03x_EVAL/peripheral/USART/Printf`、点灯 `peripheral/GPIO/LedBlink`、FreeRTOS `application/FreeRTOS/FreeRTOS_ThreadCreation`
|
||
- 开发日志与详细设计决策：`mcm-ddc-04/docs/开发日志.md`
|
||
|
||
## 工程结构（mcm-ddc-04）
|
||
|
||
```
|
||
mcm-ddc-04/
|
||
├── app/
|
||
│ ├── main.c # 入口：SystemCoreClockUpdate → USART 初始化+banner → LED 初始化 → 建队列/任务/CLI → vTaskStartScheduler
|
||
│ ├── bsp_usart.c/.h # USART1 初始化（PB6/PB7，115200 8N1）+ fputc 重定向（'\n' 前自动补 '\r'）+ DMA TX（CH1，轮询完成）+ RXDNE 中断字节队列 + TX 互斥锁
|
||
│ ├── bsp_led.c/.h # LED1(PB0)/LED2(PA6) 初始化、on/off/toggle
|
||
│ ├── app_tasks.c/.h # 3 个 FreeRTOS 任务 + 日志队列（生产者-消费者模型）+ 主动打印开关（默认关）
|
||
│ ├── app_cli.c/.h # CLI 独立任务：行接收/解析/执行/应答（应答走 DMA TX），命令表驱动
|
||
│ ├── n32wb03x_it.c/.h # NMI / HardFault 异常处理 + USART1_IRQHandler（转发到 bsp_usart_rx_isr_handler）
|
||
│ └── FreeRTOSConfig.h # heap 20KB，SVC/PendSV/SysTick 映射给 FreeRTOS port
|
||
├── MDK-ARM/
|
||
│ ├── embeddedSrc.uvprojx / .uvoptx # Keil µVision5 工程文件
|
||
│ ├── Objects/ # 编译产物（embeddedSrc.axf / .hex）
|
||
│ ├── bin/ # fromelf 生成的 embeddedSrc.bin
|
||
│ └── build.log
|
||
└── docs/开发日志.md
|
||
```
|
||
|
||
SDK 源码（固件库、CMSIS、FreeRTOS V9.0.0、启动文件）通过相对路径 `..\..\nations-tec\N32WB03x_SDK_V2.0.0` 被 uvprojx 引用，**不复制进工程**。因此 `mcm-ddc-04` 目录不能脱离仓库根单独移动。
|
||
|
||
工程配置：器件 `N32WB031`，IROM 0x01000000 / 0x40000，IRAM 0x20000000 / 0xC000，MicroLIB，全局宏 `N32WB03X, USE_STDPERIPH_DRIVER`。
|
||
|
||
## 构建与烧录
|
||
|
||
工具链：Keil µVision5（ARMCC V5.06 update 6），安装于 `D:\Keil_v5`。
|
||
|
||
命令行构建（工作目录必须为 `mcm-ddc-04/MDK-ARM`）：
|
||
|
||
```bash
|
||
"D:\Keil_v5\UV4\UV4.exe" -b embeddedSrc.uvprojx -j0 -o build.log
|
||
```
|
||
|
||
构建成功后自动执行 `fromelf --bin --output=.\bin\embeddedSrc.bin .\Objects\embeddedSrc.axf`。
|
||
当前基线结果：**0 Error(s), 0 Warning(s)**，体积 `Code=15692 RO-data=944 RW-data=112 ZI-data=23496`。
|
||
|
||
烧录与运行：
|
||
|
||
1. Keil 打开 `MDK-ARM/embeddedSrc.uvprojx`，F7 编译
|
||
2. NS-LINK 接 SWD（PA4/PA5），F8 下载
|
||
3. 串口助手接 PB6(TX)/PB7(RX)，115200 8N1，复位后应看到启动 banner 与 `caiic->` CLI 提示符（输入 `help` 查看命令；LED 滚动日志默认关闭，用 `log on` 打开）
|
||
|
||
注意：本工程当前尚未在真实硬件上实测（见开发日志第 8、9、10 节）。
|
||
|
||
## 硬件引脚约束（重要）
|
||
|
||
- **SWD 调试管脚 SWCLK=PA4 / SWDIO=PA5：应用程序绝对禁止占用**，否则下载/调试失效。
|
||
- 板载 LED：LED1=PB0（跳线 J21）、LED2=PA6（跳线 J22），蓝色，4.7K 限流。
|
||
- USART1：TX=PB6 / RX=PB7，复用 AF4，经排针 J3 引出。
|
||
- PB8/PB9 默认接 32.768K 晶振；PB3 有下拉注意事项（用户手册 5.2.4）。
|
||
|
||
## 实时架构约定
|
||
|
||
- 使用 FreeRTOS V9.0.0 原生 API（`xTaskCreate` / `vTaskDelay` / `xQueue`），**不使用 cmsis_os 封装**。
|
||
- 任务模型：LedTask（LED1，500ms）、LedTask2（LED2，1000ms）为生产者，只向日志队列投递 `LogMsg_t`；PrintTask（优先级 3，栈 1024 字）消费队列并 printf。**主动日志打印由 `AppTasks_SetLogEnabled()` 控制，默认关闭**（CLI 命令 `log on|off` 切换）。新增需要打印的任务时沿用此生产者-消费者模式，不要在中断或多个任务里直接 `printf`。
|
||
- CLI 任务（优先级 3，栈 1024 字，见 `app_cli.c`）：从 USART1 RXDNE 中断的字节队列取输入，行结束符 `\r\n` / `\n\r` / `\r` / `\n` 均识别；解析-执行-应答一体化，应答走 `bsp_usart_write_dma`（DMA_CH1）。新命令在 `s_cmds[]` 命令表中注册。支持 Tab 命令补全、上下方向键历史回翻（8 条环形缓冲）、Ctrl+Z 关闭主动打印。
|
||
- 串口输出并发：PrintTask 的整条 printf 与 CLI 的整段应答分别持有 `bsp_usart_tx_lock()` 互斥锁，避免字节级交错；调度器启动前该锁为空操作。
|
||
- SysTick 由 FreeRTOS port 接管（`FreeRTOSConfig.h` 中 `xPortSysTickHandler → SysTick_Handler` 映射）：`main` 中不要手动 `SysTick_Config`，`n32wb03x_it.c` 中不要重复定义 SVC/PendSV/SysTick_Handler。
|
||
- USART1_IRQn 中断优先级为 3（最低），因 ISR 内调用 FreeRTOS FromISR API，必须 ≥ `configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY`（=3）。
|
||
- `configTOTAL_HEAP_SIZE = 20*1024`（4 个任务栈各 1024 字 = 16KB，另加队列/TCB/空闲任务开销），使用 heap_4。
|
||
|
||
## 代码风格
|
||
|
||
- 语言为 C（ARMCC，C 库 MicroLIB），文件头与函数头使用 Doxygen 风格注释（`@file` / `@brief`），注释用英文。
|
||
- 命名：BSP 层函数 `bsp_<module>_<action>`；应用层聚合函数 `AppTasks_*` / `AppCli_*`；引脚/时钟等硬件参数集中在头文件顶部宏定义。
|
||
- 使用 SDK 标准外设库 API（如 `RCC_EnableAPB2PeriphClk`、`GPIO_InitPeripheral`、`USART_Init`），不要直接操作寄存器。
|
||
- 新增 GPIO 前必须核对开发日志第 4 节引脚分配表，避开 PA4/PA5。
|
||
|
||
## 测试策略
|
||
|
||
无自动化测试框架；验证方式为：
|
||
|
||
1. Keil 命令行构建必须保持 0 Error / 0 Warning；
|
||
2. 烧录后通过串口输出与 LED 行为人工确认。
|
||
|
||
## 其他注意事项
|
||
|
||
- `nations-tec/` 下的 SDK、器件包与 PDF 为第三方只读资料，改动应只发生在 `mcm-ddc-04/`（或新增工程目录）内。
|
||
- BLE 协议栈（`middlewares/Nationstech/ble_library`）尚未接入；官方 BLE 例程基于裸机 `rwip_schedule` 调度，与 FreeRTOS 整合需要专门设计（见开发日志第 9 节）。
|