RT-Thread CPK-RA6M4 BSP：瑞萨 RA6M4 评估板从烧录、调试到 FSP 外设配置的完整实战指南

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS

本文基于 RT-Thread 仓库中瑞萨 CPK-RA6M4 开发板的 BSP 说明文档（bsp-template/README.md），结合 ra6m4-cpk 板级目录的真实源码展开，完整覆盖开发板硬件资源、片上/外接外设支持清单、MDK5 编译与 J-Flash Lite 烧录流程、应用入口函数写法，以及进阶场景下的 FSP 外设配置、ENV 工具配置与 SEGGER_RTT 控制台技巧。读完本文，你可以独立把 RT-Thread 跑在 CPK-RA6M4 上，并知道如何为这块板添加新的 UART、ICU、WDT、RTC 等外设驱动。

开发板与硬件资源

CPK-RA6M4 是瑞萨基于 RA6M4 系列 MCU 推出的 MCU 评估板，面向 RA6M4 MCU 群组特性的评估与嵌入式应用开发。开发板正面外观如下：

核心板载资源如下：

从源码的 Kconfig 可以看到，该 BSP 的 SoC 配置项为SOC_R7FA6M4AF，并自动选择SOC_SERIES_R7FA6M4、RT_USING_COMPONENTS_INIT与RT_USING_USER_MAIN，即默认启用组件初始化框架和用户main函数入口。

BSP 源码结构

以 ra6m4-cpk 目录为例，BSP 的整体组织是理解 FSP 工作流的基础：

ra6m4-cpk/ ├── board/ # 板级初始化：board.h、board_init.c、board_leds.c、ports 端口驱动 ├── ra/ │ ├── board/ # RA 芯片级 board 文件 │ └── fsp/ # 瑞萨 FSP 驱动库（bsp/r_ioport/r_sci_uart 等） ├── ra_cfg/fsp_cfg/ # FSP 生成的配置头文件（bsp_cfg.h、r_ioport_cfg.h、r_sci_uart_cfg.h 等） ├── ra_gen/ # FSP 生成的运行时数据（hal_data.c、vector_data.c、pin_data.c、main.c） ├── script/ # 链接脚本：fsp.scat、fsp.ld、memory_regions 系列 ├── src/hal_entry.c # 应用层入口函数 ├── Kconfig # BSP 配置入口，rsource 共享的 ../libraries/Kconfig ├── configuration.xml # FSP（rasc）工程配置文件 ├── R7FA6M4AF3CFB.pincfg # 引脚配置 └── project.uvprojx # MDK5 工程文件

可以推断，ra_cfg与ra_gen两类目录都是 FSP 工具链的生成产物：前者存放编译期配置宏，后者存放 HAL 运行期数据结构与向量表。这也是后文“用 FSP 重新生成工程内容”步骤需要更新这两处目录的原因。

内存布局方面，board/board.h 定义了 SRAM 边界与堆起点：

#define RA_SRAM_SIZE 256 #define RA_SRAM_END (0x20000000 + RA_SRAM_SIZE * 1024) #ifdef __ARMCC_VERSION extern int Image$$RAM_END$$ZI$$Base; #define HEAP_BEGIN ((void *)&Image$$RAM_END$$ZI$$Base) ... #define HEAP_END RA_SRAM_END

即 SRAM 起始于0x20000000，大小 256kB，堆（Heap）从ZI段结束处一直延伸到RA_SRAM_END。内核侧关键参数可在 rtconfig.h 中确认：RT_TICK_PER_SECOND 1000、RT_THREAD_PRIORITY_MAX 32、RT_ALIGN_SIZE 8，并开启了溢出检查、钩子机制、空闲线程钩子（栈 256 字节）与软定时器线程（栈 512 字节）。

外设支持情况

本 BSP 目前的片上外设支持情况如下：

外接模块方面，该 BSP 已适配：RW007 WiFi 网络模块（对应 board/ports/drv_rw007.c 驱动源码）、HS300x 温湿度模块、zmod4410 室内空气质量模块、isl29035 光线传感器模块，这些模块均以 RT-Thread 软件包形式提供。此外板级目录还预留了 LVGL 显示移植与 FAL（Flash 抽象层，见 board/ports/fal_cfg.h）配置。

快速上手

该 BSP 提供 MDK5 工程（project.uvprojx）。下面以 MDK5 开发环境为例介绍如何把系统跑起来。

硬件连接

• 使用 USB 数据线连接开发板到 PC，通过板载 J-Link 接口下载和调试程序；
• 使用 USB 转串口工具连接 UART7：P613（TXD）、P614（RXD），这是默认的日志与 shell 输出端口。

MDK 编译与烧录

1. 编译：双击project.uvprojx打开 MDK5 工程并编译。编译产物为/object/ra6m4.hex。
2. 直接下载：如果不需要在线调试，可配置好 Flash 下载算法后直接在 MDK 中点击 Download 烧录。
3. 使用 J-Flash Lite 烧录：该工程推荐使用 J-Flash Lite 工具（建议 V7.50 及以上版本）烧录，步骤为：
   • 打开 J-Flash Lite，选择芯片型号R7FA6M4AF，点击 OK 进入工具；
   • 选择 BSP 目录下 MDK 编译出的/object/ra6m4.hex文件；
   • 点击 Program Device 按钮开始烧录。

J-Flash Lite 中选择 hex 文件的界面如下：

查看运行结果

烧录成功后系统自动运行。在终端工具中打开对应串口（115200-8-1-N），复位设备后可看到 RT-Thread 启动信息，输入help可列出系统命令：

\ | / - 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 >

应用入口函数

应用层入口函数为 src/hal_entry.c 中的void hal_entry(void)，用户编写的源文件可直接放在src目录下。默认实现是打印 Hello 并以 1 秒周期翻转 LED3：

#define LED3_PIN BSP_IO_PORT_01_PIN_06 #define USER_INPUT "P105" 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); } }

其中LED3_PIN被映射到 FSP 的 IO Port 0 第 6 脚（BSP_IO_PORT_01_PIN_06），命名遵循瑞萨 “Port01 = Port0” 的编号习惯。同一个文件还附赠了 GPIO 中断（ICU）示例命令icu_sample（非 NANO 内核下可用），它把P105配置为上升沿触发的 RT-Thread 引脚中断：

void icu_sample(void) { rt_uint32_t pin = rt_pin_get(USER_INPUT); rt_kprintf("\n pin number : 0x%04X \n", pin); rt_err_t err = rt_pin_attach_irq(pin, PIN_IRQ_MODE_RISING, irq_callback_test, RT_NULL); if(RT_EOK != err) { rt_kprintf("\n attach irq failed. \n"); } err = rt_pin_irq_enable(pin, PIN_IRQ_ENABLE); ... } MSH_CMD_EXPORT(icu_sample, icu sample);

在 shell 中执行icu_sample即可把 P105 挂接为中断输入，触发时回调irq_callback_test打印IRQ00 triggered——这个例子的 FSP 侧配置方法与下文 GPIO 中断章节完全对应。

进阶使用：FSP 外设配置

需要修改瑞萨侧的外设配置或添加新的外设端口时，必须使用瑞萨的 FSP（Flexible Software Package）配置工具。务必注意FSP 版本请使用 3.5.0，旧版本可能存在兼容性问题。完整方法可参阅仓库内的 RA系列使用FSP配置外设驱动.md，核心流程如下。

准备工作

1. 安装 FSP 3.5.0：从瑞萨官网下载 Flexible Software Package 并安装。
2. 导入 CPK-RA6M4 官方板级支持包：在 CPK-RA6M4 开发板详情页的“下载”列表中找到“CPK-RA6M4 板级支持包”，下载后按瑞萨《如何导入板级支持包》文档将其添加到 FSP 中。
3. 在 MDK 中添加启动 FSP 的自定义命令：
   • 打开 MDK，选择 “Tools -> Customize Tools Menu…”；
   • 点击 “new” 图标，添加一条自定义命令，命名为RA Smart Configurator；
   • Command 填入 FSP 安装目录下rasc.exe的完整路径；
   • Initial Folder 填$P；
   • Arguments 填--device $D --compiler ARMv6 configuration.xml；
   • 之后通过菜单 “Tools -> RA smart Configurator” 即可打开当前工程的 FSP 配置（工程根目录的 configuration.xml 即 FSP 工程描述文件）。

打开 RASC 前，请务必先检查 FSP version、Board、Device 三项配置是否正确。

添加与配置外设（命名约定）

FSP 文档中各外设添加步骤均为独立说明，排版顺序不代表添加顺序；遇到引脚冲突需查阅开发板与芯片手册。所有外设配置完成后，点击Generate Project Content生成/更新ra_cfg、ra_gen目录下的代码。由于 RT-Thread 的瑞萨系列驱动按固定的实例命名查找 FSP 生成对象，因此name、channel、callback 的命名必须与驱动约定一致，典型约定包括：

• UART：在 Stacks 页选择 New Stack -> UART，将 name、channel、callback 设为一致的标号（如uart7对应 channel 7）；
• GPIO 中断（ICU）：例如选 P105 作中断引脚，先查其可配置的 IRQ 通道号（IRQ00），打开该 IRQ 通道并创建 stack，name 与 channel 保持一致，callback 统一命名为irq_callback，再选择触发方式；验证代码即上文icu_sample命令；
• WDT：RT-Thread 侧只注册了一个 WDT 设备，未编号，新创建时 name 字段应为g_wdt；
• RTC：同样只有一个 RTC 设备，name 应为g_rtc，Callback 命名为rtc_callback。

生成后更新工程

FSP 生成新文件后不会立即加入 MDK 工程：需要先编译一次，若弹出导入新文件的提示选择“是”，再次编译即可。

除 MDK 自定义命令外，也可以在 env 流程下操作：先用scons --target=mdk5生成 MDK 工程，打开project.uvprojx，在导航栏Software Components中展开Flex Software，点击RA Configuration旁的配置按钮，工具会自动查找本机已安装的 FSP 版本，选定后即可进入配置界面，流程相同。

ENV 工具配置

本 BSP 默认只开启了 UART7 功能。若需启用更多高级功能（组件、软件包、其他外设驱动），需要利用 ENV 工具配置，步骤如下：

1. 在 BSP 目录下打开 env 工具；
2. 输入menuconfig命令配置工程，配置完成后保存退出；
3. 输入pkgs --update命令更新软件包；
4. 输入scons --target=mdk5命令重新生成 MDK5 工程。

其中menuconfig的配置项来源于 Kconfig：除标准 RT-Thread 内核配置外，它通过rsource "../libraries/Kconfig"引入瑞萨系列共享库（HAL 驱动、板级组件）的配置树，非 NANO 内核还会加载 board/Kconfig 中的板载设备驱动选项（RW007、FAL、LCD 等）。

使用 SEGGER_RTT 作为 console

由于 RA6M4 的串口输出需要 USB 转 TTL 工具，比较不方便。RT-Thread 社区提供 RTTHREAD_SEGGER_TOOL 软件包，可以把 J-Link 直接作为 RT-Thread 的 console 口：在RT-Thread Settings -> 硬件 -> 板载设备驱动下使能 SEGGER-RTT，重新生成工程后，调试器连接即可直接看到 shell 输出，无需外接串口。

FAQ

MDK 调试时提示 “Error: Flash Download failed Cortex-M33”

这是 Cortex-M33 目标下常见的 Flash 下载算法选择问题，可修改 Utilities 中的选项解决：

小结

该 BSP 以“FSP 负责外设实例化、RT-Thread 设备驱动负责系统抽象”的双层结构组织：configuration.xml+ FSP 生成ra_cfg/ra_gen，板级层board/完成堆栈、LED、引脚与外设实例的初始化，应用层从hal_entry()切入。快速上手只需 MDK5 编译 + J-Flash Lite 烧录两条命令级操作；而扩展新外设时，关键约束只有一条——严格遵循 FSP 实例的命名约定，再配合scons --target=mdk5重新生成工程，即可让新的 UART、ICU、WDT、RTC 等实例被 RT-Thread 设备框架正确识别。

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS