从零搭建STM32 IAR工程：详解配置、链接脚本与寄存器编程

1. 从“拿来主义”到“自力更生”：为什么需要创建自己的STM32 IAR工程

很多朋友在刚开始玩STM32的时候，都是从官方或者开发板厂商提供的例程开始的。就像我最初接触万利（Manley）的STM32板子时，也是直接打开一个现成的流水灯或者串口例程，然后修修改改，把GPIO口从PA0改成PC4，就算完成了自己的第一个程序。这种做法上手快，能快速建立信心，看到LED闪烁的那一刻，成就感满满。但是，久而久之，问题就来了。当你需要做一个稍微复杂点的项目，比如同时用到定时器、ADC、DMA和串口时，你会发现，从不同例程里东拼西凑代码，就像用不同规格的乐高积木搭房子，接口对不上，编译报错满天飞，底层初始化冲突，程序跑起来各种灵异现象。更头疼的是，你根本不知道那些例程里的工程选项（Options）为什么那么设置，链接脚本（Linker Script）里那些神秘的数字代表什么，一旦换一块不同Flash或RAM大小的芯片，或者想优化代码尺寸和速度，就完全无从下手。

所以，从“改例程”到“建工程”，是嵌入式开发从入门到进阶的必经之路。自己创建一个干净的、完全受控的工程，意味着你真正理解了从源代码到二进制文件，再到芯片上运行的全过程。今天，我就以在IAR Embedded Workbench for ARM环境下，为万利STM32F103开发板创建一个基础工程为例，手把手带你走一遍这个流程。我们会从打开一个空白工程开始，一步步配置编译器、链接器、调试器，最后写一个最“裸”的、不依赖任何库的流水灯程序，并生成HEX文件。这个过程会涉及很多底层细节，我会尽量把每个设置背后的“为什么”讲清楚。当你跟着走完这一趟，以后再面对任何ARM Cortex-M芯片的工程创建，你都会心中有底。

2. 工程骨架搭建：创建空白工程与核心选项初探

2.1 启动IAR与创建新工程

首先，确保你已经安装了IAR Embedded Workbench for ARM（以下简称IAR EWARM）。不同版本界面略有差异，但核心逻辑相通。我使用的是比较经典的一个版本，新版本可能菜单位置有变化，但功能关键词是一样的。

启动IAR后，你可能会看到一个“Embedded Workbench Startup”的对话框。这是一个快速入口，直接点击“Create new project in current workspace”按钮是最快的。如果你觉得这个对话框碍事，在“Tools -> Options...”里可以设置启动时不显示它。如果没看到这个对话框，也别慌，我们走标准菜单路径：点击顶部菜单栏的“Project”，在下拉菜单中选择“Create New Project...”。

这时会弹出一个“Create New Project”的窗口。这里有两个关键选择：

1. Tool chain： 必须选择“ARM”。这告诉IAR，我们接下来要编译的是针对ARM架构处理器的代码。
2. Project templates： 模板选择。这里提供了像“Empty project”（空工程）、“asm”（汇编工程）、“C++”等选项。强烈建议选择“Empty project”。从零开始虽然第一步是空的，但避免了模板自带的一些你可能暂时不理解的配置或文件，让我们对工程的每一部分都拥有完全的控制权。点击“OK”。

接下来会弹出一个保存对话框。给你的工程起个名字，比如“STM32F103_Blinky”。选择一个合适的目录来存放它，比如“D:\MyProjects\”。这里有一个非常重要的习惯：为每一个工程建立一个独立的文件夹。这样，所有工程相关的源文件、头文件、链接脚本、输出文件都会规整地放在一起，便于管理和备份。点击“保存”后，一个最基础的、空空如也的工程框架就在Workspace（工作空间）窗口里创建好了。

2.2 工程选项（Options）配置详解

现在我们的工程只是个空壳，需要告诉IAR我们的目标芯片是谁、如何编译、如何链接、如何调试。这一切都在“Options for node `STM32F103_Blinky`”对话框中完成。在Workspace窗口中，右键点击你的工程名（STM32F103_Blinky），选择“Options...”，配置之旅正式开始。

2.2.1 General Options -> Target：指明目标芯片

这是最基础也是最重要的一步，它决定了编译器生成指令的基础。

• Device： 点击“Device”旁边的按钮，会弹出芯片选择器。在厂商列表中找到“ST”，展开后选择“STM32F10x”系列。这里选择系列即可，IAR会自动根据后续的链接脚本配置来适配具体型号（如STM32F103C8T6）。如果你的芯片是STM32F1系列的其他子类，这里也通常选STM32F10x。
• Endian mode： 选择“Little”。ARM Cortex-M内核默认采用小端模式（Little Endian），即数据的低字节存放在低地址。这是绝大多数ARM嵌入式环境的标配，除非有特殊需求，否则不要动。
• Stack align： 设置为“4”。这指的是栈指针（SP）的对齐方式。Cortex-M系列内核要求栈指针必须4字节对齐，否则在访问栈内数据或进行异常处理时会导致硬件错误（HardFault）。设置为4确保了编译器生成的代码和运行时库不会破坏这一对齐规则。

注意： 这里的“Stack align”设置与后面链接脚本里定义的堆栈大小（-D_CSTACK_SIZE）是两回事。前者是编译器的行为约束，后者是给链接器分配的具体内存空间大小。

2.2.2 General Options -> Output：控制输出文件格式

这个标签页保持默认即可。“Output file”默认是“Debug\Exe$(ProjectName).out”，这是IAR自己的调试格式文件，包含了丰富的调试信息（如符号表），用于在C-SPY调试器中加载和调试。我们最终要的HEX或BIN文件，是通过链接器额外生成的。

2.2.3 General Options -> Library Configuration：运行时库的选择

• Library： 选择“Full”。这表示使用标准的完整C/C++运行时库（DLIB）。它提供了完整的标准库函数（如printf,malloc,memcpy等）和底层系统调用（如__write,__read用于半主机Semihosting，或重定向到串口）。对于资源极其紧张的项目，可以选择“Normal”或“Custom”来裁剪，但作为起步工程，“Full”是最省心、功能最全的选择，能避免很多因库函数缺失导致的链接错误。

2.2.4 C/C++ Compiler -> Language：C语言规范设置

• Language： 选择“C”。我们的主程序是C语言文件。
• Require prototypes：务必勾选。这个选项要求函数在使用前必须有声明或定义。这是一个非常好的编程习惯强制检查，能避免很多因函数调用参数不匹配导致的隐蔽错误。勾选后，如果你调用了一个还未声明或定义的函数，编译器会报错。
• Language conformance： 选择“Relaxed ISO/ANSI”。这个模式比严格的“ISO”模式更宽松，允许一些编译器的扩展语法和不太符合标准但常见的写法，对初学者更友好。例如，它允许在代码中间声明变量（C99特性），而严格的ISO C89要求变量声明必须在函数开头。

3. 链接与调试配置：打通从代码到芯片的最后一公里

3.1 Linker配置：内存布局与输出控制

链接器（Linker）负责将编译器生成的多个目标文件（.o）和库文件合并成一个可执行文件，并按照指定规则分配到芯片的Flash和RAM地址上。

• Output标签页： 勾选“Allow C-SPY-specific extra output file”。这个选项允许生成额外的输出文件，通常用于调试。保持勾选。
• Extra Output标签页： 勾选“Generate extra output file”。这里可以指定生成其他格式的文件，比如我们后面要用的Intel HEX文件。但先不急，我们稍后在链接脚本里统一配置。
• Config标签页： 这是链接器配置的核心。
  1. 勾选“Override default”，覆盖默认的链接器配置文件。
  2. 点击浏览按钮，定位到IAR安装目录下的默认链接脚本。通常路径类似于：C:\Program Files (x86)\IAR Systems\Embedded Workbench x.x\arm\config\lnkarm.xcl。这个xcl文件就是IAR的链接器命令文件，它用一套特定的指令定义了内存区域、段分配等。
  3. 关键操作：不要直接使用这个系统路径下的文件。而是将它复制一份，粘贴到你当前工程的根目录下（即和STM32F103_Blinky.ewp工程文件在同一目录）。然后，在“Override default”下方的输入框里，将路径改为$PROJ_DIR$\lnkarm.xcl。$PROJ_DIR$是IAR预定义的一个宏，代表当前工程文件所在的目录。这样做的好处是，链接脚本成了工程的一部分，你可以随意修改它而不用担心影响其他工程，也便于工程迁移和版本管理。

3.2 修改链接脚本以适配具体芯片

现在，用记事本或任何文本编辑器（推荐Notepad++、VS Code等）打开你刚复制到工程目录下的lnkarm.xcl文件。我们需要根据万利板子上STM32F103芯片的具体型号来修改内存地址和大小。假设板载芯片是STM32F103C8T6，它有64KB Flash（0x10000字节）和20KB RAM（0x5000字节）。

找到文件中定义内存区域的部分（通常通过-D选项定义符号，-Z选项分配段）。我们需要修改以下几处：

// 原内容可能是（注释掉的是默认值或示例）： //-DROMSTART=08000 //-DROMEND=FFFFF //-DRAMSTART=100000 //-DRAMEND=7FFFFF // 修改为STM32F103C8T6的配置： -DROMSTART=0x8000000 // Flash起始地址，对于STM32F1，固定为0x08000000 -DROMEND=0x800FFFF // Flash结束地址 = 起始地址 + 大小 - 1 = 0x08000000 + 0x10000 - 1 = 0x0800FFFF -DRAMSTART=0x20000000 // RAM起始地址，Cortex-M3内核固定为0x20000000 -DRAMEND=0x20004FFF // RAM结束地址 = 0x20000000 + 0x5000 - 1 = 0x20004FFF // 修改中断向量表的存放位置，必须放在Flash起始处 //-Z(CODE)INTVEC=00-3F -Z(CODE)INTVEC=ROMSTART-ROMEND // 将INTVEC段分配到整个ROM区域，链接器会将其放在起始位置 // 调整栈和堆的大小。对于简单应用，默认的栈（2KB）可能够用，堆（8KB）可能太大。 //-D_CSTACK_SIZE=2000 //-D_HEAP_SIZE=8000 -D_CSTACK_SIZE=800 // 栈大小设置为2KB (0x800)。对于没有复杂函数调用和局部变量的简单程序，可以更小。 -D_HEAP_SIZE=400 // 堆大小设置为1KB (0x400)。如果不使用malloc等动态内存分配，甚至可以设为0。

实操心得：-Z(CODE)INTVEC=ROMSTART-ROMEND这一行看起来是把整个中断向量表分配到了整个Flash区域，这合理吗？实际上，INTVEC是一个特殊的段名，链接器识别到它后，会优先将其放置在所分配区域的最起始地址。所以这样写是没问题的，是一种常见的技巧。更精确的写法可以是-Z(CODE)INTVEC=ROMSTART-ROMSTART+0x3F，但前者更简洁通用。

最后，为了生成HEX文件，我们需要在lnkarm.xcl文件的末尾（在所有其他命令之后）添加一行：

-Ointel-extended,(CODE)=.hex

这行命令告诉链接器，在链接完成后，额外生成一个Intel HEX格式的文件，输出内容为CODE段（即程序代码和常量数据），文件后缀为.hex。

3.3 Debugger配置：连接硬件调试器

要让程序能下载到板子上并调试，需要配置调试器。

• Setup标签页：
  • Driver： 选择“Third-Party Driver”。因为万利板子通常配套的是ST-Link调试器（也可能是J-Link等其他调试器），我们需要指定其专用的驱动DLL文件。
• Download标签页： 勾选“Use flash loader”。这样在下载程序时，调试器会使用Flash编程算法来擦写芯片内部的Flash，而不是直接写RAM。这是必须的。
• Third-Party Driver标签页：
  • IAR debugger driver： 在这里输入你的ST-Link调试器驱动DLL文件的完整路径。这个驱动文件通常由ST官方提供的STM32 ST-LINK Utility软件或独立驱动包安装。常见路径如C:\Program Files (x86)\STMicroelectronics\STM32 ST-LINK Utility\ST-Link Driver\ST-LinkIII-KEIL_SWO.dll，或者如果你用的是万利提供的驱动，可能在C:\Manley\drivers\STLink\目录下，文件名为STM32Driver.dll。请根据你电脑上的实际安装路径填写。如果找不到，可以去ST官网下载最新的ST-LINK驱动。

注意事项： 如果你使用的是J-Link，Driver则应该选择“J-Link/J-Trace”，并在对应的J-Link配置页中指定芯片型号。调试器的选择和驱动配置是下载和调试成功的关键，配置错误会导致IAR无法识别到硬件。

4. 编写“裸奔”的流水灯程序：直接操作寄存器

工程配置完毕，现在我们来写代码。我们将不依赖ST的标准外设库（StdPeriph Lib）或HAL库，直接通过内存地址访问寄存器来控制LED。这种方式虽然原始，但对于理解STM32的底层硬件工作原理至关重要。

4.1 硬件连接与寄存器分析

查看万利STM32板的原理图，假设4个LED（LED2, LED3, LED4, LED5）分别连接在GPIOC的Pin4、Pin5、Pin6、Pin7上，并且是共阳极接法（即IO输出高电平时LED点亮）。

我们需要控制三个关键部分：

1. 开启GPIOC的时钟： STM32的任何外设（包括GPIO）在使用前，必须先使能其时钟。相关寄存器是RCC_APB2ENR（APB2外设时钟使能寄存器），它的Bit 4（IOPCEN）控制GPIOC的时钟。地址：0x40021018。
2. 配置GPIOC的Pin4-7为输出模式： 每个GPIO端口有配置寄存器GPIOx_CRL（用于Pin0-7）和GPIOx_CRH（用于Pin8-15）。我们要配置Pin4-7，所以用GPIOC_CRL。地址：0x40011000。每个引脚占用4个bit（CNF[1:0]和MODE[1:0]）。我们要设置为推挽输出、最大速度50MHz，对应的配置是CNF=00, MODE=11。
3. 控制GPIOC的Pin4-7输出高低电平： 有两种方法：
   • 使用GPIOx_BSRR（端口位设置/清除寄存器），写1到位0-15置位对应引脚（输出高），写1到位16-31清除对应引脚（输出低）。地址：0x40011010。
   • 使用GPIOx_BSRR的低16位置位，配合GPIOx_BRR（端口位清除寄存器）来清零。地址：0x40011014。我们采用后者，逻辑更清晰。

4.2 代码实现与解析

在IAR的Workspace中，右键工程，选择“Add -> Add Files...”，创建一个新的C文件，命名为main.c。将以下代码复制进去：

// 定义寄存器地址。使用volatile防止编译器优化对这些地址的访问。 #define RCC_APB2ENR (*((volatile unsigned int *)(0x40021018))) // APB2外设时钟使能寄存器 #define GPIOC_CRL (*((volatile unsigned int *)(0x40011000))) // 端口C配置寄存器低8位 #define GPIOC_BSRR (*((volatile unsigned int *)(0x40011010))) // 端口C位设置/清除寄存器 #define GPIOC_BRR (*((volatile unsigned int *)(0x40011014))) // 端口C位清除寄存器 // 简单的软件延时函数，用于演示。实际项目中应使用定时器。 void Delay(void) { volatile unsigned int i; // volatile防止循环被优化掉 for(i = 0; i < 0x3FFFF; i++); // 循环次数可根据主频调整 } int main(void) { // 1. 使能GPIOC的时钟 // RCC_APB2ENR的Bit4是IOPCEN，将其置1 RCC_APB2ENR |= (1 << 4); // 2. 配置PC4, PC5, PC6, PC7为推挽输出，最大速度50MHz // 先清除PC4-PC7对应的配置位（CRL寄存器的高16位，每4位控制一个Pin） // 即清除Pin4(bit19:16), Pin5(bit23:20), Pin6(bit27:24), Pin7(bit31:28) GPIOC_CRL &= 0x0000FFFF; // 高16位清0，低16位（PC0-PC3）保持不变 // 然后设置这些位为：CNF=00 (推挽输出), MODE=11 (50MHz) // 0x3 = 0b0011，左移到对应位置即可。 // Pin4: 0x3 << 16 = 0x00030000 // Pin5: 0x3 << 20 = 0x00300000 // Pin6: 0x3 << 24 = 0x03000000 // Pin7: 0x3 << 28 = 0x30000000 // 将它们或运算在一起，就是0x33330000 GPIOC_CRL |= 0x33330000; // 3. 主循环，实现流水灯效果 while(1) { // LED5 (PC4) 灭， LED2 (PC7) 亮 GPIOC_BRR = (1 << 4); // 清除PC4，输出低电平，LED5灭 GPIOC_BSRR = (1 << 7); // 置位PC7，输出高电平，LED2亮 Delay(); // LED2 (PC7) 灭， LED3 (PC6) 亮 GPIOC_BRR = (1 << 7); GPIOC_BSRR = (1 << 6); Delay(); // LED3 (PC6) 灭， LED4 (PC5) 亮 GPIOC_BRR = (1 << 6); GPIOC_BSRR = (1 << 5); Delay(); // LED4 (PC5) 灭， LED5 (PC4) 亮 GPIOC_BRR = (1 << 5); GPIOC_BSRR = (1 << 4); Delay(); } // 理论上main函数不应返回，这里用死循环保证。 }

4.3 编译、下载与调试

1. 编译： 点击工具栏上的“Make”按钮（或按F7）。如果一切配置正确，你会在下方的“Build”窗口中看到编译和链接成功的提示，显示“Total number of errors: 0”。

2. 下载与调试：

   • 确保你的万利STM32板通过ST-Link与电脑连接好，并供电。
   • 点击工具栏上的“Download and Debug”按钮（或按Ctrl+D）。IAR会先编译工程（如果自上次编译后有改动），然后通过C-SPY调试器将程序下载到芯片Flash中。
   • 下载成功后，程序会暂停在main函数的入口处。你可以按F5（Go）全速运行，或者按F10/F11单步执行。
   • 观察板子上的LED，应该能看到流水灯效果。

3. 查找HEX文件： 打开你的工程目录，进入Debug\Exe子文件夹（如果你在编译时选择了“Release”配置，则进入Release\Exe），你应该能看到一个STM32F103_Blinky.hex文件。这个文件就可以通过STM32的ISP工具（如FlyMCU）通过串口下载到芯片中，脱离调试器独立运行。

5. 进阶思考与常见问题排查

5.1 从“裸寄存器”到“标准库”

直接操作寄存器虽然直观，但代码可读性差，且容易出错（比如算错位偏移）。在实际项目中，我们强烈建议使用ST提供的标准外设库（StdPeriph Library）或更现代的HAL/LL库。这些库用结构体和函数封装了寄存器操作，例如：

#include "stm32f10x.h" #include "stm32f10x_gpio.h" #include "stm32f10x_rcc.h" void LED_Init(void) { GPIO_InitTypeDef GPIO_InitStructure; RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOC, ENABLE); GPIO_InitStructure.GPIO_Pin = GPIO_Pin_4 | GPIO_Pin_5 | GPIO_Pin_6 | GPIO_Pin_7; GPIO_InitStructure.GPIO_Mode = GPIO_Mode_Out_PP; GPIO_InitStructure.GPIO_Speed = GPIO_Speed_50MHz; GPIO_Init(GPIOC, &GPIO_InitStructure); }

使用库函数，上面的初始化代码变得清晰易懂。要将我们的工程改为使用库，需要：

1. 在工程中添加库的源文件（stm32f10x_xxx.c）和头文件路径。
2. 在工程选项中C/C++ Compiler -> Preprocessor的“Additional include directories”中添加库的头文件目录。
3. 在stm32f10x.h中通过#define选择正确的芯片型号。
4. 可能还需要修改链接脚本，因为库代码会占用一定的Flash和RAM空间。

5.2 常见编译、链接与调试问题排查

1. 编译错误：undefined symbol __write或类似：

   • 问题： 这通常是因为程序中使用了printf等需要底层IO支持的函数，但链接器找不到对应的实现。我们选择的是“Full”库，它默认可能依赖半主机（Semihosting）机制，而我们的裸机程序没有。
   • 解决： 有几种方法：a) 避免在裸机程序中使用printf；b) 重定向printf到串口（需要自己实现_write等函数）；c) 在工程选项General Options -> Library Configuration中，将printfformatter设置为“Tiny”或“None”，以减小体积并避免依赖。

2. 链接错误：placement fails或section overlaps：

   • 问题： 链接器报告某个段（section）无法放入指定的内存区域，或者段之间发生重叠。
   • 解决： 这几乎总是因为链接脚本中定义的内存区域（ROMSTART/ROMEND,RAMSTART/RAMEND）大小小于程序实际需要的大小。请仔细核对芯片数据手册的Flash和RAM容量，并正确计算ROMEND和RAMEND的值。例如，对于128KB Flash的芯片，ROMEND应为0x08000000 + 0x20000 - 1 = 0x0801FFFF。

3. 下载错误：Failed to load flash loader或No debug unit found：

   • 问题： 调试器无法连接芯片或找不到Flash编程算法。
   • 解决：
     • 检查硬件连接：USB线、调试器排线是否接好？板子是否供电？
     • 检查调试器驱动路径是否正确（在Third-Party Driver配置中）。
     • 尝试给板子断电再上电，然后重新点击下载。
     • 检查芯片型号是否选择正确。有时需要手动指定Flash编程算法。在Options -> Debugger -> Download标签页，点击“Edit...”按钮，可以手动添加或选择Flash loader文件（.flash文件通常在IAR安装目录的arm\config\flashloader\ST下）。

4. 程序下载后不运行：

   • 问题： 程序能成功下载，但复位后LED不亮，或者调试时发现PC指针乱飞。
   • 解决：
     • 首先检查main函数是否被正确调用。确保启动文件（startup_stm32f10x_xx.s）已正确添加到工程中。启动文件负责初始化堆栈指针、向量表，然后跳转到main函数。在我们的“裸奔”例子里，我们没有显式添加启动文件，是因为IAR在链接时，如果找不到用户提供的__iar_program_start等入口，可能会使用库中默认的启动代码。最稳妥的方式是从标准外设库例程中复制对应的启动文件（如startup_stm32f10x_md.s用于中等容量STM32F103）到工程并添加。
     • 检查中断向量表是否正确放置。在链接脚本中，必须确保INTVEC段被放置在Flash起始地址（0x08000000）。我们的修改-Z(CODE)INTVEC=ROMSTART-ROMEND通常能保证这一点。
     • 使用调试器单步执行，查看程序是否真的运行到了你的main函数中的代码，以及寄存器操作是否生效（通过查看“Register”窗口或“Memory”窗口）。

5.3 工程管理的建议

1. 目录结构： 建立清晰的目录结构，例如：

   MyProject/ ├── EWARM/ # IAR工程文件、调试配置等 ├── User/ # 用户应用代码（main.c, app.c等） ├── Libraries/ # 第三方库（如ST标准库） │ ├── CMSIS/ │ └── STM32F10x_StdPeriph_Driver/ ├── Drivers/ # 自己的底层驱动（led.c, key.c, uart.c等） └── Output/ # 编译输出文件（可由IAR选项设置）

   在IAR的工程选项C/C++ Compiler -> Preprocessor和Assembler -> Preprocessor中，将User、Libraries等目录添加到“Additional include directories”中。

2. 版本控制： 使用Git等版本控制系统管理你的工程代码，但注意忽略Debug、Release等输出目录以及IAR生成的.dep、.pbd等临时文件。可以创建一个.gitignore文件。

3. 不同的构建配置： IAR允许你创建多个构建配置（Build Configuration），如“Debug”和“Release”。在“Debug”配置中，可以开启优化等级为None，并包含完整的调试信息；在“Release”配置中，可以开启高级别优化（如High for size），并关闭调试信息，以减小最终二进制文件的大小。通过工具栏上的下拉列表可以快速切换。

自己创建一个干净的IAR工程，就像为自己搭建了一个专属的工作台。一开始可能会觉得繁琐，但一旦搭建好并理解了每个配置项的意义，后续的开发效率会大大提升，并且能从根本上避免许多因环境混乱导致的问题。从直接操作寄存器开始，虽然原始，但能让你最深刻地理解芯片是如何工作的，这份理解是日后熟练运用各种高级库和框架的坚实基础。当你下次再看到那些库函数时，你就能清晰地知道它背后在操作哪个寄存器、哪一位，这种感觉，才是真正掌握了嵌入式开发的门道。