1. JTAG_Interface 库概述：面向 MKR Vidor 4000 的 FPGA-CPU 协同开发基础设施

JTAG_Interface 是一个专为 Arduino MKR Vidor 4000 开发板设计的底层硬件抽象库，其核心使命是 在 SAMD21 微控制器（MCU）与 Cyclone 10 LP FPGA 之间建立稳定、低开销、可编程的实时通信通道 。该库并非仅用于一次性配置 FPGA，而是构建了一套完整的运行时数据交换机制——既支持 FPGA bitstream 的安全烧录，也支撑 MCU 与 FPGA 用户逻辑之间的双向寄存器级交互。

MKR Vidor 4000 的硬件架构天然具备 JTAG 链路：SAMD21 的 SWD/JTAG 接口通过专用引脚（TCK/TMS/TDI/TDO）物理连接至 FPGA 的 JTAG TAP 控制器。传统 Arduino 库（如 VidorGraphics 或 VidorPeripherals ）正是利用此链路，在上电时自动加载预置 bitstream 并封装通信协议，使用户无需感知底层细节。然而，一旦开发者脱离官方固件，转向使用 Intel Quartus 自行设计 FPGA 逻辑，这套“魔法”即告失效—— FPGA 成为一块沉默的硅片，MCU 无法读取其状态，也无法向其下发指令或数据 。

JTAG_Interface 正是为此而生。它将 JTAG 链路从单纯的配置通道，升格为 可编程的片上总线（On-Chip Bus） 。其本质是一个轻量级、参数化、可综合的 Verilog 模块 jtag_interface ，部署于 FPGA 用户逻辑中，作为 MCU 访问 FPGA 内部寄存器的唯一入口点。MCU 端通过标准 JTAG 指令序列（ SAMPLE/PRELOAD , EXTEST , IDCODE 等）驱动该模块，实现对 FPGA 片内寄存器组的原子性读写操作。整个过程不依赖任何额外的物理总线（如 SPI/I2C），完全复用现有 JTAG 引脚，零硬件改动即可启用。

该库的价值在于 工程确定性 ：它规避了 USB-UART 桥接、专用 GPIO 模拟总线等方案带来的时序不确定性与资源开销；它提供了比 Xilinx/Intel 官方 JTAG 调试器更直接、更低延迟的寄存器访问能力；更重要的是，它将 FPGA 开发流程标准化——Quartus 工程只需例化对应模块，Arduino 代码即可立即获得确定性的 I/O 映射。

2. 系统架构与核心模块设计原理

2.1 整体通信模型

JTAG_Interface 构建了一个 主从式、寄存器映射（Register-Mapped I/O） 的通信模型：

• 主设备（Master） ：SAMD21 MCU，运行 Arduino 固件，通过 HAL 库（ HAL_GPIO_WritePin , HAL_GPIO_ReadPin ）精确控制 JTAG 引脚电平与时序，模拟 JTAG TAP 控制器行为。
• 从设备（Slave） ：FPGA 中的 jtag_interface 模块，作为 JTAG TAP 的用户指令扩展（User Instruction），响应特定指令并执行寄存器读写。
• 通信载体 ：标准 JTAG 链路（TCK, TMS, TDI, TDO），工作频率由 MCU 软件精确控制（典型值 1–5 MHz，远低于硬件 TAP 最大速率，确保可靠性）。

此模型的关键优势在于 硬件解耦 ：MCU 不需要理解 FPGA 内部逻辑，只需按协议操作寄存器；FPGA 不需要为每种外设定制接口，只需将用户逻辑信号连接至 jtag_interface 的输入/输出端口。

2.2 jtag_interface 模块的 Verilog 实现逻辑

jtag_interface 的核心是一个状态机，其行为由 JTAG TAP 状态机与用户指令共同驱动。其 Verilog 结构可概括为：

module jtag_interface #(
    parameter NUM_REGS = 3,      // 可配置寄存器数量：3, 7, 15, 31
    parameter REG_WIDTH = 32     // 每个寄存器位宽（默认32位）
) (
    input  wire clk_120m,        // FPGA 主时钟（120 MHz）
    input  wire tck,             // JTAG 时钟
    input  wire tms,             // JTAG 模式选择
    input  wire tdi,             // JTAG 数据输入
    output reg tdo,             // JTAG 数据输出
    output reg [REG_WIDTH-1:0] out_regs [NUM_REGS-1:0], // 输出寄存器组（MCU可写）
    input  wire [REG_WIDTH-1:0] in_regs [NUM_REGS-1:0]   // 输入寄存器组（MCU可读）
);

// 1. JTAG TAP 状态机同步采样（关键！）
reg [4:0] tap_state;
always @(posedge tck) begin
    if (tms) 
        case (tap_state)
            5'b00001: tap_state <= 5'b00010; // Test-Logic-Reset -> Run-Test/Idle
            5'b00010: tap_state <= 5'b00100; // Run-Test/Idle -> Select-DR-Scan
            5'b00100: tap_state <= 5'b01000; // Select-DR-Scan -> Capture-DR
            5'b01000: tap_state <= 5'b10000; // Capture-DR -> Shift-DR
            5'b10000: tap_state <= 5'b00000; // Shift-DR -> Exit1-DR
            default: tap_state <= 5'b00001;
        endcase
    else
        case (tap_state)
            5'b00001: tap_state <= 5'b00001; // Test-Logic-Reset
            5'b00010: tap_state <= 5'b00010; // Run-Test/Idle
            5'b00100: tap_state <= 5'b00100; // Select-DR-Scan
            5'b01000: tap_state <= 5'b01000; // Capture-DR
            5'b10000: tap_state <= 5'b10000; // Shift-DR
            default: tap_state <= 5'b00001;
        endcase
end

// 2. 用户指令识别（固定为0x01，对应BYPASS指令的变体）
wire user_instruction = (tap_state == 5'b10000) && (tdi == 1'b1); // 简化示意，实际需解析IR

// 3. 寄存器读写引擎（核心逻辑）
reg [4:0] reg_addr; // 当前操作寄存器地址（5位足够寻址32个寄存器）
reg [REG_WIDTH-1:0] shift_reg; // 移位寄存器
reg write_en;

// 在Shift-DR状态下，TDI数据移入shift_reg
always @(posedge tck) begin
    if (tap_state == 5'b10000) begin // Shift-DR
        shift_reg <= {shift_reg[REG_WIDTH-2:0], tdi};
        if (write_en) begin
            out_regs[reg_addr] <= shift_reg; // 写入输出寄存器
        end
    end
end

// TDO输出：在Shift-DR期间，输出当前输入寄存器的对应位
assign tdo = (tap_state == 5'b10000) ? in_regs[reg_addr][0] : 1'b0;

endmodule

设计要点解析 ：

• 时钟域隔离 ： jtag_interface 运行在 clk_120m 下，但所有 JTAG 信号（ tck/tms/tdi/tdo ）均视为异步输入。模块内部通过两级触发器进行同步采样，彻底消除亚稳态风险，这是工业级 JTAG 设计的黄金准则。
• 地址空间优化 ： NUM_REGS 参数被严格限定为 2^n - 1 （3, 7, 15, 31）。原因在于：若使用 2^n 个寄存器（如 4, 8, 16），则地址译码需 n+1 位，但最高位恒为 0，导致地址空间浪费。 2^n - 1 可保证 n 位地址线满载利用，例如 31 个寄存器仅需 5 位地址（ 0x00 – 0x1E ），无冗余。
• 位宽灵活性 ： REG_WIDTH 参数允许用户根据数据吞吐需求调整寄存器宽度。32 位是 ARM Cortex-M0+ 的自然字长，可单次传输一个 uint32_t ；若需节省 FPGA 逻辑资源，可设为 8 或 16 位，此时 MCU 需分多次读写。

2.3 MCU 端软件协议栈

MCU 端固件实现了完整的 JTAG 协议栈，其关键函数位于 JTAG_Interface.h 中：

函数名	原型	功能说明
JTAG_Init()	void JTAG_Init(void)	初始化 JTAG 引脚（TCK/TMS/TDI/TDO）为推挽输出，TDO 为浮空输入；执行 JTAG 复位序列（TMS=1 连续 5 个 TCK）
JTAG_ShiftDR(uint32_t data_in, uint32_t *data_out, uint8_t bits)	void JTAG_ShiftDR(uint32_t data_in, uint32_t *data_out, uint8_t bits)	在 Shift-DR 状态下，将 data_in 的低 bits 位串行移入 FPGA，并将 FPGA 移出的 bits 位存入 *data_out 。这是所有读写操作的基础
JTAG_WriteReg(uint8_t addr, uint32_t value)	void JTAG_WriteReg(uint8_t addr, uint32_t value)	向地址 addr 的输出寄存器写入 value 。内部调用 JTAG_ShiftDR ，先发送地址+写命令，再发送数据
JTAG_ReadReg(uint8_t addr, uint32_t *value)	void JTAG_ReadReg(uint8_t addr, uint32_t *value)	从地址 addr 的输入寄存器读取数据到 *value 。内部调用 JTAG_ShiftDR ，先发送地址+读命令，再接收数据

时序关键点 ：所有 JTAG 操作均基于 HAL_Delay(1) 的粗粒度延时，这在 1–5 MHz 速率下完全可行。若需更高性能，可替换为 __NOP() 循环或 SysTick 定时器微秒级延时。

3. 快速上手：从库安装到首个自定义 Bitstream

3.1 库安装与验证

安装流程已深度集成 Arduino IDE 生态：

1. 打开 Arduino IDE → 工具 → 库管理...
2. 在搜索框中输入 JTAG Interface
3. 选择 JTAG_Interface 库（作者：herrnamenlos123），点击 安装
4. 安装完成后，重启 IDE，打开 文件 → 示例 → JTAG_Interface → simple 示例

simple 示例代码的核心逻辑如下：

#include <JTAG_Interface.h>

void setup() {
  Serial.begin(115200);
  JTAG_Init(); // 初始化JTAG引脚与链路
  
  // 向FPGA的寄存器0写入0xDEADBEEF
  JTAG_WriteReg(0, 0xDEADBEEF);
  
  // 从FPGA的寄存器0读回数据并打印
  uint32_t val;
  JTAG_ReadReg(0, &val);
  Serial.printf("Read from FPGA reg0: 0x%08X\n", val);
}

void loop() {
  // 主循环中可周期性读写寄存器，实现状态监控或指令下发
  delay(1000);
}

成功运行此示例，表明 MCU 与 FPGA 的 JTAG 通信链路已建立。

3.2 Quartus 工程集成与 Bitstream 生成

库的 src/ 目录下附带了完整的 Quartus 工程模板（路径： FPGA/projects/example_simple/ ）。首次开发应遵循以下步骤：

1. 定位库路径 ：Arduino 默认库路径为 C:/Users/<USERNAME>/Documents/Arduino/libraries/ ，进入 JTAG_Interface 文件夹。
2. 打开 Quartus 工程 ：使用 Intel Quartus Prime Lite 21.1.1.850（或兼容版本）打开 FPGA/projects/example_simple/MyDesign.bdf 。
3. 理解顶层结构 ： MyDesign.bdf 是原理图文件，其核心是 MKRVIDOR4000_top.v （Verilog 顶层模块）。在 MKRVIDOR4000_top.v 中，找到 jtag_interface 的例化语句：

   jtag_interface #(.NUM_REGS(3), .REG_WIDTH(32)) uut_jtag (
       .clk_120m(clk_120m),
       .tck(tck),
       .tms(tms),
       .tdi(tdi),
       .tdo(tdo),
       .out_regs({leds, sw}), // 将LED和SW开关连接至输出寄存器
       .in_regs({btn, adc_data}) // 将按钮和ADC数据连接至输入寄存器
   );
   

4. 定制寄存器映射 ：根据你的 FPGA 逻辑需求，修改 .out_regs 和 .in_regs 的连接。例如，若需控制 PWM 占空比，可将 pwm_duty 信号接入 out_regs[1] ；若需读取传感器数据，可将 sensor_value 接入 in_regs[2] 。
5. 编译与生成 Bitstream ：
   • 点击工具栏蓝色播放按钮（ Start Compilation ）。
   • 编译成功后，Bitstream 文件位于 output_files/MKRVIDOR4000.sof （SRAM Object File）。

3.3 Bitstream 转换与烧录：ByteReverser 工具链

Quartus 生成的 .sof 文件是二进制格式，需转换为 Arduino 可识别的 C 数组头文件 FPGA_Bitstream.h 。此任务由配套工具 ByteReverser 完成：

1. 下载 ByteReverser ：从项目 GitHub Releases 页面获取 Windows 可执行文件。
2. 创建转换配置 ：
   • 输入文件： output_files/MKRVIDOR4000.sof
   • 输出文件： <Arduino_Lib_Path>/JTAG_Interface/src/FPGA_Bitstream.h
   • 关键选项： Reverse Bytes （字节反转）——这是 Cyclone 10 LP FPGA 加载要求的必要步骤。
3. 执行转换 ：运行 ByteReverser.exe ，加载配置并执行。生成的 FPGA_Bitstream.h 包含类似以下内容：

   #ifndef FPGA_BITSTREAM_H
   #define FPGA_BITSTREAM_H
   const unsigned char fpga_bitstream[] PROGMEM = {
       0xFF, 0x00, 0xAA, 0x55, ... // 数万字节的bitstream数据
   };
   const unsigned int fpga_bitstream_size = 123456;
   #endif
   

4. 烧录到 FPGA ：在 Arduino 代码中调用 JTAG_UploadBitstream() 函数，该函数会遍历 fpga_bitstream[] 数组，通过 JTAG 链路将数据逐字节写入 FPGA 的配置 SRAM。

4. 高级应用：扩展寄存器数量与多模块协同

4.1 扩展寄存器数量：从 31 到 N

当预置的 31 个寄存器（ jtag_interface31.v ）仍不满足需求时，可手动扩展。扩展方法严格遵循 jtag_interface 的设计范式：

1. 复制模板 ：将 jtag_interface31.v 复制为 jtag_interface63.v 。
2. 修改参数与逻辑 ：
   • 将 parameter NUM_REGS = 31 改为 63 。
   • 修改地址计数器位宽：原 reg [4:0] reg_addr （5位）需升级为 reg [5:0] reg_addr （6位）。
   • 更新 reg_addr 的最大值判断逻辑（如 if (reg_addr == 6'd62) ）。
3. 生成符号文件 ：在 Quartus 中， File → Create/Update → Create Symbol Files for Current File 。新模块 jtag_interface63 将出现在元件库中，可供原理图调用。

工程权衡 ：增加寄存器数量会线性增长 FPGA 的 LUT 与寄存器资源消耗。31 个寄存器约占用 200–300 个逻辑单元，63 个则接近 500。务必在资源紧张时，优先考虑复用寄存器（如用 1 位标志位 + 31 位数据域）而非盲目扩容。

4.2 多模块协同：JTAG 作为片上总线

jtag_interface 的终极价值在于其可组合性。一个复杂的 FPGA 系统可划分为多个功能模块，每个模块拥有自己的 jtag_interface 实例，共享同一 JTAG 链路：

// 顶层模块中例化多个jtag_interface
jtag_interface #(.NUM_REGS(3), .REG_WIDTH(32)) uut_pwm (
    .clk_120m(clk_120m),
    .tck(tck), .tms(tms), .tdi(tdi), .tdo(tdo_pwm),
    .out_regs({pwm_ch0_duty, pwm_ch1_duty, pwm_freq}),
    .in_regs({pwm_ch0_status, pwm_ch1_status, reserved})
);

jtag_interface #(.NUM_REGS(7), .REG_WIDTH(16)) uut_adc (
    .clk_120m(clk_120m),
    .tck(tck), .tms(tms), .tdi(tdi), .tdo(tdo_adc),
    .out_regs({adc_config, adc_trigger}),
    .in_regs({adc_ch0, adc_ch1, adc_ch2, adc_ch3, adc_ch4, adc_ch5, adc_status})
);

// 多路复用TDO：使用TMS作为片选信号
assign tdo = (tms == 1'b0) ? tdo_pwm : tdo_adc;

MCU 端通过 JTAG_WriteReg() 的地址参数，结合 tms 电平，即可选择性地与不同模块通信。这种架构将 JTAG 从单一接口升格为 可扩展的片上调试总线（On-Chip Debug Bus） ，为大型 FPGA 项目提供清晰的模块化调试路径。

5. 故障排查与工程实践建议

5.1 常见故障现象与根因分析

现象	可能根因	验证与解决方法
JTAG_Init() 后无法读写任何寄存器， JTAG_ReadReg() 返回全 0	FPGA 未上电或 JTAG 引脚物理断开	用万用表测量 TCK/TMS/TDI/TDO 对地电压；检查 VCCIO_3.3V 是否正常；确认 jtag_interface 模块是否已正确例化并连接时钟
JTAG_UploadBitstream() 失败，FPGA 无响应	Bitstream 格式错误或字节序未反转	用 Hex Editor 检查 FPGA_Bitstream.h 中的前 4 字节是否为 0xFF, 0x00, 0xAA, 0x55 （Cyclone 标准魔数）；重新运行 ByteReverser 并勾选 Reverse Bytes
寄存器读写值与预期不符（如写 0x12345678，读回 0x78563412）	MCU 与 FPGA 的字节序不一致	JTAG_ShiftDR() 函数内部已处理字节序转换；若自行修改，需确保 uint32_t 在移位时按小端序（ARM 默认）处理
Quartus 编译报错 Can't place multiple pins assigned to pin location	JTAG 引脚被其他逻辑（如 USB PHY）复用	检查 MKRVIDOR4000_top.v 中 tck/tms/tdi/tdo 的 assign 语句，确保无其他 assign 冲突；在 Quartus Assignment Editor 中，将这些引脚设置为 Use as regular I/O

5.2 工程最佳实践

• 时序裕量优先 ：始终以最低可靠速率（1 MHz）开始调试。待功能稳定后，再逐步提高 JTAG_ShiftDR() 中的延时精度。
• 寄存器命名规范 ：在 MKRVIDOR4000_top.v 中，为每个 out_regs 和 in_regs 信号添加清晰注释，例如 // out_regs[0]: PWM Channel 0 Duty Cycle (16-bit) 。
• 状态机健壮性 ：在 MCU 端 JTAG_ShiftDR() 中加入超时检测，避免因 FPGA 挂死导致 MCU 死锁。
• 资源监控 ：在 Quartus 编译报告中，重点关注 jtag_interface 模块的 Logic utilization 与 Register utilization ，确保其增长符合线性预期。

JTAG_Interface 库的诞生，标志着 MKR Vidor 4000 从“玩具级开发板”向“专业级 FPGA 原型平台”的跃迁。它不提供花哨的图形界面，却赋予工程师最珍贵的东西： 对硬件的完全掌控权 。当你的第一个自定义 PWM 控制器通过 JTAG 寄存器精准调节占空比，当 ADC 采样数据经由同一链路实时回传至串口监视器——那一刻，你触摸到的不是 Arduino 的抽象层，而是硅基世界最本真的脉动。