企业官网建设流程全解析

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS

CMSIS（Common Microcontroller Software Interface Standard，通用微控制器软件接口标准）是 ARM 为 Cortex 系列处理器制定的软硬件接口规范。本文以 RT-Thread 仓库bsp/ht32下 Holtek HT32 固件库（FWLib）中随包分发的 CMSIS README 为主线，结合仓库内的实际头文件、构建脚本与板级配置，说明 CMSIS Version 5 的组件构成、目录组织方式，以及它在 RT-Thread HT32 BSP 的 SCons 构建体系与 Cortex-M0+/M3 启动流程中承担的角色。读完本文，你将掌握如何在该仓库中定位 CMSIS 核心头文件、理解设备头文件与core_cm*.h的包含关系，并能在自己的 HT32 工程中正确配置 CMSIS 相关宏与头文件路径。

一、CMSIS Version 5 是什么

按仓库内 README 的定义，CMSIS 是 ARM 发布的 Cortex-M/A 处理器及外设的统一软件接口标准。它位于硬件与应用程序之间，提供：

• 标准化的处理器核心与外设访问 API；
• 面向 Cortex-M4/M7/M33/M35P 的 SIMD（单指令多数据）内建函数；
• 可跨编译器（ARMCC、armclang、GCC、IAR）移植的编译抽象层。

该 README 说明其master分支对应 CMSIS Version 5 的正式发布线，develop分支则反映持续开发状态。仓库内这份 README 与其携带的 ARM.CMSIS.pdsc 包描述文件共同表明，当前随 HT32 FWLib 分发的是 CMSIS 5.9.0 版本（2022-05-02 发布），其中 CMSIS-Core(M) 为 5.6.0、CMSIS-DSP 为 1.10.0、CMSIS-NN 为 3.1.0、CMSIS-RTOS2 为 2.1.3、CMSIS-SVD 为 1.3.9、CMSIS-DAP 为 2.1.1。

二、CMSIS 5 组件全景：一份标准该管什么

README 中的组件总表列出了一整套面向 Cortex 生态的接口规范，各组件分工明确：

对嵌入式开发者而言，日常使用频率最高的是Core(M)（处理器寄存器与内建函数）和Driver（外设接口抽象），而DSP / NN / RTOS v2则对应信号处理、端侧 AI 与 RTOS 移植等进阶场景。

三、仓库内 CMSIS 的实际目录布局：两种 FWLib 双线分发

在 RT-Thread 的bsp/ht32下，CMSIS 头文件并非单一存放，而是跟随 Holtek 官方固件库按芯片系列分别存放：

• 5 系列（Cortex-M0+）：bsp/ht32/libraries/HT32_STD_5xxxx_FWLib/library/CMSIS
• 1 系列（Cortex-M3）：bsp/ht32/libraries/HT32_STD_1xxxx_FWLib/library/CMSIS

以 5 系列为例，其 CMSIS 目录包含三部分：

1. Include/：精简发布集，仅有cmsis_armcc.h、cmsis_armclang.h、cmsis_compiler.h、cmsis_gcc.h、cmsis_iccarm.h、cmsis_version.h、core_cm0plus.h、core_cm3.h、mpu_armv7.h。这正好覆盖 HT32F5 系列实际使用的 Cortex-M0+（core_cm0plus.h）以及兼容编译所需的工具链抽象层。
2. Core/Include/：完整的 CMSIS-Core(M) 发布集，包含全部核心头文件——core_cm0.h、core_cm0plus.h、core_cm1.h、core_cm3.h、core_cm4.h、core_cm7.h、core_cm23.h、core_cm33.h、core_cm35p.h、core_cm55.h、core_cm85.h、core_sc000.h、core_sc300.h、core_starmc1.h，以及core_armv81mml.h、core_armv8mbl.h、core_armv8mml.h等 Armv8-M 变体；此外还有cachel1_armv7.h（L1 Cache API）、mpu_armv7.h/mpu_armv8.h（MPU API）、pac_armv81.h（Pointer Authentication）、pmu_armv8.h、tz_context.h（TrustZone 上下文）。
3. Core/Template/ARMv8-M/：main_s.c与tz_context.c两个安全态模板源文件，供 Armv8-M 安全扩展项目参考。

这样的“精简 Include + 完整 Core/Include”双份结构，兼顾了“开箱即用的最小依赖”与“面向全系 Cortex-M 的完整源码”，与 README 所述“CMSIS/Core 为发布用文件、CoreValidation 不参与发布”的分层思想一致。

四、CMSIS 在 RT-Thread HT32 BSP 中的真实调用链

CMSIS 不是孤立存放的静态文件，它通过设备头文件与 RT-Thread 的 SCons 构建脚本被实际编译进工程。以下是仓库内的证据链：

4.1 设备头文件对 core 头文件的引用

HT32F5 系列设备头文件 ht32f5xxxx_01.h 在寄存器定义之后直接包含：

#include "core_cm0plus.h" /* Cortex-M0+ processor and core peripherals */

而 HT32F1 系列设备头文件 ht32f1xxxx_01.h 则包含：

#include "core_cm3.h" /* Cortex-M3 processor and core peripherals */

这一包含关系说明：设备头文件只负责外设寄存器布局（ht32f5xxxx_01.h等），而处理器核心寄存器（NVIC、SysTick、SCB 等）的访问统一交由 CMSIS 的core_cm*.h完成，这正是 CMSIS “标准接口 + 厂商扩展”分层设计的落地体现。

4.2 SCons 构建脚本把头文件路径接入编译

bsp/ht32/libraries/HT32_STD_5xxxx_FWLib/SConscript 中，path列表明确加入了三个头文件目录：

path = [ cwd + '/library/HT32F5xxxx_Driver/inc', cwd + '/library/CMSIS/Include', cwd + '/library/Device/Holtek/HT32F5xxxx/Include' ]

这意味着使用 RT-Thread 的 SCons 构建时，core_cm0plus.h、cmsis_gcc.h等 CMSIS 头文件会自动进入编译器搜索路径；1 系列固件库的 SConscript 同样将library/CMSIS/Include加入CPPPATH。同一脚本还依据 Kconfig 选中的SOC_xxx符号，通过get_source()从Source_file配置中挑选对应的system_ht32f5xxxx_xx.c系统初始化源文件与驱动源文件，从而做到“选芯片即自动配 CMSIS 系统文件”。

4.3 内核选择与启动文件的联动

在 bsp/ht32/ht32f52352/board/Kconfig 中，芯片内核通过CORTEX_M0/CORTEX_M3选项选择，并据此select SOC_SERIES_HT32F5或SOC_SERIES_HT32F1。板级 SConscript 再根据rtconfig.CROSS_TOOL选择对应启动文件：

• gcc：Source/GCC/startup_ht32f5xxxx_gcc_01.s
• keil：Source/ARM/startup_ht32f5xxxx_01.s
• iar：Source/IAR/startup_ht32f5xxxx_iar_01.s

启动文件完成向量表、堆栈初始化后跳转到SystemInit()（定义于system_ht32f5xxxx_xx.c），再进入 RT-Thread 的entry。这条链路表明 CMSIS 提供的SystemInit、core_cm*.h与启动汇编一起，构成了 HT32 BSP 复位后的最小运行环境。

4.4 版本号的源码依据

bsp/ht32/libraries/HT32_STD_5xxxx_FWLib/library/CMSIS/Include/cmsis_version.h 中定义了 CMSIS-Core(M) 的版本宏：

#define __CM_CMSIS_VERSION_MAIN ( 5U) /*!< [31:16] CMSIS Core(M) main version */ #define __CM_CMSIS_VERSION_SUB ( 6U) /*!< [15:0] CMSIS Core(M) sub version */

即当前 CMSIS-Core(M) 为5.6.0，与ARM.CMSIS.pdsc中 5.9.0 发布说明（CMSIS-Core(M): 5.6.0）一致。同时，core_cm3.h的@version V5.1.2、core_cm0plus.h的@version V5.0.9、cmsis_gcc.h的@version V5.4.1等头文件级版本标注也随包可见，方便开发者在排查编译问题时核对具体头文件版本。

五、CMSIS 目录结构约定（README 对照）

README 给出了 CMSIS 5 源码仓的标准目录布局，仓库内 FWLib 的library/CMSIS正是按其中Core子集精简而来：

在 bsp/ht32/libraries/HT32_STD_5xxxx_FWLib/library/CMSIS/Core/Include 中可以看到这些目录约定的直接对应物：Core/Include即CMSIS/Core的头文件部分，Core/Template/ARMv8-M即安全扩展模板。理解这套命名规范，有助于你快速在任何 CMSIS 5 工程中定位“核心寄存器定义”“编译器适配层”“MPU/Cache/TrustZone 扩展”等文件。

六、编译器抽象层：一份代码，四套工具链

CMSIS 5 的移植性核心在于编译器适配头文件。仓库Include/与Core/Include/中成对出现的四个文件，分别面向主流工具链：

• cmsis_armcc.h：Arm Compiler 5（ARMCC / Keil MDK）
• cmsis_armclang.h：Arm Compiler 6（armclang / Keil MDK AC6），另有cmsis_armclang_ltm.h用于链接时多义（LTM）场景
• cmsis_gcc.h：GNU GCC（RT-Thread 的rtconfig.py默认CROSS_TOOL = 'gcc'时即走此路径）
• cmsis_iccarm.h：IAR Embedded Workbench

它们通过cmsis_compiler.h统一派发：cmsis_compiler.h根据__ARMCC_VERSION、__clang__、__GNUC__、__ICCARM__等编译器宏自动选择对应实现，并定义统一的__STATIC_INLINE、__ASM、__attribute__等抽象宏。正因如此，同一份core_cm0plus.h才能在 RT-Thread 的 GCC 构建、Keil 工程（project.uvprojx）与 IAR 工程（template.ewp系列）中无差别编译。值得一提的是，cmsis_gcc.h等文件头部带有#pragma system_header/#pragma system_include类声明（对应 clang/IAR 路径），使 CMSIS 头文件在 MISRA 检查与编译告警中被视为系统头文件，从而降低第三方代码带来的告警噪音。

七、CMSIS 5 的关键增强与演进方向

README 中列出的“已实现增强”包括：

• 提供 Windows/Linux 均可用的CMSIS-Pack 生成 shell 脚本模板；
• 支持通过 Eclipse 菜单Window - Preferences - CMSIS Packs - Manage Local Repositories与 Keil MDK 的 Pack 安装界面进行CMSIS-Pack 的 Git 工作流管理；
• CMSIS-Zone 1.0 发布，支持多处理器、TrustZone 与 MPU 配置；
• 支持Armv8.1-M 架构与 Cortex-M55（2020 年 3 月发布）；
• CMSIS-DSP 全面移植到 SIMD，面向 Cortex-M 家族（Armv8.1-M）以及带 NEON 的 Cortex-A/Cortex-R，且保持 API 兼容。

“进一步规划”则集中在 CMSIS-Pack 的SDF 系统描述格式（描述比 Debug Description 更复杂的调试拓扑）、CPDSC 工程文件格式（IDE 无关的工程模板）与CMSIS-Build 命令行构建系统（面向 CI 测试）上。仓库内ARM.CMSIS.pdsc中 5.9.0 的发布说明还补充了本包携带的更新：Cortex-M85 与 Arm China STAR-MC1 内核支持、CMSIS-NN 3.1.0 的 int16 卷积/池化与 int8 膨胀卷积优化、CMSIS-DSP 1.10.0 等，说明这份随 HT32 FWLib 分发的 CMSIS 已涵盖到较新的 Arm 内核特性（core_cm85.h、core_starmc1.h的存在即为佐证）。

八、生成文档与打包发布（README 操作指南）

README 说明，CMSIS 5 的 GitHub 开发仓不预置 RTOS/RTOS2 的预编译库，要生成完整软件包需要自备构建环境。打包发布所需工具及版本如下：

在 Windows PC 上可据此生成两类产物：

• CMSIS 文档：运行./CMSIS/Doxygen下的批处理脚本gen_doc.sh；
• CMSIS 软件包：运行./CMSIS/Utilities下的批处理脚本gen_pack.sh（该脚本不生成文档，且仓库内不包含 RTX4/RTX5 预编译库）。

此外，./CMSIS/DoxyGen/How2Doc.txt描述了创建 API 文档的书写规则，适合需要为自有库编写 Doxygen 注释的开发者参考。对大多数使用 RT-Thread HT32 BSP 的开发者而言，本仓库已经以源码形式打包好了 CMSIS 头文件，无需重复执行打包流程，直接用 SCons 或 Keil/IAR 工程编译即可。

九、许可协议与贡献约定

CMSIS 采用Apache License 2.0许可（仓库内 LICENSE.txt 同步携带）。README 明确：贡献代码同样在 Apache 2.0 下被接受，且只接受全部由你本人编写的代码提交。issue 管理约定了一整套标签语义，用于让社区反馈可被高效分类处理：

• bug：确认的缺陷，将进行调查；
• wontfix：认可但不改动现有行为；
• enhancement：即将实现的新特性；
• future：尚未排期的内容；
• out-of-scope：与 CMSIS 关联较弱、可能在 CMSIS 之外实现；
• question：需要进一步澄清的问题；
• documentation：文档缺陷，后续改进；
• review：评审中，请耐心等待；
• DONE：已解决，请复核并关闭；
• duplicate：已在他处处理，见评论中的引用；
• Important Information：关于重大增强的关键信息。

十、在 RT-Thread 工程中使用 CMSIS 的实用要点

结合仓库实际情况，归纳几条可直接落地的经验：

1. 不要手动复制 CMSIS 头文件：bsp/ht32/libraries/HT32_STD_5xxxx_FWLib/library/CMSIS/Include已由 固件库 SConscript 加入编译路径，Keil/IAR 工程（project.uvprojx、template.ewp）同样引用此目录，新增工程时保持该 include 路径即可。
2. 核对__CORTEX_M宏：core_cm3.h中__CORTEX_M (3U)、core_cm0plus.h中对应的 0/0+ 定义由设备头文件或工程宏决定，编译时需确保与所选芯片一致，否则可能触发断言或错误的寄存器访问。
3. 版本可追溯：通过cmsis_version.h的__CM_CMSIS_VERSION与各头文件@version注释核对 CMSIS-Core(M) 版本（本仓库为 5.6.0），遇到编译器报错可先确认工具链适配头文件（cmsis_gcc.h等）是否被正确选中。
4. 启动链路完整闭环：复位后执行顺序为 启动汇编 →SystemInit()（system_ht32f5xxxx_xx.c）→ RT-Thread 入口。若修改了时钟配置，优先检查system_ht32f5xxxx_xx.c中与Source_file选择对应的系统初始化函数。

总之，这份随 HT32 FWLib 分发的 CMSIS Version 5 是连接 Holtek 外设寄存器与 RT-Thread 内核、驱动框架之间的标准化桥梁。理解它的组件划分、目录约定与构建接入方式，是高效开发 HT32 系列 BSP 工程的第一步，也是阅读bsp/ht32下三个评估板工程（ht32f12366、ht32f52352、ht32f53252）源码的基础。

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS