3. HAL库串口初始化实战：MX_USART1_UART_Init()函数深度解析

好，咱们正式开始动手配置串口。这一节我会带着你，把 MX_USART1_UART_Init() 这个函数从头到尾拆开来看。你可能会觉得，不就是个初始化函数嘛，有什么好看的？

嗯，我刚开始用HAL库的时候也这么想。直到有一次，板子怎么都发不出数据，折腾了一整天，最后发现是GPIO的复用功能没配对。从那以后，我每次都会把初始化流程完整过一遍。

3.1 初始化函数整体框架

先看下STM32CubeMX生成的初始化代码长什么样：

static void MX_USART1_UART_Init(void)
{
  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();
  }
}

这段代码看起来简单，但背后藏着不少细节。我习惯把它分成两个层面来理解：

• 结构体赋值层：配置波特率、字长、停止位等参数
• HAL_UART_Init()调用层：真正执行硬件寄存器配置

说白了，前面那些赋值只是把参数填到结构体里，真正干活的是 HAL_UART_Init()。这个函数内部会调用 HAL_UART_MspInit()，完成GPIO、时钟、中断等底层配置。

3.2 GPIO配置：复用功能（Alternate Function）

串口的TX和RX引脚，不能当普通GPIO用。你需要把它们配置成复用推挽输出和复用浮空输入。

我个人习惯在 HAL_UART_MspInit() 里完成GPIO配置。来看一个典型配置：

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_PIN_10;
    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_AF_INPUT;
    GPIO_InitStruct.Pull = GPIO_NOPULL;
    HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);
  }
}

这里有个坑，我曾经踩过——TX和RX的Mode不一样：

引脚	功能	GPIO Mode	说明
PA9	USART1_TX	AF_PP（复用推挽输出）	由外设控制输出电平
PA10	USART1_RX	AF_INPUT（复用浮空输入）	接收外部数据

3.3 波特率、字长、停止位、校验位配置

这些参数直接决定了通信双方能不能"对上话"。我整理了一个常用配置表：

参数	常用值	HAL宏定义	说明
波特率	9600 / 115200 / 921600	直接写数值	双方必须一致，误差<2%
字长	8位 / 9位	UART_WORDLENGTH_8B / 9B	常用8位，9位用于多机通信
停止位	1位 / 2位	UART_STOPBITS_1 / 2	1位最常用
校验位	无 / 偶校验 / 奇校验	UART_PARITY_NONE / EVEN / ODD	无校验最常用

你想想看，如果板子A配的是115200、8N1，板子B配的是9600、8E1，那它们之间通信就是鸡同鸭讲。我调试的时候，第一件事就是拿逻辑分析仪抓波形，数一下波特率对不对。

3.4 HAL_UART_MspInit()回调函数深度解析

这个函数是HAL库的精髓之一。它由 HAL_UART_Init() 内部调用，专门负责MCU底层硬件配置。说白了，就是把"外设参数配置"和"底层硬件配置"分开了。

MspInit里通常做三件事：

1. 时钟使能：打开USART外设时钟和对应GPIO时钟
2. GPIO配置：配置TX/RX引脚的复用功能
3. NVIC配置：使能中断并设置优先级（如果使用中断方式）

来看一个完整的MspInit示例：

void HAL_UART_MspInit(UART_HandleTypeDef* huart)
{
  static DMA_HandleTypeDef hdma_usart1_tx;
  static DMA_HandleTypeDef hdma_usart1_rx;

  if(huart->Instance == USART1)
  {
    // 1. 时钟使能
    __HAL_RCC_USART1_CLK_ENABLE();
    __HAL_RCC_GPIOA_CLK_ENABLE();
    __HAL_RCC_DMA1_CLK_ENABLE();

    // 2. GPIO配置
    GPIO_InitTypeDef GPIO_InitStruct = {0};
    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);

    // 3. DMA配置（如果使用DMA方式）
    hdma_usart1_tx.Instance = DMA1_Channel4;
    hdma_usart1_tx.Init.Direction = DMA_MEMORY_TO_PERIPH;
    // ... 其他DMA参数
    HAL_DMA_Init(&hdma_usart1_tx);
    __HAL_LINKDMA(huart, hdmatx, hdma_usart1_tx);

    // 4. 中断配置
    HAL_NVIC_SetPriority(USART1_IRQn, 0, 0);
    HAL_NVIC_EnableIRQ(USART1_IRQn);
  }
}

3.5 时钟使能与分频

串口时钟来自APB2总线（USART1）或APB1总线（USART2/3）。时钟频率直接影响波特率能否配准。

STM32F103的时钟树是这样的：

• USART1：挂在APB2上，最高72MHz
• USART2/USART3：挂在APB1上，最高36MHz

波特率计算公式：

BaudRate = Clock / (16 × USARTDIV)

其中USARTDIV是一个16位的分频系数，HAL库会自动计算。但如果你用的时钟频率比较特殊，比如8MHz晶振配PLL到56MHz，那就要小心了——有些波特率可能配不准。

3.6 知识结构总览

下面这张图把整个初始化流程串起来了，你可以对照着看：

这张图把整个初始化流程串起来了。你可以看到，从入口函数到最终的硬件配置，一共经历了四层调用。每一层都有明确的职责，这也是HAL库的设计哲学——分层解耦。