Ruleset File Syntax (XML)
<?xml version="1.0" encoding="UTF-8"?>
<ruleset version="2" name="#RULESET_NAME#" library="#LIBRARY_NAME">
<include relative="#INCLUDED_RULESET_FILE_RELATIVE_1" file="#INCLUDED_RULESET_FILE_1" />
...
<include relative="#INCLUDED_RULESET_FILE_RELATIVE_N" file="#INCLUDED_RULESET_FILE_N" />
<include since="#INCLUDED_SINCE_DATE" />
<configuration>
<architecture>
<component
type="#COMPONENT_TYPE_1#"
base-class="#COMPONENT_BASE_CLASS_1#"
name-pattern="#COMPONENT_NAME_PATTERN_1#"
/>
...
<component
type="#COMPONENT_TYPE_N#"
base-class="#COMPONENT_BASE_CLASS_N#"
name-pattern="#COMPONENT_NAME_PATTERN_N#"
/>
</architecture>
<effort-levels>
<effort level="#EFFORT_LEVEL_1#" time="#EFFORT_LEVEL_TIME_1#" />
...
<effort level="#EFFORT_LEVEL_N#" time="#EFFORT_LEVEL_TIME_N#" />
</effort-levels>
<skip-file
name-pattern="#SKIP_FILE_NAME_PATTERN#"
/>
<skip-element
name-pattern="#SKIP_ELEMENT_NAME_PATTERN#"
/>
<failed
severity="#FAILED_SEVERITY#"
/>
<timeout
process="#PROCESS_TIMEOUT" session="#SESSION_TIMEOUT" check="#CHECK_TIMEOUT"
/>
<annotation
name="#ANNOTATION_NAME_1#" show-in="#ANNOTATION_LOCATION_1#" type="#ANNOTATION_TYPE_1#" ...
/>
...
<annotation
name="#ANNOTATION_NAME_N#" show-in="#ANNOTATION_LOCATION_N#" type="#ANNOTATION_TYPE_N#" ...
/>
<thread-dump interval="#THREAD_DUMP_INTERVAL#" delay="#THREAD_DUMP_DELAY#" rules="#THREAD_DUMP_RULE_NAME_1#,...,#THREAD_DUMP_RULE_NAME_N" />
<histogram-dump rules="#HISTOGRAM_DUMP_RULE_NAME_1#,...,#HISTOGRAM_DUMP_RULE_NAME_N" />
<include-creation-date />
<include-html-code />
</configuration>
<category
name="#CATEGORY_NAME_1#"
description ="#CATEGORY_DESCRIPTION_1#">
<tag key="#TAG_KEY_1#" value="#TAG_VALUE_1" />
...
<tag key="#TAG_KEY_N#" value="#TAG_VALUE_N" />
<rule
id="#RULE_ID_1#"
severity="#RULE_SEVERITY_1#"
name="#RULE_NAME_1#"
title="#RULE_TITLE_1"
description="#RULE_DESCRIPTION_1#"
allow-override="#RULE_ALLOW_OVERRIDE_1#"
timeout="#RULE_TIMEOUT_1#"
effort-level="#RULE_EFFORT_LEVEL_1#"
autocorrect="#RULE_AUTOCORRECT_1#"
disable="#RULE_DISABLE_1#">
<tag key="#TAG_KEY_1#" value="#TAG_VALUE_1" />
<tag key="#TAG_KEY_2#" value-append="#APPEND_TAG_VALUE_2" />
<property
key="#PROPERTY_KEY_1#"
value="#PROPERTY_VALUE_1#"
/>
<property
key="#PROPERTY_KEY_2#"
value-append="#APPEND_PROPERTY_VALUE_2#"
/>
...
<property
key="#PROPERTY_KEY_N#"
value="#PROPERTY_VALUE_N#"
/>
<pre-waiver
include-path="#PRE_WAIVER_INCLUDE_PATH_1#, #PRE_WAIVER_INCLUDE_PATH_2#,..., #PRE_WAIVER_INCLUDE_PATH_N#"
exclude-path="#PRE_WAIVER_EXCLUDE_PATH_1#, #PRE_WAIVER_EXCLUDE_PATH_2#,..., #PRE_WAIVER_EXCLUDE_PATH_N#"
/>
</rule>
<override-rule
name="#RULE_NAME_1#"
severity="#RULE_SEVERITY_1_1#"
title="#RULE_TITLE_1"
description="#RULE_DESCRIPTION_1_1#"
timeout="#RULE_TIMEOUT_1_1#"
effort-level="#RULE_EFFORT_LEVEL_1_1#"
autocorrect="#RULE_AUTOCORRECT_1#"
disable="#RULE_DISABLE_1#">
<property
key="#PROPERTY_KEY_1#"
value="#PROPERTY_VALUE_1_1#"
/>
<property
key="#PROPERTY_KEY_2#"
value-append="#APPEND_PROPERTY_VALUE_2_1#"
/>
...
<property
key="#PROPERTY_KEY_N#"
value="#PROPERTY_VALUE_N_1#"
/>
<pre-waiver
include-path="#PRE_WAIVER_INCLUDE_PATH_1_1#, #PRE_WAIVER_INCLUDE_PATH_2_1#,..., #PRE_WAIVER_INCLUDE_PATH_N_1#"
exclude-path="#PRE_WAIVER_EXCLUDE_PATH_1_1#, #PRE_WAIVER_EXCLUDE_PATH_2_1#,..., #PRE_WAIVER_EXCLUDE_PATH_N_1#"
/>
</override-rule>
<rule
id="#RULE_ID_2#"
severity="#RULE_SEVERITY_2#"
name="#RULE_NAME_2#"
title="#RULE_TITLE_2"
description-append="#APPEND_RULE_DESCRIPTION_2#"
timeout="#RULE_TIMEOUT_2#"
effort-level="#RULE_EFFORT_LEVEL_2#"
autocorrect="#RULE_AUTOCORRECT_2#"
disable="#RULE_DISABLE_2#">
...
</rule>
...
<rule
id="#RULE_ID_N#"
severity="#RULE_SEVERITY_N#"
name="#RULE_NAME_N#"
title="#RULE_TITLE_N"
description="#RULE_DESCRIPTION_N#"
timeout="#RULE_TIMEOUT_N#"
effort-level="#RULE_EFFORT_LEVEL_N#"
autocorrect="#RULE_AUTOCORRECT_N#"
disable="#RULE_DISABLE_N#">
...
</rule>
</category>
...
<category
name="#CATEGORY_NAME_N#"
description ="#CATEGORY_DESCRIPTION_N#">
...
</category>
</ruleset>
#RULESET_NAME#
The name of the ruleset, used in generated ruleset documentation.
This attribute is optional.
#LIBRARY_NAME#
The name of the ruleset library, it can be “uvm” or “ovm”.
This attribute is optional.
If missing it can be set in batch via the “-ovm” flag, or it will default to “uvm”.
#INCLUDED_RULESET_FILE#
Ruleset files can be included. Only the categories from these rulesets will be included before the categories defined in the current file, the configuration will be skipped.
Can be a file. System variables can be used.
#INCLUDED_RULESET_FILE_RELATIVE#
Can be “true” or “false”.
When “true” the path of the included file will be considered relative to the folder containing the ruleset file.
When “false” the path of the included file will be considered either absolute or relative to the current working directory.
#INCLUDED_SINCE_DATE#
Include in a separate category all new rules added since the specified date.
Date format must be: yyyy-MM-dd, for example 2019-01-31
#COMPONENT_TYPE#
The type of the component for which a custom base class or name pattern can be defined. It can be one of the following:
“ACTIVE_COMPONENT” - default base class: none, default pattern: “.*master.*”
“AGENT” - default base class: “xvm_agent”, default pattern: “.*_agent”
“CONFIGURATION_OBJECT” - default base class: none, default pattern: “.*_cfg|.*_config”
“COVERAGE_COLLECTOR” - default base class: none, default pattern: “.*_cov”
“DRIVER” - default base class: “xvm_driver”, default pattern: “.*_driver|.*_drv”
“ENVIRONMENT” - default base class: “xvm_env”, default pattern: “.*_env”
“MONITOR” - default base class: “xvm_monitor”, default pattern: “.*_monitor|.*_mon”
“REACTIVE_COMPONENT” - default base class: none, default pattern: “.*slave.*”
“SCOREBOARD” - default base class: “xvm_scoreboard”, default pattern: “.*_scb”
“SEQUENCE” - default base class: “xvm_sequence”, default pattern: “.*_seq|.*_vseq”
“SEQUENCER” - default base class: “xvm_sequencer”, default pattern: “.*_sequencer”
“SEQUENCE_ITEM” - default base class: “xvm_sequence_item”, default pattern: “.*_item|.*_trans”
“TEST” - default base class: “xvm_test”, default pattern: none
“TESTBENCH” - default base class: none, default pattern: “.*_tb|tb_.*|.*_sve”
If a component type is not defined then the architecture model will contain types that match the default values for base class or name pattern according to the defined library name (see above - “xvm” above stands for “ovm” or “uvm” according to the specified library).
Patterns are used for rules like “All sequence items must inherit from uvm_sequence_item”. In order for this rule not to be a tautology, patterns are used to identify what are sequence item candidates without considering inheritance. Once identified, inheritance is checked.
#COMPONENT_BASE_CLASS#
The name of the parent base class used to filter a type of component in the architecture model
All the classes that extend this one will be found in the architecture model
#COMPONENT_NAME_PATTERN#
The name pattern for a defined component type
If the user defines a name pattern and a base class for a component type, the architecture model will contain types that match at least one of these
If the user defines only the name pattern or the base class for a component type then the undefined criteria will be considered the default one according to the component type and the defined library name
#SKIP_FILE_NAME_PATTERN#
The name pattern for the files that will be skipped when analyzing the source code
The <skip-file> default value depends on the selected library name
#SKIP_ELEMENT_NAME_PATTERN#
The name pattern for the elements that will be skipped when creating the architecture model
The <skip-element> default value depends on the selected library name
#FAILED_SEVERITY#
The default severity for all rules in the ruleset, it can be overwritten using severity attribute on each rule.
It can be one of the following: “ERROR”, “WARNING” or “INFO”.
#ANNOTATION_NAME#
The name of the annotation that will be used in the HTML report
This attribute is mandatory
#ANNOTATION_LOCATION#
The annotation location is a comma separated list of locations where the annotation will appear
The locations can be: “DETAILS”, “FILTERS”, “TABLE”
This attribute is optional, the default value is “DETAILS”
#ANNOTATION_TYPE#
The annotation processor used to annotate failures
This attribute is mandatory
Available types:
FS: This will use the file system to extract blame information for every failure. This annotation type requires an additional fs-field attribute to specify which information to extract. The valid fs-field values are: “last-modified” which will add the last modified date of each file to the failures in that file
GIT: This will use git to extract blame information for every failure. This annotation type requires an additional git-field attribute to specify which blame information to extract. The valid git-field values are: “author”, “author-mail”, “author-time”, “committer”, “committer-mail”, “committer-time”, “SHA1” and “summary”
P4: This will use Perforce to extract blame information for every failure. This annotation type requires an additional p4-field attribute to specify which blame information to extract. The valid p4-field values are: “author”, “revision-number”, “date”
SVN: This will use svn to extract blame information for every failure. This annotation type requires an additional svn-field attribute to specify which blame information to extract. The valid svn-field values are: “author”, “commit”, “date”
CC: This will use ClearCase to extract blame information for every failure. This annotation type requires an additional cc-field attribute to specify which blame information to extract. The valid cc-field values are: “username”, “full-username”, “date” and “comment”
TAG: This will allow creation of custom tags that can be used inside categories and checks to annotate every failure. This annotation type requires an additional tag-key attribute.
#EFFORT_LEVEL#
The name of the effort level that will be used in the effort-level attribute of a check.
This attribute is mandatory.
#EFFORT_LEVEL_TIME#
The time value of the effort level, [hms] can be used to define the time units, ex: 1h2m3s, 70s, 90m 30s, …
This attribute is mandatory.
#PROCESS_TIMEOUT#
The time in seconds after which the linting process will be stopped, including the building of the project.
This attribute is optional.
#SESSION_TIMEOUT#
The time in seconds after which the linting session will be stopped.
This attribute is optional.
#CHECK_TIMEOUT#
The default time in seconds after which the execution of a single check will be stopped.
This attribute is optional.
#CATEGORY_NAME#
Rules can be placed in categories, the name will be displayed in the GUI.
This attribute is optional.
#CATEGORY_DESCRIPTION#
Every category can have a description.
The description may contain HTML code to be displayed in the HTML report. The HTML code must be wrapped between @html@…@html@ tags.
This attribute is optional.
#RULE_ID#
Must be one of the unique IDs of the rules form the rule pool.
This attribute is mandatory.
#RULE_SEVERITY#
It can be one of the following: “ERROR”, “WARNING” or “INFO”.
This attribute is optional.
#RULE_NAME#
User can overwrite the default name of the rule using this attribute.
The name of the rule is also used for waiving the rule.
The name of the rule must be unique in the ruleset, there can not be two rules with the same name
This attribute is optional.
#RULE_TITLE#
User can overwrite the default title of the rule using this attribute.
This attribute is optional.
#RULE_DESCRIPTION#
User can overwrite the default description of the rule using this attribute.
The description may contain HTML code to be displayed in the HTML report. The HTML code must be wrapped between @html@…@html@ tags.
This attribute is optional.
#APPEND_RULE_DESCRIPTION#
User can append additional information to the default description of the rule using this attribute.
The description may contain HTML code to be displayed in the HTML report. The HTML code must be wrapped between @html@…@html@ tags.
This attribute is optional.
#RULE_ALLOW_OVERRIDE#
If the allow-override attribute is set to ‘none’, the check cannot be overridden.
This attribute is optional.
#RULE_TIMEOUT#
The time in seconds after which the execution of this check will be stopped. It has precedence over #CHECK_TIMEOUT#
This attribute is optional.
#RULE_EFFORT_LEVEL#
User can assign an effort level based on the effort levels declared in the ruleset configuration.
This attribute is optional.
#RULE_AUTOCORRECT#
Users can specify if they want to enable auto-correct for this rule when running in batch mode. It can be one of the following: “on” or “off”. By default, it is “off”.
This attribute is optional.
#RULE_DISABLE#
Users can specify if they want to disable a rule from the ruleset instead or deleting or commenting it. It can be one of the following: “true” or “false”. By default, it is “false”.
This attribute is optional.
#TAG_KEY#
If configuration contains TAG annotations declaring a tag-key, user can tag failures in categories and rules by specifying values for this tag-key.
This attribute is mandatory.
#TAG_VALUE#
This attribute represents the value of the tag selected by tag-key
This attribute is optional for if #APPEND_TAG_VALUE# is used.
#APPEND_TAG_VALUE#
This attribute appends to the value of the tag selected by tag-key, value that can be set by the category.
This attribute is optional for if #TAG_VALUE# is used.
#PROPERTY_KEY#
If a rule is configurable, user can overwrite the default properties.
This attribute identifies the property to be overwritten.
This attribute is mandatory.
#PROPERTY_VALUE#
This attribute represents the value of the property selected by #PROPERTY_KEY#.
This attribute is optional if #APPEND_PROPERTY_VALUE# is used.
#APPEND_PROPERTY_VALUE#
User can append new values to the default values of the property selected by #PROPERTY_KEY#.
This attribute is optional if #PROPERTY_VALUE# is used.
#PRE_WAIVER_INCLUDE_PATH#
This attribute specifies on which files the rule should be applied.
This attribute is a comma separated list of path patterns.
#PRE_WAIVER_EXCLUDE_PATH#
This attribute specifies on which files the rule should not be applied.
This attribute is a comma separated list of path patterns.
#THREAD_DUMP_INTERVAL#
This attribute specifies the interval of thread dumps for a rule.
This attribute is optional. Default value: 200ms.
#THREAD_DUMP_DELAY#
This attribute specifies the delay before a rule will generate thread dumps.
This attribute is optional. Default value: 0ms.
#THREAD_DUMP_RULE_NAME#
This attribute specifies on which rules to collect thread dumps.
This attribute is a comma separated list of rule names.
#HISTOGRAM_DUMP_RULE_NAME#
This attribute specifies on which rules to collect histogram dumps.
This attribute is a comma separated list of rule names.
Note
If you get syntax errors or you want to use special characters (e.g. new line) in the XML read: How to use special characters in XML?