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

15 KiB
Raw Blame History

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 时抛出动态链接错误:

/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 行),其动态库组装顺序为:
    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 文件中导出:

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 最前:

setenv HDLICE_HOME $prefix
prepend-path PATH $prefix/bin

2.3 问题三:Forking xeCompile -z3 ... Error: unknown option '-z3'

【现象】

ixcom 进入综合阶段,fork 调用 xeCompile -z3 时报错:

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 时报错:

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 抓取底层系统调用,发现致命报错行:

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 具备完整的工具链查找支持:

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 配置文件:

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 源码:

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 参数(官方包装器完全支持并识别):

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 中引入硬件时钟模型:

always #10 clk_osc = ~clk_osc;

ixcom 的 vhelab 阶段报错中断:

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 报错:

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 载入最新网表:

xeDebug -input ice/scripts/run_xedebug_ice.tcl

2.8 问题八:Windows CRLF 换行符导致 Linux 报错 /bin/sh^M: 解释器错误

【现象】

从 Windows 检出脚本并在 Linux 下执行时报错:

/bin/sh^M: 解释器错误: 没有那个文件或目录

【解决办法】

在仓库根目录添加 .gitattributes 配置文件,全局强制所有平台均使用 Linux 风格的 LF 换行:

* 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

#%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

#%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 环境加载

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 模式硬件全逻辑编译

cd palladium_z3_demo
./ice/scripts/compile_ice.sh

成功标志:

Info            [FLOW_SUCCESS]
        Successfully built target (xeCompile)
Info            [FLOW_SUCCESS]
        Successfully built target (nc elaborate)

4.3 ICE 模式 Palladium Z3 上机运行

# 启动 Z3 交互调试器并自动执行判读
xeDebug -input ice/scripts/run_xedebug_ice.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 模式硬件编译与运行

# 编译
./scripts/compile_sa.sh

# 调试与仿真协同运行
cd ixcom_db
xeDebug -tcl -play ../scripts/run_xedebug.tcl

5. 【实测通过】Palladium Z3 上机实测完整记录

5.1 硬件综合与映射日志(compile_ice.log)

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)

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 模式全硬件流程正式跑通闭环。