单片机与物联网 / 系统课时
编译烧录并单步调试最小工程
编译烧录并单步调试最小工程
让一块 Cortex-M 开发板运行自己编写的裸机程序,并通过 ST-LINK 在 main 函数入口停机,是验证工具链与调试链路的直接方法。本课使用 CMSIS 设备头文件操作 GPIO 寄存器,完成编译、Flash 下载、断点调试和板载 LED 验证。
学习目标
- 使用 CMSIS 设备头文件编写不依赖 HAL 函数的最小应用程序。
- 将工程编译为 ELF 固件,通过 ST-LINK 下载到片内 Flash。
- 在
main入口停机,使用单步调试与寄存器观察确认程序执行正确。
准备开发板与最小工程
以 NUCLEO-F401RE 开发板、STM32F401RE 微控制器及 STM32CubeIDE 1.16.x 为例。该芯片采用 Arm Cortex-M4 内核,开发板自带 ST-LINK 调试器,绿色用户 LED LD2 连接到 PA5 引脚。其他 STM32 型号的设备头文件、寄存器和 LED 引脚可能不同,不能直接照搬。
准备 STM32CubeIDE、可传输数据的 USB 线和开发板。通过开发板的 ST-LINK USB 接口连接电脑,确认系统识别出调试器。首次使用时,根据 STM32CubeIDE 提示安装相应驱动或更新 ST-LINK 固件。
创建工程的操作顺序如下:
- 打开
File > New > STM32 Project,进入新建工程向导。 - 在
Board Selector中搜索NUCLEO-F401RE,选择对应开发板。 - 将工程命名为
CortexM_Minimal,使用 C 语言创建项目。 - 如出现外设初始化询问,选择使用默认初始化配置。
- 生成工程后确认存在
Core/Src/main.c、Core/Src/system_stm32f4xx.c、启动汇编文件以及以.ld结尾的链接脚本。
不同 CubeIDE 版本的向导名称和布局可能略有变化。这里借助生成器提供启动代码、链接脚本和 CMSIS 依赖,应用业务逻辑直接操作芯片寄存器,不使用 HAL GPIO 函数。

启动文件负责复位后的执行入口和异常向量表,链接脚本规定 Flash、RAM 的地址及程序段布局,system_stm32f4xx.c 提供系统初始化相关实现。CMSIS 设备头文件则提供 RCC、GPIOA 等寄存器定义。如果只有一个 main.c 而缺少启动文件和链接脚本,通常不能直接构建可启动的裸机固件。
编写直接操作寄存器的程序
打开 Core/Src/main.c。为了保留 CubeIDE 生成工程的其他文件,只替换该文件的应用代码,不删除启动汇编、系统初始化源文件和中断处理文件。
以下程序使用 stm32f4xx.h 中定义的寄存器结构。运行时首先开启 GPIOA 时钟,再将 PA5 配置为推挽输出,最后反复切换 LED 电平。
#include "stm32f4xx.h"
static void delay_cycles(void)
{
// volatile 防止空循环被编译器直接消除
for (volatile uint32_t i = 0; i < 500000U; ++i) {
__NOP();
}
}
int main(void)
{
// 打开 GPIOA 所在 AHB1 总线的外设时钟
RCC->AHB1ENR |= RCC_AHB1ENR_GPIOAEN;
(void)RCC->AHB1ENR;
// PA5 的 MODER[11:10] = 01,配置通用输出
GPIOA->MODER &= ~(3U << 10);
GPIOA->MODER |= (1U << 10);
GPIOA->OTYPER &= ~(1U << 5);
while (1) {
GPIOA->ODR ^= (1U << 5);
delay_cycles();
}
}这段代码直接通过 CMSIS 定义的外设结构体访问内存映射寄存器。RCC_AHB1ENR_GPIOAEN 是 STM32F4 设备头文件中的 GPIOA 时钟使能位,GPIOA->MODER 用于设置引脚模式,GPIOA->ODR 用于写入输出电平。__NOP() 是 CMSIS 提供的处理器空操作指令接口。
delay_cycles() 只是演示用的忙等待,不是精确计时器。循环耗时取决于时钟频率、编译优化级别及执行环境,不应将其视为固定毫秒延时。
编译并检查 ELF 固件
先将构建配置切换为 Debug。在 STM32CubeIDE 中选择 Project > Build Configurations > Set Active > Debug,然后执行 Project > Build Project,也可以单击工具栏锤子图标。
首次构建时,CubeIDE 调用 GNU Arm Embedded 工具链,对 C 源文件和启动汇编进行编译,再由链接器根据 .ld 脚本生成 ELF 文件。正常情况下,构建目录会出现 CortexM_Minimal.elf,通常位于工程的 Debug 目录中。
预期结果:构建控制台显示类似以下内容,具体构建日志、工具名称和文件大小随安装版本及生成配置变化。
Build Finished. 0 errors, 0 warnings.ELF 文件不仅包含机器指令,还可以包含函数符号、变量信息和源代码调试信息,因此后续可以直接在 main 处停机,而不必手动查找机器指令地址。
如果希望独立检查生成文件,可在配置好 Arm GNU 工具链环境变量后,从工程根目录执行以下命令。这里假设目标 ELF 文件已经构建成功。
arm-none-eabi-size Debug/CortexM_Minimal.elf预期输出:显示 text、data、bss 和 dec 等列,具体数值由实际构建结果决定。
text data bss dec hex filename
<TEXT> <DATA> <BSS> <DEC> <HEX> Debug/CortexM_Minimal.elf以上尖括号字段表示实际构建产生的数值,并非命令原样输出。text 主要反映代码及只读数据占用,data 表示已初始化可写数据,bss 表示未初始化或零初始化数据;不能简单把三者相加当作 Flash 的精确占用量。
如果出现 stm32f4xx.h: No such file or directory,应检查 CMSIS Device 组件是否已生成,并核对工程的 Properties > C/C++ Build > Settings 中编译器头文件搜索路径。若出现 undefined reference to 错误,则检查缺失符号对应的源文件是否参与构建,而不要通过随意删除函数调用掩盖链接问题。
使用 ST-LINK 下载并停在 main
单击工具栏 Debug 图标,或选择 Run > Debug Configurations,找到工程对应的 STM32 C/C++ Application 调试配置。
首次调试时重点检查以下配置:
| 配置位置 | 推荐设置 | 用途 |
|---|---|---|
| Debugger | ST-LINK 调试接口 | 连接板载调试器 |
| Debugger / Interface | SWD | 使用芯片的串行调试端口 |
| Startup / Load Image and Symbols | Download 与 Load symbols 均启用 | 下载 ELF 并载入符号 |
| Startup / Runtime Options | Set breakpoint at main 启用 | 启动后在 main 入口停机 |
| 构建配置 | Debug | 保留调试符号,便于单步观察 |
设置完成后启动 Debug。IDE 通常先构建工程,然后通过 ST-LINK 下载固件至目标 Flash,复位目标并运行至 main 的临时断点。首次进入 Debug 透视图时选择切换即可。

预期结果:Debug 视图显示主线程暂停,编辑器高亮 main 函数内第一条可调试语句,通常是 RCC->AHB1ENR 时钟使能操作。Debug 构建中编译器仍可能调整指令排列,因此实际停靠行由调试信息决定。
单步观察寄存器与程序计数器
成功停在 main 后,打开 Window > Show View > Registers 查看处理器寄存器,也可以使用 Expressions 观察寄存器表达式。
首先确认 PC(Program Counter)指向有效的代码地址。STM32F401RE 的主 Flash 从 0x08000000 开始,正常从 Flash 启动时,停在 main 附近的 PC 通常落在 Flash 地址范围内,但具体地址由链接结果决定。
接下来使用调试快捷键:
| 操作 | 常用快捷键 | 作用 |
|---|---|---|
| Step Into | F5 | 进入被调用函数 |
| Step Over | F6 | 执行当前源代码行,不进入函数 |
| Step Return | F7 | 运行到当前函数返回 |
| Resume | F8 | 继续运行到下一断点 |
| Suspend | 调试工具栏暂停按钮 | 暂停正在运行的 CPU |
按 F6 逐步执行 GPIO 初始化语句,并在 Expressions 视图添加 RCC->AHB1ENR、GPIOA->MODER 和 GPIOA->ODR。若表达式求值不可用,可通过外设寄存器视图查看同名寄存器。
在执行完初始化代码之后,预期满足以下位级条件:
(RCC->AHB1ENR & 0x1)等于0x1,说明 GPIOA 外设时钟已启用。((GPIOA->MODER >> 10) & 0x3)等于0x1,说明 PA5 被配置为通用输出。((GPIOA->OTYPER >> 5) & 0x1)等于0x0,说明 PA5 为推挽输出。- 每执行一次
GPIOA->ODR异或语句,ODR 的第 5 位翻转一次。
继续按 F8 恢复运行,开发板 LD2 应周期性闪烁。若要观察每次翻转,可在 GPIOA->ODR ^= (1U << 5); 这一行设置断点,再执行 Resume。命中断点时尚未执行当前语句,按 F6 后再观察 ODR 的变化。
处理下载失败与断点异常
如果编译通过但无法连接 ST-LINK,应按连接层、下载层和程序执行层分别定位,而不是立刻修改 GPIO 代码。
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| ST-LINK not detected | USB 数据线、驱动、接口 | 换数据线,确认连接板载 ST-LINK 端口 |
| No target found | 供电、SWD 连接、目标芯片 | 检查板卡供电和调试接口,必要时降低 SWD 频率 |
| 下载失败 | Flash 保护、目标状态 | 查看调试日志和芯片保护状态,避免盲目全片擦除 |
| 不能停在 main | 启动断点、ELF 符号、调试配置 | 确认加载符号及 main 断点已启用 |
| PC 位于 HardFault_Handler | 异常调用栈、启动配置 | 检查链接脚本、向量表和故障寄存器 |
| LED 不亮 | GPIOA 时钟、PA5 模式、ODR | 单步检查相应位是否符合预期 |
如果芯片中的旧程序不断重配置 SWD 引脚或立即进入低功耗状态,可以在调试器连接设置中尝试 Connect under reset。该方法依赖目标板复位线路正确连接,且不是所有无法连接的情况都能解决。
当 CPU 进入 HardFault 时,不要将问题直接归因于烧录失败。先查看 PC、LR 和堆栈指针,再检查 SCB 的故障状态寄存器;对于 Cortex-M4,SCB->CFSR 和 SCB->HFSR 可提供进一步线索。
完成验收时,应同时满足四个条件:工程零错误构建、ELF 成功下载、CPU 在 main 附近停机、GPIOA 寄存器变化与板载 LED 行为一致。只看到 LED 闪烁,尚不能证明断点、调试符号和单步链路均已正常工作。