做FPGA工程的人，手里但凡有几块带Zynq或者带MicroBlaze的板子，早晚会遇到一个需求：要挂一块SPI Flash、接一个SPI接口的ADC，或者跟某个SPI传感器通信。我第一次用AXI Quad SPI IP核的时候，在Vivado里点完配置向导，以为就万事大吉了，结果板子上电一测，MISO一直低电平，SCK死活没有波形。后来翻手册看寄存器，花了一下午才定位到问题。这篇文章就是把从添加IP核到最后收到正确数据的完整流程，连带着我当时踩过的坑一起整理出来，给正准备搭建SPI通信系统的朋友做个参考。内容会覆盖AXI Quad SPI的几种工作模式、Vivado里的参数怎么选、软件侧怎么收发数据，以及几种常见故障的排查思路。
1. 先搞明白：AXI Quad SPI IP核到底是什么
1.1 它解决什么问题，和手写SPI控制器相比有什么优势
很多FPGA开发者第一次接触SPI通信时，第一反应是“SPI协议这么简单，我自己写个状态机不就行了”。SPI确实只有SCK、MOSI、MISO、CS四根线，单字节收发逻辑用Verilog写几十行就能完成，但一旦落到实际工程里，情况就会变得复杂得多。
你的主控要跟谁通信？是SPI Flash、SPI ADC、SPI DAC，还是多个SPI从机？每个从机的速率要求是多少？时钟极性和相位是模式0还是模式3？数据长度是8位还是16位？要不要处理连续读写？是用查询、中断还是DMA？主控侧是AXI总线还是自定义总线？这些如果全靠自己写RTL，开发周期会被拉得非常长，而且每一个需求变化都可能让你重写一遍状态机。
AXI Quad SPI是Xilinx提供的官方IP核，专门解决这类问题。它把SPI控制器、FIFO、中断管理、时钟分频、从机选择逻辑都封装好了，对外提供标准的AXI接口。你不需要关心内部时序细节，只要在Vivado里配置好参数，然后在软件里写几行驱动就能完成数据收发。这样项目周期和调试成本能明显降下来。
很多人还有个误区，以为“AXI Quad SPI”只能接SPI Flash。实际上它支持三类用法：标准SPI模式（接普通SPI外设）、双通道SPI模式、四通道SPI模式（后两种多半用于SPI Flash高速读写）。如果你只是接一个普通的SPI温度传感器，用标准模式就够了。
1.2 三种工作模式：标准SPI、双通道SPI和四通道SPI
AXI Quad SPI这个“Quad”指的是数据线可以扩展到四根，对应三种工作模式：
- 标准SPI模式：使用SCK、MOSI、MISO、片选CS四根线，也就是大家熟悉的单通道全双工方式。
- Dual SPI模式：把MOSI和MISO两根线复用来传输数据，读操作时两根线都变成输入，写操作时两根线都变成输出。这种方式通常用于SPI Flash的读加速。
- Quad SPI模式：四根IO线全部参与数据传输，读Flash的时候一次能搬4个bit。这是Xilinx这个IP核对SPI Flash高速访问的主要卖点，配合DMA可以大幅提升吞吐率。
配置的时候需要想清楚你当前项目到底需要哪种模式。如果只是跟ADC、DAC、传感器通信，选Standard即可，没必要为了“看起来高级”去选Quad模式，因为Quad模式的数据引脚定义会变，普通外设根本没法接。
在IP配置向导里，这个选项就是“SPI Mode”，一般有三个选择：Standard、Dual、Quad。选定之后对应的引脚名称也会变，比如Quad模式下引脚会显示为IO0、IO1、IO2、IO3，而不再叫MOSI/MISO。
1.3 什么时候用静态配置，什么时候用动态配置
AXI Quad SPI在配置路径上分为两种：静态配置和动态配置。这里的“静态”指的是在Vivado IP配置向导里直接把参数固化下来，比如时钟分频系数、指令宽度、地址宽度、从机数量、是否启用FIFO等。这些参数在编译之后就写死在IP核内部，软件运行期间不能改动。
动态配置则是软件在运行时通过寄存器来改变某些行为。但要注意一个很多人踩过的坑：AXI Quad SPI的时钟分频值并不支持运行时任意修改，能通过寄存器动态设置的只是SPI模式（CPOL/CPHA）、主从模式、片选控制方式、指令/地址模式等一部分功能。分频比在生成IP时定了就是定了，想改就得重新定制IP并重新生成比特流。
这一点跟MCU上习惯不同。比如STM32的SPI外设，波特率寄存器随时可以改，嵌入式工程师很容易默认FPGA这边也一样。实际调试中，我就遇到过有人想在软件里动态把SCK从10MHz改成1MHz来适配一块慢速传感器，结果发现无论怎么写寄存器SCK频率都不变，最后回头查IP配置才发现分频参数被固化在向导里了。所以做方案的时候，先确认好各路SPI从机的工作频率上限，再用最高的那个去反推分频系数，留出余量，这样才稳妥。
2. 配置前必须理清的协议细节与总线关系
2.1 SPI四种模式（CPOL/CPHA）和IP核的对应关系
SPI协议本身并不复杂，但模式选错是最常见的“第一坑”。SCK在空闲时是高还是低，数据在SCK上升沿还是下降沿采样，这两个维度组合出四种模式：
| 模式 | CPOL | CPHA | 空闲电平 | 采样边沿 |
|---|---|---|---|---|
| Mode 0 | 0 | 0 | 低 | 上升沿 |
| Mode 1 | 0 | 1 | 低 | 下降沿 |
| Mode 2 | 1 | 0 | 高 | 下降沿 |
| Mode 3 | 1 | 1 | 高 | 上升沿 |
大多数SPI Flash和通用SPI外设默认支持Mode 0或Mode 3。配置AXI Quad SPI时，CPOL和CPHA在Vivado里各有对应的下拉框，但这两个参数同样可以在运行期间通过SPI控制寄存器（CR）里的位来调整。
我个人建议是：在硬件设计阶段就把每颗从机需要的模式记下来，画一张简单的模式表贴在工作站旁边。调试时如果发现数据对不上，先查对方数据手册的波形图，再对着IP配置核对，往往能省下半天时间。曾经有块SPI温度传感器，数据手册时序图画得不太规范，我按Mode 0怎么配都读不出正确数据，后来用逻辑分析仪抓从机的输出才发现它对时钟无效边沿有特殊要求，换成Mode 3才正常。
2.2 硬件片选与软件片选：一字之差，坑却很大
片选是SPI通信里最容易被忽略但又最容易出问题的信号。AXI Quad SPI支持两种片选管理方式：硬件片选（自动从机选择）和软件片选（手动从机选择）。
硬件片选模式下，IP核在传输开始时会自动拉低对应的从机片选信号，传输结束自动释放。软件只负责发起一次传输，不用操心底层片选。这种方式用起来省心，适合单从机或从机切换不频繁的场景。
软件片选模式下，片选信号的拉低和拉高完全由软件控制。你需要先写从机选择寄存器（SSR）选中某个从机，然后再发起传输，传输结束后还要记得释放片选。这个模式更灵活，但也更容易出事故。我就见过有人在一次传输结束后忘了释放片选，结果SPI总线上所有从机都被莫名其妙地选中，出现总线冲突和数据错乱。
在IP配置向导里，这两个方式对应一个选项，一般叫“Slave Select Mode”或“Manual Slave Select Enable”。如果是Zynq上跑Linux，设备树里也会反映这个配置。选硬件片选还是软件片选，我的经验是：只有一根片选、从机固定不变，用硬件自动控制；如果有多从机且需要精确控制时序窗口，或者从机要求片选在整个命令序列期间保持有效，就用软件片选。
2.3 AXI接口和SPI时钟域之间的FIFO数据通路
AXI Quad SPI虽然对外提供的是AXI4-Lite接口，但内部实际上是一个跨时钟域数据通路。AXI侧运行在S_AXI_ACLK下，SCK则来自SPI时钟分频后的信号。数据从AXI总线写入发送FIFO，再被SPI状态机取走，按SCK节奏逐位发送；接收方向类似，SPI状态机把收到的数据写入接收FIFO，软件再通过AXI总线的数据接收寄存器（DRR）读走。
理解这条数据通路，对后续定位问题非常关键。比如接收数据一直是0xFF，不一定是SPI时序出错，也可能是接收FIFO空的时候软件就发起了读操作。又比如发送数据发不出去，可能是发送FIFO满，软件写数据寄存器时被阻塞，也可能是IP配置里FIFO深度太小，一次DMA传输的数据量超过了FIFO容量。
AXI Quad SPI内部FIFO的深度可以在Vivado配置向导里设置，默认值通常是256字节。如果一次要传输大块数据，建议开启DMA并选带AXI4 Full接口的版本，让DMA直接搬运数据到FIFO，避免CPU单点瓶颈。如果只是偶尔读写几个寄存器，轮询方式配上默认FIFO就足够了，不必上DMA。
3. Vivado中IP核配置实操
3.1 在Vivado中添加AXI Quad SPI IP核的完整过程
在Vivado里搭建SPI通信系统的流程并不复杂，但每一步都有容易出错的地方。我以Zynq平台为例，把从零开始的操作串一遍。
新建一个Block Design（BD工程），在Diagram窗口空白处右键，选择“Add IP”，搜索“AXI Quad SPI”，双击添加。IP核添加成功后，Vivado会自动提示你连接AXI接口。如果芯片型号是Zynq，把IP的S_AXI接口接到Zynq处理系统的M_AXI_GP0或M_AXI_GP1上，S_AXI_ACLK连接到PS端对应的时钟输出上。
尤其要注意S_AXI_ACLK和SPI时钟的关系。S_AXI_ACLK是整个IP寄存器访问和FIFO读写的工作时钟，一般接100MHz或150MHz。SPI的SCK由这个时钟分频而来。有些设计里还有EXT_SPI_CLK引脚，那是用于从模式下接收外部时钟的，主模式一般不需要连接。
添加完IP后别忘了运行“Connection Automation”自动连接工具，它可以把片选信号、中断、时钟复位等自动接好。但自动连接并不一定完全正确，特别是当有多个SPI从机或者有自定义引脚约束时，还是需要手动检查一遍连线。
3.2 关键参数逐项拆解
AXI Quad SPI的配置向导里参数比较多，但真正需要关注的核心参数其实就那么几个。我把常用配置整理成一个参考表：
| 参数名 | 推荐值 | 说明 |
|---|---|---|
| SPI Mode | Standard / Dual / Quad | 按实际外设选择，普通传感器选Standard |
| Transaction Width | 8 bit | 大部分SPI外设是8位传输，个别设备用16位 |
| Clock Divider | 根据输入时钟计算 | SCK = S_AXI_ACLK / (2 × (分频值+1)) |
| Slave Select Mode | Auto / Manual | 单从机选Auto，多从机或特殊时序选Manual |
| Enable FIFO | 勾选 | 建议默认开启，中断和DMA依赖FIFO |
| FIFO Depth | 256 | 数据量小可以减小，减少资源占用 |
| Instruction Width | 8 bit | 只有SPI Flash场景需要关注 |
| Address Width | 24 bit | 只有SPI Flash场景需要关注 |
分频系数怎么算？这里给个实际例子。如果S_AXI_ACLK是100MHz，外设要求的最大SCK是10MHz，那么理论上分频系数5就能得到10MHz，但考虑到信号质量，建议保守一点，分频系数取8，SCK就是100 / (2 × (8+1)) ≈ 5.56MHz。具体公式以IP数据手册为准，不同版本可能有细微差别。
Instruction Width和Address Width是给SPI Flash指令使用的。如果项目是用AXI Quad SPI去驱动SPI Flash，这两个参数分别定义Flash命令字段和地址字段的位宽，常见是8位指令和24位地址。如果接的是普通外设，这两个参数可以设为1或置0，没有影响。
3.3 连接IP核、生成地址映射
IP核参数配置完后，回到Block Design连线。前期手动配置时，可以用包含DMA的AXI Quad SPI版本，也可以选只带AXI4-Lite的寄存器版本。如果选了带DMA的版本，那么IP会有S_AXI4接口，需要接AXI Interconnect再到PS端的高性能端口HP，DMA搬运才能发挥带宽优势。
连线完成后，在Block Design工具栏里先做一次“Validate Design”，检查有没有未连接的端口或错误的时钟/复位连接。然后右键IP的S_AXI_Lite接口，选择“Make External”或者交给PS地址映射。编译前记得在Address Editor里给AXI Quad SPI分配一个地址段。假设分配基地址是0x41600000，那么后续软件读写时就会用到这个地址。
生成比特流之前，建议先导出硬件（Export Hardware）包含bitstream，再启动软件开发。如果是纯FPGA工程，没有PS和SDK，就用MicroBlaze加AXI Interconnect，地址映射和软件操作方式类似，只是时钟复位需要手动处理。
3.4 生成比特流并导出硬件
在Vivado里点击Generate Bitstream，等待编译完成。如果SDK或后续测试需要，启动“Export Hardware”，勾选“Include bitstream”，然后启动Xilinx SDK或Vitis。
这里分享两个实操提醒：第一，每次修改IP配置并重新生成比特流后，硬件导出必须同步更新，否则软件侧用的寄存器地址和IP配置可能不一致；第二，如果添加了ILA调试核，记得在保存波形配置时把探针信号一起保存，否则下次打开工程又得重新设一遍触发条件。
4. 嵌入式软件侧驱动与收发实现
4.1 Zynq/SDK场合下的驱动初始化
硬件导出到SDK/Vitis后，可以通过现成的Xilinx驱动库来操作AXI Quad SPI。驱动库使用起来很直接，核心就几个函数：查找设备配置、初始化、设置从机选择、设置SPI模式、发起传输。
初始化阶段的代码可以这样写：
#include "xspi.h" XSpi Spi; int SpiInit(void) { int Status; XSpi_Config *Config; Config = XSpi_LookupConfig(XPAR_AXI_QUAD_SPI_0_DEVICE_ID); if (Config == NULL) { return XST_FAILURE; } Status = XSpi_CfgInitialize(&Spi, Config, Config->BaseAddress); if (Status != XST_SUCCESS) { return Status; } Status = XSpi_Start(&Spi); if (Status != XST_SUCCESS) { return Status; } XSpi_IntrGlobalDisable(&Spi); // 设置为Master模式，CPOL=0，CPHA=0 u32 Options = XSP_MASTER_OPTION; XSpi_SetOptions(&Spi, Options); // 选择第0个从机（硬件片选模式下此调用可选） XSpi_SetSlaveSelect(&Spi, 0x01); return XST_SUCCESS; }这段代码里，XSpi_LookupConfig根据设备ID找到IP核的配置信息，XSpi_CfgInitialize完成基地址和内部FIFO的初始化，XSpi_Start让IP进入可工作状态。XSpi_SetOptions里设置SPI模式，这里假设是Mode 0；如果外设是Mode 3，需要额外加上对应CLK_POLARITY和CLK_PHASE的选项，具体宏定义在xspi.h里都有。
一个小提醒：如果IP配置向导里选的是软件片选，那么XSpi_SetSlaveSelect这一步很重要，不仅要选中从机，还必须在每次传输结束后保持或释放片选，否则后续传输会异常。硬件片选模式下可以忽略片选操作，IP会在每次传输时自动处理。
4.2 数据收发流程与轮询/中断方式的选择
收发数据的最简单方式是轮询调用XSpi_Transfer。这个函数会把发送缓冲区数据写入发送FIFO，同时从接收FIFO读回数据。函数内部会在数据全部发送且接收完成后返回，适合数据量不大的场景。
int SpiReadFlashId(u8 *Id) { u8 TxBuffer[4] = {0x9F, 0x00, 0x00, 0x00}; u8 RxBuffer[4] = {0}; int Status = XSpi_Transfer(&Spi, TxBuffer, RxBuffer, 4); if (Status != XST_SUCCESS) { return Status; } // 读Flash的JEDEC ID时，第一个字节是命令，后三个字节是ID Id[0] = RxBuffer[1]; Id[1] = RxBuffer[2]; Id[2] = RxBuffer[3]; return XST_SUCCESS; }这里收发共用同一个缓冲区长度参数，SPI是全双工协议，发送4个字节的同时也会接收4个字节。很多新手第一次用这个函数时，容易把收发缓冲区当两个独立过程处理，其实SPI收发是同步的：每发送一个字节，必然同时接收到一个字节，即使对方没有数据返回，接收缓冲里也会是固定电平对应的0xFF或0x00。
工程中如果一次要传输几百字节甚至更多，轮询方式会占用CPU大量时间。这时候就需要用中断或DMA。AXI Quad SPI带中断输出信号，可以在发送FIFO半空、接收FIFO非空等条件下触发中断，从而实现数据流的流水线处理。更高效的做法是配置IP为DMA模式，使用AXI DMA把数据从DDR搬运到SPI FIFO，再由IP自动转换位串行数据发出，整个过程CPU只在传输完成时收到一次中断。
中断模式和DMA模式的配置会比轮询复杂不少，建议先把轮询跑通，确认SPI链路没问题之后，再考虑升级。很多人一开始直接上DMA，一旦数据错位，很难判断是DMA配置问题还是SPI时序问题，调试难度会翻倍。
4.3 Linux下通过spidev访问SPI设备
如果Zynq上面的系统是Linux，那就不必再裸机写驱动了。Linux内核里有现成的SPI子系统支持AXI Quad SPI，设备树中把SPI控制器配置好，用户态通过spidev节点就能访问SPI从机。
设备树中SPI控制器节点的一个示意如下：
axi_quad_spi_0: axi-quad-spi@41600000 { compatible = "xlnx,xps-spi-1.00.a"; reg = <0x41600000 0x10000>; #address-cells = <1>; #size-cells = <0>; xlnx,num-transfer-bits = <8>; spidev@0 { compatible = "spidev"; reg = <0>; spi-max-frequency = <5000000>; }; };用户态程序打开/dev/spidev0.0后，先用ioctl设置模式、速率、字长，再通过SPI_IOC_MESSAGE来收发数据：
#include <linux/spi/spidev.h> int fd = open("/dev/spidev0.0", O_RDWR); unsigned char mode = SPI_MODE_0; unsigned int speed = 5000000; unsigned char bits = 8; ioctl(fd, SPI_IOC_WR_MODE, &mode); ioctl(fd, SPI_IOC_WR_MAX_SPEED_HZ, &speed); ioctl(fd, SPI_IOC_WR_BITS_PER_WORD, &bits); unsigned char tx[4] = {0x9F, 0x00, 0x00, 0x00}; unsigned char rx[4] = {0}; struct spi_ioc_transfer tr = { .tx_buf = (unsigned long)tx, .rx_buf = (unsigned long)rx, .len = 4, .speed_hz = speed, .bits_per_word = bits, }; ioctl(fd, SPI_IOC_MESSAGE(1), &tr);这种方式非常方便，适合快速验证硬件链路。如果发现spidev节点没有生成，大概率是设备树里compatible没配对，或者内核没有使能CONFIG_SPI_SPIDEV选项。另外注意，某些Linux内核版本会因为安全策略拒绝“spidev”作为兼容字符串，这种情况可以在设备树里使用你的具体SPI芯片型号，或者换成该芯片对应的兼容名。
5. 调试经验与常见问题排查实录
5.1 调试工具与抓波形准备
SPI调试最有效的工具是逻辑分析仪，其次是ILA和串口打印。条件允许的话，强烈建议先在硬件上加ILA来抓SCK、MOSI、MISO、CS这几根关键信号。ILA是Xilinx的在线逻辑分析仪IP核，可以通过JTAG实时观测内部信号，不怕干扰，抓完波形再分析比盲目打印高效得多。
ILA的添加方式不复杂：在Block Design里加一个ILA IP核，把SPI引脚引出到ILA的探针端口。或者直接在顶层RTL里例化ILA，把IP核输出引脚连过去。抓波形时注意先设置好触发条件，比如用CS下降沿触发，这样每次SPI传输开始都能被抓住。
使用逻辑分析仪时，探头地线要尽量靠近SPI芯片，否则高速信号容易引起振铃和误采样。我自己遇到过一种情况：逻辑分析仪显示SCK频率和数据内容都对，但实际从机就是不响应。后来发现是逻辑分析仪的探头电容太大，把本来就不太强的驱动信号拉变形了，SPI速率降到1MHz以下才恢复正常。所以测量高频SPI时要选择低电容探头，并且保证板子供电稳定。
5.2 常见问题速查表
调试过程中我积累了一些高频问题的处理思路，列成表格方便查阅：
| 现象 | 可能原因 | 排查与解决办法 |
|---|---|---|
| SCK完全没有波形 | IP没有进入Master模式 | 检查CR寄存器，确认Master/Slave位配置；检查IP是否已经Start |
| SCK频率不对 | 分频系数配置错误 | 对照公式重新计算SCK；注意分频参数与运行时间不可变 |
| MOSI有波形但MISO始终为高 | SPI模式不匹配 | 核对CPOL/CPHA与外设要求；用ILA抓波形确认采样点位置 |
| 接收数据固定为0xFF | 接收FIFO为空时读了DRR | 确认每次传输后等待接收完成位；检查RX_FIFO_NON_EMPTY标志 |
| 接收数据固定为0x00 | MISO引脚被拉死或未正确连接 | 用万用表测量MISO电平，确认下拉/上拉电阻；检查引脚约束 |
| 片选信号只拉低了一次 | 软件片选模式未手动释放 | 在传输结束后的代码路径里重新写SSR寄存器释放片选 |
| 多个从机互相干扰 | 片选不生效导致总线冲突 | 核实片选信号是否接到所有从机；用示波器确认空闲时CS全部为高 |
| 数据读写到寄存器时无响应 | 地址映射错误 | 检查Address Editor中分配的地址，确认SDK里配置的基地址一致 |
5.3 一个完整排查案例：MISO全为高但有时能读到数据
之前在某块载板上调一颗SPI DAC，现象很怪异：同一份代码，复位后第一次写数据大概率成功，第二次以后就失败，并且MISO读到的一直是0xFF。从现象看像是时序退化，于是先用ILA抓了一次正常情况下的波形，CS、SCK、MOSI都没问题。奇怪的是MISO在DAC没有任何输出时确实是高电平，这符合SPI三态总线空闲置高的惯例。
继续往后查，发现这块DAC在CS拉高之后有一个很短的“bus turnaround”时间窗口，也就是说CS释放得太快，DAC还没完全释放MISO总线，主控就发起下一次传输，导致主控端的输入采样点正好落在DAC三态输出的不确定区域。
解决方法是把片选改成软件控制，在两笔传输之间插入一小段延时，保证MISO总线稳定后再发起新的SPI事务。这也解释了为什么恢复概率存在——它取决于上一次传输结束到下一次传输开始之间的间隔是否碰巧超过DAC的释放时间。
这个案例说明，SPI调试不能只看IP核本身配置，还要结合具体芯片的时序要求来调整片选控制和传输节奏。硬件片选虽然省心，但对这类对时序敏感的从机来说，软件片选加延时反而更可靠。
5.4 关于IP核版本和资料查询的几条经验
Xilinx的文档体系比较庞大，AXI Quad SPI的相关资料分散在PG153（Product Guide）以及各平台的Embedded Software Documentation里。我的经验是，拿到一个新版本Vivado后，先打开IP配置向导里的Datasheet链接，确认当前版本支持的寄存器列表和引脚定义是否与旧版有差异。不同小版本的IP核在寄存器位定义上偶尔会有调整，如果参考的是网上旧资料，很容易踩坑。
另外，搜索问题时要多留意Xilinx官方论坛和GitHub上的Xilinx SDK代码，很多异常波形都有现成的解释。但论坛方案不一定完全适合你的工程，还是要回到自己的时序波形上验证。
关于仿真，Vivado的仿真环境对AXI Quad SPI支持得很好。建议在工程阶段先跑一遍行为仿真，用逻辑分析仪脚本验证波形是否符合预期，再进行板级调试。不过仿真通过并不代表硬件一定没问题，尤其是信号完整性和片选时序这一类问题，仿真里是看不出来的，只能靠示波器和ILA实测。
结尾的一点实际体会
做了这么多SPI项目之后，我最大的体会是：AXI Quad SPI这个IP核本身并不复杂，难点几乎都集中在“没看清参数含义”和“不够重视外设时序”这两个地方。特别是SPI模式、时钟分频、硬件片选与软件片选这几项，配置之前一定要把数据手册和IP配置向导对照着看，不要凭直觉选。另一个建议是调试顺序尽量循序渐进：先把SCK和CS确认正常，再验证单字节收发，然后才上多字节、中断、DMA这些高级功能。每一步都确认了再往下走，出问题时能快速缩小范围。如果你也正卡在某一个SPI通信环节，不妨按这个思路把配置和波形逐步过一遍，很多问题其实并不难解。
