Clock / Reset / Signal 场景指南
Author: syan
这份指南从项目需要完成的动作出发，帮助选择组件、时序和示例。完整 API 与时间语义见 使用指导，支持和实测范围见 验证记录。全部命令从产品仓库根执行，先配置 VCS/UVM1.2；本版后端要求全设计 precision 为1ps。
1. 先选最小接入范围
| 项目需求 | filelist | 导入的 package |
|---|---|---|
| 只产生/控制 TB clock | control/clock/files.f |
common + clock |
| 只控制 reset | control/reset/files.f |
common + reset |
| 只控制或观察配置/IRQ 等信号 | control/signal/files.f |
common + signal |
| Clock + Signal | control/coordinator/clock_signal.f |
common + clock + signal |
| 完整控制与跨组件 recipe | control/files.f |
svip_control_pkg::* |
上表 common/clock/reset/signal 分别指 svip_control_common_pkg、svip_clock_pkg、svip_reset_pkg、svip_signal_pkg。单组件只依赖 common，不必创建其他 controller；coordinator 仅在需要组织跨组件动作时使用。
例如，独立编译并运行 Reset：
vcs -full64 -sverilog -ntb_opts uvm-1.2 -timescale=1ps/1ps \
-debug_access+all -f control/reset/files.f \
control/reset/examples/svip_reset_example.sv \
-top svip_reset_example -o simv
./simv
该示例使用项目 HDL clock，不需要 Clock UVC。单独运行 Signal 时，将上述三个 reset 路径/名称分别换为 control/signal/files.f、control/signal/examples/svip_signal_example.sv、svip_signal_example。
自定义组合在项目 filelist 中放一次 common，再放选中的组件源码：
-f control/common/files.f
-f control/clock/sources.f
-f control/signal/sources.f
不要同时叠加多个独立 files.f；这些入口各自已经包含公共 package 和 DPI。共享一个项目 registry 管理物理 ownership，组件实例分别持有自己的 endpoint。
2. 绑定一次，让 testcase 只调用控制 API
env 初始化时完成实际 pin/interface、canonical root/slice、writer/observer 角色和 endpoint 注册，之后 sequence/testcase 持有 controller 调用。每个物理 pin/vector 只有一个 writer；DUT 输出用 passive binding，不能反向驱动。
可直接复制的完整接入分别见 Clock、Reset、Signal、Clock + Signal 和 完整 quickstart。这些示例包含真实 pin/RTL 结果检查，不只有命令发送。
时间参数统一为整数1ps ticks。用 svip_control_now() 取得当前 tick，用 23ns/1ps 表达23ns；不能直接把1ns timeunit 调用方的 $time 当作 ticks。每次动作检查 result.status，每个等待给出独立绝对 deadline。
3. 根据接收时刻选择 phase
| 想达到的效果 | 选择 | 需要的时钟信息 |
|---|---|---|
| 在指定绝对 tick 改值，不对齐时钟 | SVIP_CONTROL_ASYNC_AT |
不需要 clock reference |
| 让指定 capture edge 采到新值 | SVIP_CONTROL_BEFORE_CAPTURE，正 setup_ticks |
可预测且有效的 rising tick |
| 该 edge 采旧值，NBA 后在同 timestamp 改为新值 | SVIP_CONTROL_AFTER_SOURCE_EDGE |
实际运行 clock 的未来 rising edge ID |
按边沿控制接受公共 svip_control_clock_ref。可以直接传 Clock 组件的 controller，也可以使用项目已有 HDL clock 的 reference，写法见 Reset/Signal 独立示例。无法可靠预测的外部时钟不能承诺 BEFORE_CAPTURE；不要用假周期绕过校验。
CAPTURE_VALUE 来自实际 HDL edge sampler；POST_SETTLE_VALUE 来自只读后端的最终 pin 值。二者分别回答“接收 edge 采到了什么”和“本 timestamp 最终是什么”，不能互换。对应测试：sampling、tick_boundary、backend_four_state。
4. 常见功能如何选
| 场景 | API / 组件 | 可复制或定位的集成 case |
|---|---|---|
| 安全停钟、恢复、改变周期 | Clock stop_low() / start() / set_period_at_boundary() |
clock_timing、tick_boundary |
| software/watchdog 多源 reset | Reset set_source() / source_at() / source_after_edge() |
reset_lifecycle |
| functional 停低、reference 持续、gap 内释放 reset | coordinator + svip_reset_clock_map |
reset_gap、tick_gap |
| 单 bank 部分 bit 更新、保留高位 | Signal set(value, mask, when, deadline, result) |
example_basic、wide_masks |
| reset 打断 pulse，防止旧 cleanup 覆盖新状态 | Reset attach() + Signal pulse |
phase_reset_collision、stopped_pulse |
| tieoff 锁定、POR/load 窗口装载 fuse/strap | svip_tieoff_control / svip_fuse_mirror |
example_lifecycle |
| 主动 IRQ 激励、精确短 pulse、只观察 DUT IRQ | svip_irq_source / svip_irq_observer |
example_irq |
| 同域 capture edge 接收完整配置 tuple | coordinator capture_coherent() |
profile_policies、profile_cancel |
| CSR 控制输出，区分总线完成和真实生效 | 可选 signal/adapters APB adapter + passive observer |
example_csr、csr_failures |
集成 case 的入口是 catalog，实现位于 examples、P0a compliance 和 P0b compliance。运行例如：
python3 control/scripts/run.py --case example_irq --case reset_gap --waves
python3 control/scripts/run.py --case example_csr --case csr_failures
stop_low 完成表示实际已停低；start 接受后完整等 low_ticks 才出现首 edge。gap 是停钟窗口内释放外部 reset，不能称为对停止 clock 的同步释放。IRQ 不自动同步或拉长。跨域 barrier 不代表同时生效，多 CSR 没有真实硬件 commit 就不承诺 atomic。
5. 打开 tracker，分别检查命令与实际效果
svip_control_result::open_tracker("control.log");
// 调用 controller，逐项检查 result.status，并观察需要的实际 pin/receiver。
svip_control_result::close_tracker();
svip_control_result::write_coverage("control-coverage.json");
结果分别记录 requested、scheduled、applied、observed、effective。普通 pin write 或 APB completion 不能自动证明 DUT 业务逻辑已接收；用 expect_value() 或项目明确的 ack/receiver 证据确认效果。CSR 输出必须 passive，清 IRQ 通过源条件或 CSR。
runner 自动开启 tracker/coverage 并校验命令 terminal 与统计一致；--waves 默认 FSDB，也支持 --waves vcd。FSDB settled 轨迹帮助定位边沿和值；同 timestamp 的 NBA/delta 先后还要结合 HDL 断言和两种观察视图。
6. 接入后执行哪些测试
# 独立组件、选配组合和完整入口，均做真实编译与引脚检查。
python3 control/scripts/standalone.py
# 全部集成场景及指定容器；各次运行保留独立日志和输入身份。
python3 control/scripts/run.py --suite full
python3 control/scripts/run.py --suite full --max-width 257 --seed 17
# 无 license 的工具/目录依赖检查。
python3 -m unittest discover -s control/scripts -p 'test_*.py'
故意错误 case 的 PASS 表示指定故障被准确检出，不能删除 checker 报告预算来消除失败。P1/P2 后续能力与未测后端见 验证记录，不属于本版已通过的保证。