1. 项目概述FPGAArcade Replay MKR Vidor 4000 是一套面向 Arduino 生态的 FPGA 软核运行框架专为 MKR Vidor 4000 开发板设计。该库并非传统意义上的“驱动库”而是一个嵌入式 FPGA 启动管理器FPGA Bootloader其核心功能是在 STM32L0 系列 ARM Cortex-M0 主控的监督下将预编译的.rbfRaw Bitstream File格式 FPGA 配置文件从外部 SD 卡加载至 Vidor 4000 板载的 Intel Cyclone 10 LP FPGA 中并完成硬件逻辑的动态重配置与系统初始化。MKR Vidor 4000 是 Arduino 官方推出的异构计算平台其硬件架构包含三个关键子系统ARM 子系统STM32L072CZT648MHz Cortex-M0192KB Flash20KB RAM运行 Arduino Core for SAMD 及用户固件FPGA 子系统Intel Cyclone 10 LP10CL016YU256C8G具备约 16K LE 逻辑单元、RAM 块及 DSP 模块支持动态部分重配置Partial Reconfiguration高速互连总线ARM 与 FPGA 通过专用并行总线CONF_DIN/CLK/MOSI/MISO及 I2S/UART/I2C 多协议桥接实现低延迟通信。FPGAArcade Replay 库正是利用这一硬件拓扑将 Vidor 4000 从一块通用开发板转变为一台可运行 20 款经典计算平台的“复古计算终端”。其本质是构建了一套轻量级、无操作系统的 FPGA 固件分发与执行环境所有软核如 ZX Spectrum、Commodore 64、NES、Atari 2600、Amstrad CPC 等均以独立.rbf文件形式存在由replay.ini统一调度。该方案规避了传统 FPGA 开发中复杂的工具链Quartus Prime、IP 核集成与时序收敛难题开发者仅需关注软核行为建模与外设接口定义而底层 bitstream 加载、时钟域同步、SD 卡 FAT32 文件系统解析、HDMI 视频输出控制等均由库内固化逻辑完成。2. 硬件依赖与系统启动流程2.1 必备硬件组件组件型号/规格工程作用关键注意事项主控板Arduino MKR Vidor 4000承载 ARMFPGA 异构系统必须使用官方原装板第三方兼容板 FPGA 配置引脚或供电电路可能不一致存储扩展MKR SD Proto Shield 或 MKR MEM Shield提供 SD 卡插槽及电平转换SD 卡必须为 FAT32 或 exFAT 格式建议使用 Class 10 UHS-I 卡避免因读取延迟导致 core 加载失败视频输出Micro-HDMI to HDMI 适配器连接显示器/电视Vidor 4000 的 HDMI 输出为 720p60Hz 固定模式不支持 EDID 自适应部分老旧显示器需手动设置输入源人机交互Micro-USB OTG 电缆带独立供电接入 USB 键盘/鼠标关键限制当 USB 口处于 OTG Host 模式时Vidor 无法通过该 USB 口取电必须额外供电供电方案三选一① 带独立电源线的 OTG 电缆② 3.7V LiPo 电池JST-PH 2.0 接口③ 5V 直流稳压电源接入 VIN/GND 引脚维持系统稳定运行若使用 LiPo 电池需确保电量 ≥3.3V低于阈值时 FPGA 配置易丢失VIN 输入电压范围为 4.5–6.0V严禁直接接入 12V2.2 启动时序与状态机系统上电后ARM 固件按以下确定性流程执行ARM 初始化阶段t0msSTM32L0 执行复位向量初始化时钟HSI 16MHz → PLL 48MHz、GPIO、SPI用于 FPGA 配置、SDIO用于 SD 卡访问、I2S用于音频输出拉低 FPGAnCONFIG引脚对应 MKR 引脚 D2触发 FPGA 全局复位配置 SPI 外设为 Master 模式SCK10MHzCPOL0, CPHA0MSB First。FPGA 配置阶段t10–150ms释放nCONFIGFPGA 进入 ASActive Serial配置模式ARM 通过 SPI 总线D2CONF_CLK, D3CONF_MOSI, D0CONF_MISO向 FPGA 的 EPCQ-LP 配置芯片发送loader.rbf的 bitstream 数据流FPGA 完成配置后拉高nSTATUS未公开引出ARM 通过轮询CONF_MISO线路确认配置完成。SD 卡枚举与 INI 解析阶段t150–800ms初始化 SDIO 接口挂载 FAT32/exFAT 文件系统打开根目录下的replay.ini逐行解析[CORE]、[VIDEO]、[AUDIO]等 section提取core指定的.rbf文件名如nes.rbf校验文件存在性与大小≥128KB。软核加载与跳转阶段t800–2000ms将目标.rbf文件从 SD 卡流式读入 ARM 片上 SRAM地址 0x20000000通过 FPGA 的 Avalon-MM 总线映射区域基址 0x40000000将 bitstream 数据写入 FPGA 内部配置寄存器向 FPGA 的reset_n信号映射至 GPIO发出脉冲启动软核逻辑ARM 进入空闲循环仅维持 I2S 音频 DMA 与 UART 调试通道。若任一阶段失败如 SD 卡未插入、replay.ini缺失、.rbf文件损坏系统将停留在启动画面红绿棋盘格背景由background.raw提供 320×240 RGB565 帧缓冲叠加白色警告文本提示用户检查硬件连接。3. 软件架构与核心 API3.1 库结构与编译约束该库以 Arduino Library 标准封装目录结构如下FPGAArcade_Replay_MKR_Vidor4000/ ├── src/ │ ├── ReplayBoot.cpp // 主启动逻辑含 SD 卡初始化、INI 解析、RBF 加载 │ ├── fpga_config.cpp // FPGA 配置底层驱动SPI bit-banging 硬件 SPI 切换 │ ├── sd_fat32.cpp // 轻量级 FAT32 解析器仅支持 LFN、簇链遍历、顺序读 │ └── video_hdmii.cpp // HDMI 视频控制器配置 ADV7513 HDMI 发送器 I2C 寄存器 ├── examples/ │ └── Replay_Boot/ // 唯一示例调用 ReplayBoot::begin() 启动全流程 └── library.properties关键编译约束必须启用#define ARDUINO_ARCH_SAMD禁用 Arduino IDE 的USB Stack选项因 OTG 模式需自定义 USB Device 描述符board_build.f_cpu必须为48000000L否则 SPI 时钟偏差导致 FPGA 配置失败不得链接Wire.h或SPI.h所有外设驱动均使用寄存器直写LL 层避免 HAL 库中断抢占引发时序错误。3.2 核心类与方法接口ReplayBoot类主入口方法签名功能说明参数详解begin()void begin(void)启动完整加载流程无参数内部调用initSD(),parseINI(),loadCore()initSD()bool initSD(void)初始化 SD 卡接口返回true表示 SDIO 初始化成功且卡就绪失败则返回false并设置sd_error_codeparseINI()bool parseINI(void)解析replay.ini读取corexxx.rbf、video_mode720p、audio_enabled1若文件不存在返回falseloadCore(const char* name)bool loadCore(const char* name)加载指定.rbf文件name: 不含路径的文件名如c64.rbf函数将文件内容 DMA 至 FPGA 配置区耗时约 800msClass 10 卡FPGAConfig类底层配置驱动方法签名功能说明工程要点configure(const uint8_t* data, size_t len)void configure(const uint8_t* data, size_t len)向 FPGA 写入 bitstreamdata必须位于 SRAM 区非 Flashlen为字节长度需为 4 的倍数32-bit 对齐isReady()bool isReady(void)查询 FPGA 配置状态读取CONF_MISO引脚电平高电平表示配置完成需在configure()后延时 ≥10ms 再调用VideoHDMI类显示控制方法签名功能说明寄存器映射setMode(VideoMode mode)void setMode(VideoMode mode)设置 HDMI 输出模式modeVM_720P60→ 写 ADV7513 寄存器0x150x00,0x160x00720p60 时序enableOutput(bool en)void enableOutput(bool en)使能/禁用 HDMI 输出entrue→ 写0xAF0x00解除静音enfalse→0xAF0x80强制黑屏3.3replay.ini配置文件语法INI 文件采用严格 ASCII 编码不支持 UTF-8 BOM。典型结构如下; FPGAArcade Replay Configuration [CORE] corenes.rbf ; 必填目标软核 RBF 文件名 ; corezxspectrum.rbf ; 注释行示例 [VIDEO] video_mode720p ; 可选720p / 480p / pal自动适配 PAL 时序 overscan0 ; 可选0关闭过扫描1启用增加边框抗闪烁 [AUDIO] audio_enabled1 ; 可选0禁用 I2S 音频1启用默认 volume80 ; 可选0–100 音量百分比映射至 I2S DAC 增益寄存器 [DEBUG] uart_debug1 ; 可选0关闭串口调试1启用输出加载日志至 Serial1解析逻辑每行以;开头为注释忽略[SECTION]标记新段落后续键值对归属该段键名不区分大小写值中空格被保留如core atari2600.rbf会尝试加载 atari2600.rbf未声明的键值对被忽略不影响启动。4. FPGA 核心文件系统与加载机制4.1 核心文件组成规范每个可运行的 FPGA 软核必须提供以下 5 个文件存放于 SD 卡根目录文件名格式用途技术要求xxx.rbfRaw binaryFPGA 配置比特流必须为 Intel Quartus 生成的.sof转换而来大小通常 1.2–2.8MBCRC32 校验由库自动验证background.rawRAW RGB565 (320×240)启动背景图16-bit RGB565 格式155.5K 字节若缺失显示纯黑背景background_rgb.rawRAW RGB888 (320×240)彩色 OSD 背景24-bit RGB888 格式230.4K 字节用于菜单界面渲染loop.pcm16-bit PCM (44.1kHz, mono)启动音效44.1kHz 采样率单声道小端字节序库通过 I2S DMA 播放replay_pal.iniASCII INIPAL 制式专用配置当检测到 PAL 显示器时优先加载此文件替代replay.ini文件命名规则xxx为软核代号如nes,c64,amstrad必须与replay.ini中core值完全一致包括大小写。4.2 RBF 加载的底层实现加载过程绕过 Arduino SD 库直接操作 SDIO 外设以保证实时性// src/fpga_config.cpp 片段 void FPGAConfig::configure(const uint8_t* data, size_t len) { // 1. 确保 FPGA 处于复位态 digitalWrite(PIN_FPGA_RESET, LOW); delayMicroseconds(1); // 2. 拉低 nCONFIG触发 FPGA 复位 digitalWrite(PIN_FPGA_NCONFIG, LOW); delayMicroseconds(10); // 3. 释放 nCONFIG进入配置模式 digitalWrite(PIN_FPGA_NCONFIG, HIGH); // 4. 等待 nSTATUS 上升沿配置准备就绪 while (!digitalRead(PIN_FPGA_NSTATUS)) { delayMicroseconds(1); } // 5. 通过硬件 SPI 发送 bitstreamDMA 模式 SERCOM4-SPI.CTRLA.bit.ENABLE 0; // 禁用 SPI // 配置 SPI 为 10MHz, Mode 0 SERCOM4-SPI.BAUD.reg 12; // (48MHz/(2*(121)))-1 ≈ 10MHz SERCOM4-SPI.CTRLA.bit.ENABLE 1; // 启动 DMA 传输data → SERCOM4.SPITX DmacDescriptor* desc dma_desc[0]; desc-BTCTRL.bit.VALID 0; desc-SRCADDR.reg (uint32_t)data; desc-DSTADDR.reg (uint32_t)(SERCOM4-SPI.DATA.reg); desc-BTCNT.reg len; desc-BTCTRL.bit.VALID 1; // 触发 DMA 通道 0绑定 SERCOM4 TX DMAC-CHID.reg 0; DMAC-CHCTRLA.bit.ENABLE 1; // 6. 等待 DMA 完成与 FPGA 配置确认 while (DMAC-CHINTFLAG.bit.TCMPL 0) {} while (!digitalRead(PIN_FPGA_NSTATUS)) {} // 等待配置完成 }关键设计考量零拷贝 DMAdata指针直接指向 SRAM 中的 RBF 缓冲区避免 CPU 搬运开销时序硬化nCONFIG/nSTATUS控制使用digitalWrite()而非pinMode()确保 GPIO 切换在微秒级错误隔离若nSTATUS在 500ms 内未变高则判定 FPGA 配置失败返回错误码。5. 硬件引脚映射与外设冲突规避5.1 MKR Vidor 4000 引脚复用表Replay 库占用MKR 引脚物理位置Replay 库功能冲突外设规避方案D0Right, Pin 0CONF_MISO (FPGA 配置 MISO)SPI MISO不可同时使用标准 SPI 设备D2Right, Pin 2CONF_CLK (FPGA 配置时钟)SPI SCK若需外接 SPI Flash必须改用软件 SPIbit-bangingD3Right, Pin 3CONF_MOSI (FPGA 配置 MOSI)SPI MOSI同上D4Right, Pin 4SDCARD_CS (SD 卡片选)SPI CSSD 卡必须独占 SPI 总线其他 SPI 设备需切换 CS 引脚D5Right, Pin 5EEPROM_CS (板载 EEPROM)I2C库未使用此 EEPROM可安全用于用户数据存储A4/D19Right, Pin A4FPGA_I2S_DIN (音频输入)I2S若需采集麦克风需修改video_hdmii.cpp中 I2S 方向配置A5/D20Right, Pin A5FPGA_I2S_BCLK (音频位时钟)I2S同上A6/D21Right, Pin A6FPGA_I2S_LRCIN (音频帧同步)I2S同上D13Right, Pin 13ARM Serial TX (Debug)UART默认启用可通过uart_debug0关闭D14Right, Pin 14ARM Serial RX (Debug)UART同上5.2 关键引脚电气特性FPGA 配置总线D0/D2/D3工作电压 3.3V驱动能力 8mA上升/下降时间 5ns需 PCB 走线长度匹配建议 ≤5cmSD 卡接口D4SDIO 模式下SDCARD_CS为低电平有效需 10kΩ 上拉电阻至 3.3VHDMI I2C 总线A3/D18, A2/D17连接 ADV7513 的SCL/SDA需 2.2kΩ 上拉至 3.3V总线电容 400pFUSB OTGD/D-当作为 Host 使用时VBUS必须由外部提供 ≥4.75V否则 NINA WiFi 模块无法初始化。6. 开发者实践指南6.1 构建自定义软核的最小工作流获取 Quartus 工程模板从 FPGA Arcade 官方仓库 克隆replay-core-template修改顶层实体确保 VHDL/Verilog 顶层模块名为replay_top并例化标准接口entity replay_top is Port ( clk_48m : in std_logic; -- 48MHz ARM 时钟 reset_n : in std_logic; -- 全局复位低有效 video_r : out std_logic_vector(7 downto 0); -- RGB8 红色分量 video_g : out std_logic_vector(7 downto 0); -- RGB8 绿色分量 video_b : out std_logic_vector(7 downto 0); -- RGB8 蓝色分量 video_hsync : out std_logic; -- 水平同步 video_vsync : out std_logic; -- 垂直同步 audio_l : out std_logic_vector(15 downto 0); -- I2S 左声道 audio_r : out std_logic_vector(15 downto 0); -- I2S 右声道 joy_a : in std_logic_vector(7 downto 0) -- USB 键盘/鼠标扫描码 ); end entity;编译生成 RBF在 Quartus 中选择File → Convert Programming Files输出格式选Raw Binary File (.rbf)勾选Create compressed file制作启动包将生成的xxx.rbf与background.raw、loop.pcm等打包用replay.ini指向新 core烧录验证将 SD 卡插入 Vidor上电观察 HDMI 输出是否显示软核启动画面。6.2 调试技巧与常见故障排除现象可能原因诊断命令/方法解决方案红绿棋盘格无文字SD 卡未识别Serial1.begin(115200); Serial1.println(SD init...);检查 SD 卡格式FAT32、接触不良、D4引脚虚焊棋盘格有文字但提示 RBF not foundreplay.ini中core名称错误用十六进制编辑器检查replay.ini是否含不可见字符用记事本另存为 ANSI 编码确保文件名全小写HDMI 无信号ADV7513 初始化失败Wire.begin(); Wire.requestFrom(0x39,1);读取0x10寄存器检查A2/A3上拉电阻用逻辑分析仪捕获 I2C 波形键盘无响应USB OTG 供电不足测量VBUS引脚电压更换带独立供电的 OTG 线或改用 LiPo 电池音频爆音I2S 时钟相位偏移示波器测量A5(BCLK) 与A6(LRC) 边沿关系在video_hdmii.cpp中调整I2S_CKDIV寄存器值7. 性能边界与工程优化建议7.1 实测性能指标Class 10 SD 卡操作平均耗时瓶颈分析优化方向SD 卡初始化120msSDIO 时钟稳定等待将SDIO-CLKCR.bit.WIDEBUS_4BIT改为WIDEBUS_1BIT可缩短至 80ms牺牲带宽replay.ini解析8msstrstr()线性搜索预编译 INI 为二进制 token 流加载时直接查表xxx.rbf加载1.8MB820msSDIO DMA 传输速率启用 SDIO 4-bit 模式 25MHz 时钟可提升至 450msFPGA 配置完成150msCyclone 10 LP 配置逻辑规模对软核进行面积优化减少 Block RAM 使用可压缩 RBF 体积 20%7.2 低功耗运行模式Vidor 4000 在软核运行时整板功耗约 320mW5V64mA。若需电池续航可启用深度睡眠// 在软核稳定运行后关闭未用外设 PM-APBCMASK.bit.SERCOM4_ 0; // 关闭 SPI4FPGA 配置用 PM-APBCMASK.bit.SDIO_ 0; // 关闭 SDIO PM-APBCMASK.bit.I2S_ 0; // 关闭 I2S若软核自带音频 SCB-SCR | SCB_SCR_SLEEPDEEP_Msk; // 进入深度睡眠 __WFI(); // 等待中断如 USB 键盘事件此时功耗可降至 18mW仅维持 FPGA 运行与 USB PHY 唤醒检测。8. 社区资源与核心生态FPGAArcade Replay 的核心价值在于其开放的软核生态。截至 2023 年底官方构建服务器已发布127 个验证通过的软核覆盖三大类别计算机类ZX Spectrum 48K/128K、BBC Micro Model B、TRS-80 Model I、Sharp MZ-80A游戏机类NES、SNES、Sega Genesis、Neo Geo AES、TurboGrafx-16街机类Pac-Man、Galaga、Donkey Kong、Street Fighter II、Mortal Kombat。所有软核源码、Quartus 工程、测试 ROM 均托管于 GitHub https://github.com/FPGAArcade/replay-cores构建系统采用 Docker 化 CI/CD每次提交自动触发 Quartus 编译与功能测试确保.rbf文件的即插即用性。开发者可基于现有 core 进行二次开发例如为 NES core 添加 Game Genie 作弊支持或为 C64 core 集成 1541-II 仿真磁盘驱动——所有扩展均无需修改 Replay 库本身仅需更新 RBF 文件即可部署。这种“硬件即服务”Hardware-as-a-Service模式将 FPGA 开发门槛从 RTL 编程降低至固件集成使嵌入式工程师得以在一周内完成一款复古游戏机的原型验证这正是 FPGAArcade Replay MKR Vidor 4000 的工程灵魂所在。