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

270 lines
9.9 KiB
Markdown
Raw 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"
```
---
## 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 -tcl -play ice/scripts/run_xedebug_ice.tcl
```
脚本自动连接硬件:
```tcl
debug .
host z7f1x8c-5k9p3m
xc on -run
run 2000
get z3_demo_ice_top.check_state
get z3_demo_ice_top.check_pass
```
### 4.4 SA 模式硬件编译与运行
```bash
# 编译
./scripts/compile_sa.sh
# 调试与仿真协同运行
cd ixcom_db
xeDebug -tcl -play ../scripts/run_xedebug.tcl
```