1. 问题诊断：为什么.text段会溢出？

如果你正在用RT-Thread开发STM32项目，尤其是像STM32F103C8T6这种只有64KB Flash的“小内存”芯片，大概率会遇到这个经典的编译错误：

rtthread.elf section `.text' will not fit in region `ROM'
region `ROM' overflowed by 10136 bytes

看到这个错误，很多新手的第一反应是：“我的代码怎么可能超过64K？我明明没写多少东西啊！” 别急，这背后有深层原因，而且解决起来比你想象的要简单。

这个错误是链接器（ld）在最后一步报出来的。简单来说，链接器就像一个“空间规划师”，它的任务是把编译器生成的所有代码段（.text）、数据段（.data、.bss等）合理地摆放到芯片的物理内存（Flash和RAM）里。它手里有一张“规划图”，就是链接脚本（通常是link.lds或.ld文件）。这张图里定义了Flash（ROM）和RAM的起始地址和大小。当它发现所有代码加起来的大小超过了规划图中为ROM区域预留的空间时，就会抛出这个“溢出”错误。

那么，为什么代码会“膨胀”呢？我总结了几种常见情况：

  1. 组件和软件包开多了：RT-Thread最吸引人的就是其丰富的组件和软件包生态。你在RT-Thread Settings里勾选了文件系统（FATFS）、网络协议栈（lwIP）、图形界面（LVGL）或者一堆物联网组件，每一个都会引入大量的库代码。不知不觉，你的.text段（存放代码和常量）就“吃胖”了。
  2. 优化等级没开或开低了：编译器有个很重要的功能叫“代码优化”。在-O0（无优化）或-O1（轻度优化）等级下，编译器会生成非常“直白”甚至“啰嗦”的机器码，以便于调试。但这也意味着代码体积最大。切换到-Os（优化大小）或-O2（平衡优化）能显著压缩体积。
  3. 链接脚本的“误会”：这是最隐蔽但也最关键的一点。链接脚本里定义了.data段（已初始化的全局变量）的存放规则。.data段的变量在运行时位于RAM，但它们的初始值需要保存在Flash里，上电后由启动代码拷贝到RAM。如果链接脚本没有明确告诉链接器“.data段的初始值也要占Flash空间”，链接器在计算总Flash占用时，就可能漏算这部分，导致它误以为空间足够，但实际上烧录进去的程序已经超出了物理Flash大小。这就是网上一些帖子提到的“STM32 GCC链接脚本的Bug”的实质。

所以，面对溢出错误，别慌着换芯片。我们可以从三个层面入手，层层递进地解决问题：调整链接脚本、优化编译器选项、裁剪代码。下面我就结合STM32F103C8T6的实战案例，把这三种方案的原理和操作掰开揉碎了讲给你听。

2. 方案一：精细调整链接脚本

链接脚本是解决空间问题的“手术刀”。它直接决定了程序各个部分在内存中的布局。理解它，你就能从根源上掌控你的程序。

2.1 理解链接脚本的核心：MEMORY和SECTIONS

一个典型的STM32链接脚本主要包含两个部分：MEMORY和SECTIONS。

MEMORY块就像房产证，声明了你芯片上有多少地皮（内存区域）以及它们的用途。对于STM32F103C8T6，通常是这样的：

MEMORY
{
    ROM (rx)  : ORIGIN = 0x08000000, LENGTH = 64K
    RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 20K
}

这定义了：

  • ROM区域：从0x08000000开始，长度64K，属性为r（可读）x（可执行），这就是Flash。
  • RAM区域：从0x20000000开始，长度20K，属性为rwx（可读可写可执行）。

SECTIONS块则是装修设计图，规定各个房间（段）放在哪块地皮上。最重要的几个“房间”是：

  • .text：存放你的程序代码和只读常量（比如字符串）。它必须放在ROM里。
  • .data：存放已初始化的全局变量和静态变量。它的运行时地址（VMA）在RAM，但它的初始值（Load Address, LMA）必须保存在ROM里，上电后拷贝过去。
  • .bss：存放未初始化的全局变量和静态变量。它只占RAM空间，不占ROM。
  • .stack和.heap：栈和堆空间，只存在于RAM。

2.2 关键修复：确保.data段占用被正确统计

很多RT-Thread BSP自带的GCC链接脚本，在定义.data段时可能省略了关键信息，导致链接器“算错账”。我们来看一个常见的、有问题的写法：

/* .data section which is used for initialized data */
.data : AT (_sidata)  /* AT(_sidata) 表示加载地址紧接在_sidata符号之后，但未指定区域 */
{
    . = ALIGN(4);
    _sdata = .;        /* 运行时起始地址 */
    *(.data)
    *(.data*)
    . = ALIGN(4);
    _edata = .;        /* 运行时结束地址 */
} >RAM                 /* 只指定了运行时地址在RAM */

这段脚本只说了.data段运行时在RAM（>RAM），并通过AT(_sidata)指定了加载地址（LMA）为_sidata（通常指向.text段末尾）。但它没有明确告诉链接器，这个加载地址是在ROM区域里。链接器在检查ROM区域是否溢出时，可能不会把.data的初始值算进去。

正确的写法应该明确指出.data段的加载地址位于ROM区域：

/* .ARM.exidx is sorted, so has to go in its own output section. */
.ARM.exidx :
{
    *(.ARM.exidx* .gnu.linkonce.armexidx.*)
} >ROM

/* 关键修改在这里：_sidata 指向 .data 段的加载地址（在ROM中） */
_sidata = LOADADDR(.data);

.data : AT (_sidata)   /* 加载地址为 _sidata */
{
    . = ALIGN(4);
    _sdata = .;        /* 运行时起始地址（在RAM中） */
    *(.data)
    *(.data*)
    . = ALIGN(4);
    _edata = .;        /* 运行时结束地址（在RAM中） */
} >RAM AT> ROM         /* 运行时在RAM，加载时在ROM */

修改要点：

  1. 使用 LOADADDR(.data) 或明确指定 AT> ROM 来设置加载地址区域。
  2. 在.data段定义末尾使用 >RAM AT> ROM，清晰地声明了“运行时在RAM，但镜像中存放在ROM”。
  3. 确保.ARM.exidx（异常处理索引表）等只读段也正确放置在ROM中。

这样修改后，链接器就会把.data段的初始值大小计入ROM的总占用，从而在真正超出Flash容量时准确报错。

2.3 实战：修改STM32F103C8T6的链接脚本

在RT-Thread Studio或你的项目目录中，找到BSP对应的链接脚本，通常位于 bsp/stm32/stm32f103-xxx/linker_scripts/link.lds。

  1. 备份原文件：这是好习惯。
  2. 定位.data段定义：用编辑器打开link.lds，找到类似上面示例的.data段。
  3. 进行修改：参照上面的正确写法进行修改。重点是确保.data段有 AT> ROM 或类似的明确指向ROM区域的声明。
  4. 检查.ARM.exidx段：确保它被放置在ROM区域（>ROM）。
  5. 重新编译：保存文件，在项目上点击右键，选择“清理项目”，然后“构建项目”。观察错误是否依然存在，或者错误信息是否发生了变化（比如从.text溢出变成了.data溢出，这说明链接器现在算对了）。

注意：修改链接脚本后，如果编译通过，务必完整地烧录程序并测试功能。因为修改涉及内存布局，如果改错了，程序可能无法正常启动或运行。

3. 方案二：编译器优化与配置调整

如果调整链接脚本后，空间依然紧张，或者你想先尝试更简单的方法，那么编译器优化是你的第二把利器。

3.1 优化等级：从“-O0”到“-Os”

GCC编译器的-O选项是控制代码生成策略的开关。对于资源紧张的MCU，-Os（Optimize for size）通常是首选。

  • -O0 (默认/无优化)：完全不优化，生成代码最直观，调试最方便，但体积最大，速度最慢。仅在深度调试时使用。
  • -O1：一些基本的优化，能减小部分体积并提升速度，对调试影响不大。
  • -O2：更激进的优化，包括指令调度、循环展开等，能较好平衡速度和体积。
  • -Os (重点推荐)：在-O2的基础上，优先选择那些不会显著增加代码大小的优化。这是为节省空间而生的选项，通常能比-O0减少20%-40% 的代码体积。
  • -Oz：比-Os更极致的空间优化，可能会牺牲更多性能。

如何在RT-Thread Studio中修改？

  1. 右键点击项目 -> “属性”。
  2. 找到“C/C++构建” -> “设置”。
  3. 在“工具设置”标签页下，找到“MCU GCC编译器” -> “优化”。
  4. 在“优化等级”下拉框中，选择“-Os”（或者“优化大小”）。
  5. 点击“应用并关闭”，然后重新编译。

命令行（scons/CMake）修改： 如果你使用scons构建，可以在rtconfig.py文件中修改：

CFLAGS = ' -Os'  # 注意前面有空格

3.2 链接时优化（LTO）：跨文件的“瘦身术”

LTO（Link Time Optimization）是一项“黑科技”。传统编译优化只在单个.c文件内进行。LTO允许链接器在最终链接阶段看到所有模块的中间代码，进行跨文件的全局优化，比如删除未被调用的函数、内联小函数等，从而进一步减小体积。

启用方法（在优化等级设置附近）：

  • RT-Thread Studio：在编译器设置的“优化”或“其他”选项中，勾选“-flto”。
  • 命令行/rtconfig.py：在CFLAGS和LDFLAGS中都加上-flto。
    CFLAGS = ' -Os -flto'
LDFLAGS = ' -flto'

警告：启用LTO后，调试信息可能会变得不准确，给单步调试带来困难。建议在开发后期、需要极致压缩体积时再开启。

3.3 移除不必要的库和启动文件

有时候，编译器会链接一些你用不到的库函数，比如浮点数软实现库（libgcc.a中）、某些C库函数等。

  • -nostartfiles / -nostdlib：谨慎使用！这些选项告诉链接器不要使用标准系统启动文件和库。RT-Thread有自己的启动机制，有时可以尝试，但必须确保你提供了所有必要的底层函数（如_start, _exit等），否则会链接失败。除非你很清楚在做什么，否则不建议新手尝试。
  • -specs=nano.specs：使用newlib-nano库。这是一个为嵌入式系统定制的精简版C库，比标准newlib库小很多。在RT-Thread Studio的链接器“其他”选项中添加此参数，或者在LDFLAGS中加入即可。

实测效果：在一个简单的RT-Thread项目上，仅将优化等级从-O0改为-Os，并启用-specs=nano.specs，.text段大小就从45KB降到了32KB，效果立竿见影。

4. 方案三：代码与组件裁剪

如果前两种方法用尽，空间还是捉襟见肘，那就必须对自己写的代码和RT-Thread本身“动刀”了。这是最根本的解决方案。

4.1 使用RT-Thread的裁剪工具

RT-Thread最大的优势之一就是高度可裁剪性。千万不要把你用不到的功能都编进去。

  1. 使用menuconfig或RT-Thread Settings：

    • 在ENV工具中执行menuconfig，或者在RT-Thread Studio中打开图形化配置界面。
    • 核心组件：评估你是否需要DFS（文件系统）、LWIP（网络）、POSIX接口等。如果项目只是简单的控制，可以先关掉。
    • 设备驱动：只启用你实际使用的硬件外设驱动，如UART、I2C、SPI等。不用的ADC、CAN、SDIO等都关掉。
    • 软件包：这是“重灾区”。仔细检查已添加的软件包。每个软件包（如cJSON、EasyFlash、WebClient）都会带来几KB到几十KB的开销。只保留项目必需的。
    • 内核功能：可以调整RT-Thread内核本身的配置，比如：
      • 任务最大数量 (RT_THREAD_PRIORITY_MAX)
      • 定时器线程栈大小 (RT_TIMER_THREAD_STACK_SIZE)
      • 空闲任务栈大小 (RT_IDLE_THREAD_STACK_SIZE)
      • 是否启用钩子函数、调试日志等。

  2. 手动检查rtconfig.h：所有配置最终都体现在这个头文件里。你可以直接搜索并修改宏定义来禁用功能。例如：

    #define RT_USING_DFS             0 // 关闭文件系统
#define RT_USING_LWIP            0 // 关闭网络
#define RT_USING_CONSOLE         1 // 保留控制台（调试用）
#define RT_CONSOLEBUF_SIZE     256 // 减小控制台缓冲区

4.2 优化你自己的应用程序代码

  1. 避免使用大型库函数：比如printf的完整版非常庞大。使用rt_kprintf代替，或者使用libc里更轻量的实现。
  2. 减少全局变量，多用局部变量：全局变量占用.data或.bss段（RAM），但已初始化的全局变量还会占用.data的初始值空间（ROM）。尽量使用函数内的局部变量。
  3. 使用const和static：
    • 将不需要修改的常量数组、字符串字面量用const修饰，确保它们被放入.rodata（只读数据段，通常与.text一起放在ROM），而不是.data。
    • 在函数内部用static const定义局部常量，也能帮助编译器优化。
  4. 检查编译器映射文件（.map）：编译后会生成一个.map文件（在构建目录下）。这个文件详细列出了每个源文件、每个函数、每个全局变量占用了多少空间。搜索.text和.data，找到占用空间最大的那些对象，分析是否可以优化。
    • 你可能会发现某个你没怎么用的库函数被链接进来了。
    • 你可能会发现某个数组定义得过大。

4.3 终极策略：功能拆分与重构

如果经过以上所有优化，64KB的Flash依然不够，你可能需要面对现实：这个芯片的物理资源确实无法承载你的全部功能需求。这时可以考虑：

  1. 功能降级：砍掉一些非核心的、锦上添花的功能。
  2. 代码重构：将部分常量数据（如图标、字库）转移到外部存储器（如SPI Flash），运行时再加载到RAM。但这会增加代码复杂度和访问时间。
  3. 更换芯片：这是最后的选择。升级到Flash更大的型号，如STM32F103CBT6（128KB）或STM32F103RET6（512KB）。在项目早期进行合理的硬件选型可以避免后期的这种痛苦。

5. 总结与实战流程建议

面对.text段ROM溢出，我建议你按照以下流程来排查和解决，像侦探破案一样，步步为营：

第一步：确认问题根源

  1. 重新编译项目，完整查看错误信息，确认溢出大小（例如overflowed by 10136 bytes）。
  2. 使用arm-none-eabi-size工具（或IDE自带的Size Analyzer）查看详细的内存占用报告。你会看到类似下面的输出：
       text    data     bss     dec     hex filename
  72364    1024    4108   77496   12eb8 rtthread.elf
    • text: 代码+常量，占Flash。
    • data: 已初始化全局变量，占Flash（初始值）和RAM（运行时）。
    • bss: 未初始化全局变量，只占RAM。
    • Flash总占用 ≈ text + data。用这个值和你芯片的Flash大小对比。

第二步：实施优化“三板斧”

  1. 优先尝试方案二（编译器优化）：将优化等级改为-Os，并考虑启用-specs=nano.specs。这通常能快速释放10-30%的空间，且风险最低。重新编译，看错误是否消失。
  2. 接着进行方案三（代码裁剪）：通过menuconfig或RT-Thread Settings，大刀阔斧地关闭所有你确认不需要的组件、驱动和软件包。每关闭一项就编译一次，观察text和data大小的变化。这是一个非常有效的方法。
  3. 最后检查方案一（链接脚本）：如果上述方法后空间依然紧张，或者你想确保链接器计算准确，就按照第2章的方法检查和修正链接脚本。修正后，你可能会得到一个更准确的、甚至更大的溢出值，但这反而是好事，说明你看到了真实情况。

第三步：深入分析与权衡 如果经过“三板斧”后，空间占用仍然超过芯片容量（比如还需要再减5KB），那么你需要：

  • 仔细分析.map文件，找到体积最大的模块。
  • 审视自己的应用代码，是否有优化空间（如大数组、冗余代码、使用轻量函数替代重型库函数）。
  • 在功能、性能、成本和开发周期之间做出权衡。是削减功能，还是增加成本换芯片？

在我处理过的很多STM32F103项目中，大多数.text溢出问题通过开启-Os优化和合理裁剪RT-Thread组件这两招就能解决。链接脚本的修正更像是为精确计算和长期稳定性加的一道保险。嵌入式开发就是与有限的资源共舞，理解这些工具和原理，能让你在方寸之间游刃有余。

Logo
乐奇 Rokid 开放社区

更多推荐

cover

英语外教智能体应用实践——从场景选择到连续语音对话的设计与实现

avatar 乐奇 Rokid 开放社区
cover

三键之内的意图：用 AIUI 在 Rokid 眼镜上做一个能玩的 21 点

avatar 乐奇 Rokid 开放社区
cover

从对话到行动：我用 AIUI 把采购需求变成一张可核对的现场清单

avatar 乐奇 Rokid 开放社区