01 · 工程契约、环境准备与黄金基线

本章目标：先定义什么叫跑对

本系列只使用一个固定深度 4、宽度 8 的同步 FIFO。DUT 模块为 course_fifo，实例为 tb_top.dut_i；主机端 Testbench 产生时钟、复位、写读请求，并独立计算期望值。默认输入 64 笔，事务 k 的数据为 (17×k+3) mod 256。先写满制造阻塞，再交错读写并排空。后续商业仿真、SA、波形与优化都复用这一契约，不能在中途更换输入序列后仍宣称结果可比。

接口时序：以边沿前的标志决定接受

每个上升沿之前，wr_en 且非 full 才接受写入，rd_en 且非 empty 才接受读取。读数据在该边沿的寄存器更新后生效，因此检查器先记录是否发生读取，再延后到 NBA 更新之后比较 dout。本工程在软件 Testbench 中用 #1 避免采样竞争，这一延迟不进入 DUT。满时同时读写只读，空时同时读写只写；这些是本工程的定义，不代表任意厂商 FIFO IP。

工程目录与运行身份

下载页末实验包后保留其目录结构。源码、控制脚本与结果分开：build 保存特定输入编译出的 snapshot，runs 保存每次运行的证据。flow.py 是本站原创调度与验收脚本，不是 Cadence 命令；它会记录实际执行命令和输入摘要，并拒绝覆盖已有运行编号。对外共享问题时应选择最小必要结果，不需要把商业工具数据库上传网站。

工程实际目录；build 与 runs 由运行脚本创建。

palladium-course/
  rtl/course_fifo.sv
  tb/tb_top.sv
  files.f
  flow.py
  config/site.example.json
  scripts/run_sa.tcl
  scripts/run_wave.tcl
  scripts/run_profile.tcl
  scripts/offline.tcl
  build/                 # 编译后产生，不在下载包中
  runs/                  # 运行后产生，不在下载包中

操作步骤：先获得可用的软件基线

本机有 Python 3、iverilog 与 vvp 即可完成这一节，无需商业许可证。环境检查只证明可执行文件能被找到；执行成功还需检查 RUN_PASS、result.json 与事务 CSV。本站测试采用 Icarus Verilog 13.0，64 笔测试的 cycles 与 full_stall 是这份代码的实测值，不是 Palladium 厂商日志。若缺少工具，先安装对应软件或在团队已有仿真环境执行。

1. 解压并进入工程根目录

   预期与判定：确认 files.f 的两条源路径都存在，不修改顶层或数据宽度。

2. 执行 preflight 与 compile local

   预期与判定：打印工具路径并生成 build/local/build.json；编译失败先查 compile.log。

3. 运行 golden

   预期与判定：应生成 64 行数据、零差异，result.json 状态为 PASS。

4. 保留黄金证据

   预期与判定：runs/golden 下的 transactions.csv 将作为第三章的跨环境对照，course.vcd 仅是软件波形。

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

python3 flow.py preflight
python3 flow.py compile local
python3 flow.py run local --id golden --vcd

预期输出与下一章输入

下面是本工程软件自测的关键输出，省略了工具 banner、绝对路径和逐笔中间日志。墙钟时间取决于机器，不作为通过标准。transactions.csv 第一笔为 0,3，最后一笔为 63,50；这比只看终端 PASS 更容易审计。后续环境允许执行耗时不同，但接受的事务序列和功能结果必须一致。

本站软件实测摘要；不是商业工具实测记录。

COURSE_START N=64 width=8 depth=4
COURSE_TX seq=0 data=3 cycle=13
COURSE_TX seq=1 data=20 cycle=14
...
COURSE_DONE sent=64 received=64 mismatches=0 cycles=121 full_stall=32
RUN_PASS: golden {...}

# result.json 的关键字段
{"status":"PASS","transactions":64,"mismatches":0,"cycles":121,"full_stall":32}

准备 Linux 站点环境，不复制旧版安装路径

本地手册发行标识是 WXE 24.05，但 TBA Tutorial 的安装章节仍展示 20.05 与 Xcelium 20.03 的历史配对。应使用管理员提供、已验证的环境脚本和版本矩阵，不能因文档封面写着 24.05 就照抄其中旧目录。site.json 只记录站点事实，不会替你配置服务器、许可证、硬件预约或修改 PATH；必须先在当前 shell 加载真实环境。

硬件环境准备；/actual/site/setup.sh 是明确的待替换路径，不是本站提供的文件。

cp config/site.example.json config/site.json
# 编辑 site.json，填写 validated_tool_pair、resource_configuration、setup_script
source /actual/site/setup.sh   # 替换为管理员提供的真实路径
python3 flow.py preflight --hardware
xrun -version
xeDebug -version

典型故障：预检查通过但资源仍不可用

命令可见性、授权可用性和设计可运行是三个不同层次。下面是一个用于练习定位的构造案例。保留失败发生的阶段与完整日志，先用同一环境运行站点已知通过的最小设计。只有环境基线恢复后，才继续分析本课程工程，这能避免把平台连通性问题误判成 HDL 不受支持。

完成检查

• 软件基线 64 笔事务通过，黄金 CSV 已保存
• 明确固定 FIFO 语义和 tb_top.dut_i 边界
• 硬件站点信息来自实际验证矩阵，未把预检查当作设备通过

延伸阅读与来源

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

• Getting Started with TBA on Palladium · WXE 24.05

  第 11–14 页：历史安装示例与 SA 通信边界。 页码为本次查阅版本的印刷页码；公开链接通向厂商入口，受限原手册不在本站分发。

• Setting Up Palladium Utilities and Tools · WXE 24.05

  第 9–15 页：工具分工与模式。 页码为本次查阅版本的印刷页码；公开链接通向厂商入口，受限原手册不在本站分发。

继续阅读