STM32 HAL库中__weak函数被用户重定义后链接脚本仍选中默认实现的排查路径

一、问题现象与背景

在STM32 HAL库中，大量回调函数以__weak修饰，例如：

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

用户通常在自己的.c文件中写一个同名强符号函数来覆盖它。但实际项目中常出现：用户函数已编译进目标文件，链接后却仍跳转到HAL默认实现。这不是HAL的bug，而是链接器符号解析规则与工程配置共同作用的结果。

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

  • __weak是编译器/链接器扩展属性，表示该符号为弱符号。
  • 链接器在解析同名符号时遵循：强符号优先于弱符号；若只有弱符号，则选弱符号；若出现多个强符号，则报重复定义错误。
  • 关键点：“强符号优先”只在链接器能看到该强符号时成立。如果用户函数所在目标文件未被链接进最终镜像，或符号被隐藏/改名，链接器就只会看到HAL库中的弱符号。

因此排查核心是：确认用户强符号是否真正进入链接器的符号表，并且与弱符号同名同签名。

三、系统化排查路径

1. 确认函数签名完全一致

C语言没有函数重载，符号名由函数名决定，但参数类型不影响符号名（在C中）。然而以下情况会导致“看似同名实则不同”：

  • 用户函数写在extern "C"缺失的C++文件中，符号被mangle。
  • 参数类型写错但函数名相同，编译能过，链接仍选弱符号（因为强符号名不同？实际C中同名即同符号，但若声明冲突会报错）。
  • 使用了static修饰，符号变为局部符号，链接器不可见。

检查方法：用nm查看目标文件符号。

arm-none-eabi-nm -C build/User/user_uart.o | grep RxCpltCallback

应看到T（全局强符号），而不是t（局部）或U（未定义）。

2. 确认目标文件被链接进最终镜像

这是最常见原因。用户把重定义函数写在某个.c中，但该文件因以下原因未参与链接：

  • 未被加入工程源文件列表（IDE中漏加）。
  • 位于静态库中，且库中该目标文件未被任何未定义符号引用，链接器按需抽取，导致未抽取。
  • 被--gc-sections回收（若函数未被引用且未加KEEP）。

检查方法：查看map文件，搜索用户函数符号。

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

若只出现一个W（弱符号）地址，说明强符号未进入。

3. 检查链接顺序与库抽取规则

当用户函数放在静态库libuser.a中，而HAL库也在静态库中时，链接器从左到右扫描。若HAL库先被扫描并已解析了弱符号，后续库中的强符号可能不再被抽取（取决于是否已有定义）。

建议：

  • 将重定义函数放在直接参与链接的.o中，而非静态库。
  • 若必须用库，使用--whole-archive包裹用户库，或调整链接顺序。

4. 检查链接脚本与段放置

少数情况下，用户函数被放入自定义段，而链接脚本未将该段放入可执行区域，导致符号地址异常或未被保留。

  • 检查.map中用户函数地址是否落在Flash有效范围。
  • 若使用__attribute__((section(".user_code")))，确认链接脚本有对应KEEP与放置规则。

5. 检查编译宏与条件编译

HAL中部分回调受宏控制，例如USE_HAL_UART_REGISTER_CALLBACKS。若用户代码被#if屏蔽，实际未编译。

检查方法：预处理后查看。

arm-none-eabi-gcc -E -I... user_uart.c | grep RxCpltCallback

6. 检查C++混编与符号修饰

若用户文件为.cpp，必须用extern "C"包裹重定义函数，否则符号被mangle，链接器看不到C符号。

extern "C" void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    // 用户实现
}

四、完整验证示例

以下示例演示正确重定义与验证流程。

user_uart.c

#include "main.h"

/* 强符号重定义，覆盖HAL弱实现 */
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART1) {
        /* 用户业务：将接收字节放入环形缓冲 */
        RingBuf_Put(&g_rx_buf, g_rx_byte);
        HAL_UART_Receive_IT(&huart1, &g_rx_byte, 1);
    }
}

验证命令

# 1. 查看目标文件符号
arm-none-eabi-nm build/user_uart.o | grep HAL_UART_RxCpltCallback
# 期望输出：00000000 T HAL_UART_RxCpltCallback

# 2. 查看最终ELF符号
arm-none-eabi-nm build/firmware.elf | grep HAL_UART_RxCpltCallback
# 期望只出现一个 T 符号，地址为用户函数

# 3. 反汇编确认调用点
arm-none-eabi-objdump -d build/firmware.elf | grep -A2 "bl.*HAL_UART_RxCpltCallback"

若第2步出现W与T两个符号，说明弱符号未被覆盖，需回到第三节排查。

五、注意事项

  • 不要用static修饰重定义回调，否则符号局部化，链接器无法覆盖。
  • C++文件必须extern "C"，否则符号名被修饰。
  • 静态库中的重定义函数可能不被抽取，优先放直接链接的源文件。
  • --gc-sections可能回收未被引用的用户函数，必要时加KEEP或__attribute__((used))。
  • map文件是最可靠证据，排查时先看符号表再看调用点反汇编。
  • 修改后务必全量重新编译，避免增量构建残留旧目标文件造成误判。

六、小结

__weak重定义不生效的本质是“强符号未进入链接器视野”。按“签名一致→目标文件参与链接→库抽取顺序→段放置→条件编译→C++修饰”的顺序排查，配合nm、objdump与map文件，可在几分钟内定位根因。养成用符号表验证链接结果的习惯，能避免大量“代码明明写了却不执行”的困惑。