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

在STM32 HAL库中，回调函数（如HAL_UART_RxCpltCallback）通常被声明为__weak，允许用户重定义。但许多开发者遇到：自己定义了同名函数，编译链接无报错，运行时却仍进入HAL库的默认空实现。

// 用户代码：main.c
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    // 自定义逻辑
    HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
}

现象：LED不翻转，断点命中stm32f1xx_hal_uart.c中的弱定义。

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

__weak是编译器扩展（ARMCC/GCC均支持），将函数标记为弱符号。链接器解析符号时遵循：

强符号优先：若存在强符号定义，则忽略所有弱符号。
弱符号兜底：仅当无强符号时，才使用弱符号。
多重强符号冲突：链接报错（multiple definition）。

理论上，用户强符号应覆盖HAL库弱符号。但实际链接顺序可能打破这一规则。

关键：静态库(.a)的链接顺序

HAL库通常编译为静态库libHAL.a。链接器处理静态库时，只提取当前未定义符号所需的成员。若用户目标文件在库之前链接，链接器先看到用户强符号，库中的弱符号不会被提取——这是期望行为。

但若链接顺序相反（库在前，用户目标文件在后），链接器先处理库，发现HAL_UART_RxCpltCallback被引用（如HAL_UART_IRQHandler调用），于是从库中提取弱符号定义。随后处理用户目标文件时，强符号已存在，但链接器可能因“符号已解析”而忽略用户定义，或报重复定义（取决于链接器策略）。

常见陷阱：在IDE（如STM32CubeIDE）中，链接顺序由工程配置决定。若用户源文件被编译为独立目标文件，但链接脚本或工程设置将库置于前面，则弱符号抢先解析。

排查步骤与配置

步骤1：确认符号类型

使用arm-none-eabi-nm查看目标文件和库中的符号：

arm-none-eabi-nm -C build/main.o | grep HAL_UART_RxCpltCallback
# 输出：T HAL_UART_RxCpltCallback  (T表示强符号，位于代码段)
arm-none-eabi-nm -C libHAL.a | grep HAL_UART_RxCpltCallback
# 输出：W HAL_UART_RxCpltCallback  (W表示弱符号)

若用户目标文件中符号为T，库中为W，则定义正确，问题在链接顺序。

步骤2：检查链接命令顺序

在Makefile或IDE的链接器调用中，确保用户目标文件（.o）出现在静态库（.a）之前：

# 正确顺序：用户目标文件在前，库在后
$(CC) $(OBJS) -lHAL -o firmware.elf

# 错误顺序：库在前，用户目标文件在后
$(CC) -lHAL $(OBJS) -o firmware.elf

STM32CubeIDE中，可在“Project Properties > C/C++ Build > Settings > Tool Settings > MCU G++ Linker > Libraries”调整库顺序，但更可靠的是将用户源文件加入工程编译（而非仅链接库）。

步骤3：使用链接器选项强制符号

若无法调整顺序，可用--undefined强制链接器保留用户符号：

LDFLAGS += -Wl,--undefined=HAL_UART_RxCpltCallback

或使用--whole-archive强制包含库中所有目标文件（不推荐，增大体积）。

完整代码示例：验证链接顺序影响

以下示例模拟用户代码与HAL库的链接场景。

hal_weak.c（模拟HAL库，编译为libhal.a）

#include <stdio.h>

__attribute__((weak)) void HAL_UART_RxCpltCallback(void) {
    printf("Default weak callback\n");
}

void HAL_UART_IRQHandler(void) {
    HAL_UART_RxCpltCallback(); // 调用回调
}

user.c（用户强定义）

#include <stdio.h>

void HAL_UART_RxCpltCallback(void) {
    printf("User callback\n");
}

void HAL_UART_IRQHandler(void);

int main(void) {
    HAL_UART_IRQHandler();
    return 0;
}

编译与链接

# 编译库
gcc -c hal_weak.c -o hal_weak.o
ar rcs libhal.a hal_weak.o

# 编译用户
gcc -c user.c -o user.o

# 正确顺序：用户目标文件在前
gcc user.o -L. -lhal -o test_ok
./test_ok  # 输出：User callback

# 错误顺序：库在前
gcc -L. -lhal user.o -o test_fail
./test_fail  # 输出：Default weak callback

注意事项

避免将用户回调放在静态库中：若用户代码也编译为库，链接器可能因顺序问题忽略。
STM32CubeMX生成代码：用户回调应放在main.c或独立源文件，确保参与编译而非仅链接。
GCC与ARMCC差异：ARMCC对弱符号处理更严格，可能直接报重复定义；GCC可能静默选择先遇到的符号。
使用__attribute__((used))：防止用户函数被优化掉（若未被引用）。
调试技巧：在默认弱实现中加断点，若命中则检查nm输出和链接map文件（-Wl,-Map=output.map）。

总结

__weak函数重定义失效的根因通常是链接顺序导致弱符号抢先解析。通过nm确认符号类型、调整链接命令顺序、必要时使用--undefined强制符号，可彻底解决。理解链接器对静态库的提取规则，是嵌入式开发中避免此类隐蔽问题的关键。

STM32 HAL库中__weak函数重定义失效？链接顺序排查与原理详解