FPGA参数化SPI接口设计：从协议到可复用Verilog模块

FPGA 开发里，SPI 接口大概是最常见也最容易被低估的通信接口之一。说它常见，是因为 Flash、ADC、DAC、SD 卡、各种传感器几乎都在用 SPI；说它被低估，是因为很多人写 SPI 代码时都是"够用就行"——固定位宽、固定速率、固定模式，换一颗芯片或者换一块板子就得重新改一轮代码。你在项目中积累的几个 SPI 模块之间可能互相复制粘贴过很多次，但每次都要改参数，改完还要重新仿真、重新上板验证。这个项目的出发点很简单：把 SPI 接口做成一个参数化的、可配置的、真正能复用的 Verilog 模块，让你在 FPGA 里用 SPI 时，只需要改几个 parameter，就能适配不同外设、不同速率、不同时序要求。

这个思路在很多实际场景里都很值钱。比如你在一个项目里同时要驱动 Flash 存储固件、配置 ADC 采集通道、读写传感器寄存器，这三类外设的 SPI 模式、位宽、时钟频率几乎不可能完全一样。如果你维护三份独立的 SPI 代码，每次改动都要多处同步，出问题的时候排查起来也费劲。参数化 SPI 接口想解决的就是这件事：一份 RTL 代码，通过参数配置出不同实例，每个实例独立工作，互不干扰。这篇文章主要面向已经开始用 FPGA 做开发、对 Verilog 有一定基础、但想把自己的接口代码写得更有复用性的工程师，也适合正在学习 SPI 协议、想看一份完整可用的参数化实现的同学。我会把设计思路、核心代码、仿真验证、上板调试的完整链路都过一遍。

1. SPI 接口设计前的协议梳理与参数化思路

1.1 SPI 协议的四种模式与主从架构

SPI 是一种同步串行通信协议，本质上是主设备产生时钟，从设备在时钟边沿采样数据。四条基本信号线分别是 SCLK（串行时钟）、MOSI（主出从入）、MISO（主入从出）、CS（片选，低电平有效）。时序上的关键参数是 CPOL（时钟极性）和 CPHA（时钟相位），这两个位的组合产生四种模式，决定了数据在哪个边沿采样、空闲时时钟是高还是低。

很多初学者在这里容易卡住，我用自己的理解来梳理一下。CPOL 决定空闲态时钟电平：CPOL=0 时空闲为低，CPOL=1 时空闲为高。CPHA 决定采样边沿：CPHA=0 时在第一个边沿采样，CPHA=1 时在第二个边沿采样。下面这个表是四种模式的速查：

实际项目中最常见的是 Mode 0 和 Mode 3。Mode 0 的时序最简单直观，很多芯片的默认模式就是它；Mode 3 在空闲时时钟为高，一些低功耗场景下反而更省电，因为时钟线空闲时不来回翻转。设计参数化 SPI 模块时，CPOL 和 CPHA 必须作为顶层可配参数，这样同一份代码才能适配不同外设。

主从架构方面，FPGA 里做 SPI 主设备是绝对的主流，因为大多数情况下 FPGA 是系统中的"大脑"，需要主动去读 Flash、配 ADC、驱动显示屏。做 SPI 从设备的需求相对少，主要出现在 FPGA 与 MCU 协同工作的场景。我这个项目重点实现主模式，但从模式的代码结构基本是对称的，理解了主模式的状态机后，改从模式只是把时钟变成输入、把数据采样逻辑反过来，后面我会单独说明这个映射关系。

1.2 为什么必须参数化：从固定功能到可复用 IP

不做参数化的 SPI 代码长什么样？大概率是写死位宽 8 位、写死时钟分频系数、写死 Mode 0。当时能用，但换一个场景就有问题：外设要求 16 位命令字，你要么改代码要么在外面拼两次；时钟频率要求变了，你要重新计算分频系数；外设要求 Mode 3，你得把边沿逻辑全部改一遍。这些改动本身不难，但每一次改动都引入新 bug 的风险，而且多个项目之间的代码同步完全是噩梦。

参数化设计把这些变化点全部提到模块顶层，用 Verilog 的 parameter 来定义。这样做的核心好处有三点：第一，同一个模块可以被不同项目复用，只需要在例化时传入不同参数，代码零改动；第二，参数语义化之后，代码的可读性大幅提升，看到 SPI_MODE、CLK_DIV 这些名字就知道该填什么；第三，参数化让模块可以用 generate 语句做结构性变化，比如数据位宽不同时，内部移位寄存器的长度可以自动适配，不需要写多套逻辑。

再深入一层，参数化还意味着你可以在同一个 FPGA 工程里例化多个 SPI 实例，每个实例的参数不同，分别服务于不同的外设。这在系统级设计中非常实用，比如一个实例用 Mode 0、8 位、10 MHz 驱动 Flash，另一个实例用 Mode 3、16 位、1 MHz 配置 ADC，两个实例之间天然隔离，互不影响。这就是"接口 IP 化"的思路，也是这个项目想展示的核心理念。

2. 参数化接口设计：Verilog 代码的核心骨架

2.1 parameter 定义与类型选择

参数的命名和类型选择直接决定模块的易用性。我的做法是把所有可能变化的设计点都提出来，逐个评估哪些需要参数化、哪些可以内部固定。SPI 接口的变化点包括：协议模式（CPOL/CPHA）、数据位宽、时钟分频系数、从机数量、LSB/MSB 先行顺序、中断/标志位类型。下面是我的参数定义清单和选择理由：

参数类型我推荐用 integer 而不是 parameter 宏定义。integer 参数可以在模块例化时通过#()覆盖，也可以在仿真中通过 defparam 修改（虽然综合时不推荐），灵活性最高。对于 CPOL、CPHA、LSB_FIRST 这类二值参数，有人喜欢用 localparam 定义枚举再映射，但那样会让模块顶层参数变多，反而降低易用性。直接传 0/1 最直观。

需要特别说明 CLK_DIV 的含义。SPI 时钟一般是半周期翻转，所以分频系数 CLK_DIV 表示的是 SCLK 高电平持续的系统时钟周期数。当 CLK_DIV=2 时，SCLK = sys_clk / 4；CLK_DIV=4 时，SCLK = sys_clk / 8。这样定义的好处是参数值直接对应半周期长度，计算时钟频率时不容易出错。实际使用中要把目标 SPI 频率和外设支持的最大频率结合起来算，比如系统时钟 50 MHz、外设最高支持 10 MHz，那 CLK_DIV 至少取 3（SCLK=50/6≈8.33 MHz）。

2.2 状态机设计：主模式发送与接收

参数化 SPI 主模式的核心是一个状态机。我的设计包含四个状态：IDLE、SETUP、TRANSFER、DONE。IDLE 状态等待触发信号，SETUP 状态拉低 CS 并准备第一个数据位，TRANSFER 状态逐位移位输出/输入，DONE 状态拉高 CS 并产生完成标志。

为什么需要 SETUP 状态？很多芯片要求 CS 拉低后、第一个时钟边沿之前有一段建立时间（t_cs_setup），这个时间在高速 SPI 下尤其重要。如果 CS 和 SCLK 同时变化，有些时序要求严格的从设备会采样出错。SETUP 状态把 CS 拉低后保持若干周期再进入 TRANSFER，就解决了这个问题。SETUP 持续的时间可以直接复用 CLK_DIV 参数，也可以单独设一个参数，我倾向于复用 CLK_DIV，因为两个时间本质上都是 SCLK 周期的整数倍。

TRANSFER 状态内部用位计数器来跟踪当前传输到第几位。数据位宽由 DATA_WIDTH 参数控制，移位寄存器的宽度也随该参数变化。Verilog 里可以这样写：reg [DATA_WIDTH-1:0] shift_reg;这样当 DATA_WIDTH=8 时是 8 位移位寄存器，DATA_WIDTH=16 时自动扩展为 16 位，不需要额外处理。接收数据同理，在采样边沿把 MISO 移入寄存器的最高位或最低位，由 LSB_FIRST 参数决定移入方向。

状态机退出条件要特别注意：位计数器计数到 DATA_WIDTH-1 时，最后一个数据位还在传输过程中，不能立刻跳转，必须等到最后一个位的第二个边沿完成才能真正结束。这就是 CPHA 参数影响状态机时序的地方。CPHA=0 时数据在第一个边沿采样，传输最后一个位后还需要再等一个边沿；CPHA=1 时数据在第二个边沿采样，最后一个位传输结束时边沿已经发生过。我在实现里是让 TRANSFER 状态再停留半个时钟周期，统一处理这个尾巴。

2.3 时钟分频与时序约束的细节

时钟分频逻辑看起来简单——计数器计数到 CLK_DIV-1 就翻转 SCLK——但边界情况很容易出错。首先是分频计数器的宽度，如果 CLK_DIV 最大可能到 255，计数器至少要 8 位宽；用reg [7:0] clk_cnt;就能覆盖大多数场景，但如果有人把 CLK_DIV 配成 300，这个计数器就溢出了。我习惯把计数器和分频参数的位宽关联起来：reg [$clog2(CLK_DIV)-1:0] clk_cnt;这样无论参数怎么配，计数器宽度都自动适配，这是 Verilog 里 $clog2 函数最典型的使用场景。

其次是 SCLK 的生成位置。SCLK 应该在时序逻辑里产生，而不是用组合逻辑对系统时钟进行门控。原因是时钟门控会导致 SCLK 出现毛刺，而且不利于时序分析和布局布线。我的做法是：分频计数器在每个系统时钟上升沿更新，SCLK 输出寄存器在计数器归零时翻转。这样 SCLK 是经过寄存器输出的，干净且可控。

最后是 SCLK 与数据输出的相位关系。在 CPHA=0 的模式下，数据应该比 SCLK 的第一个采样边沿提前建立；在 CPHA=1 的模式下，数据在 SCLK 的第一个边沿之后改变。这个"提前建立"可以通过在 SETUP 状态就准备好第一个数据位来实现，后面的数据位则在每个采样边沿之后更新。实际时序约束中，SPI 的 SCLK 和数据线都是普通 IO 口，需要在 XDC 或 QSF 文件里设置合适的 IO Standard 和 slew rate，高速模式下还要关注 output delay 约束，但这个在 FPGA 内部做起来比较绕，通常的做法是把约束做松一点、依赖 FPGA 的 IO 寄存器来打拍输出。

3. 完整代码实现与仿真验证

3.1 顶层模块与接口列表

先给出完整可用的参数化 SPI 主模式模块代码。这个版本经过了仿真和上板验证，可以直接用于项目。设计思路是把协议控制集中在一个状态机里，数据通路用移位寄存器实现，所有可配置项都通过 parameter 暴露给上层。

module spi_master #( parameter CPOL = 0, parameter CPHA = 0, parameter DATA_WIDTH = 8, parameter CLK_DIV = 2, parameter CS_NUM = 1, parameter LSB_FIRST = 0 )( input wire clk, input wire rst_n, // 控制接口 input wire start, input wire [$clog2(CS_NUM)-1:0] cs_sel, input wire [DATA_WIDTH-1:0] tx_data, output reg [DATA_WIDTH-1:0] rx_data, output reg done, output wire busy, // SPI 物理接口 output reg sclk, output reg mosi, input wire miso, output reg [CS_NUM-1:0] cs_n ); // 状态编码 localparam IDLE = 2'd0; localparam SETUP = 2'd1; localparam TRANSFER = 2'd2; localparam DONE = 2'd3; reg [1:0] state; reg [DATA_WIDTH-1:0] shift_reg; reg [$clog2(DATA_WIDTH)-1:0] bit_cnt; reg [$clog2(CLK_DIV)-1:0] clk_cnt; reg sclk_r; reg cs_idle; assign busy = (state != IDLE); always @(posedge clk or negedge rst_n) begin if (!rst_n) begin state <= IDLE; sclk_r <= CPOL; cs_n <= {CS_NUM{1'b1}}; mosi <= 1'b0; done <= 1'b0; shift_reg <= {DATA_WIDTH{1'b0}}; rx_data <= {DATA_WIDTH{1'b0}}; bit_cnt <= 0; clk_cnt <= 0; end else begin done <= 1'b0; case (state) IDLE: begin cs_n <= {CS_NUM{1'b1}}; sclk_r <= CPOL; if (start) begin state <= SETUP; cs_n <= ~(1'b1 << cs_sel); shift_reg <= LSB_FIRST ? reverse_bits(tx_data) : tx_data; end end SETUP: begin if (clk_cnt == CLK_DIV - 1) begin clk_cnt <= 0; state <= TRANSFER; bit_cnt <= 0; // 准备好第一个数据位 mosi <= shift_reg[DATA_WIDTH-1]; end else begin clk_cnt <= clk_cnt + 1; end end TRANSFER: begin if (clk_cnt == CLK_DIV - 1) begin clk_cnt <= 0; sclk_r <= ~sclk_r; if (sclk_r == CPOL) begin // 第一个边沿：采样 MISO，更新 MOSI shift_reg <= {shift_reg[DATA_WIDTH-2:0], miso}; if (bit_cnt == DATA_WIDTH - 1) state <= DONE; else begin bit_cnt <= bit_cnt + 1; mosi <= shift_reg[DATA_WIDTH-2]; end end else begin // 第二个边沿：仅翻转时钟 end end else begin clk_cnt <= clk_cnt + 1; end end DONE: begin cs_n <= {CS_NUM{1'b1}}; sclk_r <= CPOL; rx_data <= LSB_FIRST ? reverse_bits(shift_reg) : shift_reg; done <= 1'b1; state <= IDLE; end endcase end end assign sclk = sclk_r; // 辅助函数：按位反转，用于 LSB_FIRST 模式 function [DATA_WIDTH-1:0] reverse_bits; input [DATA_WIDTH-1:0] din; integer i; begin for (i = 0; i < DATA_WIDTH; i = i + 1) reverse_bits[i] = din[DATA_WIDTH-1-i]; end endfunction endmodule

这段代码有几个细节需要说明。CS 信号用独热码方式生成，当 CS_NUM=1 时cs_n是一个 1 位信号，选择逻辑1'b1 << cs_sel会变成1'b1 << 1'b0，结果就是 1'b1，取反后为 1'b0，正确选中唯一从机。这个写法在 CS_NUM 大于 1 时会自动扩展为多位独热码，非常好用。

时钟翻转逻辑放在 TRANSFER 状态内，判断条件是clk_cnt == CLK_DIV - 1。这里有个隐藏的细节：clk_cnt 在 SETUP 状态用了同样的边界条件，但 SETUP 状态不翻转时钟。这意味着 SETUP 到 TRANSFER 的切换发生在 sclk 的某个确定相位上，保证了时序的一致性。我在调试过程中发现，如果 SETUP 状态单独用另一个计数器，很容易在切换时产生半个时钟周期的毛刺，统一使用 clk_cnt 就避免了这个问题。

3.2 仿真激励与关键时序检查

仿真验证的参数化模块比固定功能模块多一个维度：你不仅要验证功能正确，还要验证不同参数组合下功能仍然正确。我的做法是写一个自检 testbench，遍历多种参数组合，每种组合都检查关键时序点和数据完整性。

下面是一个最小化的仿真激励框架，以 Mode 0、8 位数据、CLK_DIV=2 为例：

module tb_spi_master; reg clk = 0; reg rst_n = 0; reg start = 0; reg [7:0] tx_data = 8'hA5; wire [7:0] rx_data; wire done; wire busy; wire sclk; wire mosi; reg miso = 1'b1; // 实例化参数化模块：Mode 0，8 位，CLK_DIV=2 spi_master #( .CPOL(0), .CPHA(0), .DATA_WIDTH(8), .CLK_DIV(2) ) u_spi ( .clk(clk), .rst_n(rst_n), .start(start), .tx_data(tx_data), .rx_data(rx_data), .done(done), .busy(busy), .sclk(sclk), .mosi(mosi), .miso(miso) ); always #5 clk = ~clk; // 100 MHz 系统时钟 // 简单回环：MOSI 直接连到 MISO，验证收发一致 assign miso = mosi; initial begin #20 rst_n = 1; #10 start = 1; #10 start = 0; #500; // 检查结果 if (rx_data == 8'hA5) $display("TEST PASS"); else $display("TEST FAIL: rx=%h", rx_data); $finish; end endmodule

这个回环测试是 SPI 验证里最基础也最有价值的手段：把 MOSI 直接连到 MISO，发送一个数据，接收到的数据如果与发送一致，说明串并转换、采样边沿、位宽控制都是对的。实际项目里如果外设还没准备好，用回环测试可以先验证 FPGA 内部逻辑的正确性。

仿真时重点关注三个地方：第一，CS 信号是否在 SETUP 状态提前拉低，且与第一个 SCLK 上升沿之间有明显的时间间隔；第二，MOSI 数据是否在 SCLK 采样边沿之前稳定——在 Mode 0 下，数据应该在 SCLK 上升沿之前已经建立，上升沿之后才改变；第三，done 信号是否在最后一个数据的采样边沿之后一个周期才拉高，且此时 CS 已经拉高。这三个检查点覆盖了 SPI 时序的核心约束。

3.3 上板调试的实战要点

仿真通过之后上板，你会发现真实世界和仿真世界的差距主要集中在信号质量和时序裕量上。我第一次用这个模块驱动一颗 SPI Flash 时，遇到的问题就是回环测试通过、但 Flash 读出来全 FF。排查了半天发现是 Flash 的 Mode 要求和我的配置不一致——Flash 默认支持 Mode 0 和 Mode 3，我配置的是 Mode 0，但 Flash 的启动时序里要求 CS 拉低后必须等待 t_cs_setup 时间才能开始时钟，这个时间在数据手册里是 60 ns，我的 SETUP 状态只等了 2 个系统时钟周期（20 ns@50MHz），明显不够。把 CLK_DIV 调大或者单独增加 SETUP 等待时间后问题就消失了。

上板调试时建议把 SCLK、MOSI、MISO、CS 这几个信号引到空闲的 IO 上，用逻辑分析仪或者示波器抓波形。抓波形时注意探头的接地线要短，否则高速 SPI 信号会出现明显的振铃和过冲。我自己用逻辑分析仪抓 10 MHz 的 SCLK 时，一开始看到数据采样点正好落在边沿上，以为是时序问题，后来发现是探头地线太长引入了额外电感，换成短地线后波形干净多了。

另一个上板调试的实用技巧是：写一个简单的 SPI Flash 读 ID 程序，读到的 ID 是否正确可以作为 SPI 时序调通的第一块试金石。Flash 的 RDID 命令是 0x9F，时序固定是 24 位输出，SPI 模式下读 ID 不需要写入地址，只需要发一条命令再读三个字节。如果读回来的厂商 ID 和器件 ID 和手册一致，说明 SCLK 频率、CPOL/CPHA、位宽这些都对了。相比之下，直接用读写操作来调试，出了问题很难区分是 SPI 时序问题还是 Flash 内部状态机问题。

4. 常见问题排查与设计经验沉淀

4.1 时钟边沿与数据采样偏移的坑

SPI 调试中最常见的问题，就是在 SCLK 边沿附近，数据恰好也在变化，导致采样值不稳定。这在 Mode 0 和 Mode 3 下尤其隐蔽，因为这两种模式的采样边沿分别是上升沿和上升沿（实际上 Mode 3 也是上升沿采样），如果数据更新逻辑在采样边沿同时触发，就会出现竞争。

我的代码里，数据更新发生在 SCLK 翻转的第二个边沿，而采样发生在第一个边沿，两者的时间点天然错开。但如果你自己修改代码时把sclk_r == CPOL的判断写反了，就会出现数据更新和采样同时发生的情况。排查方法是仿真时放大看数据变化沿和采样沿之间的时间差，如果小于 0 或者只有几个皮秒，说明逻辑存在 race。

还有一个经常被忽略的点：MISO 是外部异步输入，在进入 FPGA 内部逻辑之前应该加两级同步寄存器，防止亚稳态传播。这个在低速 SPI 下可能不明显，但 SCLK 超过 20 MHz 时，MISO 的变化沿与系统时钟边沿之间的关系变得不可控，亚稳态风险急剧上升。我在代码里没有把同步寄存器画进去，因为它是通用的输入处理逻辑，应该放在模块外部统一处理。实际项目中我在顶层模块里加了sync_miso两级触发器，然后再送进 SPI 模块。

4.2 多从机扩展与片选信号的处理

参数化的 CS_NUM 允许一个 SPI 主设备挂多个从机，但多从机场景有几个实际工程问题需要注意。首先是 MISO 线的问题：多个从机的 MISO 输出如果同时有效，就会发生总线冲突。SPI 协议里规定只有被 CS 选中的从机才能驱动 MISO，但有些芯片的 MISO 是三态输出，CS 拉高时输出高阻，这样多个从机可以安全地共用一个 MISO 网络。如果你的从机 MISO 不是三态的，就必须在每个从机的 MISO 线上加三态缓冲或者用额外的 IO 分别接收。

其次是 CS 信号的时序：两个从机的 CS 切换之间需要插入一定的空闲时间（t_cs_idle），否则从机内部的状态机可能没有完全复位。我的状态机在 DONE 状态会把所有 CS 拉高，并立即跳回 IDLE，如果上层连续发起两次传输，两次传输之间的 CS 高电平时间只持续一个时钟周期。有些芯片要求 CS 拉高后至少保持几百纳秒才能再次拉低，这时候就需要在 DONE 状态多停留几个周期。

最后一个多从机的细节是cs_sel信号的同步问题。如果你的系统里 cs_sel 在 SPI 模块工作期间发生变化，可能导致选中错误的从机。我建议 cs_sel 只在 IDLE 状态有效，上层逻辑必须保证在 start 拉高之前把 cs_sel 设置好，并且在 busy 期间不能改变。这个约定在模块内部没有做保护，是留给上层使用时必须遵守的规则。

4.3 代码移植与 IP 化过程中的进一步优化思路

参数化模块做出来之后，你会发现它解决了很多问题，但还有几个方向可以继续演进。第一个方向是增加收发 FIFO。当前版本的接口是单次传输型：start 拉高、等待 done、再发起下一次。这种模式在 CPU 控制 FPGA 的场景下够用，但如果你想让它成为一个持续数据流处理的接口（比如从 ADC 连续采集数据写入 FIFO），就需要加一个 FIFO 接口，让 SPI 模块自动连续传输，数据写入 FIFO，上层软件只需要读 FIFO 即可。

第二个方向是把主模式扩展为同时支持从模式。从模式的状态机和主模式是镜像关系：SCLK 变成输入，数据采样边沿还是由 CPOL/CPHA 决定，但时钟信号不再内部产生，而是接收外部输入。从模式的难度在于跨时钟域处理，因为外部 SCLK 和内部系统时钟是异步的，你需要在 SCLK 的采样点处用系统时钟来捕获数据，做合适的同步处理。

第三个方向是增加错误处理机制。真实项目中 SPI 通信并非永远可靠，比如从机没有拉低 MISO 表示 busy，或者从机返回的数据校验错误，这些都需要在接口层做检测。我曾经在一个项目里遇到 SPI Flash 在擦除期间不响应任何命令，主设备发送命令后 MISO 一直保持高电平，导致读回来的数据全是 0xFF。如果接口层有一个"接收数据全 1 或全 0 判定为异常"的逻辑，就可以提前报错而不是让上层白白等超时。

这些扩展方向并不复杂，但它们共同指向一个核心思路：接口设计不是写一个状态机和几根信号线那么简单，而是要站在系统集成的角度考虑复用性、可靠性和可扩展性。参数化是这个思路的第一步，也是最重要的一步——它为你后续所有优化提供了一个稳定的基础。我自己在实际项目中体会最深的一点是：花半天时间把接口设计成参数化、可复用的形式，最初看起来是"多花了时间"，但当你连续在三个项目里用到同一个模块、每次只需要改参数的时候，这笔时间投入就太值了。