4. 开发环境与工具链搭建

STM32N6 的多模型推理调度工程，本质上是一条从“模型文件”到“片上可执行固件”的完整链路。这条链路上有四个关键角色：STM32CubeIDE 负责工程组织、代码编译与调试；X-CUBE-AI（其命令行工具为 stm32ai）负责把训练好的神经网络模型转换为可在 STM32 上运行的 C 代码；STM32CubeProgrammer 负责把固件、外部 Flash 数据、模型权重烧录到芯片或外部存储；调试工具（ST-LINK、SWD、串口、ITM/SWO）负责观察推理时序、内存占用与调度行为。本节按“装什么、怎么装、装完怎么验证”的顺序展开，并给出可直接复用的环境检查清单。

一、工具链的职责边界与版本关系

很多初学者会把 STM32Cube.AI 和 X-CUBE-AI 混为一谈。严格来说，STM32Cube.AI 是 ST 面向嵌入式 AI 的整体技术品牌与生态名称，而 X-CUBE-AI 是它在 STM32Cube 扩展包中的具体实现，包含图形化插件和 stm32ai 命令行工具。在 STM32CubeIDE 中安装 X-CUBE-AI 扩展包后，工程右键会出现 “STM32Cube.AI” 菜单，这就是图形化入口；而 CI/CD 或批量转换时，则直接调用命令行。

版本匹配是第一个坑。X-CUBE-AI 的版本必须与 STM32CubeIDE、STM32CubeMX 的版本兼容，同时要支持 STM32N6 系列。截至当前，建议使用 X-CUBE-AI 9.x 及以上版本，并在安装时确认其支持列表中出现 STM32N6。若版本过旧，模型转换阶段会直接报 “unsupported device” 或找不到 N6 的硬件加速算子。

二、STM32CubeIDE 安装与工程初始化

从 ST 官网下载 STM32CubeIDE 安装包时，注意选择与操作系统匹配的版本。安装过程中会提示选择 ST-LINK 驱动和 J-Link 驱动，建议全部勾选。安装完成后首次启动，需要指定一个 workspace 目录，路径中不要包含中文和空格，否则后续 stm32ai 调用可能因路径解析失败而报错。

新建工程时，选择 File → New → STM32 Project，在芯片选择器中输入 STM32N657（以 N657X0 为例），选中对应封装后点击 Next。工程向导中要确认：Targeted Language 选 C，Targeted Binary Type 选 Executable，Project Type 选 STM32Cube。生成工程后，先不要急着写代码，而是打开 .ioc 文件，在 Project Manager → Code Generator 中勾选 “Generate peripheral initialization as a pair of .c/.h files”，这样后续添加 AI 代码时不会与自动生成代码冲突。

三、X-CUBE-AI 的两种安装方式

方式一：在 CubeIDE 中通过 Help → Manage Embedded Software Packages，找到 X-CUBE-AI 并勾选安装。安装完成后重启 IDE，工程右键菜单中会出现 “STM32Cube.AI” 子菜单。方式二：单独下载 X-CUBE-AI 压缩包，解压后把 Utilities 和 Middlewares 目录复制到工程对应位置，并在 Project Properties → C/C++ Build → Settings → Include paths 中添加头文件路径。方式二更适合需要固定版本、做版本管理的团队。

安装完成后，在终端执行以下命令验证命令行工具是否可用：

# 检查 stm32ai 版本与支持的设备
stm32ai --version
stm32ai --device-list | findstr STM32N6

# 典型模型转换命令（以 ONNX 为例）
stm32ai generate -m model.onnx --name mnist \
  --target stm32n6 --optimization balanced \
  --output ./ai_output --workspace ./ai_ws

执行后会在 ai_output 下生成 mnist.c、mnist.h 以及 mnist_report.txt。报告里会列出每一层的算子映射、权重占用、激活内存峰值。若出现 “unsupported layer”，说明该算子需要回退到 CPU 执行，此时要评估是否影响实时性。

四、STM32CubeProgrammer 与烧录配置

STM32CubeProgrammer 支持 SWD、UART、USB DFU 三种连接方式。对于 STM32N6 开发板，推荐使用 SWD 模式，连接 ST-LINK 后点击 “Connect”，若识别到芯片型号和 Flash 大小，说明连接正常。烧录外部 Flash 时，需要先加载对应的 .stldr 外部加载器文件，路径通常在 CubeProgrammer 安装目录的 ExternalLoader 下。选择 .bin 文件后，填写正确的起始地址（例如外部 XSPI Flash 映射到 0x70000000），再点击 “Download”。

五、调试工具配置与观察点

调试配置在 Run → Debug Configurations 中完成。新建 STM32 Cortex-M C/C++ Application 配置，选择对应的 .elf 文件，在 Debugger 选项卡中确认接口为 SWD，时钟频率可先设为 4 MHz，稳定后再提高。若需要观察推理耗时，建议开启 SWO 输出，在 Trace 选项卡中使能 ITM 端口 0，并在代码中通过 ITM_SendChar() 打印时间戳。

实际调试时，值得关注的观察点包括：NPU 中断是否按预期触发、DMA 搬运权重的完成标志、多模型切换时的上下文保存与恢复、以及每个模型推理前后的时间戳差值。可以用一个简单的结构体记录调度信息：

typedef struct {
    uint32_t model_id;
    uint32_t start_tick;
    uint32_t end_tick;
    uint32_t npu_cycles;
} infer_trace_t;

infer_trace_t trace[8];
trace[0].start_tick = DWT->CYCCNT;
// ... 调用模型推理 ...
trace[0].end_tick = DWT->CYCCNT;
trace[0].npu_cycles = trace[0].end_tick - trace[0].start_tick;

把 trace 数组通过 SWO 或串口输出，就能得到每个模型的真实执行周期，为后续调度策略提供依据。

六、环境检查清单

完成以上配置后，建议先用一个最小工程做“空跑验证”：不加载任何模型，只让主循环翻转一个 GPIO，用示波器确认程序正常运行；再逐步加入单个模型推理，观察内存占用与耗时。这样可以把工具链问题与模型问题分开定位，避免在调试阶段同时面对多个变量。