企业官网建设流程全解析

1. 项目背景与移植思路拆解

1.1 这套ClassB库到底是干什么的

这次折腾的是 ST 官方的 X-CUBE-CLASSB 代码往 MDK 工程里移植的事。简单说，X-CUBE-CLASSB 是意法半导体提供的一个功能安全自检库，面向的是需要过 IEC 61508 / IEC 60730 Class B 认证的家电、工控类产品。它能在 MCU 上电启动时以及运行期间，对 CPU 内核、Flash、RAM、时钟、ADC 等关键部件做一轮周期性自检，一旦检测到异常就进入安全状态，避免设备带病运行。

很多人一听到“功能安全”就发怵，觉得这东西离自己很远。但事实上，国内做家电控制器、电动工具、传感器仪表、工业面板的团队，很多都绕不开这个库，尤其是出口欧洲的产品，对 Class B 认证几乎是硬指标。X-CUBE-CLASSB 的价值就在于，它把 STM32 上最繁琐的底层自检逻辑全部封装好了，我们只需要把它正确移植进工程、配置好检测范围和错误处理，就能拿到一套现成的安全框架。

1.2 为什么 MDK 下移植会“文件多到头疼”

标题里“文件移植太多”这个描述非常真实。我第一次解压 X-CUBE-CLASSB 的压缩包时也愣了一下：里面既有 Middlewares、Drivers、Projects，又有大量文档、脚本、BSP 例程，光源文件就有几十个。很多人第一步就栽在文件筛选上，不知道怎么分辨哪些是必须的、哪些只是例程引用，干脆一股脑全部加入 MDK 工程，结果编译错误刷了满屏。

更麻烦的是这套库本身的设计就不是“复制粘贴就能用”的。它需要根据目标芯片系列配置宏定义，需要修改 MDK 启动文件，需要调整分散加载文件，还牵扯到 ARM Compiler 5 和 6 的汇编语法兼容问题。官方例程大多基于 SW4STM32 或 IAR，MDK 工程往往不完整，这也是网上“MDK 移植 X-CUBE-CLASSB”相关问题特别多的原因。

1.3 移植前必须想清楚的三个问题

在我动手之前，建议所有人都先想清楚三件事，否则后面改起来很痛苦。

第一，你的目标芯片是哪个系列。X-CUBE-CLASSB 的代码是分系列的，STM32F0、F3、G0、G4、L4、F7 等各自有对应版本。宏定义里要指定系列型号，比如MCU_STM32G0xx、MCU_STM32F0xx，选错了编译倒是能通过，但寄存器地址对不上，自检结果就没有意义。

第二，你打算用哪个编译器。MDK 从 5.37 开始默认装的是 armclang（AC6），而很多旧版本 ClassB 库的汇编文件是按 ARM Compiler 5（AC5）语法写的。如果直接用 AC6 编译，汇编文件会大量报错，这属于最常见也最劝退的问题。稳妥的做法是确认你的 ClassB 版本是否支持 AC6，不支持就回到 AC5，或者做汇编语法迁移。

第三，启动阶段的检测要覆盖多全面。ClassB 启动自检会明显延长上电到 main 函数的时间，从几毫秒到几十毫秒不等，看 Flash 大小和检测项多少。有些产品对启动时间很敏感，那就必须在移植时就要裁剪检测项，而不是等移植完再回头看。

2. 开工前的环境准备与版本匹配

2.1 MDK 版本与编译器选型建议

我用的是 Keil MDK 5.38a，核心问题不在 MDK 版本，而在编译器选择。如果工程用的是 AC6，建议先用官方较新的 X-CUBE-CLASSB 版本，比如 V2.0 以后的，这类版本对 armclang 的兼容性做了适配。老版本 V1.x 的汇编文件在 AC6 下会报A1137E: Unexpected characters at end of line这类错误，基本没法直接跑。

如果你手头的项目还是老工程，用的是 ARM Compiler 5，那就更省事，老版 ClassB 库直接能用，不必升级库。不过 AC5 和 AC6 混着用会有个坑：启动文件里的汇编指令可能不一样，尤其是Reset_Handler中要插入的BL CLASSB_Init调用，在两种编译模式下写法基本相同，但没有.syntax unified之类标记时会解析失败。

我的建议是：新工程一律用 AC6 + 新版 ClassB，老工程如果依赖太多 AC5 特性，就保持 AC5，不折腾编译器版本。

2.2 素材来源与目录规划

X-CUBE-CLASSB 库一般从 ST 官网或者 Cube 软件包下载，解压后目录大概是下面这样：

en.x-cube-classb/ ├── Documentation/ ├── Drivers/ │ ├── BSP/ │ └── CMSIS/ ├── Middlewares/ │ └── ST/ │ └── STM32_ClassB/ │ ├── classb_application.c/.h │ ├── classb_config.h │ ├── classb_core.c │ ├── classb_core_asm.s │ ├── classb_error.c/.h │ ├── classb_interface.c/.h │ ├── classb_os.c/.h │ ├── classb_runtime.h │ ├── classb_safety.h │ └── classb_startup.c/.h └── Projects/ └── ...

注意，Projects下是官方例程，里面可能有 MDK 子目录，但很多版本只给了 SW4STM32 或者 IAR 的例程，MDK 工程不全。真正的“核心代码”全部在Middlewares/ST/STM32_ClassB目录里，其它目录基本都是例程辅助资源，不用全加进来。

我移植时习惯把Middlewares/ST/STM32_ClassB整个目录拷贝到自己的工程源码目录下，比如app/classb/，这样后续升级库版本时直接替换目录就行，不会把很多无关的 example 文件混进工程。

2.3 工程编码与 MDK 全局设置

这个小细节很影响体验，但很多人第一次没注意。ClassB 源码里有少量注释包含非 ASCII 字符，而 MDK 在 Windows 中文系统上默认的源码编码可能是 ANSI（GBK），ST 的源码通常是 UTF-8，于是打开.c/.h文件后中文注释全是乱码，甚至有时会导致编译告警乱码提示看不懂。

处理方式：在 MDK 菜单Edit -> Configuration -> Editor里，把Encoding改成UTF-8 Without Signature。如果你的现有工程是老工程，整文件全是 GBK 中文注释，不建议直接切换全局编码，否则老代码会变成乱码。可以先把这个设置只针对新建文件生效，或者用 VS Code、UltraEdit 等工具批量把老源文件转成 UTF-8，再统一设置为 UTF-8 环境。这里最容易踩的坑是：转移完文件之后，编译器不报错但注释乱码，其实是 BOM 导致的，尽量保存为无 BOM 的 UTF-8，MDK 兼容性更好。

同时，在Project -> Options for Target -> C/C++ (AC6)里确认 Language C 选择了gnu11或c99，ClassB 库对语法版本要求不高，但别选成老旧的c90，有些变量声明会不通过。

3. 完整移植步骤：把 ClassB 塞进 MDK 工程

3.1 确认最小文件集合

很多人被“文件多”劝退，其实就是没搞懂最小集合。我整理了一份在 MDK 工程里真正需要添加的文件清单，按功能分组：

Drivers/BSP下的文件通通不用加，那是官方板子用的。Projects下的main.c、stm32xx_it.c也不需要加，那只是参考例程。加了反倒会跟自己的工程文件冲突，最常见的就是system_stm32xx.c和启动文件重复定义。

3.2 工程添加源文件与头文件路径配置

在 MDK 的Project窗口里，把上表列出的.c和.s文件添加进工程，建议新建一个分组叫ClassB，方便管理。添加时要注意.s文件类型，把classb_core_asm.s的Options里Assembler Architecture设置成Any或ARM，不要让它被当成 C 文件编译。

头文件路径需要添加以下几类：

• app/classb/存放 ClassB 核心源文件目录
• app/classb/interface如果有，就加上
• Drivers/CMSIS/Include如果工程没配过
• Drivers/CMSIS/Device/ST/STM32G0xx/Include按自己芯片系列来

很多编译报错fatal error: classb_config.h: No such file or directory，八成是头文件路径没加全。还有一种情况是工程里有两个同名文件，比如其它目录也有一个classb_config.h，MDK 会按包含顺序先找到错误的那个，导致宏配置错乱。我建议在自己的 ClassB 目录里只保留一份classb_config.h，并把它放在所有包含路径的前面。

3.3 宏定义、汇编选项与启动文件修改

每个系列的 ClassB 库都依赖一系列预处理宏。以 STM32G0 为例，我工程里加的宏是这样写的：

MCU_STM32G0xx RUN_IN_RAM CLASSB_USE_FLASH_ECC CLASSB_USE_SYSTICK

关键宏说明：

• MCU_STM32G0xx：指定芯片系列，必须和实际型号对应。
• RUN_IN_RAM：让 CPU 自检代码在 RAM 中运行。推荐默认开启，因为 CPU 自检会破坏 Flash 预取缓冲和流水线状态，如果在 Flash 上运行，行为会发生不可预期的问题。
• CLASSB_USE_FLASH_ECC：如果 MCU 支持 Flash ECC，打开这个宏可以做 ECC 错误检查。
• CLASSB_USE_SYSTICK：允许 ClassB 库使用 SysTick 做超时判断，移植时如果工程已经用了 SysTick，要注意是否冲突。

然后是启动文件的修改。打开 MDK 工程里的startup_stm32g0xx.s，找到Reset_Handler，在SystemInit之后、进入__main之前，插入一行调用CLASSB_Init：

Reset_Handler LDR R0, =SystemInit BLX R0 ; 插入 ClassB 启动自检 LDR R0, =CLASSB_Init BLX R0 LDR R0, =__main BX R0

注意CLASSB_Init这个函数是在classb_startup.c里实现的。有些库版本里可能叫ClassB_StartUpSelfTest，具体看头文件说明。如果你在链接时报Undefined symbol CLASSB_Init，先去找这个函数真实名称，不要照抄网上的代码。

还有一点容易被忽略：启动文件里插入的调用，必须保证在调用前栈已经初始化。MDK 的启动文件里__initial_sp和栈初始化在 Reset_Handler 开头已经做了，所以把CLASSB_Init放在SystemInit之后一般没问题。

3.4 分散加载文件与 RAM 运行区域配置

如果开启了RUN_IN_RAM，就一定要配置分散加载文件，把 ClassB 的代码段放到 RAM 中。MDK 默认使用Use Memory Layout from Target Dialog，需要先把它关掉，改成自定义分散加载文件。

我的做法是：在工程目录下新建classb.sct，内容大致如下：

LR_IROM1 0x08000000 0x00010000 { ER_IROM1 0x08000000 0x00010000 { *.o (RESET, +First) *(InRoot$$Sections) .ANY (+RO) .ANY (+XO) } RW_IRAM1 0x20000000 0x00002000 { .ANY (+RW +ZI) } RW_CLASSB_CODE 0x20002000 0x00002000 { classb_core.o (+RO) classb_startup.o (+RO) classb_application.o (+RO) } }

这个RW_CLASSB_CODE不是固定写法，本质是单独开一段 RAM，把 ClassB 相关的代码段映射进去。具体偏移和大小要根据芯片 RAM 总量来算。以 STM32G0B1 为例，RAM 是 144KB，但我实际只给 ClassB 预留了 8KB，剩下的留给用户变量和系统堆栈。如果你的芯片 RAM 较小，比如只有 8KB，那就要谨慎规划，否则编译时会报L6406E: No space in execution regions。

这里要特别提醒：ClassB 自检会破坏部分 RAM 区，所以不要把系统关键变量、RTOS 内核控制块和堆栈放在自检覆盖的区域内。分散加载文件里必须给它们划分出独立且不重叠的区域。

3.5 应用层接入：周期自检与错误处理

到了这一步，工程应该能编译过了，接下来是业务层的对接。

ClassB 库在启动阶段调用CLASSB_Init后，会自动完成启动自检。之后在 main 函数里，我们需要周期性调用应用自检接口：

while (1) { if (CLASSB_ApplicationSelfTest()) { /* 自检通过，业务正常运行 */ } else { /* 自检失败，进入错误处理 */ Error_Handler(); } }

CLASSB_ApplicationSelfTest()内部会执行 RAM、Flash、CPU、ADC 等项的检测，返回CLASSB_FALSE时说明某项测试失败。注意这个函数不是实时的，每次调用耗时取决于检测范围和数据量，从几百微秒到几十毫秒都有可能，所以别把它放在中断服务函数里，尽量放在主循环或低优先级任务里。

错误处理默认实现在classb_error.c或classb_interface.c中，通常是一个空循环：

void CLASSB_ErrorHandler(void) { while (1) { /* 用户可在这里加入故障指示，比如点亮故障灯、输出故障状态 */ } }

实际产品中不要让它空转，最好在这里点亮故障 LED、拉高故障电平输出、或者进入低功耗安全模式。如果系统接了上位机，还可以通过串口打印错误码，以便排查具体是哪个检测项失败。

4. 关键模块原理与代码衔接

4.1 CPU 自检为什么必须用汇编

ClassB 库的classb_core_asm.s是整个库中最核心也最难懂的部分，CPU 自检必须用汇编来实现。原因很简单：C 语言编译器会优化、会调整指令顺序，而且 C 语言层面看不到寄存器级别的工作状态，比如进位标志、溢出标志、饱和运算等。Class B 自检要求对 CPU 的算术逻辑单元、寄存器组、控制状态寄存器做全指令集测试，这一层只能用汇编直接操作。

这里有个大家常问的点：这个自检到底测什么？简单说，它会把 CPU 内部的通用寄存器 R0 到 R12、状态寄存器、乘法除法单元、单周期/多周期指令模式都跑一遍，用已知的输入数据和校验结果做比较。如果某个位发生物理性故障，比如寄存器粘连、加法器出错，测试值对不上，就判定 CPU 异常。

也正因为自检会破坏所有寄存器内容，所以CLASSB_CPU_SelfTest()在运行期间要求关闭中断，并且不能依赖 C 函数栈帧。库内部理论上会做寄存器保存和恢复，但在移植接入时最好也避免在调用它的临界区里嵌套其它依赖中断的操作。

4.2 RAM 和 Flash 检测的破坏性与恢复机制

ClassB 库对 RAM 的检测是采用“写-读-比较”的方法，会先往目标 RAM 区写入测试图案，再读出来比对。这就意味着被测试的 RAM 内容会被覆盖。启动自检时 RAM 还没被业务使用，可以放心测试；但运行阶段的周期自检就必须考虑破坏性了。

所以库提供了CLASSB_RAM_AREA_SECTORS这类配置，用于指定 RAM 分块。你可以把 RAM 分成多个扇区，每个自检周期只测试一个扇区，并且测试前把该扇区的数据缓存到安全区域，测试完再恢复。这个过程要保证业务数据不丢，逻辑比较复杂。如果项目对数据可靠性要求高，建议在自定义分区时把关键变量放在不被检测的区域，只在内存充足的情况下对剩余 RAM 做全检测。

Flash 检测通常是计算 CRC 或检测 ECC 错误。ClassB 启动自检时会遍历整个 Flash 区域，计算校验值。如果开启了 ECC，还会读取 Flash ECC 寄存器。这个检测耗时较长，我记得在 256KB Flash 的芯片上做全片 CRC 可能要几十毫秒，具体时间可以用定时器实测一下。

4.3 错误处理接口与业务如何联动

ClassB 库把“检测”和“处理”分开了。检测到错误后，库只负责调用一个错误处理回调，业务该怎么反应完全由开发人员决定。这也是它适配不同项目的关键。

我在实际项目里会把错误处理分成几个等级：

具体做法是：在CLASSB_ErrorHandler里读取CLASSB_GetErrorInfo()返回的错误结构体，把错误码保存到非易失区，然后根据错误等级执行不同策略。这里要牢记一点，ClassB 错误处理不要做太复杂的事，因为 CPU 已经处于“疑似不安全”状态，越复杂越不可靠。保持简单，能记录、能指示、能安全停机就够了。

5. 常见问题与排查技巧实录

5.1 编译报错对照表

我把这次移植过程中遇到的、以及网上高频出现的编译报错整理成了表，方便直接对照：

其中 AC5 和 AC6 的汇编问题最典型。如果你仓库里是旧版 ClassB，又确实想用 AC6，也可以手动改汇编文件，把EQU改成.equ、PROC改成.thumb_func、去掉END后注释里的特殊字符。但总体不建议大规模手改，改出错的风险远大于直接换编译器。

5.2 运行阶段故障排查思路

编译通过只是第一步，运行阶段遇到问题才真正磨人。最常见的就是程序卡在启动阶段，跑不到 main。

我之前遇到一次：程序一直停在CLASSB_ErrorHandler里，但看代码没有任何明显问题。后来通过阅读自检状态的寄存器才定位到，是因为工程里初始化时钟的方式和 ClassB 库预期不一样。ClassB 启动自检会读取CSI或HSI等时钟源状态，如果 CubeMX 生成的时钟配置把某个时钟关了，库里的时钟检测就会判定失败。

遇到这种情况，排查思路要按顺序走：

1. 在CLASSB_ErrorHandler里打断点，查看CLASSB_GetErrorInfo()返回的错误码。错误码会精确到具体测试项。
2. 根据错误码回查classb_config.h，看对应检测项是否需要开启时钟、外设、或特殊寄存器。
3. 用调试器观察启动流程，确认进入 main 之前是在哪一步卡住的。

比如错误码指向 RAM 检测失败，就要看分散加载文件里 ClassB 区域是否和其他变量区重叠了，尤其是__initial_sp所在的栈区，如果栈恰好被测试覆盖到，整个系统直接跑飞。

5.3 资源占用与周期自检耗时优化

ClassB 库虽然很省，但不是零成本。以我手头 STM32G0B1 的工程为例，把编译后的 map 文件打开看，ClassB 相关代码约占 Flash 8KB，RAM 静态区约 4KB，但这不包括运行时的局部缓冲。如果芯片资源紧张，建议关掉不必要的检测项。

classb_config.h里的开关设计得比较灵活，常见可裁剪项：

• CLASSB_RAM_ALL：是否检测全部 RAM，建议只测预留的分区
• CLASSB_FLASH_TEST_ENABLE：Flash CRC 检测，开启后耗时明显增加
• CLASSB_CLK_TEST_ENABLE：时钟频率测试，会额外占用几个毫秒
• CLASSB_ADC_TEST_ENABLE：ADC 自检，需要确认 ADC 通道是否空闲

如果你用的是 FreeRTOS 这类 RTOS，周期自检不要直接放在 tick 中断或者临界区里，最好单独建一个低优先级任务。但要注意，ClassB 的 RAM 检测会破坏 RAM 内容，如果检测区域和 RTOS 内核对象重叠，系统会莫名崩溃。我的习惯是在分散加载文件里给 RTOS 内核堆和任务栈单独规划区域，ClassB 的 RAM 测试范围只覆盖未使用的空白 RAM。这块配置逻辑不复杂，但很考验对链接脚本的理解，做之前先画一张内存地图，比直接调代码高效得多。

5.4 一个容易被忽略的编码坑

最后再说回 MDK 编码。我的经验是，从 ST 官网下载的 ClassB 库源码基本都是 UTF-8 编码，而 MDK 老工程默认以 ANSI 打开。如果你打开classb_config.h看到一堆中文注释乱码，不要以为代码坏了，这只是编码显示问题。解决办法前面提过：改编辑器全局编码为 UTF-8。

但有个隐蔽的坑是：MDK 5.x 的.uvprojx工程文件本身可能被写成 GBK，如果你用文本工具批量替换工程文件里的中文字符，一不小心就会把工程文件弄坏。我自己遇到过工程文件内容变成乱码后，MDK 直接无法导入。所以尽量不要用文本编辑器去批量改.uvprojx，只在 MDK 界面内操作，或者改用 VS Code 处理纯源码文件。

6. 移植完成后的个人建议

移植完 X-CUBE-CLASSB 之后，我个人觉得最有价值的不是“终于编译通过”那一瞬间的满足感，而是这套库逼着你把芯片的启动流程、链接脚本、时钟树、错误处理机制都重新过了一遍。原来写业务代码的时候，很少有人会关注上电复位到 main 函数之间发生了什么，而 ClassB 移植恰恰把这些底层细节全部翻了出来。

如果后续你还打算做更完整的功能安全，建议把注意力放在两个方向：一是把错误记录做得更完善，比如把故障类型、故障时刻、运行环境参数保存到备份寄存器或外部 EEPROM，便于售后分析；二是把周期自检和业务关键路径结合起来，在产品的核心控制循环里加入自检节奏，而不是只放在主循环末尾空跑。

最后再分享一个小技巧：移植第一阶段不要追求全功能，先把classb_config.h里所有检测项关到最少，确保启动自检能正常跑完，再逐个开启检测项验证。这个思路听起来很保守，但实际排查问题时能省下大量时间，比一次全开然后对着错误码猜原因高效多了。