04 · 从事务错误到在线采集与离线波形

本章目标：建立可重放的证据链

上一章用 CSV 判断“结果是否一致”，本章用波形解释“为什么如此”。本课程默认用例在约 1246 ns 完成，软件侧先初始化 40 ns 后切入硬件；采集脚本再推进 3000 ns，足以覆盖复位释放、首次读写、满阻塞和排空。这个窗口只针对默认 64 笔用例，不能把它用于任意长负载。flow.py 会拒绝在 wave 模式改变事务数，以免静默产生不完整证据。

HOLD 与两个时间口径

正常 Testbench 完成后会 $finish，这可能使后续采集命令没有机会执行。wave 模式传入 +HOLD，检查器仍会关闭 CSV 并写 result.json，但保持时钟与会话直到 Tcl 返回。脚本的 run 3000ns 表示在当前 40 ns 基础上再前进 3000 ns；xeset traceMemSize 3000ns 表示上传窗口长度。不要把两者都理解成从时间零开始运行，也不要使用无单位数字依赖未知 timeUnit。

scripts/run_wave.tcl 完整示例；在 xrun SA 解释器中使用，实际 trace 资源能力与层次可见性需站点验证。

# For the 64-transaction course only. Invoke with +HOLD to avoid $finish before export.
run 40ns
xc on -run
run -swap
# Unit is explicit: bare numbers inherit timeUnit; percentages unsupported in SA.
xeset traceMemSize 3000ns
database -open course_trace
probe -create tb_top.dut_i.clk tb_top.dut_i.rst tb_top.dut_i.wr_en tb_top.dut_i.rd_en tb_top.dut_i.din tb_top.dut_i.dout tb_top.dut_i.full tb_top.dut_i.empty tb_top.dut_i.count
run 3000ns
database -prepareOffline
exit

操作步骤：在线采集后离线导出

在线阶段使用与第三章完全相同的 SA 构建。flow.py 以 wave01 保存本次业务证据；原始 course_trace.phy 留在 build/sa 中，run.json 记录其位置。这个名称对应一个目录，应整体归档，不能只复制目录名或其中任意单文件。离线阶段不占用在线运行流程，但需要对应的软件环境及可用调试数据，首次预处理时间可能更长。

1. 运行 wave01

   预期与判定：必须得到正确 result.json，且 build/sa/course_trace.phy 目录存在；已有 trace 时先明确归档。

2. 检查在线窗口

   预期与判定：确认采集包含 40 ns 后的复位释放与第一次读事务，记录实际可用时间范围。

3. 启动离线脚本

   预期与判定：从 build/sa 执行 xeDebug，host -offline 打开原始目录，再选择探针并 upload。

4. 确认波形可解释

   预期与判定：至少看到 clk、rst、wr_en/rd_en、full/empty、count、din/dout；输出目录和格式以工具报告为准。

在解压后的 palladium-course 工程根目录执行。标为硬件步骤的命令需在已配置的授权 Linux 环境验证。

python3 flow.py run sa --id wave01 --mode wave
cd build/sa
xeDebug -input ../../scripts/offline.tcl
# 进入离线会话后检查实际导出路径与波形范围。

离线命令与信号选择

只探测能解释 FIFO 行为的端口，不一开始追踪整个层次或所有内部存储字。手册指出硬件 DUV 的探针与软件 Testbench 的对象支持不同，因此这里使用显式信号名，避免把软件内存逐字探测习惯直接套到硬件。若实际层次名字变化，应从该次设计浏览器确认，不通过忽略不存在对象的选项使脚本表面成功。

xeDebug 离线解释器；路径相对于 build/sa。prepareOffline 属于在线阶段，不应在此重复执行。

# xeDebug offline interpreter. Start from the SA build directory with course_trace.phy.
host -offline course_trace.phy
probe -create tb_top.dut_i.clk tb_top.dut_i.rst tb_top.dut_i.wr_en tb_top.dut_i.rd_en tb_top.dut_i.din tb_top.dut_i.dout tb_top.dut_i.full tb_top.dut_i.empty tb_top.dut_i.count
database -upload
# Remain interactive to inspect output; do not call prepareOffline in an offline session.

按一次读取解释波形，而非凭视觉猜测

先找到 CSV 中的事务编号，再在对应周期检查读请求是否真正被接受。以第一笔输出为例，软件基线在 cycle=13 读取数据 3；上升沿之前 rd_en=1 且 empty=0，之后 dout 更新为 3。count 的变化取决于同一拍是否也接受写入。不要在寄存器更新前截图后断言输出错误，也不要把 full 时被拒绝的写请求计入期望队列。

常见采集问题与恢复方式

有 .phy 目录只能说明某种原始数据被准备，不能证明已生成有效波形或覆盖了故障。先用时钟与计数确认基础链路，再扩大探针范围。错误恢复应保留原始目录、匹配构建和运行标识，避免同名覆盖导致“能打开却属于上一次测试”的情况。

典型故障：把 .phy 当成最终波形

该案例专门训练区分原始采集数据与导出波形。离线预处理、探针选择和输出格式各有独立步骤，打开错误的文件类型并不能证明 trace 损坏。按完整流程操作后仍失败，再结合工具日志、目录内容与版本配对继续诊断。

完成检查

• wave01 的业务检查通过且完整 .phy 目录已保存
• 离线导出能够观察关键端口与有效时间窗口
• 能用 full/empty 和采样边沿解释至少一次读写

延伸阅读与来源

本文为黄河电子原创教学说明。产品命令与支持范围请以实际安装版本的官方文档为准。

• Debugging in Offline Mode on Palladium · WXE 24.05

  第 9、13 页：.phy 子目录、准备离线与导出。 页码为本次查阅版本的印刷页码；公开链接通向厂商入口，受限原手册不在本站分发。

• XE Command Reference Manual · WXE 24.05

  第 784、957–958 页：probe 与 traceMemSize 单位；SA 不支持百分比窗口。 页码为本次查阅版本的印刷页码；公开链接通向厂商入口，受限原手册不在本站分发。

继续阅读