RT-Thread 瑞萨 RA4M2(RA-Eco-RA4M2-100PIN)BSP 实战指南:从 J-Flash 快速上电运行到 FSP/ENV 进阶外设配置

原创2026-09-24 10:15:351,762 阅读
文章标签:操作系统嵌入式OSRTOS物联网系统编程嵌入式

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 卡)扩展。

RA-Eco-RA4M2-100PIN 开发板正面外观

开发板与片上资源

基于瑞萨 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 的接线要求准备三条链路:

  1. 使用 USB 数据线连接开发板(串口)到 PC;
  2. 使用下载器连接 SWD 排针和 DEBUG 程序(调试);
  3. 使用 USB 转串口工具连接 UART9:P109(TXD)、P110(RXD)。

编译与下载

  1. 编译:双击 project.uvprojx 打开 MDK5 工程,编译程序。
  2. 下载:该工程需要使用 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 给出的操作流程为:

  1. 在 bsp 目录下打开 env 工具,使用 scons --target=mdk5 命令生成 MDK 工程;
  2. 打开 bsp 目录下的 project.uvprojx,在 MDK 顶部导航栏选择 Software Components,找到 Flex Software 下的 RA Configuration 配置按钮并打开。该操作会自动查找当前电脑安装的 FSP 版本,选择指定版本后进入 FSP;
  3. 进入 FSP 后可看到已配置完成的外设,点击 Generate Project Content 按钮生成所需驱动文件;
  4. 回到 env,使能所需的外设配置后保存退出。

MDK5 中 Software Components 下的 RA Configuration 配置入口

FSP 中的外设配置界面与 Generate Project Content 按钮

生成结果会体现在两类文件中:

  • 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 给出的步骤:

  1. 在 bsp 下打开 env 工具;
  2. 输入 menuconfig 命令配置工程,配置好之后保存退出;
  3. 输入 pkgs --update 命令更新软件包;
  4. 输入 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 补充外设支持与示例代码。

登录后查看全文
rt-thread