Files
Palladium-Z3-demo_ice_top/docs/PALLADIUM_Z3_24.05_SOLUTION.md

399 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Palladium Z3 (24.05 Release) 硬件编译全套问题排查与解决全景文档
## 1. 项目与环境概述
- **项目名称**:Palladium Z3 Demo (Dual Mode: ICE & SA)
- **硬件目标**:Palladium Z3 硬件平台(Domain 授权:`Palladium_Z3_Domain`,服务器:`z7f1x8c-5k9p3m`)
- **工具版本**:
- WXE: `WXE24.05.000`(内部内核版本:`24H1_WXE(Z3), V24.05.338.s005`)
- IXCOM: `IXCOM24.05.000`(`24H1_HDLICE, V24.05.338.s005`)
- XCELIUM: `XCELIUM24.09.013`
- **Git 仓库**:`https://git.cnbugs.com/demo/Palladium-Z3-demo_ice_top.git`
- **发布分支**:`24.05`
---
## 2. 踩坑与完整根因复盘(八大核心问题)
### 2.1 问题一:`hdl2qtdb: symbol lookup error: libimport.so: undefined symbol: ASSERT_RESET`
#### 【现象】
在 HDL-ICE 阶段,`vavlog` 启动 QTDB 服务端 `hdl2qtdb` 时抛出动态链接错误:
```text
/home/software/WXE.../hdl2qtdb: symbol lookup error: .../libimport.so: undefined symbol: ASSERT_RESET
QTDB server failed.
ERROR: failed to start QTDB server.
ERROR: cannot find qtref cell 'Q_EV_WOR' in QTDB.
```
#### 【深度根因】
1. 通过 `readelf -d` 和符号排查发现:`ASSERT_RESET` 符号仅存在于 `$WXE/tools.lnx86/lib/z3/64bit/libdb.so` 中;而 `$WXE/tools.lnx86/lib/64bit/libdb.so`(旧版通用库)中**没有**该符号。
2. 查看 `vavlog` 实际调用的 Cadence 底层包装脚本 `xeWrapper`(第 282 行与 436-464 行),其动态库组装顺序为:
```bash
export LD_LIBRARY_PATH=
add_libpath $RQT_LIBRARY_PATH # (1) 最先被插入
add_libpath $MY_HOME/lib${HW_DIR}/64bit
add_libpath $QTHOME/lib/64bit # (2) 插入了不含 ASSERT_RESET 的通用 libdb.so
add_libpath $USERLIBPATH # (3) 用户的 LD_LIBRARY_PATH 被追加到最后!
```
3. 无论外部如何设置 `LD_LIBRARY_PATH`,`xeWrapper` 都会清空并把用户路径追加在最后,通用 `lib/64bit/libdb.so` 永远被优先载入,导致符号缺失崩溃。
#### 【解决办法】
`xeWrapper` 在清空库后,最先读取并插入的环境变量是 **`RQT_LIBRARY_PATH`**!
只需在环境或 module 文件中导出:
```tcl
setenv RQT_LIBRARY_PATH $prefix/tools.lnx86/lib/z3/64bit
```
即可确保 Z3 专用的 `libdb.so` 处于动态库搜索首位,彻底根治。
---
### 2.2 问题二:`ERROR (vavlog): Cannot determine the path to hdlice executable because environment variable 'HDLICE_HOME' is not set.`
#### 【现象】
`vavlog` 编译时直接退出,提示 `HDLICE_HOME` 未设置。
#### 【深度根因】
1. `IXCOM24.05.000` modulefile 中缺少 `setenv HDLICE_HOME $prefix`。
2. 同时 `IXCOM24.05.000` 中的 `prepend-path PATH` 将 `$prefix/tools.lnx86/bin/64bit`(四层深度的底层裸可执行程序)排在了最前面,绕过了 `$prefix/bin` 官方包装入口,导致 `xeWrapper` 内部使用 `xeroot` 向上计算安装根目录失败。
#### 【解决办法】
在 `IXCOM24.05.000` modulefile 中补齐环境变量并保证 `$prefix/bin` 在 PATH 最前:
```tcl
setenv HDLICE_HOME $prefix
prepend-path PATH $prefix/bin
```
---
### 2.3 问题三:`Forking xeCompile -z3 ... Error: unknown option '-z3'`
#### 【现象】
`ixcom` 进入综合阶段,fork 调用 `xeCompile -z3` 时报错:
```text
xeCompile - 24H1_WXE(Z3), V24.05.138.s000
Error: unknown option '-z3'.
```
#### 【深度根因】
1. Cadence WXE 的工具体系严格分为两层:
- **包装器入口(Wrapper)**:`$WXE/tools.lnx86/bin/xeCompile`(链接到 `../../share/bin/xeWrapper`),官方文档明确说明其负责接收 `-z3`,解析后自动配置环境变量与架构路由。
- **底层裸二进制(Bare Binary)**:`$WXE/tools.lnx86/bin/z3/64bit/xeCompile`,它本身已经是 Z3 专用内核,参数中没有 `-z3` 这个开关,且缺少包装器自动注入的 `libjsoncpp` 等依赖。
2. 之前的 modulefile 中将 `tools.lnx86/bin/z3/64bit` 放在最前,导致系统优先调到了底层裸二进制。
3. 此外发现服务器上存在两个安装目录:`/home/software/WXE/WXE24.05.000`(早期不完整解压残留)和 `/home/software/WXE24.05.000`(官方完整安装目录,内含完整 `tools.lnx86/bin/xeCompile` 包装器)。
#### 【解决办法】
将 WXE modulefile 的 prefix 修正为 `/home/software/WXE24.05.000`,并将 `$prefix/tools.lnx86/bin` 置于 PATH 优先位置。
---
### 2.4 问题四:`ERROR: Fail to invoke RTL Verilog analyzer` (`ver2hdl: No such file or directory`)
#### 【现象】
`HDL-ICE` 运行 `vavlog` 时报错:
```text
WARNING: "./xc_work/xc_vawork/xc_vawork" is not an HDL-ICE library, ignored.
ERROR: Fail to invoke RTL Verilog analyzer.
```
#### 【深度根因】
通过 `strace -f -e trace=execve` 抓取底层系统调用,发现致命报错行:
```text
execve("/home/software/WXE24.05.000/tools.lnx86/bin/64bit/ver2hdl", ...) = -1 ENOENT (没有那个文件或目录)
```
1. `ver2hdl` 是 Verilog 前端分析器,属于 **IXCOM** 组件,路径为 `/home/software/IXCOM24.05/tools.lnx86/bin/64bit/ver2hdl`。
2. `hdlice_nse` 在调用 `ver2hdl` 时,根据传入的 `$QTHOME` 拼装路径。
3. 早期有人曾将 `IXCOM` 的 `hdlice` 软链接到了 `WXE24.05.000/tools.lnx86/bin/64bit/hdlice`,导致 `hdlice` 以为同级的 `ver2hdl` 也在 WXE 目录下,从而报找不到。
#### 【解决办法】
补齐对齐软链接,让 WXE 具备完整的工具链查找支持:
```bash
ln -sf /home/software/IXCOM24.05/tools.lnx86/bin/64bit/ver2hdl /home/software/WXE24.05.000/tools.lnx86/bin/64bit/ver2hdl
```
---
### 2.5 问题五:`ERROR (legacy-42598): Error: The Z3 software cannot be used with Z1/Z2 config file. Please fix the config file.`
#### 【现象】
`xeCompile` 执行了 41 秒后退出,提示 Z3 软件不能使用 Z1/Z2 配置文件:
```text
ERROR (legacy-42598): Error: The Z3 software cannot be used with Z1/Z2 config file. Please fix the config file.
ERROR (legacy-43702): Failed to add emulator configuration.
```
#### 【深度根因】
查看 `/home/software/WXE24.05.000/tools.lnx86/etc/qel/ixcom.qel` 源码:
```tcl
if { $::isLsystem } {
set defaultConfg [ file join $env(QTHOME) etc et3 lsys_default.et3confg]
} elseif { [xeset etxBuild] eq "ET8" } {
set defaultConfg [ file join $env(QTHOME) etc et3 z3_default.et3confg ]
} else {
set defaultConfg [ file join $env(QTHOME) etc et3 ua_default.et3confg ]
}
```
1. Cadence Z3 对应的核心架构代号为 **`ET8`**,对应配置文件为 `z3_default.et3confg`。
2. 之前为规避问题四在 `compile_ice.sh` 中去掉了 `-z3`,导致 `ixcom` 未向 `xeCompile` 传递 `-z3` 开关。
3. `xeCompile` 默认未开启 `ET8`,走入了 `else` 分支去加载 `ua_default.et3confg`(Z1/Z2 配置),与当前 Z3 软件发生冲突。
#### 【解决办法】
在 `compile_ice.sh` 中保留 `-z3` 参数(官方包装器完全支持并识别):
```bash
ixcom -clean -ua +dut+z3_demo_ice_top \
-z3 \
-ignoreSimSetupCheck \
-ignoreHWPlatformSetupCheck \
-ignoreVersionCheck \
"$ROOT/ice/rtl/z3_demo_top.v" \
"$ROOT/ice/rtl/z3_demo_ice_top.v"
```
---
### 2.6 问题六:`[DUT_DELAY_UNSUPPORTED] Delay statement within an always process without any sensitivity list is not allowed in dut`
#### 【现象】
在 ICE 纯硬件模式下,为了让设计脱离外部 Testbench 具备自主自振荡时钟,在 `z3_demo_ice_top.v` 中引入硬件时钟模型:
```verilog
always #10 clk_osc = ~clk_osc;
```
`ixcom` 的 `vhelab` 阶段报错中断:
```text
Error! in file .../z3_demo_ice_top.v at line 41 in module z3_demo_ice_top [DUT_DELAY_UNSUPPORTED]
Delay statement within an always process without any sensitivity list is not allowed in dut.
Please use +iscDelay+<module_name> if the always process represents a supported clock model in dut.
```
#### 【深度根因】
Cadence Palladium 硬件仿真器对 DUT 内的延迟有严格的综合语义检查。默认情况下,硬件综合器禁止在 DUT 中出现不带敏感列表的 `#delay`。
如果需要在 DUT 内部自建自由振荡时钟,必须通过 `+iscDelay+<module_name>` 告诉综合前端这是合法的时钟生成模型。
#### 【解决办法】
1. 在 `compile_ice.sh` 的 `ixcom` 命令行中加入 `+iscDelay+z3_demo_ice_top` 开关。
2. 综合器将其自动映射为专用的硬件时钟原语 `ixc_uClkGen`,实现板载无外部信号驱动下的硬件全自主运行。
---
### 2.7 问题七:`run: ucExecRunCmd failed: no simulator` 与信号全为 `1'bx`
#### 【现象】
在 `xeDebug`(`XEin>`)中执行 `run` 报错:
```text
run: ucExecRunCmd failed: no simulator
XEin> value z3_demo_ice_top.led_done
1'bx
```
#### 【深度根因】
在后台重新执行 `compile_ice.sh` 编译并重新生成全新 `xc_work` 网表时,之前已经打开的 `xeDebug` 交互会话与底层仿真器/硬件的通信进程已断开或失效。继续在该僵死会话中查询引脚值,自然全部返回 `1'bx`。
#### 【解决办法】
在当前僵死会话中执行 `quit` 退出,然后重新启动全新的 `xeDebug` 载入最新网表:
```bash
xeDebug -input ice/scripts/run_xedebug_ice.tcl
```
---
### 2.8 问题八:Windows CRLF 换行符导致 Linux 报错 `/bin/sh^M: 解释器错误`
#### 【现象】
从 Windows 检出脚本并在 Linux 下执行时报错:
```text
/bin/sh^M: 解释器错误: 没有那个文件或目录
```
#### 【解决办法】
在仓库根目录添加 `.gitattributes` 配置文件,全局强制所有平台均使用 Linux 风格的 LF 换行:
```gitattributes
* text=auto eol=lf
*.sh text eol=lf
*.v text eol=lf
*.tcl text eol=lf
```
---
## 3. 标准规范的 Module 配置文件
### 3.1 `/home/software/module/WXE24.05.000`
```tcl
#%Module1.0
##
## WXE24.05.000 Module for Palladium Z3
##
proc ModulesHelp { } {
global version prefix
puts stderr "\tLoads WXE24.05.000 for Palladium Z3"
}
module-whatis "loads Palladium Z3 WXE environment"
set version WXE24.05.000
set prefix /home/software/WXE24.05.000
# 1. 导出关键环境变量
setenv QTHOME $prefix
setenv WXE_HOME $prefix
setenv XE_HOME $prefix
setenv RQT_LIBRARY_PATH $prefix/tools.lnx86/lib/z3/64bit
# 2. 执行命令路径 (确保 tools.lnx86/bin 优先使用官方包装器)
prepend-path PATH $prefix/tools.lnx86/bin
prepend-path PATH $prefix/share/bin
# 3. 动态库与通信库
prepend-path LD_LIBRARY_PATH $prefix/tools.lnx86/lib/z3/64bit
prepend-path LD_LIBRARY_PATH $prefix/tools.lnx86/lib/z3/64bit/et3lib
prepend-path LD_LIBRARY_PATH $prefix/tools.lnx86/lib/64bit
prepend-path DBIN $prefix/tools.lnx86/lib/z3/64bit
# 4. License 服务器
prepend-path LM_LICENSE_FILE 5280@10.33.11.107
```
### 3.2 `/home/software/module/IXCOM24.05.000`
```tcl
#%Module1.0
##
## IXCOM24.05.000 Module
##
proc ModulesHelp { } {
global version prefix
puts stderr "\tLoads IXCOM24.05.000"
}
module-whatis "loads IXCOM environment"
set version IXCOM24.05.000
set prefix /home/software/IXCOM24.05
# 导出环境变量
setenv IXCOM_HOME $prefix
setenv HDLICE_HOME $prefix
setenv AXIS_HOME $prefix/tools.lnx86
# 工具路径与库 (确保 $prefix/bin 在最前面)
prepend-path PATH $prefix/tools.lnx86/bin/64bit
prepend-path PATH $prefix/tools.lnx86/bin
prepend-path PATH $prefix/bin
prepend-path LD_LIBRARY_PATH $prefix/tools.lnx86/lib/64bit
```
---
## 4. 标准编译与运行指南
### 4.1 环境加载
```bash
module purge
module load /home/software/module/WXE24.05.000
module load /home/software/module/IXCOM24.05.000
module load /home/software/module/XCELIUM24.09.013
```
### 4.2 ICE 模式硬件全逻辑编译
```bash
cd palladium_z3_demo
./ice/scripts/compile_ice.sh
```
成功标志:
```text
Info [FLOW_SUCCESS]
Successfully built target (xeCompile)
Info [FLOW_SUCCESS]
Successfully built target (nc elaborate)
```
### 4.3 ICE 模式 Palladium Z3 上机运行
```bash
# 启动 Z3 交互调试器并自动执行判读
xeDebug -input ice/scripts/run_xedebug_ice.tcl
```
脚本执行的核心调试指令:
```tcl
debug .
host z7f1x8c-5k9p3m
xc on -run
after 2000
value z3_demo_ice_top.led_done
value z3_demo_ice_top.led_pass
value z3_demo_ice_top.led_fail
value z3_demo_ice_top.led_gpio
```
### 4.4 SA 模式硬件编译与运行
```bash
# 编译
./scripts/compile_sa.sh
# 调试与仿真协同运行
cd ixcom_db
xeDebug -tcl -play ../scripts/run_xedebug.tcl
```
---
## 5. 【实测通过】Palladium Z3 上机实测完整记录
### 5.1 硬件综合与映射日志(compile_ice.log)
```text
INFO (legacy-0): 91827 smTrNets have been restored: elapsed time 0 sec
INFO (legacy-0): 89206 smTrPrims have been restored: elapsed time 0 sec
INFO (legacy-0): flat-conns have been restored: elapsed time 0 sec
INFO (legacy-0): 99159 synonyms have been setup: elapsed time 0 sec
INFO (legacy-0): smNetIDs have been setup: elapsed time 0 sec
INFO (legacy-0): CRT-FULL has been restored: elapsed time 0 sec
INFO (legacy-43368): Successfully getting critical path design net names.
0 -1 256 0 0
XEC> puts "IXCOMQEL> running $compileScript took [expr [clock seconds] - $t]s"
IXCOMQEL> running compile -names_crit took 47s
// xeCompile ended at : Tue Oct 20 08:15:54 2026 (total: 93 sec), heap memory used by IXCOM : 240.06M bytes
Info [FLOW_SUCCESS]
Successfully built target (xeCompile)
// nc elaborate started at : Tue Oct 20 08:14:19 2026
Please refer to xc_work/xc_make.log for the AVS log.
// nc elaborate ended at : Tue Oct 20 08:14:20 2026 (total: 1 sec)
Info [FLOW_SUCCESS]
Successfully built target (nc elaborate)
// ixcom ended at : Tue Oct 20 08:15:54 2026 (total: 99 sec), heap memory used by IXCOM : 207.29M bytes
// peak virtual memory size (VmPeak) used by IXCOM : 321.83M bytes, peak resident memory size (VmHWM) used by IXCOM : 27.37M bytes
```
### 5.2 硬件在线仿真执行与自动判读输出(xeDebug)
```text
XEin> debug .
XEin> host z7f1x8c-5k9p3m
XEin> xc on -run
XEin> after 2000
XEin> puts "=========================================================="
==========================================================
XEin> puts " led_done : $done_val"
led_done : 1'b1
XEin> puts " led_pass : $pass_val"
led_pass : 1'b1
XEin> puts " led_fail : $fail_val"
led_fail : 1'b0
XEin> puts " led_gpio : $gpio_val"
led_gpio : 8'b00000010
XEin>
XEin> if {$pass_val == 1 && $fail_val == 0} {
puts "===> [TEST PASSED] Palladium Z3 ICE 全硬件测试通过!"
} else {
puts "===> [TEST FAILED] ICE 硬件自检未通过"
}
===> [TEST PASSED] Palladium Z3 ICE 全硬件测试通过!
==========================================================
```
- **测试判定**:
1. 状态机完成全部 6 项硬件自检(ID 校验、复位计数、定时器超时中断、W1C 清除、跑马灯循环移位),`led_done` 稳定拉高 (`1'b1`);
2. 硬件断言全部符合预期,`led_pass` 为 `1'b1`,`led_fail` 为 `1'b0`;
3. GPIO 图案成功循环左移一位至 `8'b00000010`;
4. 验证结论:**Palladium Z3 硬件仿真平台 ICE 模式全硬件流程正式跑通闭环**。