本文以一次RA6B1专用发行包从2.1.0升级到`2.2.0的实践为观察样本。不同发行渠道中的版本号、目录名和e² studio界面可能略有差异，但升级方法与风险控制思路是相通的。
不少人第一次升级FSP灵活配置软件包，会把它理解成“在配置界面里换个版本，再点一下Generate Project Content”。这个动作确实是升级入口，却远不是升级的全部。
对RA6B1这类集成BLE、CMAC、FreeRTOS、非易失存储，甚至Bootloader/OTA的工程来说，FSP升级实际会同时影响：
BSP、外设驱动和中间件源码；
自动生成的实例、配置头文件和中断向量；
BLE静态库、CMAC Firmware等二进制组件；
编译器、链接库、链接脚本和IDE构建元数据；
API、寄存器位定义以及回调时序；
Flash分区、持久化数据和升级链路。
因此，真正可靠的目标不是“编译通过”，而是证明新FSP下的配置、二进制组件、内存布局和运行行为仍然一致。
一、先理解：FSP升级到底升级了什么
FSP不是一个可以随意拆换的单独驱动，而是一组经过配套验证的CMSIS Pack、驱动、中间件、第三方组件和代码生成规则。Renesas官方也明确提醒：FSP组件按整包进行测试，不建议混用不同版本的模块，否则可能带来支持和兼容性问题。
层级 | 典型内容 | 升级时的 处理原则 |
配置源 | configuration.xml、时钟、引脚、Stack、BSP属性 | 通过配置器迁移并人工复核 |
FSP生成 内容 | ra、ra_gen、ra_cfg，或发行包中的同类目录 | 使用目标版本完整重新生成 |
工程元数据 | .cproject、组件清单、构建配置 | 检查编译器宏、库和脚本是否被改写 |
应用代码 | 任务入口、业务模块、板级适配层 | 根据新API和新时序做兼容修改 |
产品资产 | Bootloader、链接脚本、镜像打包、烧录脚本、持久化数据 | 独立复核，不能假设生成器会替你维护 |
这里最重要的认识是：
configuration.xml是配置源，而旧版本生成出来的源码、Makefile和二进制库只是旧配置的产物。
修改FSP版本后，如果没有重新生成工程内容，就不能使用旧的构建文件证明升级成功。
二、升级前：先建立一个可回退的基线
1. 冻结旧版本的可运行状态
升级前至少记录以下信息：
当前FSP、e² studio和Arm GCC版本；
MCU完整料号、封装和目标板类型；
所有Build Configuration的编译结果；
ELF、BIN、MAP的大小、哈希和关键地址；
当前中断分配、时钟频率、引脚配置；
板测结果和关键运行日志；
BLE、低功耗、Flash、Bootloader、OTA等功能的已知正常行为。
建议给旧版本打一个Git Tag，并保存一份可以实际启动的固件。这样升级失败时，回退的是一个经过验证的完整状态，而不是“印象中的旧代码”。
先读Release Notes，再打开工程
2. 先读Release Notes，再打开工程
重点搜索以下内容：
Breaking Changes、Known Issues、Migration；
MCU/BSP、BLE、Flash、UART、Timer、FreeRTOS；
链接脚本和内存段命名变化；
编译器、J-Link和e² studio的最低版本；
安全漏洞修复和必须重新生成的组件。
不要只看FSP的版本号。e² studio、FSP Pack和工具链之间存在兼容关系，目标FSP支持的IDE与编译器版本应以对应发行说明为准。
3. 升级必须在独立分支或副本上进行
推荐流程：
旧版稳定基线
↓
建立升级分支
↓
只迁移FSP并重新生成
↓
提交一次“纯生成差异”
↓
再修改应用兼容代码
↓
提交运行问题修复
把“生成器造成的变化”和“人工修改的业务逻辑”放进不同提交，代码审查会轻松很多。后续如果发现某个行为回归，也能快速判断问题来自FSP还是应用适配。
三、在e² studio中执行版本迁移
1. 安装目标FSP及匹配工具
先安装目标FSP Pack，并确认e² studio能识别它。如果工程使用指定版本的GCC，也要在工具链集成设置中确认该版本可用。
对于RC、内部发布或芯片专用Pack，更要确认以下组件来自同一套发行物：
MCU/BSP Pack；
FSP驱动与中间件；
BLE Host/Controller Library；
CMAC Firmware；
FreeRTOS/CMSIS Pack；
编译器相关的预编译库。
2. 导入工程并切换FSP版本
用新环境导入工程，打开configuration.xml。如果IDE弹出迁移提示，确认后继续；如果没有提示，可在BSP或Summary页面选择目标FSP版本。
不建议直接用文本编辑器批量替换版本号。配置器除了更新顶层版本，还会重新选择匹配的组件、补充新增属性，并迁移组件元数据。手改一个#FSPVersion#无法完成这些工作。
切换后先检查：
Board、Device、Core、封装是否正确；
RTOS和Toolchain是否仍是预期选项；
Clocks与Pins页面是否出现错误或警告；
Stacks中是否有红色依赖项、失效模块或新增必填属性；
Components中所有Renesas组件是否已经统一到目标版本。
3. 保存配置并重新生成
点击Generate Project Content，让目标FSP重新生成完整工程内容。
建议生成前删除或隔离旧Build输出目录，避免旧对象文件、旧依赖文件或旧Makefile被继续使用。生成后再执行Clean Build，且不要只编译默认Debug配置。
如果工程包含Debug、Release、Bootloader、OTA等多个配置，应逐一确认：
宏定义；
头文件搜索路径；
静态库搜索路径；
链接脚本；
Post-build命令；
输出镜像格式。
四、生成之后，重点审查这六类差异
1. 组件版本是否真的统一
不要只检查configuration.xml顶部的FSP版本，还要确认所有BSP、FreeRTOS、CMSIS、HAL、中间件和板级Pack都已经迁移。
本次RA6B1升级中，版本变化同时覆盖了BSP、FreeRTOS、BLE、NVMC、UART、Timer、BLE ABS、CMSIS等组件。只替换某一个库会形成“头文件是新版本、实现却是旧版本”的危险组合。
2. 预编译库和固件是否配套
RA6B1的BLE不是只有C源码。至少要把下面三者视为一个不可拆分的版本单元：
BLE API/Header+ BLE 静态库+ RA6B1 CMAC Firmware
三者不一致时，编译和链接仍可能成功，但运行中可能出现初始化失败、HCI/CMAC异常、功能缺失或难以复现的时序问题。
本次升级还观察到熵源库的目录和库名发生变化。类似变化必须同步反映到所有Build Configuration的Linker Library和Library Search Path中，不能只修一个Debug配置。
3. 自动生成的中断向量与安全属性是否改变
Stack或驱动新增一个IRQ后，后续向量号可能整体后移。对普通工程，这会影响中断表；对TrustZone或安全分区工程，还会影响中断的Secure/Non-secure属性。
检查重点包括：
新增或消失的IRQ；
ISR名称和向量号；
ICU/Event Link配置；
安全分区文件中的IRQ属性；
应用中是否硬编码了向量号。
原则上，应用代码应该使用生成的符号，而不是记住某个具体IRQ数字。
4. 寄存器字段和API语义是否变化
如果应用直接访问寄存器，FSP升级风险会明显增加。本次升级中，温度传感器控制位的字段名就发生了变化。此类问题通常表现为编译错误，但更危险的是“名称还在，语义已经改变”。
建议对以下内容做全文检索：
R_*、RM_* FSP API；
*_REG_b等直接寄存器访问；
FSP枚举值和结构体初始化；
回调函数签名；
const、长度、单位和返回码变化。
不要为了消除编译错误直接强制类型转换。先查目标版本API文档，确认参数所有权、生命周期和单位是否变化。
5. 配置默认值是否被新版本改写
代码生成器可能为新增属性写入默认值，也可能改变旧属性的推荐值。生成后要逐项检查与产品行为相关的配置，例如：
Flash是否使用BGO；
参数检查等级；
BLE Bond数量和持久化开关；
低功耗、Tickless和系统定时器；
UART FIFO/DMA；
Headerless Image、TrustZone和安全启动选项。
如果应用的Flash适配层按同步接口设计，却被配置成BGO异步模式，代码可能编译正常，但擦写流程会在运行期失效。要么保持同步模式，要么实现完整的异步状态机，不能只改一个布尔开关。
6. 链接脚本和产品内存布局是否被覆盖
带Bootloader或OTA的工程，链接地址就是产品协议的一部分。
FSP重新生成后必须确认：
Vector起始地址；
Application Link Address；
Bootloader、Application、Staging区域边界；
Bond、设备地址、密钥等持久化区；
镜像头、CRC、签名和最大镜像长度；
烧录脚本、调试Launch Profile与实际布局是否一致。
不要只看GNU size的text数值。最终应从MAP、ELF Program Header、BIN/IMG文件长度和Post-build输出交叉确认。
如果项目维护了自定义内存分区，推荐使用一个“应用维护的链接脚本包装层”去加载FSP生成脚本。这样重新生成时，产品分区约束不会被悄悄恢复成整片Flash。
------------ END ------------
