Clock / Reset / Signal 架构

Author: syan · ADR-CTRL-001 / ADR-CTRL-002 · 2026-11-02

1. 结构和取舍

沿用 SV/UVM1.2、VCS 和已有 APB/AXI。控制设施采用普通 SV 对象，放在 UVM test/env 中持有即可；每根 pin 不建立 agent 或 sequencer。

Test / virtual sequence
   |                            existing APB VIP
   +-- ClockController              ^
   +-- ResetController              | optional APB adapter
   +-- SignalController <---+        |             |
   |  tieoff / fuse / IRQ   |    actual RTL CSR ---> DUT output
   +-- ControlCoordinator -+                         |
          | resource/domain registry                |
          v                                         v
   endpoint + final stamp checks            passive bound interface
          |                                         |
   one physical writer                 independent pin observation
          |                                 +-- HDL CAPTURE_VALUE
       DUT input                            +-- VPI POST_SETTLE_VALUE

ADR-CTRL-002：按控制职责独立编译

                    common <--- optional APB adapter ---> APB
        pin / binding / registry / observation
          result / stamp / clock_ref / DPI
                    ^
          +---------+---------+
          |         |         |
        clock     reset     signal
          ^         ^         ^
          +---------+---------+
                coordinator
                     ^
        svip_control_pkg integration facade

箭头指向依赖。三个组件各有自己的 package、files.f 和可运行 example，均只依赖 common。Reset 和 Signal 的按边沿 API 接受公共的 svip_control_clock_ref，不依赖具体 Clock controller；svip_clock_controller 实现该 reference，项目已有 HDL clock 也可提供自己的实现。纯异步 Signal 与绝对时间 Reset 不需要 clock reference。

coordinator 才导入三个具体组件，负责跨组件 recipe。svip_control_pkg 只 import/export 原始定义，保留既有集成 API 与类型身份，不再包含各 controller 的定义。不会因使用两个 package 产生两份 registry、result 或静态 tracker。

每个独立 files.f 自包含 common 和自身 sources.f。组合时 common 只编译一次，再添加选定的 sources.f；根 control/files.f 提供完整组合。DPI 位于 common/backend/，由 common filelist 编译一次。源码目录和独立运行结果在 Control 入口 中列出。

signal/adapters/svip_control_apb_pkg.sv 只导入 common 和现有 APB agent/sequence；无需 Clock、Reset 或 coordinator。testbench 中的 CSR、错误开关和延迟输出属于验证 fixture。

2. 资源和所有权

svip_control_pin_if#(W,INIT) 绑定实际 pin 和 capture clock，apply() 是产品驱动变量的唯一赋值点。svip_control_sv_binding 隐藏参数化 interface 的类型差异。观察接口只导出读操作，不导出 put()。

registry 使用 canonical packed-root、规范化的 low bit 和 width 识别物理范围；重复 interface handle 即使使用另一 root 名称也会归一。不同 interface 指向同一网或 slice 时，接入者仍须声明正确 canonical root/offset。这不是全芯片连通性发现器。

同一物理 bank 仅一个 active writer。clock/reset 同样登记；DUT source 以 drive_allowed=0 绑定。CSR 输出必须 passive，不能再申请 DirectPin writer。P0 recipe 对整个 canonical bank 独占，全量申请或失败；不等待交叉资源，也不允许共享 clock 被另一个 recipe 提前恢复。

clock/reset/bank 的绑定引用在构造后固定。tieoff lock、fuse window 和 control path 在 endpoint 的最终入口检查，普通 Signal API 不能绕过。

3. 时间和两个观察视图

单位固定为 1ps 整数 tick，VPI 检查全设计 precision 必须为 1ps。不能精确转换的 real 时间、零/负 high/low、超范围 value/mask 和未知控制字段均拒绝；不隐式截断。

P0 的时序保证要求明确的实际 clock 绑定及有效 reference。Clock 组件提供已登记 TB engine 的 reference；外部规则 HDL clock 可用项目 reference 表达已知边界。后者的独立示例验证预测 capture 和真实 edge ID，但不承诺任意派生或变频时钟的预测能力；reference 必须如实拒绝无法预测的边界。未建立关系的外部 clock 与 ASYNC_AT 恰好同 Active timestamp 时，不承诺物理采样结果。跨 backend 的保证须另做 conformance，本版仅声明已测 VCS。

CAPTURE_VALUE 来自 interface 中真实 pin 的 HDL 边沿采样寄存器，带 capture tick/ID。POST_SETTLE_VALUE 来自 VPI cbReadOnlySynch，包含后续 NBA 迭代的最终状态。回调只读 HDL，SV 在下一 tick 取记录，记录保留原 timestamp。它们不读取 driver shadow、profile 值或 checker expected。

4. Clock

engine 与观察分开。stop-low 在 high 中保留完整 high；在 low 中取消未来上升沿。ack 需要 engine 停止且真实 pin 的 ReadOnly 观测为 0。monitor 持续检查 stopped window 中的额外 edge，独立 timer 检查非 intentional clock loss。

start/resume 从接受时刻起完整等待 low_ticks。重复 start 已运行时幂等，重复 stop 已停止时仍确认实际低。周期切换在完整旧周期结束的 rising boundary 生效，边界前的 low 仍是旧值，之后的 high/low 都采用新值。always-on reference 的普通 stop 被拒绝。

5. Reset 和 gap

source token 做逻辑合成；任何 source active 都保持物理 reset。实际 epoch 只来自真实 inactive→active transition，重复 assert 不增加 epoch。初始 active 建立 INITIAL_ASSERTED 状态和一次 epoch。

TB assert 前先设置 pending 和取消 generation，阻止 monitor 回调之前的迟到写。实际 epoch、取消 generation、endpoint owner/command generation 各自独立。延迟 reset source 命令还检查 source generation；旧的定时 release 不覆盖新的同 source assertion。

functional clocks: ... /\__ [all acknowledged stopped at 0] ______ /\...
reference rising:          R0       R1 R2 R3       R4 R5
reset assertion:           +offset ----- release +offset
resume acceptance:                                  +offset
first functional rising:                            +low_ticks

R0 严格晚于全部 stop acknowledgement。assert=R0+offset，release=Rpre+offset，resume 接受=Rpre+post+offset。100MHz reference 的 pre3/post2 对应 assert→resume 精确 50ns，首个 functional edge 另满足完整 low 和正 release_guard。

reference 从 affected 集排除并冻结 period。同步 assertion 整段放在停钟窗口的 plan 被拒绝。source 在 gap 前已有效则 preflight 拒绝；执行中阻止物理释放则返回 partial，clock 留在 stopped 状态，调用方明确恢复。reference 丢失由独立 deadline 结束。此功能是 停钟窗口释放外部 reset。

6. Signal、profile 和生命周期

packed bank 的 masked update 在唯一 writer 内合并。用户输入和 phase、profile/plan 在接纳时冻结；最终写入再检查 stamp 和实际 reset。旧 pulse cleanup 无权修改新 generation。cycle pulse 等待 N 个未来 rising captures；停钟时等待到独立 deadline，仍有效时清到 idle，并返回 timeout。

Profile 是目标组合；TransitionPlan 是转换步骤。capture_coherent 验证同 source clock、owner、kind 和 reset dependencies，所有成员在指定 edge 前完整稳定。跨域 transition 返回逐步骤进度，barrier 不代表同时生效。没有 DUT commit 协议时，多 CSR atomic 请求明确拒绝。

tieoff 在 bootstrap 配置后 lock。fuse/strap mirror 只在指定 POR/load reset 的新实际 epoch 有效窗口装载，lock 后本 epoch 不能重开；普通 functional reset 保留 image。IRQ source 可驱动多线，IRQ observer 只观察 DUT 输出，清除走源条件或 CSR；不自动同步或拉长 pulse。

7. CSR 和结果

APB adapter 使用原 agent 的 sequencer，支持完整 word、字节使能、W1C 和显式 read-clear 读；不做盲目 RMW。超时的 inflight 请求保留，transport 隔离到 drain；不杀死已有 driver，不假装 rollback。reset-aborted 和 SLVERR 保留真实状态。更多 AXI/RAL/ack 适配留到 P1。

结果区分 requested、scheduled、PIN_WRITE_APPLIED / CSR_TRANSACTION_COMPLETED、actual observed 和经指定证据确认的 effective。bus done/readback 不设置 effective。tracker 的 local sequence 只表示日志顺序；同 timestamp 必须结合 phase、generation 和实际 edge ID。

每个等待有绝对仿真 deadline，runner 另有 wall deadline。未验证或不支持的保证不能作为 P0 通过。实际验收见 verification。