Verissimo SystemVerilog Testbench Linter User Guide
Rev. 24.2.25, 31 October 2024

8.1 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?