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

在STM32 HAL库中，许多回调函数（如HAL_UART_RxCpltCallback、HAL_GPIO_EXTI_Callback）被定义为__weak，允许用户在自己的源文件中重新实现。但不少开发者遇到这样的困惑：明明在main.c或自定义文件中写了同名函数，编译链接都通过，运行时却调用了HAL库中的空实现。

例如：

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

// 用户代码 main.c 中
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
  // 用户逻辑
}

现象是用户逻辑未执行。这通常不是代码错误，而是链接器选择了错误的符号定义。

__weak机制与链接器符号解析原理

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

  • 若存在多个同名符号，强符号优先于弱符号。
  • 若只有弱符号，则选择其中一个（通常第一个遇到的）。
  • 若同时存在多个强符号，链接报错（重复定义）。

关键点：链接器按目标文件（.o）在链接命令行中出现的顺序扫描符号。当它第一次遇到某个符号的弱定义时，会暂时记录；若后续遇到强定义，则用强定义覆盖弱定义。但若强定义所在的目标文件在弱定义之后才被扫描，且链接器已经完成了对该符号的解析（例如因为该符号被引用而立即绑定），则可能保留弱定义。

实际上，现代链接器（如GNU ld、ARM linker）通常会在所有目标文件扫描完毕后进行符号决议，强符号总会胜出。那为什么用户重定义会失败？常见原因有：

  1. 用户函数被编译器优化或未参与链接：例如函数定义在未被调用的源文件中，且链接器开启了--gc-sections，该段被回收。
  2. 用户函数所在目标文件未被加入链接：例如文件未添加到工程，或使用了静态库且库中成员未被提取。
  3. 链接顺序导致弱符号被优先绑定：在某些链接器（如ARM Compiler 5的armlink）中，若弱符号在强符号之前被引用，且链接器采用“首次定义优先”策略，则可能保留弱符号。
  4. 用户函数被声明为static：导致内部链接，无法覆盖外部弱符号。
  5. 使用了C++编译：名称修饰导致符号不匹配。

排查步骤与配置要点

步骤1：确认符号是否被正确包含

使用nm或fromelf查看最终可执行文件中该符号的地址和类型：

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

输出中T表示强符号（用户实现），W表示弱符号（库实现）。若显示W，说明用户实现未链接进来。

步骤2：检查用户源文件是否参与编译链接

  • 在IDE（Keil、STM32CubeIDE）中确认文件已添加到对应目标。
  • 若使用Makefile，检查OBJS是否包含该文件的目标文件。
  • 若函数定义在头文件中，确保没有误加static inline。

步骤3：检查链接顺序与库提取

当用户代码与HAL库以静态库形式链接时，链接器只提取库中未被解析的符号。若用户强符号已存在，库中的弱符号不会被提取，这是期望行为。但若用户强符号所在目标文件在库之后才链接，且库中弱符号已被提取（因为其他符号引用了该库成员），则可能发生冲突。此时链接器通常会报重复定义错误，除非弱符号被特殊处理。

关键配置：确保用户目标文件在链接命令行中位于HAL库之前。在Keil中，可通过“Options for Target -> Linker -> Misc controls”添加--no_remove或调整文件顺序；在GCC中，调整Makefile中OBJS的顺序，将用户文件放在库之前。

步骤4：检查链接脚本与段回收

若使用了-ffunction-sections -fdata-sections和--gc-sections，未被引用的用户函数可能被回收。确保用户函数被调用（例如在中断服务程序中调用），或使用__attribute__((used))标记。

__attribute__((used)) void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
  // ...
}

步骤5：验证C++名称修饰

若用户文件为.cpp，需使用extern "C"包裹重定义函数：

#ifdef __cplusplus
extern "C" {
#endif
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { /* ... */ }
#ifdef __cplusplus
}
#endif

完整代码示例与工程配置

以下以STM32CubeIDE（GCC）为例，展示正确重定义并确保链接优先的配置。

用户文件user_callback.c：

#include "main.h"

// 强符号定义，覆盖HAL弱符号
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
  if (huart->Instance == USART1) {
    // 用户处理逻辑
    HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
  }
}

Makefile片段（确保用户目标文件在库之前）：

OBJS = main.o user_callback.o stm32f1xx_hal_uart.o ... # 用户文件在前
LIBS = -lstm32f1xx_hal
firmware.elf: $(OBJS)
	$(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)

链接脚本检查：确保.text段包含用户函数，且未被/DISCARD/丢弃。

注意事项

  • 避免在头文件中定义非inline函数，否则多个源文件包含会导致重复定义。
  • 使用__weak重定义时，函数签名必须与库中完全一致（包括参数类型和const限定）。
  • 若使用ARM Compiler 6（AC6），链接器行为与GCC类似，强符号优先，但仍需确保用户目标文件参与链接。
  • 调试时可通过反汇编查看调用地址，确认跳转至用户函数。
  • 对于中断回调，确保在stm32f1xx_it.c中正确调用HAL处理函数，以触发回调。

通过以上排查与配置，可彻底解决__weak函数重定义不生效的问题，确保用户代码按预期执行。