问题现象：重定义__weak函数为何不生效？

在STM32 HAL库中，许多回调函数（如HAL_UART_RxCpltCallback）被定义为__weak，允许用户在自己的源文件中重新定义。但有时你明明写了同名函数，编译链接都通过，运行时却依然执行了HAL库中的空实现。例如：

// 用户文件 user_uart.c
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    // 自己的处理逻辑
    HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
}

调试发现该函数从未被调用，而库中的__weak版本（空函数）却执行了。这通常不是代码逻辑错误，而是链接器选择了错误的符号定义。

原理：__weak与链接器的符号解析规则

__weak是ARM编译器（AC5/AC6）的扩展关键字，用于声明弱符号。链接器处理规则如下：

  • 若存在一个强符号（无__weak修饰）和多个弱符号，链接器优先选择强符号。
  • 若只有弱符号，则任选一个（通常按链接顺序取第一个）。
  • 若强符号出现在静态库中，而弱符号出现在目标文件中，链接器可能不会从库中提取该目标文件，导致强符号未被链接进来。

关键点：链接器只从静态库中提取满足未定义符号的目标文件。如果HAL库以静态库（.a）形式提供，且用户重定义的回调函数位于另一个源文件，链接器可能先解析了库中的弱符号，认为符号已定义，从而不再搜索用户的目标文件。

排查步骤：从编译到链接的完整检查

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

  • 返回类型、参数类型、调用约定必须与HAL库声明完全一致。
  • 使用__weak修饰的函数在头文件中声明时通常不带__weak，用户定义时也不应带。
  • 检查是否误加了static导致内部链接。

2. 检查链接顺序与库的包含方式

  • 在IDE（如STM32CubeIDE）中，链接顺序通常为：用户目标文件 → 库文件。但若用户文件被编译为静态库，则顺序可能颠倒。
  • 确保用户源文件直接参与链接（.o文件），而非打包成库。
  • 若必须使用库，将用户库放在HAL库之前。

3. 使用链接器映射文件验证符号来源

生成.map文件（在链接选项中添加-Wl,-Map=output.map），搜索函数名：

HAL_UART_RxCpltCallback   0x08001234   Thumb Code   12  user_uart.o(.text.HAL_UART_RxCpltCallback)

若显示来自stm32f1xx_hal_uart.o，则说明链接器选择了库中的弱符号。

4. 检查分散加载文件（scatter file）或链接脚本

  • 某些工程使用自定义分散加载文件，可能将用户代码段放置在库之后，影响符号解析顺序。
  • 确保用户代码段（如.text）在库段之前被链接。

5. 强制链接用户符号（临时验证）

在链接选项中添加-Wl,--undefined=HAL_UART_RxCpltCallback，强制链接器保留该符号。若此时用户函数被调用，则确认是链接顺序问题。

完整代码示例：复现与解决

复现工程结构

  • main.c：调用HAL_UART_Transmit等，触发回调。
  • user_callback.c：重定义HAL_UART_RxCpltCallback。
  • stm32f1xx_hal_uart.c：HAL库源文件，含__weak定义。

错误链接顺序（模拟）

假设用户文件被编译为libuser.a，链接顺序为：

LDFLAGS = -lstm32hal -luser

链接器先搜索libstm32hal.a，找到弱符号定义，认为符号已解析，不再搜索libuser.a，导致用户函数未被链接。

正确做法

  • 将用户源文件直接加入编译（不打包成库）。
  • 或调整链接顺序：-luser -lstm32hal。

验证代码

// user_callback.c
#include "stm32f1xx_hal.h"

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    if (huart->Instance == USART1) {
        HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5); // 用户逻辑
    }
}

编译后查看map文件，确认符号来自user_callback.o。

注意事项与最佳实践

  • 避免将用户回调放入静态库：除非明确控制链接顺序，否则直接编译源文件最可靠。
  • 使用__attribute__((used))：防止用户函数被优化掉（尤其开启LTO时）。
  • 检查编译器版本差异：AC5与AC6对弱符号处理略有不同，AC6更严格遵循ELF标准。
  • 启用-ffunction-sections -fdata-sections与--gc-sections：可能误删未引用的用户函数，需用KEEP或__attribute__((used))保留。
  • 调试时优先查看map文件：这是定位符号解析问题的黄金手段。
  • 若使用CubeMX生成代码：确保用户代码写在/* USER CODE BEGIN */与/* USER CODE END */之间，避免被覆盖，但链接问题与代码位置无关。

通过以上排查，可彻底解决__weak函数重定义不生效的问题，确保HAL库回调按预期执行。