xverif

# xverif **英文** | [简体中文](README.zh-CN.md) > [!IMPORTANT] > **开源范围和Synopsys专有依赖** > > 本仓库中的MIT许可证仅适用于xverif项目独立开发的源代码和文档。本仓库不包括或许可Synopsys Verdi NPI、FSDB Reader、覆盖率运行时、头文件、库或文档。 > > 部分`xdebug`和`xcov`功能需要用户单独获取适用的Synopsys许可证权利，并本地安装所需软件。设置`VERDI_HOME`或能够访问供应商文件本身并不授予NPI/FSDB API使用或重新分发权利。不要将`libNPI.so`、`libnpiL1.so`、`libnffr.so`、Synopsys头文件/文档或包含这些材料的二进制文件、软件包和容器镜像与该项目一起分发。有关完整的边界，请参见 [`THIRD_PARTY.md`](THIRD_PARTY.md)。 `xverif`是用于芯片验证调试代理的本地工具包。它包含用于设计和波形调试、覆盖率、位计算、结构化条目解码、日志源位置、SVA语义、持久验证知识和统一MCP入口点的确定性工具： - [`xdebug`](xdebug/README.md): 查询设计和波形数据库中的事实。 - [`xbit`](xbit/README.md): 确定性地评估位、字面值、切片、表达式和预期值。 - [`xentry`](xentry/README.md): 将多拍字节片段解码为配置的原始字段。 - [`xloc`](xloc/README.md): 压缩和恢复UVM日志源位置。 - [`xwiki`](skills/xwiki/SKILL.md): 为代理维护持久的验证项目知识。 - [`xsva`](xsva/README.md): 将SystemVerilog Assertions编译为结构化的IR和确定性的解释。 - [`xcov`](xcov/README.md): 查询VCS/Verdi覆盖率数据库并返回紧凑的证据。 - [`xverif-mcp`](xverif_mcp/README.md): 通过一个MCP服务器将xdebug/xcov暴露为有状态后端，将其他工具暴露为无状态适配器。 简而言之，`xdebug`回答事实来自哪里以及在特定时间发生了什么；`xbit`计算确切的SystemVerilog值；`xentry`提取配置的字段；`xloc`按需解析紧凑的日志位置；`xwiki`保存项目上下文；`xsva`将时间语义降低为IR；`xcov`报告具有源证据的覆盖和未覆盖的对象；`xverif-mcp`将这些确定性能力暴露给AI代理。 ## 工具概述 ### 默认输出格式：XOUT 除非使用显式的机器协议，否则xverif命令默认发出紧凑的`xout`结构化文本。第一行标识响应契约，例如： ```text @xdebug.trace.driver.v1 ``` XOUT使用一组小的稳定节，如`target:`、`summary:`、`data:`、`evidence:`和`next:`。当脚本需要完整的JSON响应或模式验证时，请使用 `--json`。内部代理stdio和钩子协议仍为JSON。 ### xdebug `xdebug`是xtrace和xwave的统一继承者。其JSON API查询Verdi/VCS `daidir`设计事实、FSDB波形事实或在组合调试会话中连接两者。 典型用途包括： - 查找信号驱动器、负载、依赖图、路径和源证据。 - 读取波形值、变化、事件和验证窗口。 - 调查握手、APB和AXI行为、延迟、待处理流量和错误响应。 - 在特定波形时间使用`trace.active_driver`定位活动的RTL驱动器。 ```bash tools/xdebug -h printf '%s\n' '{"api_version":"xdebug.v1","action":"actions"}' | tools/xdebug - printf '%s\n' '{"api_version":"xdebug.v1","action":"actions"}' | tools/xdebug --json - tools/xverif-mcp ``` NPI支持的引擎是一个仅限源代码的包装器。用户必须针对其自己的合法许可的Synopsys安装程序进行构建和运行。请参见 [`xdebug/README.md`](xdebug/README.md) 和 [`THIRD_PARTY.md`](THIRD_PARTY.md)。 ### xbit `xbit`在不读取RTL或层次结构的情况下执行确定性的位、值和表达式计算。 ```bash tools/xbit conv "8'shff" tools/xbit eval "data[15:8] == 8'hbe" --var data=32'hdead_beef ``` 它支持SystemVerilog字面值、有符号和无符号解释、切片、连接、重复、掩码、计数、onehot检查、常量表达式和预期值比较。 ### xentry `xentry`是一个JSON优先的解码器，用于多拍条目。外部配置定义字段布局；该工具在不发明协议语义的情况下返回原始切片和出处。 ```bash printf '%s\n' '{"api_version":"xentry.v1","action":"decode","config_path":"xentry/examples/entry.yaml","input_path":"xentry/examples/fragments.jsonl"}' | tools/xentry - tools/xentry '{"api_version":"xentry.v1","action":"explain","config_path":"xentry/examples/entry.yaml"}' ``` ### xloc `xloc`用紧凑的`L_XXXXXXXX`标识符替换长的UVM源路径，并在需要时从侧车JSONL映射恢复文件、行和源上下文。 ```bash tools/xloc resolve L_00000001 --map out/sim.log.xloc.jsonl tools/xloc stats out/sim.log ``` ### xwiki `xwiki`是用于验证项目的持久内存技能。它使用`XWIKI_DIR`定位项目wiki，并允许代理查询或维护关于DUT、测试平台、接口、序列、检查器、覆盖率、工作流和调试入口点的稳定知识。 ```bash export XWIKI_DIR=/path/to/project/wiki python skills/xwiki/scripts/validate_xwiki.py ``` ### xsva `xsva`将SystemVerilog Assertion文本编译为Surface IR、Sequence IR和Timeline IR，然后生成确定性的文本、Markdown或JSON解释。 ```bash tools/xsva list --file xsva/tests/golden_ir/simple_impl/input.sva tools/xsva parse --file xsva/tests/golden_ir/ranged_delay/input.sva --property p_ranged --emit timeline-ir tools/xsva explain --file xsva/tests/golden_ir/path_expand/input.sva --property p_path ``` ### xcov `xcov`为VCS/Verdi覆盖率数据库提供AI/MCP导向的查询引擎。它支持代码和功能覆盖率、层次结构摘要、漏洞、源映射和大结果导出。 ```bash printf '%s\n' '{"api_version":"xcov.v1","action":"session.open","target":{"vdb":"fake"},"args":{"name":"cov0","fake":true}}' | tools/xcov --json - tools/xcov --stdio-loop ``` 真正的NPI覆盖率查询需要本地许可的Synopsys环境。该项目不包含或授予覆盖率运行时的权利。 ## 推荐的shell入口点 将存储库的`tools/`目录添加到`PATH`中。替换`<xverif-root>`为实际的存储库路径。 Bash或Zsh： ```bash export XVERIF_HOME=<xverif-root> export PATH="$XVERIF_HOME/tools:$PATH" ``` Tcsh： ```tcsh setenv XVERIF_HOME <xverif-root> setenv PATH "$XVERIF_HOME/tools:$PATH" ``` 所有公共命令包装器都位于`tools/`下。 ## 同步代理环境变量 由IDE或插件启动的AI代理可能不会继承交互式shell的Verdi、许可证、LSF、Python和`PATH`设置。 [`sync_agent_env.py`](sync_agent_env.py)在项目级Claude Code或Codex配置中逐渐写入当前环境： ```bash ./sync_agent_env.py --target claude ./sync_agent_env.py --target claude-local ./sync_agent_env.py --target codex ./sync_agent_env.py --target codex --dry-run ``` 当前环境中存在的变量替换匹配的配置值；配置值在当前环境中缺失时被保留。该脚本不会过滤秘密。在允许令牌、密钥或密码写入磁盘之前，请查看当前shell环境。 ## 需求 | 组件 | 需求 | |---|---| | GCC | **5.0+** | | Python | 3.11+ for xverif-mcp, xsva, and xcov; xbit/xentry/xloc支持3.6+ | | Verdi | 目前开发和测试使用 **V-2023.12-SP2**；NPI签名可能因版本而异 | Verdi相关的功能还要求适用的Synopsys许可证权利。`VERDI_HOME`仅标识本地安装，不授予许可证。当另一个Verdi版本暴露NPI兼容性错误时，请使用用户本地头文件适应包装器，而不复制这些头文件到此存储库中。 ## 构建和测试 Makefile负责构建。测试有一个公共入口点：根目录驱动的pytest插件。可以通过Miniconda创建存储库本地Python环境；`requirements-test.txt`是pip安装入口点。正常的门控使用以前发布的`.xverif-test-cache/`数据库，从不隐含运行VCS或`simv`。 ```bash python3 tools/create_python_environment.py conda activate ./.conda-xverif python3 tools/check_test_environment.py --gate fast make -C xdebug pytest --xverif-gate fast # 仅在外部沙盒环境中设置此项。 export XVERIF_TEST_EXECUTION_ENV=host python3 tools/check_test_environment.py --gate regression pytest --xverif-gate regression -n auto pytest --xverif-gate nightly -n auto ``` 显式夹具准备和验证： ```bash pytest --xverif-prepare all-generated pytest --xverif-fixture-validation --xverif-all-fixtures pytest --xverif-fixture-clean pytest --xverif-results-clean ``` 依赖检查由套件隔离。`fast`门控是密封的，不启动外部EDA进程。涉及NPI、MCP进程、VCS或真实数据库的门控或夹具操作必须在正确许可的主机环境中运行，而不使用沙盒。`XVERIF_TEST_EXECUTION_ENV=host`记录执行证据；它不提升权限或切换环境。缺少必需的夹具是一个错误，并带有显式的准备命令；测试永远不会默默准备、跳过或切换后端。裸`pytest`是一个使用错误。请参见 [`doc/agents/xdebug/tests.md`](doc/agents/xdebug/tests.md) 以获取完整合同。 ## 文档 - xdebug用户指南： [`xdebug/README.md`](xdebug/README.md) - xverif能力路由技能： [`skills/xverif/SKILL.md`](skills/xverif/SKILL.md) - xverif管理技能： [`skills/xverif-admin/SKILL.md`](skills/xverif-admin/SKILL.md) - x-npi代理技能： [`skills/x-npi/SKILL.md`](skills/x-npi/SKILL.md) - xdebug CLI参考： [`skills/xverif/references/xdebug/overview.md`](skills/xverif/references/xdebug/overview.md) - xdebug JSON API参考： [`skills/xverif/references/xdebug/json-api.md`](skills/xverif/references/xdebug/json-api.md) - 无SDK循环包装器： [`skills/xverif-admin/references/sdk-free-loop/overview.md`](skills/xverif-admin/references/sdk-free-loop/overview.md) - MCP参考： [`skills/xverif-admin/references/mcp/overview.md`](skills/xverif-admin/references/mcp/overview.md) - xbit用户指南： [`xbit/README.md`](xbit/README.md) - xentry用户指南： [`xentry/README.md`](xentry/README.md) - xloc用户指南： [`xloc/README.md`](xloc/README.md) - xwiki技能： [`skills/xwiki/SKILL.md`](skills/xwiki/SKILL.md) - xsva用户指南： [`xsva/README.md`](xsva/README.md) - xcov用户指南： [`xcov/README.md`](xcov/README.md) - xverif-mcp用户指南： [`xverif_mcp/README.md`](xverif_mcp/README.md)