RT-Thread 瑞萨 RA4M2(RA-Eco-RA4M2-100PIN)BSP 实战指南:从 J-Flash 快速上电运行到 FSP/ENV 进阶外设配置
RT-Thread 瑞萨 RA4M2(RA-Eco-RA4M2-100PIN)BSP 实战指南:从 J-Flash 快速上电运行到 FSP/ENV 进阶外设配置
本篇技术指南以 RT-Thread 仓库中 bsp/renesas/ra4m2-eco/README.md 为主体,系统讲解瑞萨 RA-Eco-RA4M2-100PIN 开发板 BSP 的完整使用方法:先按“硬件连接 → MDK5 编译 → J-Flash Lite 烧录 → 串口查看 msh”的最短路径把 RT-Thread 跑起来,再深入 FSP(Flex Software Package)外设配置与 ENV(menuconfig)工程配置两大进阶路径,并结合 rtconfig.h、board/Kconfig 等仓库源码,说明每个配置项在 BSP 中的实际落地位置。读完本文,你将能够独立完成该 BSP 的上手、烧录、外设裁剪与文件系统(SD 卡)扩展。
开发板与片上资源
基于瑞萨 RA4M2 MCU 的 RA-Eco-RA4M2-100PIN 评估板,通过灵活配置软件包(FSP)和 IDE,可帮助开发者对 RA4M2 MCU 群组的特性进行评估,并对嵌入式系统应用程序进行开发。开发板常用板载资源如下:
| 资源 | 规格 |
|---|---|
| MCU | R7FA4M2AD3CFB,100MHz,Arm Cortex-M33 内核,512kB 代码闪存,128kB SRAM |
| 调试接口 | 板载 SWD 接口 |
| 扩展接口 | 两个 PMOD 连接器、Arduino Uno 接口 |
BSP 目前对外设的支持情况(继承自原 README 的支持矩阵):
| 片上外设 | 支持情况 | 备注 |
|---|---|---|
| UART | 支持 | UART9 为默认日志输出端口(对应板级引脚 P109(TXD)、P110(RXD)) |
| GPIO | 支持 | |
| SPI | 支持 | |
| 外接外设 | 暂无 | 持续更新中…… |
从源码结构看,该 BSP 的驱动能力由 FSP 生成代码与 RT-Thread 设备层两层构成:FSP 层负责寄存器级外设初始化(ra/fsp/src 下含 r_ioport.c、r_sci_uart.c 等驱动实现与 bsp_clocks.c、bsp_irq.c 等公共模块),RT-Thread 层则通过 board/Kconfig 声明可选的外设开关,二者经 ra_cfg/ra_gen 下的生成文件衔接。
BSP 目录结构与构建体系
该 BSP 仅支持 MDK5(ARM Compiler 6)工程构建,目录组织围绕“FSP 生成物 + BSP 板级代码”划分:
| 路径 | 作用 |
|---|---|
| project.uvprojx / template.uvprojx | MDK5 工程与工程模板(scons 生成时使用模板) |
| ra/fsp | FSP 设备驱动:inc/api 下为 BSP/IOPORT/SCI-UART API,src/bsp 下为启动文件 startup.c、system.c 及时钟、中断、IO 等公共实现 |
| ra_cfg/fsp_cfg | FSP 生成的配置头文件,含 bsp/board_cfg.h、bsp/bsp_pin_cfg.h、r_sci_uart_cfg.h 等 |
| ra_gen | FSP 生成的运行时数据:main.c、hal_data.c、common_data.c、pin_data.c、vector_data.c |
| script | 链接脚本:fsp.ld、fsp.scat、memory_regions.ld |
| src/hal_entry.c | 应用层入口函数所在文件,用户源码建议直接放入 src 目录 |
| board/ | 板级代码:board.h(堆内存边界)、ports/mnt.c(SD 卡挂载)、ports/gpio_cfg.h(GPIO 外部中断引脚映射) |
| Kconfig / rtconfig.py | ENV 工具的配置入口与配置转换脚本 |
启动链路上,FSP 生成的 ra_gen/main.c 极为简洁,其职责就是把控制权交给 BSP 的应用入口:
/* generated main source file - do not edit */
#include "hal_data.h"
int main(void) {
hal_entry();
return 0;
}
而 board/board.h 定义了 RT-Thread 小内存堆(RT_USING_SMALL_MEM)的边界:RA_SRAM_SIZE 声明芯片可用 SRAM 大小,HEAP_BEGIN 在 ARMCC 下取 Image$$RAM_END$$ZI$$Base 段符号,堆从已用内存段末尾一直延伸到 RA_SRAM_END,这样静态分配与动态堆天然无缝衔接。
快速上手
硬件连接
按原 README 的接线要求准备三条链路:
- 使用 USB 数据线连接开发板(串口)到 PC;
- 使用下载器连接 SWD 排针和 DEBUG 程序(调试);
- 使用 USB 转串口工具连接 UART9:P109(TXD)、P110(RXD)。
编译与下载
- 编译:双击
project.uvprojx打开 MDK5 工程,编译程序。 - 下载:该工程需要使用 J-Flash Lite 工具烧录,建议使用 V7.50 及以上版本。打开 J-Flash Lite,选择芯片型号 R7FA4M2AD,点击 OK 进入工具;选择 BSP 目录下 MDK 编译出的
object/rtthread.hex文件,点击 Program Device 按钮开始烧录。
查看运行结果
下载成功后系统会自动运行并打印系统信息。将开发板串口连接 PC,在终端工具中打开对应串口(115200-8-1-N),复位设备后即可看到 RT-Thread 输出。输入 help 命令可查看系统支持的命令(以下为原 README 附带的输出快照,对应文档编写时的 4.0.4 内核版本):
\ | /
- RT - Thread Operating System
/ | \ 4.0.4 build Oct 11 2021
2006 - 2021 Copyright by rt-thread team
Hello RT-Thread!
msh >
msh >help
RT-Thread shell commands:
reboot - Reboot System
help - RT - Thread shell help.
ps - List threads in the system.
free - Show the memory usage in the system.
hello - say hello world
clear - clear the terminal screen
version - show RT - Thread version information
list_thread - list thread
list_sem - list semaphore in system
list_event - list event in system
list_mutex - list mutex in system
list_mailbox - list mail box in system
list_msgqueue - list message queue in system
list_timer - list timer in system
list_device - list device in system
list - list all commands in system
msh >
从 rtconfig.h 中的 RT_VER_NUM 0x50300 可确认,当前仓库配置对应的内核版本号为 5.3.0,实际烧录后 version 命令输出会与该值一致。
应用入口函数 hal_entry()
应用层入口为 src/hal_entry.c 中的 hal_entry(),用户编写的源文件可直接放在 src 目录下参与工程编译。仓库中当前的默认实现只打印问候语并进入延时循环:
void hal_entry(void)
{
rt_kprintf("\nHello RT-Thread!\n");
while (1)
{
rt_thread_mdelay(500);
}
}
README 给出了一个典型的“点灯”扩展写法,展示了如何结合 RT-Thread 的引脚(Pin)设备接口与线程延时控制板载 LED:
void hal_entry(void)
{
rt_kprintf("\nHello RT-Thread!\n");
while (1)
{
rt_pin_write(LED3_PIN, PIN_HIGH);
rt_thread_mdelay(500);
rt_pin_write(LED3_PIN, PIN_LOW);
rt_thread_mdelay(500);
}
}
rt_pin_write() 依赖 RT_USING_PIN 组件(当前配置已使能),其引脚编号与 FSP 的 IO Port 引脚一一对应;若需把某 GPIO 配置为外部中断触发源,BSP 在 board/ports/gpio_cfg.h 中提供了 PIN2IRQX_TABLE 引脚到 IRQ 通道(0~15)的映射表,覆盖 Port0~Port7 上可用引脚。
进阶使用:FSP 外设配置
仓库默认使能最小体量配置(GPIO + UART)。要启用更多板载资源,需要借助 FSP 重新生成驱动文件。原 README 给出的操作流程为:
- 在 bsp 目录下打开 env 工具,使用
scons --target=mdk5命令生成 MDK 工程; - 打开 bsp 目录下的
project.uvprojx,在 MDK 顶部导航栏选择 Software Components,找到 Flex Software 下的 RA Configuration 配置按钮并打开。该操作会自动查找当前电脑安装的 FSP 版本,选择指定版本后进入 FSP; - 进入 FSP 后可看到已配置完成的外设,点击 Generate Project Content 按钮生成所需驱动文件;
- 回到 env,使能所需的外设配置后保存退出。
生成结果会体现在两类文件中:
ra_gen/下的运行时数据(hal_data.c、pin_data.c、vector_data.c等);ra_cfg/fsp_cfg/下的配置头文件。例如 ra_cfg/fsp_cfg/r_sci_uart_cfg.h 中声明了 UART 实例的编译期开关:
#define SCI_UART_CFG_PARAM_CHECKING_ENABLE (BSP_CFG_PARAM_CHECKING_ENABLE)
#define SCI_UART_CFG_FIFO_SUPPORT (0)
#define SCI_UART_CFG_DTC_SUPPORTED (0)
#define SCI_UART_CFG_FLOW_CONTROL_SUPPORT (0)
#define SCI_UART_CFG_RS485_SUPPORT (0)
这些宏决定了 ra/fsp/src/r_sci_uart/r_sci_uart.c 中是否编译 FIFO 支持、流控与 RS485 等特性代码。因此“FSP 改引脚 → 生成代码 → env 里再勾选对应 Kconfig 项”是本 BSP 扩展外设的完整闭环。
进阶使用:ENV(menuconfig)配置
此 BSP 默认只开启了日志 UART 的功能,如需使用更多高级功能(组件、软件包、文件系统),需要用 ENV 工具配置。原 README 给出的步骤:
- 在 bsp 下打开 env 工具;
- 输入
menuconfig命令配置工程,配置好之后保存退出; - 输入
pkgs --update命令更新软件包; - 输入
scons --target=mdk5命令重新生成工程。
结合 board/Kconfig 源码,menuconfig 中 Hardware Drivers Config → On-chip Peripheral Drivers 菜单下的关键配置项及其默认值如下(这些宏最终写入 rtconfig.h 并被驱动源码消费):
| 配置项 | 类型/取值 | 默认 | 说明 |
|---|---|---|---|
BSP_USING_UART |
bool | y | 总开关,自动选择 RT_USING_SERIAL 与 RT_USING_SERIAL_V2 |
BSP_USING_UART0/1/2/3/4/9 |
bool | n | 各 UART 实例开关 |
BSP_UARTn_RX_BUFSIZE |
int,64~65535 | 256 | 串口 V2 接收缓冲大小 |
BSP_UARTn_TX_BUFSIZE |
int,0~65535 | 0 | 发送缓冲大小(0 表示关闭) |
BSP_UARTn_RX_USING_DMA / BSP_UARTn_TX_USING_DMA |
bool | n | 依赖 RT_SERIAL_USING_DMA,当前 rtconfig.h 中该总开关已使能 |
BSP_USING_SPI0/1 |
bool | n | SPI 总线开关,选择 RT_USING_SPI |
BSP_USING_SCI0~9 + choice 模式 |
bool / SPI·I2C·UART | SPI 模式 | SCI 控制器可工作在 SPI、I2C(SCPI)或 UART 三种模式,每种实例各自带 RX/TX 缓冲配置 |
BSP_USING_FS |
bool | n | 文件系统总开关,下含 BSP_USING_SPICARD_FS(SPI 卡文件系统,自动选择 SCI9 SPI、RT_USING_SPI_MSD 与 RT_USING_DFS_ELMFAT) |
当前仓库 rtconfig.h 中的实际状态可作为参照:已使能 BSP_USING_GPIO、BSP_USING_UART、BSP_USING_UART0(RX 缓冲 1024)与 BSP_USING_UART4(RX 缓冲 256),且 RT_CONSOLE_DEVICE_NAME 为 uart4——结合 README 中“P109/P110 为日志端口”的说明可以推断,板级默认把日志引脚映射给了 FSP 的 UART4 实例。此外还启用了 RT_USING_DFS/DFS_USING_POSIX、RT_USING_SERIAL_V2 与 RT_SERIAL_USING_DMA。
文件系统扩展有一个现成的实现范例:board/ports/mnt.c 在 BSP_USING_FS 使能时,通过 SCI9 的 SPI 模式(sci9s 控制器)挂载 SD 卡:
void sd_mount(void)
{
uint32_t cs_pin = BSP_IO_PORT_06_PIN_03;
rt_hw_sci_spi_device_attach("sci9s", "scpi90", cs_pin);
msd_init("sd0", "scpi90");
if (dfs_mount("sd0", "/", "elm", 0, 0) == 0)
{
LOG_I("Mount \"/dev/sd0\" on \"/\"\n");
}
else
{
LOG_W("sd card mount to '/' failed!");
}
}
int mount_init(void)
{
sd_mount();
return RT_EOK;
}
INIT_ENV_EXPORT(mount_init);
这段代码清晰展示了“FSP 的 SCI9-SPI 控制器 → RT-Thread SPI MSD 设备(/dev/sd0)→ DFS/ELM-FAT 挂载到根目录”的完整调用链,是理解该 BSP 外设扩展机制的最佳样例。
关键内核与组件配置解读
从 rtconfig.h 可提取当前最小配置的要点,便于读者对照自己的 menuconfig 结果:
| 宏 | 值 | 含义 |
|---|---|---|
RT_VER_NUM |
0x50300 |
内核版本 5.3.0 |
RT_TICK_PER_SECOND |
1000 |
系统时钟节拍 1ms |
RT_THREAD_PRIORITY_MAX |
32 |
线程优先级级别 32 |
IDLE_THREAD_STACK_SIZE |
256 |
idle 线程栈 |
RT_MAIN_THREAD_STACK_SIZE / RT_MAIN_THREAD_PRIORITY |
2048 / 10 |
main() 线程(RT_USING_USER_MAIN)的栈与优先级 |
FINSH_THREAD_NAME / FINSH_THREAD_PRIORITY / FINSH_THREAD_STACK_SIZE |
tshell / 20 / 4096 |
msh 线程参数,另启用历史行(5 行)与 Tab 选项补全 |
RT_CONSOLE_DEVICE_NAME / RT_CONSOLEBUF_SIZE |
uart4 / 128 |
控制台设备与行缓冲 |
RT_USING_DFS / DFS_FD_MAX |
使能 / 16 |
POSIX 风格虚拟文件系统,最多 16 个打开文件 |
BSP_UART0_RX_BUFSIZE / BSP_UART4_RX_BUFSIZE |
1024 / 256 |
当前使能的两路 UART 接收缓冲 |
同时 Kconfig 顶层强制 SOC_R7FA4M2AD 并 select RT_USING_COMPONENTS_INIT、RT_USING_USER_MAIN,即组件初始化机制与应用 main() 入口是该 BSP 的硬性前提;rsource "../libraries/Kconfig" 则引入瑞萨公共 HAL 驱动的共享配置。
FAQ
使用 MDK 的 DEBUG 时遇到 “Error: Flash Download failed Cortex-M33” 怎么办?
原 README 给出的解决办法是:按照其截图修改 Utilities 中的选项(即调整 MDK 调试器 Utilities 页面里下载相关的配置项)后重新下载。该截图见 docs/pictures/readme_faq1.png。另外注意本 BSP 的正式烧录路径是 J-Flash Lite(V7.50+)而非 MDK 在线下载,两者排障思路不同:J-Flash 路径下应优先核对芯片型号是否选为 R7FA4M2AD、hex 路径是否为 object/rtthread.hex。
小结与延伸
该 BSP 的工程化闭环可以概括为:FSP 负责“寄存器与引脚”,Kconfig/ENV 负责“RT-Thread 组件裁剪”,MDK5 负责“构建与调试”,J-Flash Lite 负责“烧录”。上手阶段照快速上手的四步走即可;扩展阶段则遵循“FSP 里配好外设 → Generate Project Content → env 里勾选对应 BSP_USING_* 项 → scons --target=mdk5”的固定节奏。更多瑞萨平台文档可参考 BSP 上级目录的 bsp/renesas/README.md(若当前版本存在),以及仓库中 bsp/renesas/ra4m2-eco/docs/pictures 下配套的图片资料;使用过程中若有想法和建议,可通过 RT-Thread 社区论坛联系维护者,也欢迎按仓库贡献规范为 RA4M2 补充外设支持与示例代码。


