STM32 HAL库中__weak函数被用户重定义后仍调用原函数的链接顺序陷阱与验证方法

一、问题现象：我的回调为什么没生效？

在STM32 HAL库中，HAL_UART_RxCpltCallback、HAL_GPIO_EXTI_Callback 等回调函数在库中以 __weak 修饰。按常规理解，用户只要在工程中定义同名函数，链接器就会优先使用用户版本。但实际项目中经常出现：

  • 用户已实现 HAL_UART_RxCpltCallback，串口接收完成却仍进入默认空函数；
  • 断点打在用户函数上永远不命中；
  • 反汇编发现调用目标仍是HAL库中的弱符号地址。

这类问题往往与“链接顺序”和“符号解析规则”有关，而不是C语言语法错误。

二、原理：__weak与链接器符号选择

2.1 __weak的本质

在ARM GCC中，__weak 通常展开为 __attribute__((weak))。它告诉编译器：该符号是弱符号。链接阶段，若存在同名强符号，则强符号胜出；若只有弱符号，则使用弱符号。

__weak void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
  /* 默认空实现 */
}

2.2 链接器如何选择符号

关键点在于：强符号与弱符号的判定发生在链接阶段，而不是编译阶段。链接器按输入目标文件顺序扫描符号表：

  • 遇到强符号定义，记录并标记为已解析；
  • 遇到弱符号定义，仅在没有强符号时采用；
  • 若多个强符号同名，直接报重复定义错误。

因此，只要用户函数是强符号，理论上应覆盖弱符号。但以下情况会破坏这一规则：

  • 用户函数被编译器优化为 static 或内联，未产生全局符号；
  • 用户函数所在目标文件未被链接器纳入（如未加入工程、被裁剪）；
  • 链接脚本或库顺序导致HAL库目标文件先被解析，且弱符号被“固化”；
  • 使用了LTO（链接时优化），符号可见性发生变化；
  • 用户函数签名与声明不一致，实际生成的是另一个符号。

2.3 最常见的陷阱：库文件与用户文件的链接顺序

在Keil、IAR或GCC工程中，若HAL库以静态库（.a）形式参与链接，链接器对库的扫描规则是：只提取当前未解析符号所需的成员。若用户目标文件排在库之后，且库中弱符号先被引用，链接器可能已从库中提取了包含弱定义的目标文件，后续用户强符号虽存在，但调用点已绑定到弱符号所在段。

更隐蔽的情况是：用户函数定义在另一个静态库中，而该库排在HAL库之后，链接器不会回头重新解析。

三、复现与验证方法

3.1 查看符号表

使用 arm-none-eabi-nm 查看最终ELF：

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

输出中若出现 W 表示弱符号，T 表示强符号。若只有 W，说明用户强符号未进入最终镜像。

3.2 查看反汇编调用点

arm-none-eabi-objdump -d build/firmware.elf | grep -A2 -B2 HAL_UART_RxCpltCallback

观察调用指令的目标地址，并与 nm 输出的地址比对，确认实际绑定的是哪个实现。

3.3 Map文件检查

在Keil或GCC的 .map 文件中搜索符号，确认其来自哪个目标文件。若来自 stm32f4xx_hal_uart.o 而非用户文件，即可定位问题。

3.4 最小验证工程

建立两个源文件：hal_weak.c 提供弱定义，user_strong.c 提供强定义，分别调整链接顺序编译，观察 nm 结果变化，可稳定复现该陷阱。

四、解决方案

4.1 确保用户目标文件参与链接

  • 检查IDE工程中用户源文件是否被加入编译；
  • 避免将回调实现放在未被引用的静态库中；
  • 使用 __attribute__((used)) 防止被裁剪。

4.2 调整链接顺序

在GCC链接脚本或Makefile中，将用户目标文件放在HAL库之前：

OBJS = main.o user_callbacks.o stm32f4xx_hal_uart.o ...

若使用 -l 链接库，确保用户库出现在HAL库之前，或使用 --whole-archive 强制包含。

4.3 避免LTO干扰

调试阶段可关闭 -flto，确认问题是否由LTO引起。若必须使用LTO，可在用户函数上增加 __attribute__((used, noinline))。

4.4 使用链接器 --undefined 强制保留

LDFLAGS += -Wl,--undefined=HAL_UART_RxCpltCallback

4.5 代码示例：正确的用户回调定义

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

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
  if (huart->Instance == USART1)
  {
    /* 用户逻辑 */
    HAL_UART_Receive_IT(huart, rx_buf, 1);
  }
}

注意：不要加 static，不要放在头文件中定义，确保生成全局强符号。

五、注意事项

  • 回调函数签名必须与HAL库声明完全一致，否则生成不同符号；
  • 不要在头文件中定义函数体，避免多个强符号冲突；
  • 使用 nm 和 .map 文件作为常规排查手段；
  • 升级HAL库后重新确认弱符号名称是否变化；
  • 若使用C++，注意 extern "C" 防止名称修饰导致符号不匹配。

六、总结

__weak 重定义失效的本质是链接阶段的符号解析与目标文件纳入顺序问题。掌握 nm、objdump 和 .map 三种验证手段，配合链接顺序调整与 used 属性，可稳定解决此类问题。建议在工程模板中固定用户回调文件的链接位置，从源头规避陷阱。