STM32 HAL库中__weak函数覆盖后仍进默认回调的链接脚本排查方法

一、问题现象与背景

在STM32 HAL库中,HAL_UART_RxCpltCallback、HAL_GPIO_EXTI_Callback 等回调函数在库内以 __weak 修饰定义。用户只需在工程中定义同名强符号即可覆盖。但实际开发中常出现:

  • 用户已实现 void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart),断点却进不了;
  • 编译无重复定义报错,运行却执行库内空实现;
  • 换编译器/优化等级后行为变化。

根因通常不在C代码,而在链接阶段的符号解析与段布局。

二、原理:__weak 与链接器符号解析

__weak 是编译器属性(GCC 为 __attribute__((weak))),它把符号标记为弱符号。链接器解析规则:

  • 强符号 + 弱符号同名:选强符号;
  • 多个弱符号同名:任选其一(通常先出现者);
  • 只有弱符号:使用弱符号。

关键点:强符号必须真正进入最终链接的输入文件集合。若用户实现所在的目标文件未被链接、被归档库覆盖、或被 --gc-sections 回收,则链接器看到的只有弱符号,自然进默认回调。

三、排查步骤

1. 确认符号强弱与来源

用 nm 查看目标文件符号类型:W 表示弱符号,T 表示强符号(代码段)。

arm-none-eabi-nm -C build/Drivers/STM32F4xx_HAL_Driver/*.o | grep HAL_UART_RxCpltCallback
arm-none-eabi-nm -C build/Core/Src/usart.o | grep HAL_UART_RxCpltCallback

若用户文件显示 W,说明定义被写成了弱符号(常见于复制库函数时保留了 __weak)。

2. 检查最终 ELF 的符号地址

arm-none-eabi-nm -C build/firmware.elf | grep HAL_UART_RxCpltCallback

只有一个符号且地址落在 HAL 库段内,说明强符号未参与链接。

3. 查看 .map 文件

在链接选项中加 -Wl,-Map=build/firmware.map,搜索符号:

.text.HAL_UART_RxCpltCallback
  0x0800xxxx  build/Core/Src/usart.o

若 map 中该符号来自 libxxx_hal.a 而非用户 .o,即为归档库优先问题。

4. 检查链接脚本段布局

自定义段(如把回调放入 .text.user)若未在 SECTIONS 中显式包含,可能被丢弃或落到异常位置:

SECTIONS
{
  .text :
  {
    *(.text*)
    *(.text.user*)
  } > FLASH
}

同时确认没有 *(.text.HAL_*) 之类的通配把用户段误收。

5. 排查 --gc-sections

开启 -ffunction-sections -fdata-sections -Wl,--gc-sections 时,仅被中断向量或显式引用可达的函数才保留。回调由库内部通过函数指针调用,若库以静态库形式链接且调用点被优化,可能被回收。用 -Wl,--print-gc-sections 观察:

arm-none-eabi-gcc ... -Wl,--gc-sections -Wl,--print-gc-sections

6. 静态库链接顺序

GNU ld 对归档库只解析一次,库应放在用户目标文件之后。若 HAL 以 .a 提供,确保命令行顺序为 usart.o ... -lhal。

四、完整代码示例

用户实现(强符号,勿加 __weak):

/* usart.c */
#include "main.h"

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART1) {
        /* 自定义处理 */
        HAL_UART_Receive_IT(huart, rx_buf, 1);
    }
}

库内弱定义(示意):

__weak void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    UNUSED(huart);
}

验证脚本:

ELF=build/firmware.elf
SYM=HAL_UART_RxCpltCallback
arm-none-eabi-nm -C $ELF | grep $SYM
# 期望输出形如:0800abcd T HAL_UART_RxCpltCallback
# 若为 W 或地址位于库段,继续查 map

五、注意事项

  • 覆盖函数不要保留 __weak,否则仍是弱符号;
  • 函数签名必须与库声明完全一致(含 const、指针类型),否则是不同符号;
  • C++ 工程需 extern "C",避免名字修饰导致符号不匹配;
  • 使用 -flto 时符号可能被内联,需结合 map 与 -fno-lto 对比验证;
  • 中断回调需保证对应外设中断已使能,否则看似“未覆盖”实为未触发;
  • 定期用 nm/map 做符号审计,比盲目改代码更高效。

掌握符号强弱与链接布局,是排查 HAL 回调覆盖失效的核心方法。