SPI 架构与时序契约

Author: syan

产品实现为 SystemVerilog/UVM1.2，目录内核心不依赖商业框架或 Python BFM。设计采用逐位执行的 master、事件驱动的 slave，以及读取最终解析引脚的独立 monitor。目标是让验证工程师用少量配置完成激励、响应和观察。

组件与数据流

master sequence -> standard sequencer -> master_driver --+
                                                        | independent pin
slave.enqueue_response -> copied queue -> slave_driver --+ endpoint -> SPI wires
                                                                    |
                  monitor <------------------------------------------+
                    +-> frame_ap / word_ap -> tracker / coverage / user scoreboard
                  checker/SVA <--------------------------------------+

completion_ap: local accepted transaction -> exactly one terminal result

svip_spi_agent 依据 cfg 的 MASTER/SLAVE 与 UVM_ACTIVE/UVM_PASSIVE 创建相应 driver。master 有标准 sequencer；slave 使用有界预装队列。passive 不创建 driver。monitor 始终存在；tracker、coverage 可关闭，sequence_lib 和 checker 有独立编译入口。

每个 active agent 必须绑定独立 svip_spi_if endpoint；多个 endpoint 连接同一组 tri/wire。master 只驱动 SCLK/CS/MOSI，slave 只驱动自己的 MISO/OE。不要把两个 active agent 绑定到同一组输出寄存器。全局协议 checker 每总线绑定一次，本地 OE 由相应 endpoint 检查。

支持 profile 与参数

未使用的 CS 容器位不参与解码和协议判断，可悬空；有效 CS 必须为已知值。容器和实际有效范围分别配置，驱动和 checker 都按有效范围检查。

对象、完成与所有权

master 接纳标准 sequence item 后建立私有快照；payload、有效 profile 与时序在当前事务中固定。clock_hold 与 abort 是明确的运行期控制，按实际边界消费。正常完成、reset、abort、timeout 或参数拒绝均只对应一次 item_done，finish_item 返回时结果已回写。

slave 在 enqueue 返回成功时复制对象，分配局部 serial；实际 CS 选中才消耗响应。局部 serial 仅用于调试，不是 SPI bus ID。活动/排队响应被 reset 取消时都有对应终态。修改原提交对象不会改变已接纳数据。

do_copy/clone 保留派生类型、用户字段与四态数组。AP 发布独立快照；订阅者将它们视为只读，修改前自行 clone。frame_ap 是实际物理帧，completion_ap 是本地工作终态，不能相互替代。被动部署也能检查原始引脚和导出 tracker/coverage。

边沿、首末位与事件区域

CPHA0 首 bit 在首采样沿之前预装；CPHA1 在首 launch 呈现。每 bit 的完整周期包括返回 CPOL，最后周期也不能省略或多采一位。CS hold 从最终时钟收尾计算，随后释放 CS。

双边沿 clocking 输入 #1step 保存沿前值；输出使用 NBA。SCLK idle 时改变 CPOL 的 clocking 事件可能晚于同 tick 的 CS 更新到达，slave 根据事件采样到的 CS/reset 判断归属，不能仅看当前 raw CS。配置的正物理时间形成实际建立窗口；不依赖任意 #0/#1ps 来掩盖 driver 竞争。

clock-to-out 延迟从 CS 首位预装或后续 launch 计时；延迟线程带 epoch/launch token，并随响应窗口结束取消。reset 取消 worker 后，再经过 NBA 对 idle/OE 压制，避免旧调度残留。

checker 的 setup/hold 围绕 sample edge，而非要求整个某一高相都稳定；允许合法的 launch 后传播延迟。数值窗口由 DUT/profile 决定，默认数据与高低脉宽有一个1ps精度量子的数字检查，可设0关闭窗口。CS 数值窗口默认0，接入时按 DUT 手册设置。

响应与回调

FIXED 持续发送 fill_word 的有效位；RANDOM 按未来 word 生成已知随机值；QUEUED 每个 CS 窗口消耗一个响应。QUEUED 耗尽后发送 fill，实际被采样时每帧报告一次 UNDERRUN，不阻塞 SCLK。短帧未使用的响应尾部丢弃并计数，不回流下一帧。中途 enqueue 归下一次选中。

prepare_word(prefix,index,value) 是 function，输入只有已经采样完成的 MOSI 前缀与待准备 word。CPHA0 最后一个 trailing edge 可能预备一个最终未使用的下一 word，因此回调可被推测调用；不要在其中提交不可撤销的业务副作用。依据实际 word_ap/frame_ap 完成存储提交。业务响应可以不调用 super。

用户可在此边界实现寄存器/存储语义，核心没有 address/WEL/page 等假设。收到整个请求后再等待上层 sequence 返回，无法回填同一 CS 窗口过去的响应。

reset、异常和恢复

reset 优先于同 tick 采样；driver 取消活动输出、释放 CS/OE，返回 RESET_ABORTED，队列清空。SPI 不承诺回滚外部 DUT 已接收的位或业务副作用。恢复后需要新的完整 CS 边界；若仅复位 VIP、外部 master 仍保持 CS，driver 与 monitor 均等待实际 idle-CS，丢弃无法重建的帧尾。

主动 abort 返回 ABORTED，可产生 partial 物理帧；实际协议诊断仍保留。watchdog 默认关闭，启用时从本地工作开始计时，包含配置 latency/hold；返回 TIMEOUT。slave timeout 后释放 OE，等待当前 CS 撤销再接受新帧。

非完整 word 保留 partial 值与实际 bit 数；required 数据 X/Z 保留四态并诊断。被动组件在已选中的帧中启动时标识 resync 并等待下一个干净边界，不伪造帧头。

观察、覆盖与性能边界

frame记录包含 mode/order/有效字长/CS、完整双向 word、partial、实际采样数、状态、时间与观察到的半周期跨度。word_ap 在每个实际完整 word 发出累计前缀；无订阅时不复制前缀。

coverage 的 native covergroup 和 common/cov 共享 bin 定义，按实际帧与局部完成分别采样，final hook 负责 JSON 导出。多实例 service 按组聚合计数，native covergroup 可分实例查看；详细字段见使用指导。

普通移位路径与 bit 数线性增长。用户若订阅每 word 的累计快照，或回调要求长前缀快照，会增加复制成本；长事务优先订阅 frame_ap，并让业务模型保持自己的增量状态。默认 tracker 有界预览，完整原始数组仍从 AP 提供。