Cadence Virtuoso IC251 在 WSL 中按 F1 卡死：Doc Assistant 本地端口通信故障的根因与修复

{{badge:已解决}}

注意：本文保留可复现的系统配置、环境变量和命令；已移除具体工艺名及私有工程路径。

现象

在 WSL2 / RHEL 8.10 中启动 Cadence Virtuoso Studio IC25.1-64b.ISR3.31，在 Layout XL 内按 F1 后界面长时间无响应。CIW 或启动日志中会反复出现：

*WARNING* obShowTag for tool "layout" ... status 40 = obcSocketConnectionError
WARNING (HELPAPI-041): Failed to launch Doc Assistant because port communication could not be established.

F1 调用的是 Cadence 的 Doc Assistant，不是系统浏览器。因此“没有安装浏览器”不是根因。

先确认 F1/F2 的实际绑定

所以本问题的触发点是 F1。如果 F2 后出现无响应，应先区分是保存、已有未完成操作，还是先前 F1 调用遗留的阻塞。

根因链路

flowchart LR
    A[Layout 按 F1] --> B[Doc Assistant: cda -server]
    B --> C[Qt WebEngine]
    C --> D[生成 .CDA_port 本地端口文件]
    D --> E[Virtuoso 显示帮助]

故障时，cda -server 在创建 .CDA_port 前退出；Virtuoso 一直等待本地端口，因此最后报 HELPAPI-041。

本次修复确认涉及四项条件：

1. IC251 的 cda25.12 版本解析入口；
2. Qt WebEngine 所需的 Mesa DRI 与 libpng12 运行时依赖；
3. WSL/root 下的 XDG_RUNTIME_DIR、sandbox 和 GPU 启动参数；
4. IC251 所需的 resolver ABI 兼容库与独立临时目录。

最终保留的修复

1. 补齐 cda25.12 的安装根目录解析入口

cd /eda/cadence/IC251/bin
ln -s cda cda25.12

cds_root cda25.12
# 预期：/eda/cadence/IC251

没有该入口时，Doc Assistant 会出现无法确定安装根目录的错误，并在本地端口建立前退出。

2. 安装 Qt WebEngine 和 Virtuoso 的运行依赖

dnf install -y mesa-dri-drivers libpng12

mesa-dri-drivers 提供 Qt WebEngine 所需的 swrast_dri.so。libpng12 可通过下列检查确认是 IC251 的运行依赖：

checkSysConf IC25.1 -P libpng12

3. 仅在 IC251 启动环境中配置 Doc Assistant

将下面配置加入 ~/.bashrc。它只在 CDS_INST_DIR 指向 IC251 时生效，不会影响其他 Cadence 版本。

if [ "$CDS_INST_DIR" = "/eda/cadence/IC251" ]; then
    # 兼容库为 IC251 提供所需的 resolver ABI alias。
    export LD_PRELOAD="$HOME/.local/lib/libcadence_ic251_resolv_compat.so${LD_PRELOAD:+:$LD_PRELOAD}"
    export LD_LIBRARY_PATH="$HOME/.local/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

    export CDA_ENABLE=true
    export PAR_GLOBAL_TEMP="$HOME/.cadence_tmp"

    # Qt WebEngine 以 root 身份运行时必须使用私有运行目录。
    export XDG_RUNTIME_DIR=/tmp/cadence-xdg-runtime-root
    mkdir -p "$XDG_RUNTIME_DIR"
    chmod 700 "$XDG_RUNTIME_DIR"

    # WSL/root 下关闭 Chromium sandbox，并避免 GPU 初始化失败。
    export QTWEBENGINE_DISABLE_SANDBOX=1
    export QTWEBENGINE_CHROMIUM_FLAGS="--no-sandbox --disable-gpu --disable-dev-shm-usage"
fi

兼容库应放在：

$HOME/.local/lib/libcadence_ic251_resolv_compat.so

它只提供 IC251 需要的 resolver ABI alias。隔离测试表明，移除该兼容库或 PAR_GLOBAL_TEMP 后，Doc Assistant 无法生成端口文件，因此这两项不能作为“无用修复”删除。

重新加载配置并启动：

source ~/.bashrc
ic

验证方法

不要只看 Virtuoso 主程序是否打开；应直接确认帮助服务已经建立端口：

cat "$HOME/.config/cadence/.CDA_port"
ps -ef | grep '[c]da.exe.*-server'

.CDA_port 非空且存在 cda.exe -server 时，说明 Doc Assistant 已经就绪。此时在 Layout 内按 F1 应立即显示帮助，日志不再出现 HELPAPI-041。

排查中的临时操作与清理

下列操作仅用于诊断，不应作为长期修复保留：

不要删除正在使用的 .CDA_port，也不要在 Virtuoso 仍运行时结束生产 cda.exe -server 进程。

注意事项

1. LD_PRELOAD、LD_LIBRARY_PATH 和 Qt WebEngine 参数必须限制在 IC251 条件分支内，避免干扰其他 Cadence 版本。
2. 修改 .bashrc 后，旧 Virtuoso 进程不会自动继承新变量；需要从新终端重新启动。
3. 看到 HELPAPI-041 时，优先检查 .CDA_port、XDG_RUNTIME_DIR 的权限，以及 cda.exe -server 是否仍在运行。
4. F2 是保存，不是帮助快捷键；不要把 F2 的现象直接归因于 Doc Assistant。

结论

这不是 Layout 本体、工艺层显示或浏览器缺失造成的问题。根因是 IC251 的 Doc Assistant 在 WSL/root 下没有完成 Qt WebEngine 本地端口服务启动。补齐版本解析入口、运行依赖、启动环境和 resolver ABI 兼容后，cda -server 能创建端口，F1 恢复正常。