embedded-stm32

嵌入式 STM32 / HAL 开发

此技能涵盖使用 STM32 HAL 开发 STM32 微控制器固件，包括项目结构、外设与中断处理、内存和时序约束，以及面向硬件代码的测试策略。

STM32 HAL 固件开发工作流

1. 在 CubeMX 中配置硬件 — 在 .ioc 文件中设置时钟、引脚和外设；生成 HAL 初始化代码。
2. 分离生成的代码与手写代码 — 除指定的 USER CODE BEGIN/END 块外，不要改动 CubeMX 生成的文件；将应用逻辑放在单独的文件中。
3. 只初始化一次外设 — 在 main()/MX_*_Init() 中集中调用 HAL_*_Init()，避免在代码其他位置临时重新配置。
4. 编写中断处理程序 — 保持 ISR（HAL_*_Callback 函数、EXTI/DMA/定时器 IRQ 处理程序）简短；设置标志或推送到队列，并将实际工作延后到主循环或 RTOS 任务中执行。
5. 对高吞吐量 I/O 使用 DMA — 为 UART/SPI/I2C/ADC 传输配置 DMA，避免使用会阻塞或消耗 CPU 周期的轮询方式。
6. 为所有操作添加超时 — 每个阻塞式 HAL 调用和硬件等待循环都需要超时，以及明确的错误处理路径。
7. 分层测试 — 在主机端构建中对纯逻辑进行单元测试（不依赖硬件），然后通过硬件在环测试验证外设行为。
8. 烧录并调试 — 使用配备调试器的 SWD/JTAG（ST-Link、OpenOCD 或 J-Link），并结合限速的串口日志，在真实硬件上验证行为。

项目结构

• 将板级支持（引脚/时钟配置）、驱动程序、中间件（例如 FreeRTOS、USB 协议栈）、应用逻辑和测试放在清晰分离的目录中。
• 将 CubeMX 生成的代码或供应商代码（Core/Src/main.c、Drivers/）与手写应用代码隔离，避免使用 CubeMX 重新生成代码时覆盖自定义逻辑 — 对生成文件仅在 /* USER CODE BEGIN */ ... /* USER CODE END */ 标记内进行编辑。
• 通过精简的接口封装硬件访问（例如，提供 motor_set_speed() 的 motor_driver.h），这样无需真实外设，也能在主机端构建中对应用逻辑进行单元测试。
• 在单一参考文档（README 或头文件注释）中记录时钟树（SYSCLK、HCLK、PCLK1/PCLK2 及其最大频率）、引脚映射、外设归属和中断优先级分配 — 调试时首先需要查阅这些信息。

STM32 HAL 和外设

• 在且仅在一个位置初始化每个外设；避免在多个文件中分散调用 HAL_*_Init()/HAL_*_MspInit() 或临时写入寄存器。
• 始终检查 HAL 调用的返回值（HAL_OK、HAL_ERROR、HAL_BUSY、HAL_TIMEOUT），并明确处理超时/错误情况 — 忽略 HAL_UART_Transmit 返回的 HAL_TIMEOUT 是导致“在我的桌面上能正常工作”这类问题的典型原因。
• 不要在控制循环或 ISR 等时间关键路径中使用阻塞式 HAL 调用（HAL_UART_Transmit、不带 _IT/_DMA 后缀的 HAL_I2C_Master_Receive）。
• 当 CPU 不应花费周期逐字节搬运数据时，对高吞吐量的 UART、SPI、I2C、ADC 或定时器输入捕获路径使用 DMA。
• 为每个 DMA 操作记录缓冲区的所有权和生命周期 — 在传输完成回调触发前，CPU 不得修改或释放 DMA 正在读取的缓冲区。
• 仅对与 ISR 共享的内存或内存映射硬件寄存器使用 volatile；当数据在不同上下文间共享时，volatile 不能替代正确的内存屏障或临界区。

示例：使用 DMA 和空闲线检测进行非阻塞 UART 接收

/* USER CODE BEGIN Includes */
#include "main.h"
#include <string.h>

#define RX_BUF_SIZE 128

static uint8_t rx_buf[RX_BUF_SIZE];
static volatile uint8_t rx_ready = 0;
static volatile uint16_t rx_len = 0;

extern UART_HandleTypeDef huart2;
extern DMA_HandleTypeDef hdma_usart2_rx;
/* USER CODE END Includes */

/* USER CODE BEGIN 2 */
void app_uart_start_receive(void)
{
    /* Enable idle-line interrupt so a packet of unknown length completes
     * the transfer without waiting for the buffer to fill. */
    __HAL_UART_ENABLE_IT(&huart2, UART_IT_IDLE);
    if (HAL_UART_Receive_DMA(&huart2, rx_buf, RX_BUF_SIZE) != HAL_OK) {
        Error_Handler();
    }
}
/* USER CODE END 2 */

/* USER CODE BEGIN 4 */
void USART2_IRQHandler(void)
{
    if (__HAL_UART_GET_FLAG(&huart2, UART_FLAG_IDLE)) {
        __HAL_UART_CLEAR_IDLEFLAG(&huart2);

        HAL_UART_DMAStop(&huart2);
        rx_len = RX_BUF_SIZE - __HAL_DMA_GET_COUNTER(&hdma_usart2_rx);
        rx_ready = 1; /* Deferred: main loop processes the packet. */

        /* Re-arm for the next packet. */
        HAL_UART_Receive_DMA(&huart2, rx_buf, RX_BUF_SIZE);
        return;
    }
    HAL_UART_IRQHandler(&huart2);
}
/* USER CODE END 4 */

/* Main loop excerpt: heavy work deferred out of the ISR. */
void app_main_loop(void)
{
    if (rx_ready) {
        rx_ready = 0;
        uint16_t len = rx_len;
        /* Copy out or parse rx_buf[0..len) here. Do NOT touch rx_buf
         * again until this point, since DMA may already be refilling it. */
        (void)len;
    }
}

中断与并发

• 保持 ISR 简短且行为确定——设置标志、复制少量固定大小的数据，或推入无锁队列，然后返回。
• 将繁重工作（解析、计算、日志记录）从中断中移至主循环、RTOS 任务，或在中断上下文之外处理的事件队列。
• 使用临界区（__disable_irq()/__enable_irq()，或在 RTOS 下使用 taskENTER_CRITICAL()）、原子操作或无锁队列，保护 ISR 与主上下文之间共享的数据——切勿假设多字节读写是原子的。
• 避免在中断处理程序中动态分配内存（malloc/new）；内存分配既无法保证行为确定，也无法保证可重入安全。
• 明确并记录中断优先级的设置（NVIC_SetPriority）——优先级设置不当的中断可能会让时间敏感的外设无法获得服务，或违反 FreeRTOS 的 configMAX_SYSCALL_INTERRUPT_PRIORITY 约束。

内存与时序

• 除非项目明确允许并为其预留预算，否则应避免在固件中使用堆分配——优先使用静态分配和固定大小的缓冲区/内存池。
• 检查 ISR 和 RTOS 任务的栈使用情况（链接时栈使用报告，或在 FreeRTOS 下使用 uxTaskGetStackHighWaterMark()）——在嵌入式目标上，栈溢出通常会悄无声息地造成数据损坏。
• 将查找表声明为 const，使链接器将其放在闪存中，而不是占用稀缺的 RAM。
• 对所有面向硬件的内容（寄存器值、协议字段、缓冲区大小）使用固定宽度整数类型（uint8_t、int32_t、uint32_t），而不是宽度不确定的 int/long。
• 为每次硬件等待都添加超时——如果硬件始终未置位，轮询状态标志且不设上限就会无限期挂起（时钟配置错误或外设断开时常会出现这种情况）。
• 从应用设计之初就将独立看门狗/窗口看门狗纳入考虑，而不是后期才添加——应在编写主循环之前确定刷新策略，而不是等到现场故障后再处理。

测试与调试

• 在主机版本（原生 gcc/clang）上对纯逻辑（协议解析、状态机、数学运算）进行单元测试，并通过项目结构中定义的精简接口对硬件层进行模拟或存根处理。
• 使用硬件在环测试验证实际外设行为（时序、电气信号、真实传感器数据），这些行为无法通过主机版本进行测试。
• 在调试版本中，为不可能出现的硬件状态添加断言（assert() 或自定义的 configASSERT 风格宏）；如果代码尺寸紧张，可在发布版本中将其编译掉。
• 使用 SWD/JTAG（ST-Link/V2、OpenOCD、J-Link）进行实时调试，使用逻辑分析仪排查信号级问题，并使用带速率限制的串口日志（切勿在紧密循环或 ISR 中让 UART 日志刷屏）。
• 保持故障处理程序（HardFault_Handler 等）实用：捕获复位原因（RCC->CSR）、相关故障状态寄存器（SCB->CFSR、SCB->HFSR），以及固件构建版本/哈希，以便事后诊断现场故障。

常见错误

• 在 USER CODE 块之外修改 CubeMX 生成的文件，导致下次重新生成时更改被悄然删除。
• 在没有超时的情况下无限等待硬件状态标志，导致固件遇到任何硬件异常时都会挂起。
• 在 DMA 和 CPU 之间共享缓冲区却不做同步（对于带数据缓存的内核，要执行缓存失效；或者至少应等到传输完成标志/回调触发后再读取）。
• 误以为外设在低功耗模式（Stop/Standby）唤醒后寄存器状态不会变化——许多外设在退出这些模式后都需要重新初始化。