QSPI / APB SPI Master — 功能 Spec 与验证 Testplan（详细版）

工程路径：/project/SOC_V1.1/To_Customer/QSPI/
DUT 顶层：apb_spi_master（rtl/qspi/apb_spi_master.v）
关联：IP验证环境资料.md

第一部分：功能 Spec

1. 概述

1.1 功能定义

本 IP 为 APB 从接口的 SPI/QSPI 主控制器，软件通过 寄存器 + TX/RX FIFO 组织一次 Flash 类访问：

1. 配置 命令长度、地址长度、数据长度、Dummy 周期、时钟分频、片选。
2. 写 SPI_CMD / SPI_ADR / TXFIFO。
3. 写 SPI_CTRL 触发 RD/WR/QRD/QWR 之一。
4. 轮询 SPI_STATUS 等待完成（本验证环境轮询 bit[5]）。
5. 读 RXFIFO 取回数据。

支持 标准 SPI 与 Quad SPI（四线 TX/RX），具体由 QWR/QRD 与 spi_mode 决定。

1.2 模块层次

apb_spi_master
├── spi_master_apb_if      # APB 寄存器译码
├── spi_master_fifo        # TX/RX FIFO（深度 BUFFER_DEPTH=10）
├── spi_master_controller  # 主状态机：CMD→ADDR→DUMMY→DATA
├── spi_master_clkgen      # 可编程 SCK
├── spi_master_tx / rx     # 位移/采样
└── (片选 spi_csn0~3)

TB 额外例化：qspi_device（行为 Flash 从机）。

1.3 关键参数

2. APB 接口 Spec

2.1 信号

2.2 寄存器地址映射

APB 字地址 = {PADDR[5:2], 2'b00}，与 spi_master_apb_if.v 中 `REG_* 一致：

3. 寄存器位域 Spec

3.1 SPI_CTRL @ 0x00（写触发）

注意：写 CTRL 时 RD/WR/QRD/QWR 为脉冲；同一写可同时置 QWR 等。验证常用：

• 0xF08 = QWR + CS（Quad Page Program 类）
• 0xF04 = QRD（Quad Read）
• 0xF10 = SRST（软复位）

3.2 SPI_STATUS @ 0x04（读）

spi_status 由 apb_spi_master 拼装：

spi_status = { FILL, elements_tx[LOG:0], FILL, elements_rx[LOG:0], 9'h0, spi_ctrl_status[6:0] }

验证环境轮询：while (rdata[5:0] != 1) —— 即等待 bit5=1（控制器报告 传输完成/空闲 类状态，与 IDLE 态 spi_status[5] 相关，见 controller WAIT/结束态）。

3.3 SPI_CLKDIV @ 0x08

3.4 SPI_LEN @ 0x14

示例（qspi_read_sequence）：0x00201010 → CMDLEN=0x10，ADDRLEN=0x10，DATALEN=0x20。

3.5 SPI_DUM @ 0x18

Quad 模式下 dummy 计数在 controller 内可能 ×4 对齐（见 spi_dummy_rd 与 en_quad）。

3.6 SPI_INTCFG / SPI_INTSTA @ 0x24 / 0x28

events_o 在 TB 中接 qspi_vif.interrupt。

4. 控制器状态机 Spec

4.1 状态列表（spi_master_controller.v）

4.2 事务启动条件（IDLE）

当 SPI_CTRL 写使能 spi_rd | spi_wr | spi_qrd | spi_qwr：

1. 拉低 spi_cs，使能 spi_clock_en。
2. 若 spi_cmd_len != 0 → 进入 CMD，发 spi_cmd。
3. 否则若 spi_addr_len != 0 → ADDR。
4. 否则若 spi_data_len != 0 → 根据 RD/WR 进入 DUMMY 或 DATA_TX/RX。

4.3 SPI 模式

4.4 结束

• eot 脉冲表示事务结束。
• 返回 IDLE 时 spi_status[5]=1（验证轮询用）。

5. 物理接口 Spec

TB qspi_device 与 DUT 交叉连接（DUT SDO → Device SDI）。

6. 行为从机 qspi_device Spec

6.1 支持命令（16bit 命令宽）

6.2 参数（interface 可配）

6.3 内部 FSM

IDLE → COMMAND → ADDR → WDATA/RDATA_DUMMY → RDATA，与主机 controller 配合完成 Page Program + Read。

7. 典型软件操作序列（Spec 级）

7.1 Quad Page Program + Read（与 qspi_read_sequence 一致）

写 Flash：

读 Flash：

第二部分：验证 Testplan

8. 验证目标

9. 验证环境组件（摘要）

10. 需求 — 用例跟踪

11. 测试用例详细说明

QSPI-T01 — qspi_reg_rw_test

QSPI-T02 — qspi_read_test

QSPI-T03 — qspi_clk_test

QSPI-T04 — qspi_data_length_test

QSPI-T05 — qspi_dummy_test

QSPI-T06 — qspi_interrupt_test

QSPI-T07 — qspi_soft_reset_test

QSPI-T08 — qspi_abnormal_length_test

12. Scoreboard 检查点（摘要）

13. 回归列表与命令

cd /project/SOC_V1.1/To_Customer/QSPI/sim
make comp
make run_qspi_reg_rw_test
make run_qspi_read_test
make run_qspi_clk_test
make run_qspi_data_length_test
make run_qspi_dummy_test
make run_qspi_interrupt_test
make run_qspi_soft_reset_test
make run_qspi_abnormal_length_test

注意：勿 make run（TEST=qspi_test 类不存在）。

14. 覆盖率与出口准则

15. 与 SoC 关系

• RTL 与 soc/ip/apb_subsystem/rtl/qspi 同源。
• SoC C 测试通过 0x20000000 基址访问（见 uart_test.c / soc_dma_test.c）。
• 片级 SPI pad 在 soc/test/test.v 映射，与 IP 台纯总线环回不同，集成时需对照波形。