vivado-waveform-debug

Vivado 波形诊断

可用入口：query_waveform、get_project_info、run_tcl、safe_tcl。

先提出可证伪的问题，例如“复位释放后 valid 是否出现未知值”。已有 VCD 时直接离线查询，不启动 Vivado。不支持直接读 WDB/FST，也不执行任意表达式或完整 SVA；此流程不编程硬件。

发现信号与时间单位

query_waveform(file_path="/work/sim/trace.vcd")

从返回清单选择精确层级名，不能猜测 top 或把向量的位范围拼成未列出的路径。start_time/end_time 是整数 VCD ticks；先读 timescale 再换算物理时间，例如 10 ps/tick 的 100 ticks 是 1 ns。

缩小窗口并查询

query_waveform(file_path="/work/sim/trace.vcd", signals=["top.valid", "top.ready"], start_time=0, end_time=1000, max_events=100, condition={"op": "all_equals", "values": {"top.valid": "1", "top.ready": "1"}})
query_waveform(file_path="/work/sim/trace.vcd", signals=["top.data"], start_time=100, end_time=200, max_events=50, condition={"op": "unknown", "signal": "top.data"})

条件还有 equals（signal/value）和 change（signal）；value 为二进制字符串，可含 x/z。条件引用的信号必须包含在 signals 中。all_equals 只表示采样值同时满足，不能单独证明某时钟沿发生有效握手。

initial_values 是窗口起点所有同刻更新后的状态；events 记录之后的变化。同刻只保留最终值，不能证明 delta-cycle 或毛刺不存在。equals/unknown/all_equals 也检查起点。依次检查 initial_values_complete、last_complete_time、scan_truncated 和 result_truncated，再解释 matches；截断、未记录信号或空匹配都不能证明问题不存在。simulation_verdict 为 not_evaluated，测试 PASS 仍需 assertion/scoreboard、完成条件和日志。

需要新 VCD 时

只对已选会话和已展开的 XSim 仿真操作。核对 testbench、激励、seed、目标信号与有限运行时间；已有仿真运行过目标窗口时，应保留现有结果，再按原激励重跑，不能补造过去事件。

依据 AMD UG900 的 VCD 命令说明，按以下顺序导出；路径、scope 和时长须替换为本次已核对值，文件使用新的任务路径：

safe_tcl(template="open_vcd {0}", args=["/work/sim/trace.vcd"], session_id="design")
safe_tcl(template="log_vcd {0}", args=["/tb/dut/*"], session_id="design")
safe_tcl(template="run {0}", args=["100ns"], session_id="design")
run_tcl(command="close_vcd", session_id="design")

每步检查实际返回；运行失败后也应关闭本次打开的 VCD 并保留日志。不要向共享会话发送 quit，也不要杀掉机器上全部模拟器。不同 Vivado 版本或会话若不接受仿真命令，记录实际错误并在该工程的 XSim Tcl 上下文使用同一导出序列，不声称 VCD 已生成。