在瑞萨 RA MCU 的 FSP(Flexible Software Package)工程里,避免用户代码被覆盖的核心原则一句话概括:配置改在 FSP,行为写在用户代码。凡是 FSP 能根据图形化配置重新生成的文件 —— 比如 ra_gen 生成目录、ra_cfg 配置数据库、common_data.c、hal_data.c 以及生成实例的初始化结构体 —— 都不要写入产品业务逻辑;状态机、通讯协议、控制算法、故障策略、数据处理和参数管理这些产品行为,应放到 src/app 应用层,入口文件只负责启动编排,回调函数只做轻量通知。合格的工程应该可以随时执行 Generate Project Content 重新生成,而不丢失产品功能。代码被覆盖本质上不是 FSP 出了故障,而是配置、生成结果和产品逻辑混在了同一层;靠目录分层、用户封装、回调规范、版本控制差异审查和受控升级,就能把这类风险管住。
一、先理解 FSP 的代码生成机制
FSP 采用 "配置与代码分离" 的思路:配置负责描述系统,代码负责实现功能。Smart Configurator 读取配置后生成底层工程代码,理解这一点是判断 "哪些文件会被覆盖" 的前提。
| 目录 / 文件 | 作用 | 与生成的关系 |
|---|---|---|
| ra/ | FSP 核心框架库,含 arm(CMSIS 标准组件)、board(BSP 板级支持)、fsp(接口定义 inc 与驱动实现 src) | 框架源码,一般不随每次生成重写;调试或修 bug 时可读可临时改 |
| ra_cfg/ | FSP 配置数据库,描述引脚、时钟、外设实例等系统配置 | 由配置工具维护,不要手工塞业务代码 |
| ra_gen/ | 根据 ra_cfg 自动生成的初始化代码、驱动实例代码 | 重新 Generate 后可能被覆盖,原则上不手动修改 |
| src/ | 用户应用代码区,编写业务逻辑和功能实现 | 用户代码主场,生成流程不会覆盖这里 |
| script/ | 构建脚本、链接脚本等工程配置 | 链接脚本改动需单独管理,避免升级时被覆盖 |
| Debug/ | 编译输出(elf、map、hex 等) | 构建产物,不纳入手工修改 |
| configuration.xml | Smart Configurator 配置文件 | 纳入版本管理,作为配置变更的追溯依据 |
判断某个文件能不能放产品代码,用一句话:删掉该文件后,FSP 能否按图形配置重新生成它;能重新生成,就不要把产品逻辑写进去。
二、划清覆盖边界:改动应该放在哪里
| 改动类型 | 典型内容 | 正确位置 |
|---|---|---|
| 配置改动 | 波特率、ADC 通道、GPT 周期、IRQ 优先级、引脚复用、DMA 参数、时钟源等 | 回到 FSP 配置界面修改,然后重新生成 |
| 行为改动 | 状态机、通讯协议、控制算法、故障策略、数据处理、参数管理等 | 放入 src/app 应用层目录 |
三、推荐工程分层与依赖方向
工程分为生成层和应用层,依赖尽量单向:应用层调用 FSP 生成的实例和接口,生成层不反向包含产品业务模块。这样即使重新生成导致实例配置变化,影响也主要限制在 ra_gen 等生成层文件内。
project/
├── Includes/ 头文件引用视图
├── ra/ FSP框架与模块源码
├── ra_gen/ FSP自动生成的初始化代码和实例
├── src/
│ ├── hal_entry.c 应用程序入口
│ └── app/ 状态机、控制算法、产品流程
├── Debug/ Debug构建输出
├── ra_cfg/ FSP配置相关文件
├── script/ 工程脚本
├── configuration.xml FSP Smart Configurator配置文件
├── .launch 调试启动配置
└── Developer Assistance
四、用户代码落地规范
4.1 用驱动封装替代直接修改生成文件
以 FSP 生成的 UART 实例 g_uart0 为例:生成层负责定义实例,用户层定义产品需要的接口。不要在 r_sci_uart.c、common_data.c 或 hal_data.c 里插入收发状态机。
用户层封装示例:
include "hal_data.h"
include "app_uart.h"
fsp_err_t app_uart_open(void)
{
return g_uart0.p_api->open(g_uart0.p_ctrl, g_uart0.p_cfg);
}
fsp_err_t app_uart_write(uint8_t const p_data, uint32_t length)
{
return g_uart0.p_api->write(g_uart0.p_ctrl, p_data, length);
}
明确使用 SCI UART 驱动时,也可直接调用底层函数:
fsp_err_t app_uart_open(void)
{
return R_SCI_UART_Open(&g_uart0_ctrl, &g_uart0_cfg);
}
fsp_err_t app_uart_write(uint8_t const p_data, uint32_t length)
{
return R_SCI_UART_Write(&g_uart0_ctrl, p_data, length);
}
应用层只调用 app_uart_write (),不到处访问 g_uart0.p_api 或底层驱动函数。这样封装有四个好处:
- 重新生成不会覆盖 app_uart.c;
- 封装层可统一增加超时、错误处理;
- 测试时可替换实现;
- 切换通道或实例名称时,修改范围可控。
同一模式适用于 ADC、GPT、IIC、SPI、CAN、USB、Flash 和 DMA:FSP 驱动是硬件能力提供者,用户封装才是产品接口的稳定边界。
4.2 hal_entry.c 只做入口编排
hal_entry.c 通常是用户代码入口。No RTOS 配置下,hal_entry () 适合组织启动顺序和主循环调度,不适合装下所有功能;状态机、协议、算法、故障策略、数据处理、参数管理应拆到独立模块。
推荐结构:
void hal_entry(void)
{
app_board_init();
app_uart_init();
app_fault_init();
app_main_init();
while (1) {
app_main_process();
}
}
RTOS 工程中,入口和初始化方式取决于工程模板与启动架构:hal_entry.c(如果存在)通常不作为传统主循环容器;初始化代码放在相应用户入口,线程业务逻辑放在线程入口函数,任务调度和线程间通信通过线程、队列、事件标志组、信号量、互斥锁和定时器实现。
4.3 回调函数是连接点,不是业务处理器
UART、SPI、IIC、ADC、GPT 等模块通常通过 callback 机制通知应用层。回调里建议只做轻量操作:
volatile bool g_uart_tx_done = false;
void uart0_callback(uart_callback_args_t p_args)
{
if (UART_EVENT_TX_COMPLETE == p_args->event) {
g_uart_tx_done = true;
}
}
| 回调中可以做 | 回调中不要做 |
|---|---|
| 设置标志位 | Flash 写入 |
| 写入环形缓冲区 | 复杂浮点计算 |
| 复制少量固定长度数据 | 阻塞等待、长循环 |
| 发送 RTOS 信号量 | 协议全解析等全流程业务 |
回调内长耗时或阻塞操作会影响中断实时性和系统堆栈稳定性。
五、配置变更的标准流程
配置变更和产品业务修改混在一起,生成后的差异难以审查。每次修改 FSP 配置时按固定流程走:
- 提交或暂存当前可工作代码,确保可以回退;
- 在 FSP 配置界面修改 Pins、Clocks、BSP 或 Stacks;
- 执行 Generate Project Content;
- 用版本控制工具检查生成结果差异;
- 编译工程,确认无 API、回调和资源冲突;
- 在目标板做最小验证(串口收发、ADC 采样、PWM 波形、通信握手等);
- 将配置文件、生成结果和必要的用户层适配修改作为同一逻辑变更提交。
重点留意中断优先级、DMA 通道、时钟频率和引脚复用:这些变化可能不导致编译失败,却会改变运行时行为;电机控制、工业通信和低功耗项目不能省略目标板验证。
六、必须修改生成代码时的处理方式
不建议直接改生成代码,不等于生成代码不可查看或调试。定位问题、分析驱动行为或处理特殊 workaround 时,可以阅读甚至临时修改;正式项目中按优先级管理:
- 先查配置项:确认 FSP 模块属性、BSP 设置、回调和扩展配置中是否已有对应选项;
- 用户层规避:遇到驱动缺陷或芯片勘误问题,优先在用户层封装绕开;
- 独立补丁文件:确实无法避免时,把修改维护成独立补丁,明确对应 FSP 版本、修改原因、影响范围和重新生成后的应用方式。
临时改了生成代码却没有补丁、说明和重放步骤,等于把风险留给下一次生成。
七、链接脚本与 FSP 版本升级注意事项
- 链接脚本:FSP 更新时链接脚本可能被重新生成覆盖。可在资源属性中将脚本设为只读,或把自定义内存段、自定义配置放到独立的 *.ld 文件中 INCLUDE 引用;若升级后脚本未自动更新出现错误,应新建对照工程参考官方链接脚本差异,不要直接在生成脚本里堆自定义段。
- FSP 升级作为受控迁移:不要混在功能开发提交里。升级时记录旧版和目标版本,重新生成并审查差异,处理 API 变化,验证启动、时钟、引脚、通信、ADC、定时器、DMA 和低功耗路径;关键产品保留波形、通信日志和性能数据。
- 工具链版本固定:在 README、构建脚本或工程规范中记录 FSP、e²studio、编译器和关键工具版本,并写明升级流程,避免团队成员因版本不同造成生成结果差异。
八、常见错误场景与推荐替代方案
| 风险场景 | 错误做法 | 推荐做法 |
|---|---|---|
| 加调试打印 | 直接修改 r_sci_uart.c | 在 app_uart.c 或诊断模块中增加日志接口 |
| 修改 PWM 死区或周期 | 手工编辑 common_data.c 或生成结构体 | 回到 GPT Stack 配置修改参数,生成后检查波形 |
| 修改回调函数 | 直接改生成实例初始化结构体的 p_callback | 在 FSP 配置界面指定回调函数名,并在用户文件实现回调 |
| ADC 采样窗口调整 | 直接改 common_data.c | 通过 FSP 配置修改参数,在用户层封装采样管理 |
| 电流校正 | 直接改 FSP ADC 驱动 | 在用户层实现校正流程和偏置更新 |
| DMA 搬运配置 | 手工改生成的 DTC/DMAC 描述符 | 回到 FSP 配置通道和触发源,用户层只管缓冲区生命周期 |
| 团队生成结果差异大 | 成员使用不同 FSP、IDE 或工具链版本 | 在 README、构建脚本或工程规范中固定版本并记录升级流程 |
| 重新生成后代码丢失 | 从旧工程复制回临时修改继续累积 | 先把逻辑迁移到用户目录,再用 Git 对比确认生成边界 |
九、团队提交前检查清单
- 用户业务逻辑没有写入 ra_gen、ra_cfg、fsp_cfg、common_data 或 hal_data;
- Pins、Clocks、Stacks、IRQ、DMA 和外设参数全部通过 FSP 配置修改;
- 回调函数位于用户文件,回调内没有阻塞或长耗时工作;
- 新增外设已在用户层提供稳定封装接口;
- hal_entry.c 只负责入口编排,没有堆叠协议解析、控制算法或长状态机;
- 生成前后已检查 git status 和 git diff;
- 编译通过,并完成与本次变更相关的目标板最小测试;
- 若修改过生成代码,已补充补丁、问题说明和重新应用步骤;
- FSP、IDE、编译器和关键工具版本已记录;
- FSP 升级与功能开发分开提交,升级结果有迁移说明和验证记录。
十、收尾结论
自动生成代码本身不是风险,真正的风险是配置、生成结果和产品逻辑混在一起。按本文把工程分成生成层和应用层:ra/ra_gen/ra_cfg 交给 FSP 维护,src/app 承载产品行为,入口只做编排,回调只做通知,外设访问经过用户封装;配置变更走固定流程并用 Git 审查差异,链接脚本和 FSP 升级单独受控管理。工程边界清晰之后,重新 Generate Project Content 就不再是不可控操作,而是可重复、可审查、可回退的日常工程动作。
【相关 FAQ】
问题 1:瑞萨 RA MCU 的 FSP 工程里,哪些代码重新 Generate 后会被覆盖?
回答 1: 由 FSP 根据 ra_cfg 配置自动生成或维护的文件最容易被覆盖,典型包括 ra_gen 目录下的初始化代码和驱动实例、common_data.c、hal_data.c 以及生成实例的初始化结构体;ra_cfg 配置数据库也由配置工具维护。判断标准是:删掉该文件后 FSP 能否按图形配置重新生成,能重新生成的就不要放产品业务逻辑。用户代码应放在 src/app 等用户目录,生成流程不会覆盖这里。
问题 2:FSP 生成的 UART/ADC/GPT 驱动能不能直接改,怎么避免代码被覆盖?
回答 2: 不建议直接改生成的 r_xxx 驱动、common_data.c 或实例结构体。正确做法是在用户层封装一层产品接口,例如 app_uart_write () 内部调用 g_uart0.p_api->write () 或 R_SCI_UART_Write (),业务代码只依赖封装接口。这样重新生成不会覆盖 app 层代码,还能统一处理超时和错误、便于测试替换;同一模式适用于 ADC、GPT、IIC、SPI、CAN、USB、Flash 和 DMA。
问题 3:为什么在 hal_entry.c 或回调函数里写业务逻辑容易出问题?
回答 3: hal_entry.c 应只做启动初始化顺序和主循环 / 线程调度编排,状态机、协议解析、控制算法、故障策略应拆到独立用户模块;回调函数只是驱动到应用层的连接点,只适合置标志位、写环形缓冲区、发信号量等轻量操作。在回调里做 Flash 写入、复杂浮点、阻塞等待或协议全解析,会影响中断实时性和系统堆栈稳定性;把业务堆在入口文件也会让工程难以维护和移植。
问题 4:FSP 版本升级或修改链接脚本时,如何避免用户工程被覆盖?
回答 4: 链接脚本可设为只读,或把自定义内存段放到独立 .ld 文件中 INCLUDE 引用;升级后对照新建工程的官方脚本检查差异。FSP 升级要作为一次受控迁移:记录旧版和目标版本,分开提交,重新生成后审查 diff,处理 API 变化并在目标板验证启动、时钟、引脚、通信、ADC、定时器、DMA 和低功耗路径。同时把 FSP、IDE、编译器版本和补丁说明纳入 Git 管理,确保升级可追溯、可回退。
【参考资料】
[2026-11-10](瑞萨 RA MCU FSP 工程开发指南:避免代码覆盖的最佳实践)电子工程专辑・瑞萨 MCU 小百科
[2026-10-16](RZ FSP: Avoid Linker Script Overwrite During FSP Update)Renesas Customer Hub
[2026-10-01](瑞萨 RA 工程目录结构解读:为什么 FSP 会生成 ra、ra_gen 和 ra_cfg 三个目录?)电子发烧友网・RA 生态工作室
[2025-11-08](Relocate VTOR and ISRs to RAM)Renesas Engineering Community
[2025-11-08](Linker script with FSP 6.1.0)Renesas Engineering Community
[2025-10-28](RA Smart Configurator copies the files in "Source group 1" folder to "Common sources")Renesas Engineering Community
【免责声明】
本文基于截至 2026 年 11 月 13 日公开的瑞萨 FSP 开发资料、官方社区讨论与行业技术文章整理,仅供嵌入式开发学习与工程实践参考,不构成瑞萨官方技术承诺或官方开发规范的替代。不同 FSP 版本、RA 系列型号、e²studio 工具链和工程模板的目录结构、代码生成行为及配置选项可能存在差异,具体请以对应版本的瑞萨官方手册、FSP 用户手册和工程实际生成结果为准。文中示例代码需结合具体硬件、时钟与外设配置验证后使用,因直接套用或修改生成代码导致的工程异常、产品故障,由实施方自行承担风险。
本文来自作者[Ezra36]投稿,不代表海博商机网立场,如若转载,请注明出处:https://www.hb12369.net/qyzx/202611/479.html
评论列表(4条)
我是海博商机网的签约作者“Ezra36”!
希望本篇文章《瑞萨 RA MCU FSP 工程开发避坑指南生成层与应用层分层,避免重新 Generate 覆盖用户代码》能对你有所帮助!
本站[海博商机网]内容主要涵盖:互联网行业的追踪与探索
本文概览:在瑞萨 RA MCU 的 FSP(Flexible Software Package)工程里,避免用户代码被覆盖的核心原则一句话概括:配置改在 FSP,行为写在用户代码。凡是 FSP 能根据图形化配置重新生成的文件 —— 比如 ra_gen 生成目录、ra_cfg 配置数据库、common_data.c、hal_data.c 以及生成实例的初始化结构体 —— 都不要写入产品业务逻辑;状态机、通讯协议、控制算法、故障策略、数据处理和参数管理这些产品行为,应放到 src app 应用层,入口文件只负责启动编排,回调函数只做轻量通知。合格的工程应该可以随时执行 Generate Project Content 重新生成,而不丢失产品功能。代码被覆盖本质上不是 FSP 出了故障,而是配置、生成结果和产品逻辑混在了同一层;靠目录分层、用户封装、回调规范、版本控制差异审查和受控升级,就能把这类风险管住。