问题现象：回调函数为何“失效”？

最近有读者反馈：在STM32F4项目中使用HAL库的HAL_UART_RxCpltCallback回调，明明在main.c中重定义了该函数，但串口接收完成中断触发后，回调函数内的LED翻转和打印语句均未执行。调试发现程序跳转到了HAL库默认的__weak空函数。

用户代码：void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { ... }
库中定义：__weak void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { }
现象：用户函数未被调用，程序运行到库中空函数。

这并非HAL库Bug，而是链接器对__weak符号的处理顺序与用户工程配置共同导致。

原理：__weak符号与链接器选择规则

__weak是ARM编译器（AC6）和GCC均支持的扩展属性，用于声明弱符号。链接器处理规则如下：

若存在强符号（普通函数定义），则优先使用强符号，忽略弱符号。
若只有弱符号，则使用弱符号。
若存在多个强符号，链接器报重复定义错误。
若存在多个弱符号，链接器通常选择第一个遇到的弱符号（取决于链接顺序）。

HAL库中回调函数均定义为__weak，用户重定义后本应产生强符号覆盖弱符号。但实际工程中，若用户函数被编译器优化为弱符号（例如通过__attribute__((weak))误加），或链接脚本/库顺序导致库中弱符号先被解析，就可能出现覆盖失败。

更隐蔽的情况：用户将回调函数定义在**静态库（.a）**中，而链接器在扫描静态库时，若库中目标文件未被显式引用，则不会提取该目标文件，导致用户强符号根本未进入链接过程。

排查步骤：定位覆盖原因

1. 确认符号类型与地址

使用arm-none-eabi-nm查看最终ELF文件中回调函数的符号类型：

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

输出示例：

0800a1b0 T HAL_UART_RxCpltCallback   // T: 强符号，位于用户代码段
0800b2c4 W HAL_UART_RxCpltCallback   // W: 弱符号，位于库代码段

若只看到W符号，说明用户强符号未参与链接。

2. 检查用户函数是否被误声明为弱符号

检查头文件或源文件中是否误加__weak或__attribute__((weak))。
检查是否通过宏定义将函数名替换为弱符号（如#define HAL_UART_RxCpltCallback __weak ...）。

3. 检查链接顺序与静态库依赖

在STM32CubeIDE中，查看Project Properties > C/C++ Build > Settings > Tool Settings > MCU/MPU GCC Linker > Libraries，确认用户静态库位于HAL库之后。
若用户函数在静态库中，确保该库被显式引用（例如在main.c中调用库内其他函数），或使用--whole-archive强制链接。

4. 查看链接器map文件

在build/Debug/Project.map中搜索回调函数名，观察其来源：

.text.HAL_UART_RxCpltCallback
    0x0800a1b0    0x1c  ./Core/Src/main.o
    0x0800b2c4    0x4   ./Drivers/STM32F4xx_HAL_Driver/libHAL.a(stm32f4xx_hal_uart.o)

若用户目标文件未出现，说明该文件未被链接。

完整代码示例：正确重定义回调

以下示例展示在main.c中重定义UART接收完成回调，并确保强符号生效。

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

UART_HandleTypeDef huart2;

/* 用户强符号定义，不加__weak */
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART2) {
        HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
        /* 重新启动接收 */
        HAL_UART_Receive_IT(&huart2, rx_buf, 1);
    }
}

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

    HAL_UART_Receive_IT(&huart2, rx_buf, 1);

    while (1) {
        /* 主循环 */
    }
}

编译后使用nm确认：

arm-none-eabi-nm -C build/Debug/Project.elf | grep HAL_UART_RxCpltCallback
# 输出应为：0800a1b0 T HAL_UART_RxCpltCallback

注意事项与最佳实践

不要将回调函数定义在静态库中，除非明确使用--whole-archive或确保库被引用。
避免在用户代码中重复添加__weak，强符号才能覆盖弱符号。
检查链接顺序：用户目标文件应位于HAL库之前，确保强符号优先被解析。
使用-Wl,--trace-symbol=HAL_UART_RxCpltCallback 让链接器打印符号解析过程，快速定位。
定期查看map文件，确认关键函数地址与来源。
若使用AC6编译器，注意__weak与__attribute__((weak))等价，但混用可能引发警告。

通过以上排查与规范，可彻底避免__weak函数被意外覆盖的问题，确保回调机制稳定运行。

STM32 HAL库中__weak函数被用户重定义后链接顺序导致的意外覆盖排查