Cadence Vmanager vsif文件编写指南（持续更新...）

目录

1.NTF格式介绍

1.1.1 {属性：值}定义

1.1.2类别

1.1.3语法

2.vsif文件中有效的container

2.1 session {…}

---

1.NTF格式介绍

Cadence的Vmanager工具采用vsif类型的文件作为regression的输入文件，采用vplanx/csv类型的文件作为vplan的输入文件，vplanx、vsif文件采用标准的嵌套文本格式（NTF），NTF是一种元格式，类似于XML，本文有关于Vmanager采用的NTF格式的介绍如下：

1. NTF的BNF（巴克斯范式）描述
2. NTF的预处理（#include，环境变量）
3. NTF的限制
4. NTF的错误处理

1.1 NTF的BNF（巴克斯范式）描述

BNF可以理解为专门用于描述（定义）语言的元语言，就是用书面文字的方式来定义编程语言，多出现在各种语言的官方文档中，比如Python官方文档：

NTF的BNF格式如下：

1. 容器（container）的标识符取决于文件类型，比如：

• vsif files--session，group，test
• vplan files--import，section，perspective，coverage，extend，instantiate，within

1. 标识符不区分大小写；
2. 可以在任何BNF元素之间自由使用空白。若要保留名称或属性值中的空格，需要将其放在双引号中；
3. 使用“//”或者“--”可以注释掉该行；
4. 容器（container）的关闭符号“}”后面的分号“;”是可选的；
5. vManager在读取文件时从字符串中删除引号；
6. 有关{属性（attribute）: 值（value）}的完整说明，可以参阅attribute : value；
7. NTF 中没有前向引用（需要按顺序定义属性）。例如，在 vplan 文件中，必须首先定义section属性，然后定义views属性，然后定义section的扩展属性 within 属性。

1.1.1 {属性：值}定义

使用“:”定义一个属性的具体值。

1.1.2类别

属于容器的成员变量（可以把容器理解为一个类，属性就是该类的成员变量，值就是成员变量的具体值）

1.1.3语法

attribute_name: attribute-value；

举例：

weight : 2；

coverage : usb*.*.* ;

• attribute_name 是仅包含字母数字字符和下划线字符的标识符。attribute_name中不允许有空格，但允许在attribute_name前后使用空格。attribute_name区分大小写。session属性的name必须与所有的test属性的name不同。换言之，不能在test和session中使用相同的attribute_name。
• attribute_value可以为空或者按如下语法：
  1. 字符串，可选用引号括起来，如果attribute_value在引号中，则删除引号，保留引号中的内容。如果attribute_value不在引号中，则删除初始和最终空格，并将任何多个空格替换为一个空格。
  2. 注意（所有字符串属性（预定义和用户定义）限制为 32672 个字符。当尝试输入超过 32672 个字符时（在所有方法中 - vsif、edit、scanning），该值将被截断并以“ ..."代替.）
     1. vManager沿 $VMANAGER_PATH 搜索file的完整或部分路径名
     2. 多行文本，按如下方式括起来<text></text>，<text>必须是第一行中的第一个非空格标记，并且</text>必须是最后一行中的最后一个非空白标记。<text> 和</text>可能出现在同一行上，尽管这相当于在实际文本周围使用双引号。举例：如下2个dut_error含义相同。
     3. 
• 注意，后定义的容器内属性会覆盖以前的属性。

1.2 NTF的预处理（#include，环境变量获取）

#include语法如下：

• 包含的文件必须用双引号括起来。
• 每个 include 指令都必须写在仅包含自身的一行中。
• 不允许在 include 指令的末尾使用分号。
• include 指令中允许使用环境变量。使用类似 shell 的语法 $ENV_VAR 或 ${ENV_VAR}。
• 不要在 #include 指令中使用 vsif 指令 $ENV（）、$RUN_DIR、$DIR（） 或 $ATTR（）。

如果未将包含的文件指定为绝对路径，vManager 将搜索以下目录：

• 包含文件的目录（包含 #include 指令或 import {} 的文件）。
• 运行vManager 的目录。
• $VMANAGER_PATH 环境变量指定的任何目录。

1.3 NTF的限制

• 如果数据本身带<text>这个字符的话，vManager就不能编译在<text> </text>标识符之间的数据。
• NTF 容器必须在打开它们的文件中关闭。如果在一个文件中打开容器，则无法在包含的文件中关闭它。例如，不支持以下内容：

1.4 NTF的错误处理

解析 NTF 文件时，可能有两种类型的错误：

• NTF 不兼容错误 -- 文件不是 NTF 格式。
• 特定于应用程序的错误 -- 文件采用 NTF 格式，但根据正在读取的格式，其中的数据是错误的。例如，编写“seed： 123”是有效的 NTF 语法，把seed作为vsif中的container的{属性:值}是正确的，但seed放在vplan 中会产生错误。

2.vsif文件中有效的container

vsif 文件指定要在单个session中运行的一个或多个test。为了支持 vsif 文件的链接，一个 vsif 文件中允许有多个session容器。

vsif 文件还允许以下语法：

• 标准 C++ 编译器指令，包括 #include、#define、#ifdef 和 #ifndef；
• 属性值指令，包括 $ENV、$RUN_ENV、$ATTR 和 $DIR；

以下是 vsif 文件中的有效 NTF 容器：

对于上面每个容器，它可以容纳的用户定义属性数是有限制的。如下：

其中：

• other types包括：path，duration，enum，long，double，boolen。
• other containters包括：test，group，session，run，session_output。

2.1 session {…}

在session容器中可以定义如下属性：

属性	描述	语法	归属
abort_dependent_jobs_on_nonzero_exit	指定当job以非零退出代码退出时，是否必须中止job的从属job。	abort_dependent_jobs_on_nonzero_exit : boolean（默认1）	session
abort_dependent_runs_on_failure	指定在test失败时是否必须中止test的依赖test。此属性的行为类似于abort_dependent_jobs_on_nonzero_exit属性，但当主test失败时，此处的依赖test将失败（在scan阶段发现错误）。	abort_dependent_runs_on_failure : boolean（默认0）	session
automation_file	用于指定每个 vsif 的自动化。	automation_file : path（path 是包含自动化命令的文件的路径，自动化命令文件中的指令和batch命令一致。） （如/vsif/automation/ida.automation;）	session
create_debug_logs	要求 vManager 创建日志文件以帮助调试 DRM 问题	create_debug_logs : boolean	session
create_optimized_coverage_data	指定是否创建优化的覆盖率数据。	create_optimized_coverage_data: <text>string</text> (string可以为NONE,ALL,ALL_SESSION，其中NONE表示该session的优化覆盖率不会被收集，ALL表示该session下每个run的覆盖率都被单独收集，ALL_SESSION表示该session下的每个覆盖率都会被合并收集)	session
default_dispatch_parameters	指定 DRM ExecCommand 的默认选项或参数	default_dispatch_parameters:<text>string</text> 不建议在此字符串中使用环境变量。	session
description	定义一个session的描述	description: description 举例：description : <text>This session contains 10 tests run with random seeds generated by IntelliGen</text>;	session
drm	指定要用于session、group或test的 DRM	drm:<text>string</text> 其中string可以为如下： lsf-- Specifies the DPL-based integration with IBM Platform Load Sharing Facility (LSF). sge--Specifies the DPL-based integration with the open source batch-queuing system, Sun Grid Engine (SGE), supported by Sun Microsystems. openlava  --Specifies the DPL-based integration with OpenLava workload scheduler. nc  -- Specifies the DPL-based integration with NetworkComputer based job. loadleveler -- Specifies the DPL-based integration with IBM's LoadLeveler. parallel local -- Specifies the DPL-based execution of runs in parallel on the local machine. serial local -- Specifies the DPL-based execution of runs serially on the local machine. user defined -- Specifies DRM that you created using the DRM API.	session
file_policy	使用户能够选择每次运行时要在 NFS 上保留哪些文件。	file_policy: Perl Boolean expression（采用perl语法）（默认值为1，默认NFS保留所有文件） 例如：要保留failed用例的全部信息，和passed用例的指定文件，可以仿照如下写法： session sess{     top_dir: $ENV(MY_TOP_DIR);     output_mode: terminal;     file_policy: <text> getStatus() eq "FAILED"</text>; }; group g{     file_policy: <text> getFile() =~ /\.log/ and "$ATTR(test_name)" eq "t3" </text>;     scan_script: true;     test t1{         file_policy: <text> getFile() =~ /cov_work\/scope/ </text>;         run_script: "xrun $ENV(WORK_AREA)/test.sv -coverage all -access r -svseed random";};     test t2{         run_script: "xrun $ENV(WORK_AREA)/test.sv -coverage all -access r -svseed random; exit 1";};     test t3{     run_script: "xrun $ENV(WORK_AREA)/test.sv -coverage all -access r -svseed random"; }; }; 如果t1 PASSED，t2 FAILED，t3 PASSED，则会保留t1的覆盖率，t2的全部文件，t3的带.log的文件。	session
max_runs_in_parallel	指定DRM 并行执行的run的最大次数	max_runs_in_parallel:integer 例如：max_runs_in_parallel:5	session
free_hosts	需要 DRM 为后续run重新分配主机	free_hosts:boolean（默认为1） 若为true，主机被释放，DRM 可以为任何剩余run重新分配此计算机（或其他计算机）。如果为 FALSE，则在session完成之前不会释放主机	session
group_automation_file	指定每个 vsif 中的group自动化。	group_automation_file__:<path for group automation file > automation_file中的内容同automation_file命令	session
host_lock_timeout	指定DRM 任务的timeout时间	host_lock_timeout:time（时间以秒为单位）