STM32 HAL库中__weak函数被覆盖后仍进入默认实现的链接脚本排查方法

一、问题现象与背景

在STM32 HAL库开发中,我们经常重写__weak函数来实现回调,例如:

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    // 用户自定义逻辑
}

但有时编译链接都通过,运行时却仍然进入HAL库中的默认空实现,导致自定义逻辑不执行。这类问题通常不是C语言语法错误,而是链接阶段的符号绑定出了问题。

二、__weak与符号覆盖原理

  • __weak是编译器(ARMCC/AC6/GCC)扩展属性,将函数标记为弱符号。
  • 链接器在解析符号时,强符号优先于弱符号。若存在同名强符号,则弱符号被丢弃。
  • 若用户函数未正确生成强符号,或链接器未参与符号解析,就会保留HAL库中的弱实现。
  • 常见原因包括:函数签名不一致、函数被定义在未被链接的目标文件中、链接脚本使用--gc-sections误删、static修饰、C++名字修饰等。

三、排查方法一:查看Map文件

Map文件是链接器生成的符号映射表,最直接的排查手段。

  1. 在工程配置中开启Map文件生成:
    • Keil:Options for Target → Listing → 勾选“Linker Map”。
    • STM32CubeIDE:Project Properties → C/C++ Build → Settings → Linker → 勾选“Generate map file”。
  2. 在.map文件中搜索目标函数名,例如HAL_UART_RxCpltCallback。
  3. 观察符号来源:
    • 若只出现stm32f4xx_hal_uart.o,说明用户实现未被链接。
    • 若出现用户.o文件且地址有效,说明覆盖成功。

示例Map片段:

HAL_UART_RxCpltCallback  0x08001234  Thumb Code  ...  stm32f4xx_hal_uart.o

若用户文件未出现,继续下一步。

四、排查方法二:使用nm/objdump检查符号绑定

在命令行中使用工具链检查目标文件符号:

arm-none-eabi-nm -C build/main.o | grep HAL_UART_RxCpltCallback
arm-none-eabi-nm -C build/stm32f4xx_hal_uart.o | grep HAL_UART_RxCpltCallback

输出中:

  • T表示全局强符号(Text段)。
  • W或w表示弱符号。
  • t表示局部符号。

若用户目标文件中该符号为t(局部)或不存在,说明函数被static修饰或未编译进目标文件。

也可用objdump -t查看符号表:

arm-none-eabi-objdump -t build/main.o | grep HAL_UART_RxCpltCallback

五、排查方法三:检查链接脚本与--gc-sections

链接脚本(.ld)和链接选项可能影响符号保留:

  • 若使用-ffunction-sections -fdata-sections配合--gc-sections,未被引用的段会被回收。
  • 用户回调函数若仅通过弱符号间接调用,可能被误判为未引用而删除。
  • 检查链接脚本中是否将用户目标文件放入正确的段,或是否使用了KEEP()保留关键符号。

示例:在链接脚本中保留回调段:

KEEP(*(.text.HAL_UART_RxCpltCallback))

或在链接选项中临时关闭--gc-sections验证问题是否消失。

六、完整复现代码与修复步骤

6.1 复现工程结构

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

UART_HandleTypeDef huart2;

/* 用户重写回调 */
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART2) {
        HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
    }
}

int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_USART2_UART_Init();

    uint8_t rx;
    HAL_UART_Receive_IT(&huart2, &rx, 1);

    while (1) { }
}

6.2 错误配置示例

/* 错误:使用static导致局部符号,无法覆盖弱符号 */
static void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    // ...
}

6.3 修复步骤

  1. 去掉static,确保函数为全局强符号。
  2. 确认函数签名与HAL库声明完全一致(参数类型、返回类型)。
  3. 确认包含该函数的.c文件被加入编译并链接。
  4. 检查Map文件,确认用户.o文件参与链接。
  5. 若使用--gc-sections,在链接脚本中用KEEP()保留回调符号。
  6. 重新编译,使用nm确认符号为T。

七、注意事项

  • 函数签名必须与HAL库声明严格一致,否则链接器视为不同符号。
  • C++工程中需使用extern "C"避免名字修饰。
  • 不要用static修饰需要覆盖的弱函数。
  • 多文件重复定义强符号会报链接错误,需确保唯一实现。
  • 使用--gc-sections时,回调函数可能因“看似未引用”被回收,需用KEEP()保护。
  • 不同工具链(ARMCC、AC6、GCC)的__weak关键字写法不同,注意宏定义兼容。

通过以上Map文件、符号表与链接脚本三层排查,可快速定位并解决__weak函数覆盖失效问题。