问题现象：外设初始化莫名失效

在使用STM32 HAL库开发时，你可能遇到过这样的场景：明明在main.c中调用了HAL_UART_Init()，但串口就是没有输出；或者HAL_GPIO_Init()配置了引脚，电平却毫无反应。更诡异的是，代码编译链接一切正常，没有报错，调试器单步执行也显示函数被调用，但外设就是“罢工”。

这类问题往往与HAL库中大量使用的__weak弱函数有关。当用户重定义了某个弱函数（例如HAL_UART_MspInit），却因链接顺序问题导致实际调用的是库中的空实现，外设初始化自然失效。

原理讲解：__weak与链接顺序

什么是__weak函数

__weak是编译器（如ARMCC、GCC）支持的弱符号修饰符。在HAL库中，许多回调函数和MSP（MCU Support Package）初始化函数被定义为弱函数，例如：

__weak void HAL_UART_MspInit(UART_HandleTypeDef *huart)
{
  /* 空实现，等待用户重定义 */
}

弱符号的特点是：如果链接器发现一个强符号（用户定义的同名函数），则使用强符号；否则使用弱符号。这允许用户在不修改库源码的情况下重定义函数。

链接顺序如何影响符号解析

问题出在链接器处理多个目标文件时的符号解析顺序。假设工程中有两个文件：

stm32f1xx_hal_uart.c（库文件，包含弱函数HAL_UART_MspInit）
usart.c（用户文件，包含强函数HAL_UART_MspInit）

如果链接器先处理库文件，它可能将弱函数地址绑定到调用点，后续遇到强函数时不会覆盖已解析的符号（取决于链接器的具体行为，如GCC的--allow-multiple-definition或默认的“先到先得”）。这导致HAL_UART_Init()内部调用的HAL_UART_MspInit()实际指向库中的空函数，用户的初始化代码从未执行。

典型触发场景

使用Makefile或IDE（如Keil、IAR）时，文件链接顺序被意外调整。
将用户重定义函数放在静态库（.a）中，而库文件链接顺序靠后。
使用了-ffunction-sections和--gc-sections，但未正确保留用户函数。

排查步骤：定位链接顺序问题

步骤1：确认弱函数是否被正确重定义

首先检查用户代码中重定义的函数签名是否与库中完全一致（包括参数类型、const修饰等）。例如：

// 正确
void HAL_UART_MspInit(UART_HandleTypeDef *huart) { ... }

// 错误：参数类型不匹配，链接器视为不同函数
void HAL_UART_MspInit(UART_HandleTypeDef *huart, int extra) { ... }

步骤2：查看映射文件（.map）

在Keil中，勾选“Linker”选项卡的“Generate Map File”；在GCC中，链接时添加-Wl,-Map=output.map。打开.map文件，搜索HAL_UART_MspInit，观察其地址和所属目标文件。如果地址指向库文件（如stm32f1xx_hal_uart.o），则说明弱函数未被覆盖。

步骤3：使用nm工具检查符号

对于GCC工具链，使用arm-none-eabi-nm查看目标文件符号：

arm-none-eabi-nm -C build/usart.o | grep HAL_UART_MspInit
# 输出应为 T（强符号）或 W（弱符号）

若用户文件显示W（弱符号），说明定义时漏掉了__weak的移除（用户定义不应加__weak）。

步骤4：调整链接顺序

确保用户目标文件在链接命令中位于库文件之前。例如在Makefile中：

# 错误：库在前
$(CC) $(LDFLAGS) -o firmware.elf libhal.a main.o usart.o

# 正确：用户对象在前
$(CC) $(LDFLAGS) -o firmware.elf main.o usart.o libhal.a

在Keil中，可在“Options for Target” → “Linker” → “Misc controls”中添加--symbols查看符号，或通过“File”顺序调整（Keil通常自动处理，但静态库需注意）。

完整代码示例：正确重定义与验证

以下示例展示如何正确重定义HAL_UART_MspInit并验证链接结果。

usart.c（用户文件）

#include "stm32f1xx_hal.h"

UART_HandleTypeDef huart1;

void HAL_UART_MspInit(UART_HandleTypeDef *huart)
{
  GPIO_InitTypeDef GPIO_InitStruct = {0};
  if (huart->Instance == USART1)
  {
    __HAL_RCC_USART1_CLK_ENABLE();
    __HAL_RCC_GPIOA_CLK_ENABLE();

    GPIO_InitStruct.Pin = GPIO_PIN_9;
    GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
    GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_HIGH;
    HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

    GPIO_InitStruct.Pin = GPIO_PIN_10;
    GPIO_InitStruct.Mode = GPIO_MODE_INPUT;
    GPIO_InitStruct.Pull = GPIO_NOPULL;
    HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);
  }
}

main.c（调用）

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

  huart1.Instance = USART1;
  huart1.Init.BaudRate = 115200;
  huart1.Init.WordLength = UART_WORDLENGTH_8B;
  huart1.Init.StopBits = UART_STOPBITS_1;
  huart1.Init.Parity = UART_PARITY_NONE;
  huart1.Init.Mode = UART_MODE_TX_RX;
  huart1.Init.HwFlowCtl = UART_HWCONTROL_NONE;
  huart1.Init.OverSampling = UART_OVERSAMPLING_16;
  if (HAL_UART_Init(&huart1) != HAL_OK)
  {
    Error_Handler();
  }
  // 此时若MspInit未执行，GPIO不会配置，串口无输出
  HAL_UART_Transmit(&huart1, (uint8_t*)"Hello\r\n", 7, 100);
  while (1) {}
}

验证方法：在HAL_UART_MspInit内设置断点，若未命中，检查.map文件确认符号地址。

注意事项与预防措施

用户重定义函数不要加__weak：否则链接器仍可能选择库中的弱符号（取决于顺序）。
避免将重定义函数放入静态库：静态库中的符号解析顺序更复杂，建议直接编译为对象文件。
使用链接脚本或--undefined强制保留：在GCC中可添加-Wl,--undefined=HAL_UART_MspInit确保符号被引用。
定期检查.map文件：尤其在添加新外设或调整工程结构后。
统一工具链行为：ARMCC与GCC对弱符号的处理略有差异，跨平台时需重新验证。

通过以上方法，你可以快速定位并解决因链接顺序导致的__weak函数重定义失效问题，确保外设初始化代码正确执行。

STM32 HAL库中__weak函数重定义导致外设初始化失效的排查与解决