X Npi

x-npi

**License 环境优先规则：**如果当前 EDA/NPI 环境存在 license 约束，优先尝试使用 bsub 提交到 LSF 队列运行。提交失败必须明确报告，不得静默回退到本机执行。

x-npi 用来教 AI agent 编写可复用的 Python pynpi 批量分析脚本。交互式会话查询和 active-driver 因果追踪继续使用 xdebug；当任务需要扫描大量信号、时间窗口、事务、coverage database 或设计 handle 时，使用 x-npi。

任务路由

可复用 helper

可 import 的 helper 包位于 scripts/x_npi/。

from x_npi.runtime import json_stdout_quarantine, pynpi_lifecycle
from x_npi.wave import open_fsdb, iter_edge_samples
from x_npi.protocol import axi_summary
from x_npi.urg import export_summary, parse_summary
from x_npi.coverage import load_exclusion_files, open_covdb, compile_csv_to_el
from x_npi.container import plan_container_records, write_csv_set

公共 helper 按模块分组：

• runtime：verdi_home、configure_pynpi、json_stdout_quarantine、pynpi_lifecycle。
• wave：open_fsdb、close_fsdb、time_in、preflight_signals、sample_values、iter_signal_changes、iter_edge_samples、clock_edges、edge_samples、value_statistics。
• protocol：apb_transactions、apb_summary、axi_transactions、axi_summary、stream_summary。
• urg：urg_path、export_summary、parse_summary；coverage read/export 的默认且推荐入口， 固定 -full64 -xml_verbose -format text -show summary，不加载 pynpi。
• coverage：只负责 exclusion 的 open_covdb、close_covdb、test_names、 merged_test_handle、load_exclusion_files、set_report_time_excluded、 save_exclusion_file、unload_exclusions、compile_csv_to_el。不再提供 NPI coverage read。
• exclusion_csv：parse_document、parse_directory、validate_directory、 format_document、format_directory；reason 只保存在 CSV sidecar。
• design：handle_name、statement_row、trace_driver、trace_load。
• jsonio：ok、error、print_json、split_limited。

运行示例时，可以把 skill 的 scripts 目录加入 PYTHONPATH，也可以直接执行 scripts/examples/ 下的文件。

决策规则

• 针对已经打开的 xdebug 会话做一次性 AI debug 时，使用 xdebug。
• 需要批量 FSDB 扫描、事务提取、coverage export、值分布统计或报告生成时，使用本 skill 编写 Python 脚本。coverage 读取优先 URG；不要把 x-npi 的名字误解为所有 coverage 工作都必须走 pynpi。
• 不确定 pynpi API、类名、枚举或调用约定时，AI 可以直接查看 $VERDI_HOME/share/NPI/python/pynpi/ 下当前安装版本的 Python 包和实现；例如 waveform 的时间归并遍历可查 pynpi/waveform.py 中的 TimeBasedHandle。先核对当前安装 API，再写脚本，不凭记忆猜接口。这是正式 API 查证入口，不是失败后的 fallback。
• 做波形协议分析、事务统计、窗口验证或跨信号相关性判断时，必须基于同一个 clock 的 edge 采样。公开配置只接受 edge=negedge|posedge；posedge 还必须显式指定 sample_point=before|after，negedge 禁止 sample_point。默认使用 negedge。
• 大窗口优先使用流式 iter_edge_samples，让 Python 状态机边读边聚合；只有确实需要完整采样行时才使用会物化列表的 edge_samples。
• AI 可直接用 Python 对结构化结果做过滤、分组、关联、统计、临时索引或任务内缓存，具有很高的自定义自由度。优先一次扫描生成任务需要的聚合，不默认建设持久化缓存数据库，也不为通用示例增加固定业务过滤器。
• 需要 active-driver、active-driver-chain、activeTime、PVC active check、force/root-cause 分类，或在某个症状时间点做接口因果追踪时，改用 xdebug/C++ NPI。当前 Python pynpi 不暴露这些 active trace 所需 API。
• Python NPI coverage API 没有 bulk summary，必须从 instance/metric/object/bin 逐层遍历；设计越大， 启动和遍历成本越高，而且容易把 parent aggregate 与 child bin 重复计分。普通 summary、层次、 test list、code/assert/functional typed 统计和 detail export 一律优先 URG；NPI 在 coverage 部分只用于 exclusion target 的必要遍历以及 EL load/set/save/unload。
• compile_csv_to_el(db, test, csv_dir, output_dir) 内建 indexed resolver：code/assertion 对 CSV 中 唯一 exact scope 使用 handle_by_name，不遍历 instance hierarchy；functional 预检按请求的 group/point/cross 前缀剪枝，apply 用短生命周期 locator trie 重放，不做第二次全树扫描。零/多匹配 和两遍间身份变化均失败并回滚；不缓存 native handle、不建立全 bin 索引、不接受外接 resolver。
• container_exclude.py 是 x-npi 独立容器入口：从既有 fixed URG report 解析，或使用固定 full64 URG 命令新生成 report；递归 instance 只展开 XML 真实节点，然后生成 exact container CSV 并原子 发布四份 EL。NPI 在该流程只用于排除定位和 EL 操作。
• URG summary 百分比使用其 typed subtree ratio；root scope 从 XML 的 instance parent 关系推导， 不假设名称为 top。单 metric pct 为 covered/coverable；多 root 时先按 metric 合并 root 分子/分母，多 metric root/scope SCORE 再对可评分的非 null metric pct 做算术平均。无 coverable object 的 0/0 保留 null 且不参与平均；全部不可评分时 SCORE 为 null。 count 不是 coverage pct。
• 不支持从固定 summary 伪造 per-test attribution、source evidence 或 functional bin；需要 gap 时使用受限 URG text detail，不回退 NPI 全树扫描。
• 脚本 stdout 必须只有一个 JSON document。使用 json_stdout_quarantine 隔离 NPI native banner；summary 默认输出到 stdout，transactions|timeline|full 必须配合 --output 写文件，stdout 只返回摘要和文件位置。协议工具不提供 line_limit。
• 时间字段保持 FSDB integer tick，并在 meta.scale_unit 返回数据库 time scale；不要先转换成 float 时间再做配对或排序。
• 当环境需要 Synopsys license 访问时，真实 pynpi/FSDB/daidir 验证应在受限沙箱外运行。