单片机与物联网 / 系统课时
Cube 工程目录
Cube 工程目录
本课解决“CubeMX 生成的文件分别该改哪里、哪些文件不要随意动”的问题。读完后,你能按目录快速定位业务代码、外设驱动、启动入口和链接配置,并用用户代码区域避免重新生成工程时覆盖手写内容。
学习目标
- 说明
Core、Drivers、启动文件和链接脚本的职责 - 根据修改目标选择正确文件,而不是在生成代码中盲目搜索
- 正确使用
USER CODE区域保护自定义逻辑
从目录看工程分层
一个常见的 STM32CubeIDE 工程可以分为应用层、芯片驱动层和构建启动层。应用代码主要位于 Core,HAL 与 CMSIS 位于 Drivers,启动文件负责复位后的最早执行流程,链接脚本决定程序各段放入哪一片存储器。

典型工程的关键目录如下。不同芯片系列会使 STM32xxxx 和启动文件名发生变化,但各层职责基本一致。
Project/
├── Core/
│ ├── Inc/
│ ├── Src/
│ └── Startup/
├── Drivers/
│ ├── CMSIS/
│ └── STM32xxxx_HAL_Driver/
├── STM32xxxx_FLASH.ld
└── project.ioc.ioc 保存 CubeMX 图形化配置,是重新生成初始化代码的重要来源;不要只备份生成后的 .c/.h 文件而遗漏它。
Core:放应用入口和中断衔接
Core/Inc 保存应用头文件,Core/Src 保存应用源文件。main.c 通常包含 HAL 初始化、系统时钟配置、外设初始化和主循环;stm32xxxx_it.c 保存中断服务函数;stm32xxxx_hal_msp.c 负责 GPIO 复用、外设时钟和 NVIC 等底层资源初始化。
修改业务逻辑时,优先进入 main.c 或新增独立的 .c/.h 模块。不要把所有代码堆进主循环,也不要直接删除 CubeMX 生成的初始化函数,否则后续调整引脚或外设配置时难以重新生成。
Drivers:区分 CMSIS 与 HAL
Drivers/CMSIS 提供 Cortex-M 内核定义、芯片寄存器映射和启动所需类型;Drivers/STM32xxxx_HAL_Driver 提供 GPIO、UART、TIM、ADC 等外设的 HAL 驱动。普通应用通常调用 HAL API,而不是修改驱动库源码。
只有在确认库缺陷、需要移植补丁或进行极端性能优化时,才考虑改动 Drivers。更常见的做法是在应用层封装驱动接口,避免升级 Cube 固件包后手工合并大量修改。
启动文件与链接脚本
启动文件通常名为 startup_stm32xxxx.s。它定义中断向量表、初始栈顶和 Reset_Handler,并在复位后转入运行库初始化,最终调用 main()。中断函数名称如果与向量表不一致,处理器会进入默认处理函数。
链接脚本通常以 .ld 结尾。它声明 Flash、RAM 的起始地址和容量,并安排 .text、.data、.bss、堆和栈的位置。更换芯片容量、使用 Bootloader、把特定数据放入指定 RAM 区域时,才需要重点修改它。
启动文件决定“上电后先执行什么”,链接脚本决定“编译产物放到哪里”。两者都不是日常业务代码文件。
用户代码区域的使用原则
CubeMX 会在生成文件中保留 /* USER CODE BEGIN ... */ 与 /* USER CODE END ... */。需要写在生成文件里的自定义代码,应放进匹配的区域;区域外的内容可能在下一次生成时被覆盖。
/* USER CODE BEGIN 2 */
App_Init();
/* USER CODE END 2 */
while (1)
{
/* USER CODE BEGIN WHILE */
App_Run();
/* USER CODE END WHILE */
}这是片段示例,依赖工程中已声明并实现 App_Init() 与 App_Run()。
预期结果:修改 .ioc 并重新生成代码后,这两个调用仍保留在原用户代码区域,工程能够继续编译;若调用被删除,说明代码写在了生成器管理区域之外。
更稳妥的组织方式是只在生成文件中保留少量入口调用,把完整业务实现放入自己创建的模块。这样既能安全重新生成,也能让应用代码与芯片初始化代码分离。