# 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+ if the always process represents a supported clock model in dut. ``` #### 【深度根因】 Cadence Palladium 硬件仿真器对 DUT 内的延迟有严格的综合语义检查。默认情况下,硬件综合器禁止在 DUT 中出现不带敏感列表的 `#delay`。 如果需要在 DUT 内部自建自由振荡时钟,必须通过 `+iscDelay+` 告诉综合前端这是合法的时钟生成模型。 #### 【解决办法】 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 模式全硬件流程正式跑通闭环**。