摘要

本文介绍在STM32应用开发中HAL2项目工程格式的使用方法，对比说明了HAL2相较于HAL1结构的变更点、新工程结构对用户代码的影响，以及安全配合代码自动生成的操作方式。

文中说明：在HAL2架构下，main.c作为用户主代码区，不再被代码生成工具覆盖；自动生成层具备更强的可移植性与复用性。同时介绍了借助代码生成菜单、代码预览功能保护用户代码的手段、新工程格式适配VS Codeworkspace的方式，以及HAL2中驱动、handles和中断服务函数的组织结构。

简介

HAL2的推出标志着STM32Cube软件生态迎来重要升级。从驱动层面来看，HAL2优化了运行性能与内存占用，为外设handles设计了逻辑更清晰的状态机，并统一依托底层LL接口实现寄存器访问。从工程层面来看，HAL2重构了生成代码的目录架构，同时调整了用户代码的集成方式。

本文梳理HAL1与HAL2在工程格式及文件架构上的差异。

前置准备

需安装下述工具：

• STM32CubeMX2
• 最新版STM32C5 HAL2驱动库
• STM32CubeIDE for Visual Studio Code扩展插件

1、文件目录结构

1.1 HAL1架构

在HAL1架构中：

黄色区块为Core文件夹：

• Core/Inc（头文件目录）：包含main.h、stm32zyxx_hal_conf.h、stm32zyxx_it.h等头文件
• Core/Src（源文件目录）：包含main.c、stm32zyxx_hal_msp.c、stm32zyxx_it.c、syscalls.c、sysmem.c、system_stm32zyxx.c等源文件

粉色区块为Drivers文件夹：

• Drivers/CMSIS/……
• Drivers/STM32zyxx_HAL_Driver/Inc
• Drivers/STM32zyxx_HAL_Driver/Src

在该架构下，main.c存放于Core/Src目录，与其他自动生成文件混放。HAL驱动保存在“项目工程本地”的Drivers文件夹中，以下三类代码无明确划分边界：

• 工具生成代码
• device/driver包代码
• 用户自定义代码

工程配置重新生成代码时会覆盖Core目录全部内容（含main.c、stm32zyxx_it.c），用户只能依托文件内/USER CODE/预留区域编写代码。

1.2 HAL2架构

HAL2将工程划分为三层独立目录。

Generated与DFP（黄色框）

黄色框包含顶层生成目录（内含hal、utilities、misc等子目录）以及stm32c5xx_dfp目录。

本层为generated+DFP（Device Family Pack）层：

• generated：存放由工程配置生成的代码：
• HAL初始化与配置代码（mx_系列源码、辅助工具代码）。
• stm32c5xx_dfp/（命名随芯片系列变化）：存放器件固件包内容：
• Include、Source：器件头文件与启动文件；
• CMakeLists.txt、RTE_Components.h；
• IDE补丁与metadata。

该目录归属工具管理：STM32CubeMX2可重新生成或更新本目录内容，不会改动用户应用代码。

代码重新生成时可开启差异对比提示：在STM32CubeMX2的【Project settings】标签页，点击【Advanced】，选择【Custom…】可自定义配置代码生成分类规则。

HAL驱动软件包（粉色框）

粉色框圈选stm32c5xx_drivers目录：

• 目录内含：
• hal、ll
• os_port、timebases、templates、utils
• CMakeLists.txt、LICENSE.md、README.md

本目录是该芯片系列对应的HAL2驱动包，独立于工程本体：

• 作用等同于工程引用的软件包。
• 不建议在单工程内直接修改。
• 同芯片系列的多个工程可共用此驱动包。

该结构由HAL1时代Drivers/STM32ZYxx_HAL_Driver迭代优化而来，现已实现标准化打包与版本管控。

用户可修改应用代码（蓝色框）

蓝色框是架构改动最明显的区域，包含user_modifiable用户可编辑目录。

• 编译输出目录（_debug_GCC_NUCLEO…、_release_GCC_NUCLEO…）
• Application\STM32C5xx…应用文件夹。
• 关键存在多版本main文件：
• main.c
• [email]main.base@0.1.0[/email]
• main.h
• [email]main.base@0.1.0.h[/email]

本区域明确标注为用户可修改：

• main.c为用户代码文件。
• main.base@…是工具生成的备份模板文件，用于版本比对与代码迁移，不作为业务逻辑开发位置。
• 应用代码编辑路径：
• user_modifiable/main.c
• 用户在该目录下自行新增的各类源码。

如需避免main.c被生成操作覆盖，建议将分类规则改为【Custom】，用户可编辑文件选项配置为【Don’t generate】或【Backup】。

和HAL1的关键区别：main.c不再存放于工具管控的Core/Src生成目录内，而是单独放在标识明确的用户目录下，HAL2工具在重新生成代码时默认不会覆盖该文件。

1.3 HAL1与HAL2对比

HAL1

• 工程源码、生成代码与用户自定义代码全部混杂在 Core、Drivers 目录下。
• main.c由工具生成，用户代码只能写在 USER CODE 注释标记区间内。
• HAL 驱动仅作为 Drivers 下普通子目录存在。

HAL2

• 工程目录拆分为三层独立结构：
• generated + stm32c5xx_dfp：依赖配置、由生成工具管控的代码；
• stm32c5xx_drivers：对应芯片系列的HAL2/LL驱动软件包；
• user_modifiable：应用层代码（含main.c），归属用户所有。
• 重新生成仅更新生成目录与软件包配置，user_modifiable源码完整保留。
• 在VS Code资源管理器中可直观区分可修改目录与禁止改动目录。

简言之，HAL2把HAL1杂乱混编的单目录工程，拆分为三层架构：device package、generated HAL、独立隔离的用户应用区（main.c置于该区核心）。

**总结

**

HAL1与HAL2对比可见：工程架构从代码混杂模式升级为分层规整架构。HAL1中main.c、生成代码、HAL驱动共处Core与Drivers文件夹，重生成极易误改用户业务代码。

HAL2实现功能解耦：配置相关代码存放于生成目录；器件包与HAL2驱动分别封装在stm32c5xx_dfp、stm32c5xx_drivers；用户文件（重点是main.c）移入专属user_modifiable目录，工具管控目录和用户开发目录一目了然。

由此代码生成更安全、版本升级更便捷；工程移植至新开发板/芯片时，只需重新生成HAL2层，原有应用代码可直接复用。HAL2配套驱动质量更优，工程结构健壮、易于维护。