野火启明6M5（ebf_qm6m5）Zephyr 板级包制作指南

本文记录如何为野火启明6M5（MCU R7FA6M5BH3CFC）制作 Zephyr 板级支持包（BSP）。按此流程也可移植其他 RA 系列开发板。

1. 前置条件与总体思路

• SoC 已被 Zephyr 支持：本仓库 Zephyr（D:\zephyrproject，v4.4）已内置 r7fa6m5bh3cfc 的 SoC 级 dtsi（dts/arm/renesas/ra/ra6/r7fa6m5bh3cfc.dtsi）和 RA 平台驱动（GPIO/SPI/SCI/UART/QSPI 等）。因此不需要写任何驱动代码，板级包全部是声明式文件（Kconfig + devicetree + cmake）。

• 参照板：Zephyr 官方 ek_ra6m5（boards/renesas/ek_ra6m5）使用同型号 SoC，整体结构直接对照复制，再按野火原理图改引脚。

• 信息来源：野火原理图（docs/野火_瑞萨启明6M5开发板_原理图.pdf）。先把关键引脚整理成文档（本仓库产物：docs/启明6M5开发板_引脚分配.md），再动手写 dts。

2. 目录结构（HWMv2 外置板卡）

板卡放在工程仓库内（不进 Zephyr 源码树），通过 BOARD_ROOT 引入：

D:\RA\RA6M5\                    ← BOARD_ROOT 指向这里
└── boards\
    └── ebf\                    ← vendor 目录（板卡厂商）
        └── ebf_qm6m5\          ← 板卡目录，目录名即板卡名
            ├── board.yml               # 板卡声明（HWMv2 必需）
            ├── Kconfig.ebf_qm6m5       # BOARD_EBF_QM6M5 选择 SoC
            ├── Kconfig.defconfig       # 板级默认 Kconfig
            ├── ebf_qm6m5_defconfig     # 默认使能的配置项
            ├── ebf_qm6m5.yaml          # twister 元数据
            ├── board.cmake             # 烧录 runner（jlink/pyocd）
            ├── ebf_qm6m5.dts           # 板级 devicetree（核心）
            └── ebf_qm6m5-pinctrl.dtsi  # 引脚复用定义

编译时通过 -DBOARD_ROOT=D:/RA/RA6M5 告诉 west 去这里找板卡（要求 boards/<vendor>/<board> 层级）。

3. 各文件作用与本板内容

3.1 board.yml —— 板卡声明（HWMv2 必需）

board:
  name: ebf_qm6m5
  full_name: EmbedFire QiMing 6M5 Board (野火启明6M5)
  vendor: ebf
  socs:
  - name: r7fa6m5bh3cfc     # 必须与 dts/arm/renesas/ra/ra6/ 下的 dtsi 文件名一致

3.2 Kconfig.ebf_qm6m5 —— 绑定 SoC

config BOARD_EBF_QM6M5
    select SOC_R7FA6M5BH3CFC

3.3 Kconfig.defconfig —— 板级默认配置

if BOARD_EBF_QM6M5

endif # BOARD_EBF_QM6M5

本板暂无板级默认项（需要时在 if 内加，如 config FOO default y）。

3.4 ebf_qm6m5_defconfig —— 开箱可用的最小配置

CONFIG_GPIO=y
CONFIG_SERIAL=y
CONFIG_UART_CONSOLE=y
CONFIG_UART_INTERRUPT_DRIVEN=y
CONFIG_CONSOLE=y

保证任何 app 编进来都有 GPIO 和串口控制台。

3.5 ebf_qm6m5.yaml —— 元数据（twister/文档用）

identifier: ebf_qm6m5
name: EmbedFire QiMing 6M5
type: mcu
arch: arm
ram: 512          # R7FA6M5BH：512KB SRAM
flash: 2048       # 2MB code flash
toolchain: [zephyr, gnuarmemb]
supported: [gpio, spi, watchdog]
vendor: ebf

3.6 board.cmake —— 烧录 runner

board_runner_args(jlink "--device=R7FA6M5BH")   # 注意：J-Link 器件名不带后缀封装
board_runner_args(pyocd "--target=R7FA6M5BH")

include(${ZEPHYR_BASE}/boards/common/jlink.board.cmake)
include(${ZEPHYR_BASE}/boards/common/pyocd.board.cmake)

之后 west flash -r jlink 即可。device 名写错会连不上目标，可用 JLink.exe 命令行试连确认。

3.7 ebf_qm6m5.dts —— 核心文件

骨架：

/dts-v1/;
#include <renesas/ra/ra6/r7fa6m5bh3cfc.dtsi>   /* SoC 级定义（Zephyr 自带） */
#include "ebf_qm6m5-pinctrl.dtsi"

关键内容（按原理图逐项确定）：

chosen —— 控制台/存储绑定

chosen {
    zephyr,sram = &sram0;
    zephyr,flash-controller = &flash1;
    zephyr,flash = &flash0;
    zephyr,console = &uart4;        /* SCI4 → CH340G USB 串口（跳线 J35） */
    zephyr,shell-uart = &uart4;
    zephyr,entropy = &trng;
    zephyr,crc = &crc;
};

时钟 —— 与 EK-RA6M5 相同的 24MHz 主晶振：PLL 200MHz（24MHz ÷3 ×25）、PLL2 240MHz（÷2 ×20）供 USB 48MHz（÷5）。野火板与 EK 晶振一致，直接沿用。

控制台串口：SCI4（TXD=P512、RXD=P511），115200 8N1：

&sci4 {
    pinctrl-0 = <&sci4_default>;
    pinctrl-names = "default";
    status = "okay";
    uart4: uart {
        current-speed = <115200>;
        status = "okay";
    };
};

LED / 按键（低电平点亮/按下，按原理图）：LED1/2/3 = P400/P403/P404；KEY1/2 = P004/P005（IRQ9/IRQ10，需同时使能 &port_irq9/&port_irq10 并填中断号）。aliases 里映射 led0/sw0 以兼容 Zephyr 示例程序。

SPI0（PMOD1 接 LCD）：

&spi0 {
    pinctrl-0 = <&spi0_default>;
    pinctrl-names = "default";
    cs-gpios = <&ioport3 1 GPIO_ACTIVE_LOW>;   /* P301 作 GPIO CS */
    status = "okay";
};

注意 RA 的 SPI 片选：不挂 cs-gpios 也不手动控制的话，CS 不会动（详见调试笔记 §3）。

QSPI Flash：W25Q32JVSSIQ 4MB（P305~P310）。注意 EK 板是 32MB+，容量/型号必须按实际改。

其余：所有用到的 &ioportN 置 okay；&trng/&crc/&wdt 置 okay；&flash1 划分 8KB storage 分区。

3.8 ebf_qm6m5-pinctrl.dtsi —— 引脚复用

RA 平台用 RA_PSEL(功能, 端口, 引脚) 三元组，功能号见 include/zephyr/dt-bindings/pinctrl/renesas/pinctrl-ra.h（如 RA_PSEL_SCI_4、RA_PSEL_SPI、RA_PSEL_QSPI、RA_PSEL_ADC）：

&pinctrl {
    sci4_default: sci4_default {
        group1 {
            psels = <RA_PSEL(RA_PSEL_SCI_4, 5, 12)>,   /* TXD4 = P512 */
                <RA_PSEL(RA_PSEL_SCI_4, 5, 11)>;   /* RXD4 = P511 */
        };
    };

    spi0_default: spi0_default {
        group1 {
            /* MOSI=P203、RSPCK=P204；P202 留作 LCD DC（GPIO），SSL 不用 */
            psels = <RA_PSEL(RA_PSEL_SPI, 2, 3)>,
                <RA_PSEL(RA_PSEL_SPI, 2, 4)>;
            drive-strength = "high";
        };
    };
    /* qspi_default / adc0_default 同理 */
};

SPI 引脚功能由引脚本身决定（P203=MOSIA、P204=RSPCKA、P202=MISOA、P205=SSLA0），RA_PSEL 只把引脚切到 SPI 外设模式；选脚时查 SoC 数据手册的引脚功能表，或参考 ek_ra6m5-pinctrl.dtsi 的注释。把某个 SPI 功能位（如 MISO 位 P202）用作 GPIO 时，不放进 pinctrl 组即可，应用层 gpio_pin_configure 会接管。

4. 构建与验证流程

复制blinky到app目录下面

cd /d/RA/RA6M5
export ZEPHYR_BASE=/d/zephyrproject/zephyr \
  ZEPHYR_SDK_INSTALL_DIR=/d/luglZephyrproject/zephyr-sdk-1.0.1/zephyr-sdk-1.0.1 \
  PATH="/c/ncs/toolchains/936afb6332/opt/bin:/c/Program Files/SEGGER/JLink:$PATH"

# 构建（BOARD_ROOT 指向板卡所在仓库）
west build -b ebf_qm6m5 -d build/blinky app/blinky -- -DBOARD_ROOT=D:/RA/RA6M5
# 烧录
west flash -d build/blinky -r jlink

脱手复位（不启动 GDB server）：build/jlink_reset.jlink（内容 reset/go/exit）：

"/c/Program Files/SEGGER/JLink/JLink.exe" -device R7FA6M5BH -if SWD \
  -speed 4000 -autoconnect 1 -CommanderScript build/jlink_reset.jlink

建议的验证顺序（每一步通了再进行下一步）：

1. west build 编译通过（先验证板卡定义本身合法，可用 samples/blinky）

1. 串口控制台有输出（验证 SCI4 + 时钟 + pinctrl）

2. LED 闪烁（samples/basic/blinky，验证 GPIO 与 aliases）

1. 按键中断（验证 port_irq 中断号）

2. 各外设逐个启用验证（SPI/QSPI/ADC…）

5. 本板特有的坑（实测记录）

• J-Link 读不到外设寄存器：RA6M5 的 0x4004xxxx/0x4008xxxx 区域经 J-Link 读取全返回 0，不要用它判断寄存器状态，以固件日志为准。

• 调试串口选择：板上有两路控制台候选——SCI4（CH340 USB 串口，跳线 J35 默认接通）和 SCI2（P112/P113，JTAG 座 17/19 脚，DAP 调试器虚拟串口）。本 BSP 选 SCI4。

• boot 模式：MD 跳线 J17 置 2-3 进 SCI/USB boot 模式（可用 rfp runner），正常运行置 1-2。

• 串口中文日志在 PowerShell 下显示为 ?：是读取端编码问题，非固件问题；日志可用英文规避。

• Zephyr gpio-i2c 在 RA6M5 不可用（输出模式 PIDR 读回恒 0），触摸等需要 bit-bang I2C 的场景需自研方向切换实现，详见 docs/LCD-PAR-S035_Zephyr调试笔记.md §5。

6. 参考资料

• Zephyr 官方 Board Porting Guide：https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html

• 参照板：D:\zephyrproject\zephyr\boards\renesas\ek_ra6m5\

• SoC dtsi：D:\zephyrproject\zephyr\dts\arm\renesas\ra\ra6\r7fa6m5bh3cfc.dtsi