第三章 工程模板创建：从CubeMX到最小工程
说实话，很多新手工程师拿到一块开发板，第一件事就是打开Keil直接写main函数。嗯，这种做法在51单片机时代还行得通，但在STM32这种Cortex-M内核的芯片上，你很快就会发现——连个LED都点不亮。为什么？因为启动文件、链接脚本、时钟配置这些底层东西，缺一个都不行。
我个人习惯，每个新项目都从STM32CubeMX开始。不是因为它有多智能，而是它能帮我把那些重复性的、容易出错的初始化代码一次性生成好。今天我们就来走一遍这个流程，顺便把Keil工程的结构扒开看看。
本章核心目标：掌握使用STM32CubeMX生成初始化代码的方法，理解Keil工程中启动文件、链接脚本和HAL库的作用，最终能手动搭建一个最小工程模板。
3.1 使用STM32CubeMX生成初始化代码
STM32CubeMX是个图形化工具，说白了就是帮你配置芯片外设、生成初始化C代码。我刚开始用的时候也觉得它只是个代码生成器，后来才发现，它生成的时钟树配置和引脚分配，比自己手写靠谱得多。
3.1.1 新建工程与芯片选择
打开CubeMX，点击"New Project"。在芯片选择界面，你可以按型号搜索，也可以按内核、系列、封装来筛选。我建议直接输入芯片型号，比如STM32F103C8T6，这样最快。
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1 | 选择芯片型号 | 输入完整型号，确认封装和Flash大小 |
| 2 | 配置引脚功能 | 在Pinout视图中分配GPIO、外设引脚 |
| 3 | 配置时钟树 | 设置HSE、LSE、PLL倍频系数 |
| 4 | 配置外设参数 | 如USART波特率、SPI模式、定时器周期 |
| 5 | 生成代码 | 选择IDE类型（MDK-ARM），点击生成 |
小技巧：在Pinout视图中，直接点击芯片图上的引脚就能分配功能。我曾经因为没注意引脚复用冲突，调了整整一个下午的SPI通信，最后发现是PB3和PB4被JTAG占用了。所以，记得先检查System Core里的SYS Debug配置，把JTAG关掉或者改成SWD。
3.1.2 时钟树配置要点
时钟树是CubeMX里最核心的配置页面。你想想看，CPU跑多快、外设能不能正常工作，全看时钟配得对不对。我个人习惯先确定系统时钟目标频率，比如72MHz，然后从HSE（外部晶振）开始，经过PLL倍频，最后分频给AHB、APB1、APB2总线。
/* 典型的时钟配置流程 */
1. HSE = 8MHz（外部晶振）
2. PLL倍频 = x9 → PLL输出 = 72MHz
3. SYSCLK = PLL输出 = 72MHz
4. AHB分频 = /1 → HCLK = 72MHz
5. APB1分频 = /2 → PCLK1 = 36MHz（最大36MHz）
6. APB2分频 = /1 → PCLK2 = 72MHz注意：APB1总线的最大频率是36MHz（F1系列），如果你把APB1分频设成/1，PCLK1就会跑到72MHz，超出规格。芯片虽然不会立刻烧掉，但长期运行稳定性会出问题。我曾经在量产前才发现这个坑，还好改得及时。
3.2 Keil工程结构解析
CubeMX生成完代码后，你会得到一个Keil工程。打开它，你会看到一堆文件。很多初学者看到这个就懵了——这么多文件，到底哪些是必须的？
其实，一个标准的Keil工程，核心就三部分：启动文件、链接脚本、HAL库。我们一个一个来看。
3.2.1 启动文件（startup_xxx.s）
启动文件是汇编写的，芯片上电后第一条指令就从这里开始。它的工作很简单：设置堆栈指针、初始化中断向量表、调用SystemInit、最后跳转到main函数。
我记得第一次看启动文件时，满屏的汇编指令看得头皮发麻。后来发现，其实你不需要完全读懂每一行，只要知道它干了什么就行。
; 启动文件核心流程（简化版）
Reset_Handler PROC
EXPORT Reset_Handler
LDR R0, =__initial_sp ; 设置主堆栈指针
LDR R1, =SystemInit ; 调用系统初始化
BLX R1
LDR R1, =main ; 跳转到main函数
BLX R1
ENDP| 启动文件段 | 作用 | 是否可修改 |
|---|---|---|
| 堆栈初始化 | 设置主堆栈指针（MSP） | 一般不改 |
| 中断向量表 | 定义所有中断服务函数入口 | 可添加自定义中断 |
| 复位处理函数 | 上电后执行的第一个函数 | 不建议改 |
| 异常处理函数 | HardFault、NMI等默认处理 | 可重写 |
避坑指南：我曾经在移植一个FreeRTOS项目时，发现任务切换死活不成功。查了两天，最后发现是启动文件里的堆栈大小没改，默认的0x400（1KB）根本不够用。所以，如果你要用RTOS或者大数组，记得在启动文件里把Stack_Size和Heap_Size改大。
3.2.2 链接脚本（xxx.sct 或 .ld）
链接脚本告诉链接器：代码该放哪、数据该放哪、堆栈该放哪。Keil用的是分散加载文件（.sct），GCC用的是链接脚本（.ld）。
说白了，链接脚本就是一张内存地图。芯片的Flash从0x08000000开始，RAM从0x20000000开始。你的代码、常量、初始化的全局变量，都要被安排得明明白白。
; Keil分散加载文件示例（简化）
LR_IROM1 0x08000000 0x00010000 ; 加载区：Flash起始地址64KB
{
ER_IROM1 0x08000000 0x00010000 ; 执行区：代码在Flash中执行
{
*.o (RESET, +First) ; 启动文件放最前面
*(InRoot$$Sections)
.ANY (+RO) ; 所有只读数据
}
RW_IRAM1 0x20000000 0x00005000 ; 执行区：RAM起始地址20KB
{
.ANY (+RW +ZI) ; 读写数据和零初始化数据
}
}注意：链接脚本里的地址和大小必须和芯片规格书一致。如果你把Flash大小写大了，链接器不会报错，但生成的固件烧进去会直接跑飞。我见过一个同事把STM32F103C8（64KB Flash）的链接脚本写成了128KB，结果程序在烧录后莫名其妙死机，查了三天才发现是链接脚本的问题。
3.2.3 HAL库与LL库
HAL（硬件抽象层）库是ST官方提供的外设驱动库。它把寄存器操作封装成了函数，比如HAL_GPIO_WritePin、HAL_UART_Transmit。好处是移植性好，坏处是代码量大、效率低。
LL（低层）库则更接近寄存器操作，代码量小、执行快，但移植性差。我个人习惯：原型验证用HAL库，量产优化时换成LL库或者直接操作寄存器。
| 特性 | HAL库 | LL库 |
|---|---|---|
| 代码量 | 大（包含超时、错误处理） | 小（仅基本操作） |
| 执行效率 | 较低（函数调用层级多） | 高（接近寄存器操作） |
| 移植性 | 好（API统一） | 一般（依赖具体芯片） |
| 适用场景 | 快速原型、复杂外设 | 性能敏感、简单外设 |
3.3 手动创建最小工程模板
理解了工程结构之后，我们来手动创建一个最小工程。为什么要手动创建？因为CubeMX生成的工程里有很多你用不到的文件，手动创建能让你清楚知道每个文件的作用。
3.3.1 最小工程文件清单
一个能跑起来的最小工程，只需要以下文件：
- startup_stm32f103xb.s — 启动文件（从STM32Cube固件包复制）
- stm32f1xx_hal_conf.h — HAL库配置文件（裁剪掉不需要的外设）
- stm32f1xx_hal.c — HAL库核心文件（包含延时、错误处理）
- stm32f1xx_hal_gpio.c — GPIO驱动（点灯必备）
- stm32f1xx_hal_rcc.c — 时钟配置（系统时钟初始化）
- main.c — 主函数（你的业务逻辑）
- main.h — 主函数头文件（函数声明、宏定义）
关键点：这个最小工程只有7个文件，编译出来的固件大小不到10KB。相比CubeMX生成的工程（动辄几十个文件），它轻量得多，也更容易理解。
3.3.2 手动配置步骤
嗯，这里要注意。手动创建工程时，最容易出错的是时钟配置。我建议你先用CubeMX生成一次时钟配置代码，然后复制到自己的工程里。这样既保证了时钟树的正确性，又保持了工程的简洁。
// main.c 最小工程示例
#include "main.h"
int main(void)
{
HAL_Init(); // 初始化HAL库
SystemClock_Config(); // 配置系统时钟（从CubeMX复制）
__HAL_RCC_GPIOB_CLK_ENABLE(); // 使能GPIOB时钟
GPIO_InitTypeDef GPIO_InitStruct = {0};
GPIO_InitStruct.Pin = GPIO_PIN_0;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);
while (1)
{
HAL_GPIO_TogglePin(GPIOB, GPIO_PIN_0);
HAL_Delay(500); // 500ms闪烁
}
}个人经验：手动创建工程时，记得在Keil的Options for Target里配置好芯片型号和Flash下载算法。我刚开始时经常忘记选Flash算法，结果每次烧录都报错，还以为是硬件坏了。另外，C/C++选项卡里的Optimization建议先选Level 0，调试时不会出现变量被优化掉的情况。
3.4 本章知识体系
为了让你更直观地理解本章的知识结构，我画了一张流程图。它展示了从CubeMX配置到最小工程创建的完整路径。
从这张图你可以看到，整个流程是线性的：CubeMX配置 → 生成代码 → 理解工程结构 → 手动创建最小工程。每一步都建立在前一步的基础上。
总结：工程模板创建不是简单的"点几下鼠标就完事"。你需要理解启动文件怎么初始化芯片、链接脚本怎么安排内存、HAL库怎么封装寄存器。只有把这些底层逻辑搞清楚了，你才能在遇到问题时快速定位。手动创建一次最小工程，比用CubeMX生成一百次工程都管用。