一、引言

在STM32 HAL库开发中，我们经常通过重定义__weak函数来实现自定义回调（如HAL_UART_RxCpltCallback）。但不少开发者遇到过：明明写了回调函数，却从未被调用，调试发现实际执行的是HAL库中的空函数。这往往是由于链接顺序导致用户函数被库中弱符号覆盖。本文将剖析这一陷阱的根源，并提供系统的排查与解决方案。

二、__weak机制与链接器行为

2.1 什么是__weak

__weak是编译器（如GCC、ARMCC）支持的属性，用于声明弱符号。链接器在处理多个同名符号时，优先选择强符号；若只有弱符号，则任选一个。HAL库中大量回调函数被定义为__weak，以便用户提供强符号覆盖。

2.2 链接顺序的影响

链接器按命令行中目标文件/库的顺序依次解析符号。若用户目标文件在库之前，链接器先看到用户强符号，后续库中的弱符号被忽略；反之，若库在前，链接器先解析到弱符号，可能不再搜索用户目标文件中的强符号（取决于链接器策略）。GCC默认行为：当遇到弱符号定义时，若后续出现强符号，仍会用强符号覆盖；但若弱符号来自库且库已被加载，则可能不再提取用户目标文件。

三、陷阱现象与复现

3.1 典型场景

用户新建callback.c实现HAL_UART_RxCpltCallback，但工程链接顺序为：libHAL.a在前，callback.o在后。编译无报错，但运行时回调未执行。

3.2 复现代码

// callback.c
#include "stm32f1xx_hal.h"
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    // 用户代码：点亮LED
    HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
}

若链接顺序错误，实际调用的是HAL库中的空函数。

四、排查方法

4.1 检查map文件

在map文件中搜索HAL_UART_RxCpltCallback，观察其地址来源。若地址位于库段（如libHAL.a），则用户函数未被链接。

4.2 使用nm工具

执行arm-none-eabi-nm -C elf_file | grep HAL_UART_RxCpltCallback，查看符号类型：T表示强符号，W表示弱符号。若显示W，说明用户函数未生效。

4.3 调试器断点

在用户函数设置断点，若从未命中，结合反汇编确认实际调用地址。

五、解决方案与配置步骤

5.1 调整链接顺序

确保用户目标文件在库之前。在Makefile中，将callback.o放在-lHAL之前。

5.2 使用链接脚本强制保留

在链接脚本中通过KEEP保留用户段，或使用--undefined选项强制链接符号。

5.3 代码示例：正确的Makefile片段

OBJS = main.o callback.o system_stm32f1xx.o
LIBS = -lHAL -lm
$(TARGET): $(OBJS)
    $(CC) $(CFLAGS) -o $@ $(OBJS) $(LIBS)

5.4 验证

重新编译后，用nm检查符号类型应为T，map文件中地址位于用户段。

六、注意事项

• 避免在多个文件中定义同一回调，否则链接器报重复定义。
• 使用__weak时，确保用户函数签名与库中完全一致（包括参数类型）。
• 若使用静态库，注意库的链接顺序，必要时使用--whole-archive。
• 定期检查map文件，确认关键函数地址来源。
• 在IDE（如STM32CubeIDE）中，检查链接顺序设置，用户文件通常默认在前，但自定义库需留意。

七、总结

__weak函数重定义是HAL库灵活性的体现，但链接顺序不当会导致覆盖陷阱。通过理解链接器行为、利用map文件和nm工具排查，并调整链接顺序或使用链接脚本，可确保用户函数正确链接。掌握这些技巧，能显著提高嵌入式开发调试效率。