问题现象与背景

在STM32 HAL库开发中，我们经常重定义__weak函数来实现自定义回调，例如：

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    // 用户代码
}

但有时编译链接后，程序却执行了HAL库中的默认空实现（__weak void HAL_UART_RxCpltCallback(...) {}），导致自定义逻辑未生效。这通常不是编译器错误，而是链接器符号解析问题。

__weak 与链接器机制

__weak是编译器扩展（ARMCC/GCC均支持），用于声明弱符号。链接器在解析符号时，优先选择强符号；若只有弱符号，则使用弱符号。HAL库将回调函数定义为弱符号，用户重定义即为强符号，理应覆盖。但以下情况会导致覆盖失败：

函数签名不一致：参数类型、数量或返回值不同，编译器视为不同函数，链接器不会替换。
未包含声明头文件：用户定义未在头文件中声明，编译器可能生成不同修饰名（C++）或警告，链接器找不到匹配。
链接顺序问题：若用户目标文件在库文件之后链接，且库中弱符号已被引用，链接器可能不回溯。
优化等级导致符号被丢弃：高优化等级下，未使用的弱函数可能被移除，但用户函数若未被调用也可能被移除。
多文件定义冲突：多个强符号定义导致链接错误，或弱符号被意外选中。
C++名称修饰：在C++环境中未使用extern "C"，导致符号名不匹配。

排查步骤与配置

1. 检查函数签名

确保用户函数与HAL库声明完全一致。打开stm32f4xx_hal_uart.h（以F4为例），查看回调声明：

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart);

用户定义必须相同：

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    // 正确
}

2. 包含正确头文件

在用户源文件中包含stm32f4xx_hal.h或具体外设头文件，确保声明可见。

3. 检查链接映射文件

生成.map文件（Keil: Options -> Listing -> Linker Map；GCC: -Wl,-Map=output.map），搜索函数名，确认用户函数地址是否被使用。若只看到库中地址，则覆盖失败。

4. 调整链接顺序

在Keil中，确保用户目标文件在库文件之前；在GCC链接脚本中，将用户对象放在库之前。例如：

$(CC) $(OBJS) -L. -lhal -o firmware.elf

确保OBJS包含用户文件。

5. 检查优化等级

若使用-Os或-O2，确保用户函数被调用（通过volatile函数指针或__attribute__((used))防止丢弃）。

6. C++环境处理

若在C++中重定义，使用extern "C"：

extern "C" void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    // ...
}

完整代码示例

以下示例展示正确重定义UART接收完成回调，并验证链接。

main.c

#include "stm32f4xx_hal.h"

UART_HandleTypeDef huart2;

void SystemClock_Config(void);
static void MX_GPIO_Init(void);
static void MX_USART2_UART_Init(void);

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

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

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

// 正确重定义回调
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    if (huart->Instance == USART2) {
        // 用户处理
        HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
        // 重新启动接收
        HAL_UART_Receive_IT(huart, &rx_data, 1);
    }
}

注意：rx_data需为全局或静态变量，确保生命周期。

注意事项

始终检查HAL库版本，不同版本回调名可能不同。
使用__weak函数时，避免在多个文件中定义强符号，否则链接错误。
若使用静态库，确保用户函数在库之前被链接，或使用--whole-archive强制包含。
在IAR中，弱符号处理类似，但需检查链接器配置中的“Allow weak symbols”选项。
调试时，可在用户函数入口设置断点，若未命中则说明链接未覆盖。
使用nm命令（GCC）或fromelf（Keil）查看符号表，确认函数地址。

通过以上排查，可解决绝大多数__weak函数覆盖失败问题。

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