本文基于 renesas_ra2t1 基础工程,完整说明从零搭建构建环境、执行一次可复现的编译、到板级与应用的代码实现,
以及最后的 J-Link 烧写准备。
与常见的「e2studio + FSP」或「RASC + Keil」测评分册文章不同,本工程不使用 IDE 管理构建:
CMake + Ninja + Arm GNU Toolchain 全程命令行完成,FSP 源码随仓库提供(vendored),
不依赖本机安装的 FSP 目录,也不需要打开图形配置工具即可复现编译产物。
1. 三种开发路径的分工
| 路径 | 配置方式 | 构建 | 适用 | 本文关系 |
|---|---|---|---|---|
| e2studio + FSP | IDE 内 RASC 图形配置 | e2studio managed build | 首次点灯、断点调试最省事 | 可用来交叉核对配置 |
| RASC + Keil MDK | RASC 生成 Keil 工程 | Keil / armclang | 习惯 Keil 的团队 | 配置来源相同,均为 configuration.xml |
| 本工程:CMake + GCC | 手写 configuration.xml(可被 RASC 直接打开) |
CMake + Ninja + arm-none-eabi-gcc | 可脚本化、可 CI、可长期维护 | 本文主体 |
三者共用同一份 RASC 配置(时钟、引脚、GPT 实例),因此配置结论可以互相验证;
不同之处只在「谁来生成代码」和「谁来编译链接」。
2. 环境准备
2.1 硬件
| 项 | 值 |
|---|---|
| 开发板 | RA-Eco-RA2T1-48PIN(V1.0) |
| 调试探针 | J-Link V9(需支持 ARMv8-M/Cortex-M23) |
注意:旧版 J-Link(如 V8/OB 系列)不支持 M23 内核,连接会失败;本工程烧写配置按 V9 编写。
2.2 软件
| 依赖 | 版本 |
|---|---|
| CMake | ≥ 3.20(本机 4.3.2) |
| Ninja | 较新版本 |
| Arm GNU Toolchain | - |
| RA Smart Configurator (RASC) | sc_v2026-04.2_fsp_v6.5.0 |
| FSP | 6.5.0 |
| SEGGER J-Link | V9.50 |
工具链版本必须与 FSP 例程要求一致(configuration.xml 中记录为 13.2.1.arm-13-7),
版本不一致时 newlib 的启动文件与链接脚本可能对不上。
2.3 换机器时的两个覆盖开关
# 工具链不在默认位置
cmake -S . -B build -G Ninja -DBOARD=ra2t1_48pin -DAPP=led_blink `
-DRA_TOOLCHAIN_ROOT=D:/tools/xpack-arm-none-eabi-gcc-13.2.1
# RASC 不在默认位置
cmake -S . -B build -G Ninja -DBOARD=ra2t1_48pin -DAPP=led_blink `
-DRA_RASC_EXECUTABLE=D:/Renesas/RA/sc_v2026-04.2_fsp_v6.5.0/eclipse/rasc.exe
RASC 只在配置变化时才会被调用,日常编译不依赖它。
3. 工程目标与关键取舍
- 与 SDK 例程目录彻底解耦:不引用
RA2T1_example/下任何路径,构建过程不读不写该目录。 - 离线可构建:FSP 6.5.0 以源码形式入库(
third_party/fsp/ra/,101 个文件、约 4.87 MB),
只保留当前配置真正用到的部分,剔除示例、文档、pack 安装包、预编译库fsp/lib、构建产物与.git。 - 换板只改一层:引脚、极性、定时器实例全部收敛在
board/<板名>/,应用只调用逻辑接口。 - 构建配置集中:CPU 选项、链接脚本、include、宏定义只在
cmake/ra_platform.cmake写一份,
不随板卡/应用复制。 - 生成物不污染源码树:RASC 输出统一落到
build/generated/<board>/,源码目录保持只读语义。
4. 目录结构与分层
renesas_ra2t1/
├── CMakeLists.txt 顶层入口:-DBOARD= / -DAPP=
├── cmake/
│ ├── ra_platform.cmake 公共构建模块
│ └── toolchains/
│ └── arm-none-eabi-gcc.cmake 交叉编译工具链
├── third_party/fsp/ra/ vendored FSP 6.5.0
├── board/ra2t1_48pin/
│ ├── config/configuration.xml RASC 配置(时钟 / 引脚 / GPT)
│ ├── board_api.h 板级对外接口
│ └── board.c 板级实现
├── apps/
│ ├── low_power_base/src/app.c 最小应用:初始化后 WFI
│ └── led_blink/src/app.c GPT 500 ms 翻转 P914
├── jlink/ J-Flash 工程与 Commander 脚本
└── build/ 构建产物(不入库)
| 层 | 位置 | 职责 | 换板影响 |
|---|---|---|---|
| 芯片驱动 | third_party/fsp/ra/ + RASC 生成 |
FSP、BSP、CMSIS | 不变 |
| 板级 BSP | board// |
引脚、时钟、LED/按键、板载定时器 | 只改这一层 |
| 应用 | apps// |
业务逻辑,只用 board_api.h |
不变 |
5. 构建系统详解
5.1 顶层入口
CMakeLists.txt 只做三件事:指定工具链、读入公共模块、按参数展开构建目标。
set(BOARD "" CACHE STRING "板级配置名")
set(APP "" CACHE STRING "应用名(可分号分隔多个,或 all)")
include("${CMAKE_CURRENT_LIST_DIR}/cmake/ra_platform.cmake")
ra_add_board("${BOARD}") # 生成代码 + 编成 OBJECT 库
foreach(_app IN LISTS _apps)
ra_add_app("${_app}" "${BOARD}") # 每个应用一个 elf
endforeach()
-DAPP=all 时会遍历 apps/* 逐个加入,因此新增应用不需要改顶层脚本。
5.2 工具链文件
set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_C_COMPILER "${RA_TOOLCHAIN_ROOT}/bin/arm-none-eabi-gcc.exe")
set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
set(RA_CPU_FLAGS -mcpu=cortex-m23 -mthumb -mfloat-abi=soft)
两个容易踩的点:
CMAKE_SYSTEM_NAME Generic+TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY:
交叉编译无法在主机上运行测试程序,必须避免 CMake 做可执行文件探测。RA_CPU_FLAGS必须是 CMake 列表。写成单字符串"-mcpu=cortex-m23 -mthumb"会被当成一个参数传给编译器,直接报错。
5.3 板级目标:ra_add_board()
这一步承担「生成 + 编译平台」两件事:
- 调 RASC 生成代码到
build/generated/<board>/,以产物存在 + 配置哈希判断是否跳过; - 收集源文件:
fsp/src/bsp全量 + RASC 生成目录中实际出现的驱动模块 +board/<board>/*.c+ra_gen/*.c; - 编成
OBJECT库ra_platform_<board>,同时把 include、宏、编译选项设为PUBLIC,
应用只需链接一次即可继承全部平台参数。
源文件范围的判定方式值得说明:
file(GLOB _gen_mod_dirs LIST_DIRECTORIES true "${_gen_dir}/ra/fsp/src/*")
foreach(_md IN LISTS _gen_mod_dirs)
get_filename_component(_mn "${_md}" NAME)
if(NOT _mn STREQUAL "bsp")
# 只编译配置里真正引用到的驱动,如 r_gpt、r_ioport
file(GLOB_RECURSE _mod_srcs "${FSP_PATH}/fsp/src/${_mn}/*.c")
list(APPEND _fsp_srcs ${_mod_srcs})
endif()
endforeach()
这样做的结果是:未使用的驱动(SCI、ADC、I2C……)既不会进入编译,也不会因为缺少 *_cfg.h 而报错;
而一旦 configuration.xml 新增了某个模块,构建会明确提示「vendored FSP 缺少该模块」,
而不是给出难以定位的链接错误。
5.4 应用目标:ra_add_app()
file(GLOB_RECURSE _app_srcs "${_app_dir}/src/*.c" "${_app_dir}/src/*.S")
add_executable(${app} ${_app_srcs})
target_link_libraries(${app} PRIVATE ra_platform_${board})
target_link_options(${app} PRIVATE
${RA_CPU_FLAGS}
-T "${_gen_dir}/script/fsp.ld"
"-L${_gen_dir}/script" "-L${_gen_dir}"
-Wl,--gc-sections
"-Wl,-Map=${_out_dir}/${app}.map"
--specs=nano.specs --specs=nosys.specs
)
链接脚本使用 RASC 为当前板卡生成的那一份(build/generated/<board>/script/fsp.ld),
因此 main 栈大小、Flash/RAM 分区都跟着 configuration.xml 走,不在 CMake 里硬编码。
objcopy 在 POST_BUILD 阶段产出 hex/bin,并打印尺寸。
5.5 RASC 调用的幂等性
file(SHA1 "${gen_dir}/configuration.xml" _cfg_hash)
# 产物齐全且哈希一致 -> 跳过;否则调用 rasc.exe --generate
两个实战经验:
- RASC 命令行即使生成成功也可能返回非零退出码,因此判定成功要看
ra_gen/、script/fsp.ld是否真的存在; - 连续调用偶发失败,因此内置了重试(最多 2 次)。
5.6 vendored FSP 的边界
| 项 | 值 |
|---|---|
| 版本 | FSP 6.5.0 |
| 路径 | third_party/fsp/ra/(可用 -DFSP_PATH= 覆盖) |
| 内容 | fsp/inc、fsp/src/bsp(cmsis + mcu/all + mcu/ra2t1)、board/ra2t1_fpb、arm/CMSIS_6、r_gpt、r_ioport |
| 体积 | 101 个文件,约 4.87 MB |
升级或新增驱动时,把新版对应的 fsp/src/<driver> 复制进来即可,构建会自动纳入编译。
6. 一次完整构建(实测输出)
6.1 配置
cmake -S . -B build -G Ninja -DBOARD=ra2t1_48pin -DAPP=all
首次会调用 RASC 生成代码;之后配置未变时直接跳过:
-- [board:ra2t1_48pin] RASC 生成代码已是最新,跳过
-- Configuring done (0.1s)
-- Generating done (0.1s)
-- Build files have been written to: .../renesas_ra2t1/build
6.2 编译
cmake --build build
实际编译顺序(32 个构建步骤):
| 顺序 | 内容 | 说明 |
|---|---|---|
| 1–2 | startup.c、system.c |
向量表与时钟初始化 |
| 3–17 | bsp_*(clocks/irq/io/guard/security/sdram…) |
FSP 全量 BSP |
| 18–21 | board_leds.c、board_init.c、r_ioport.c、r_gpt.c |
板级支持 + 配置用到的驱动 |
| 22 | board/ra2t1_48pin/board.c |
本工程板级实现 |
| 23–27 | ra_gen/*.c(main/hal_data/pin_data/vector_data/common_data) |
RASC 生成代码 |
| 28–29 | apps/*/src/app.c |
两个应用 |
| 30–31 | 链接 + objcopy |
生成 elf/hex/bin/map |
注意:RASC 还会生成一份
build/generated/<board>/src/hal_entry.c模板,
但构建只收集ra_gen/*.c,模板不参与编译。真正的入口在apps/<app>/src/app.c,
这是本工程与 IDE 例程最容易混淆的一点。
6.3 链接与内存布局
RASC 生成的 memory_regions.ld:
RAM_START = 0x20004000; RAM_LENGTH = 0x00002000; /* 8 KB */
FLASH_START = 0x00000440; FLASH_LENGTH = 0x0000fbc0;
DATA_FLASH_START = 0x40100000; DATA_FLASH_LENGTH = 0x00000800;
OPTION_SETTING_OFS0_START = 0x00000400; /* OFS0/OFS1/SECMPU 占 0x400~0x43C */
代码从 0x440 开始,是因为 0x400 起是选项设置区(OFS0/OFS1/SECMPU),
这部分由 RASC 和链接脚本固定,不要手动改。
6.4 产物与尺寸
build/apps/led_blink/led_blink.elf|hex|bin|map
build/apps/low_power_base/low_power_base.elf|hex|bin|map
实测尺寸:
| 应用 | text | data | bss | 说明 |
|---|---|---|---|---|
led_blink |
3104 B | 0 | 1196 B | BSP + GPT + IOPORT + 应用 |
low_power_base |
1924 B | 0 | 1160 B | 最小镜像,可用于对比增量 |
两个应用的差值(约 1.2 KB text)就是 GPT 驱动 + 定时器实例 + 应用逻辑的成本,
在 64 KB Flash 上占用很小,bss 主要是 FSP 的实例结构体。
6.5 链接告警怎么看
链接时会出现 _close is not implemented and will always fail 等提示:
libc_nano.a(libc_a-closer.o): warning: _close is not implemented and will always fail
这是 --specs=nosys.specs 的正常现象:裸机没有文件系统,newlib 的 _read/_write/_close
桩函数直接返回失败。只要不使用 printf/文件接口就不会被调用,不影响运行。
若后续需要串口打印,应实现 _write 重定向到 SCI,而不是引入半主机。
7. 板级实现(board/ra2t1_48pin/)
7.1 引脚核对
配置来自原理图 SCH_Schematic4_2026-06-10.pdf 与器件数据手册:
| 信号 | 引脚 | 配置 | 备注 |
|---|---|---|---|
| LED2(状态灯) | P914 | 输出,初始低 | 高电平点亮,48 脚 LQFP 第 14 脚 |
| LED1 | P213 | 输出,初始低 | 高电平点亮 |
| SWDIO / SWCLK | P108 / P300 | 复用为 SWD | 被复用成 GPIO 会导致下载后失联 |
| VCOM TXD / RXD | P109 / P110 | SCI9 | 板载调试串口 |
| 板载按键 SW | P200 | IRQ(NMI) | 已配置引脚,当前应用未使用 |
board_api.h 只暴露逻辑资源,不暴露引脚号:
typedef enum e_board_led
{
BOARD_LED_STATUS = 0, /* 板上用户 LED(LED2 / P914) */
BOARD_LED_COUNT
} board_led_t;
void board_init(void);
void board_led_write(board_led_t led, bool on);
void board_led_toggle(board_led_t led);
bool board_timer_start(void (*p_callback)(void));
void board_timer_stop(void);
7.2 启动链路与引脚生效
复位
→ startup.c(向量表、栈、.data 搬运)
→ SystemInit()(system.c,时钟)
→ R_BSP_WarmStart(BSP_WARM_START_RESET)
→ C 运行时初始化
→ R_BSP_WarmStart(BSP_WARM_START_POST_C)
└─ R_IOPORT_Open(&IOPORT_CFG_CTRL, &IOPORT_CFG_NAME) // 生效 g_bsp_pin_cfg
→ main()(ra_gen/main.c)
└─ hal_entry()(apps/<app>/src/app.c)
引脚配置不是应用自己写的,而是 RASC 把 configuration.xml 里的引脚表生成成 g_bsp_pin_cfg,
在 R_BSP_WarmStart(POST_C) 时一次性生效。所以 P914 在上电时就已是输出低电平,
board_init() 里的熄灭动作是幂等的保险。
7.3 LED 读写与翻转
void board_led_write(board_led_t led, bool on)
{
if (BOARD_LED_STATUS == led)
{
R_IOPORT_PinWrite(&g_ioport_ctrl, BOARD_LED_STATUS_PIN,
on ? BSP_IO_LEVEL_HIGH : BSP_IO_LEVEL_LOW);
}
}
void board_led_toggle(board_led_t led)
{
bsp_io_level_t level = BSP_IO_LEVEL_LOW;
R_IOPORT_PinRead(&g_ioport_ctrl, BOARD_LED_STATUS_PIN, &level);
board_led_write(led, BSP_IO_LEVEL_LOW == level);
}
翻转采用「先读回电平再取反」,而不是维护一个软件标志:
这样即使别处直接改过引脚,状态也不会错位。
7.4 GPT 500 ms 的参数推导
configuration.xml 中只填了「周期 500 ms」,具体寄存器参数由 RASC 算出并写进 hal_data.c:
.mode = TIMER_MODE_PERIODIC
.period_counts = 0x7a12 // 31250
.source_div = 10 // PCLKD / 1024
.channel = 1 // GPT1
.cycle_end_ipl = 2 // NVIC 优先级 2
.p_callback = board_gpt_callback
推导:
PCLKD = HOCO 64 MHz / 1 = 64 MHz
计数时钟 = 64 MHz / 1024 = 62500 Hz
周期计数 = 0.5 s × 62500 = 31250 = 0x7A12
时钟树(configuration.xml):HOCO 64 MHz 作为主时钟源,ICLK/2 = 32 MHz、PCLKB/2 = 32 MHz、PCLKD/1 = 64 MHz。
选 GPT1 而不是软件延时,是因为 500 ms 用 R_BSP_SoftwareDelay() 会一直占着 CPU,
而 GPT 周期中断可以配合 __WFI() 进低功耗。
7.5 中断链路
GPT1 计数器溢出
→ VECTOR_NUMBER_GPT1_COUNTER_OVERFLOW
→ r_gpt 驱动 → g_timer_board_cfg.p_callback
→ board_gpt_callback()(过滤 TIMER_EVENT_CYCLE_END)
→ s_timer_callback()(应用注册的 app_tick)
→ board_led_toggle(BOARD_LED_STATUS)
board_gpt_callback 做了事件过滤,并检查回调指针非空,避免定时器已启动但应用尚未注册回调时跳飞。
8. 应用实现(apps/)
8.1 led_blink
static void app_tick(void)
{
board_led_toggle(BOARD_LED_STATUS);
}
void hal_entry(void)
{
board_init(); /* 上电先熄灭 */
if (!board_timer_start(app_tick)) /* GPT 500 ms 周期中断 */
{
__disable_irq();
while (1) { }
}
while (1)
{
__WFI();
}
}
运行效果:P914 上的 LED2 每 500 ms 翻转一次,即周期 1 s 的方波;
主循环用 WFI 等待中断,不做忙等。启动失败时关中断并停住,便于调试器查看。
8.2 low_power_base
void hal_entry(void)
{
board_init();
while (1)
{
__WFI();
}
}
这是最小可运行镜像,用来验证「BSP + 时钟 + 引脚」链路本身没有问题。
它和 led_blink 共用同一份板级与生成代码,因此两者的尺寸差可以直接反映外设开销。
9. 烧写与调试
9.1 参数
| 项 | 值 |
|---|---|
| 器件 | R7FA2T107 |
| 接口 | SWD,4000 kHz |
| 复位 | Reset,烧录后启动 |
J-Link V9.50 原生支持该器件,不需要手写 flash loader,也不需要像 Keil 那样手工指定
「Programming Algorithm」和「RAM for Algorithm」——这部分由 J-Link 的器件描述文件接管。
9.2 J-Flash(图形界面)
File → Open Project...打开jlink/RA2T1_base.jflash;File → Open Data File...选择build/apps/<app>/<app>.hex;Target → Auto(擦除、编程、校验、复位运行一次完成)。
9.3 J-Link Commander(命令行)
jlink/flash.jlink:
si SWD
speed 4000
connect
erase
loadfile build/apps/led_blink/led_blink.hex
verifyfile build/apps/led_blink/led_blink.hex
r
g
q
执行:
```powershell
& "C:\Program Files\SEGGER\JLink_V950\JLink.exe" `
-device R7FA2T107 -if SWD -speed 4000 -autoconnect 1 `
-CommandFile "$PWD\jlink\flash.jlink"
烧其他应用时复制脚本,改 loadfile / verifyfile 两行的路径即可。
9.4 调试
需要断点调试时可用 JLinkGDBServerCL.exe 配合 arm-none-eabi-gdb:
& "C:\Program Files\SEGGER\JLink_V950\JLinkGDBServerCL.exe" `
-device R7FA2T107 -if SWD -speed 4000 -singlerun
再在另一终端连接 build/apps/led_blink/led_blink.elf 即可设置断点、单步、查看变量。
本工程保留了 -g 调试信息,.map 文件也可用于核对符号地址。
10.3 换一块板
新增 board/<新板名>/:
config/configuration.xml:从当前板配置派生,改引脚与时钟;board_api.h:逻辑资源接口,保持与应用一致;board.c:引脚号、极性、定时器实例。
应用与构建脚本都不需要改,构建时传入 -DBOARD=<新板名> 即可。
不同板卡、不同应用各自使用独立 build 目录即可并存。
附:常用命令速查
powershell
单应用
cmake -S . -B build -G Ninja -DBOARD=ra2t1_48pin -DAPP=led_blink
cmake --build build
全部应用
cmake -S . -B build -G Ninja -DBOARD=ra2t1_48pin -DAPP=all
cmake --build build
烧写
"C:\Program Files\SEGGER\JLink_V950\JLink.exe" -device R7FA2T107 -if SWD -speed 4000 `
-autoconnect 1 -CommandFile "$PWD\jlink\flash.jlink"
查看尺寸
"C:\Users\Administrator\AppData\Local\ArmGNU\xpack-arm-none-eabi-gcc-13.2.1-1.1\bin\arm-none-eabi-size.exe" `
build\apps\led_blink\led_blink.elf
最后奉上Gitee地址:https://gitee.com/superyu88/renesas.git




全部评论