Verissimo SystemVerilog Testbench Linter User Guide
Rev. 24.1.5, 13 March 2024

9.1 Lint Waivers File Syntax (XML)

There are two types of waivers:

  • waivers applied before running the checks (pre-waivers), excluding files from linting

  • waivers applied after running the checks (waivers), hiding the failures in the final results

Waivers file MUST contain on the first line the prolog:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

If a waiver has invalid values it will be ignored and if the waiver's file is not XML compliant an error is reported and waivers are not loaded.

Syntax:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<waivers version="7">
    <include relative="#INCLUDED_WAIVERS_FILE_RELATIVE_1#">#INCLUDED_WAIVERS_FILE_1#</include>
    ...
    <include relative="#INCLUDED_WAIVERS_FILE_RELATIVE_N#">#INCLUDED_WAIVERS_FILE_N#</include>
    <pre-waiver name="#NAME#" apply-on="#APPLY_ON_MODE#">
     <description>#DESCRIPTION#</description>
        <paths regex="#REGEX_MODE">
            <path>#PATH_1#</path>
            ...
            <path>#PATH_N#</path>
        </paths>
        <elements regex="#REGEX_MODE#">
            <element>
                <type>#ELEMENT_TYPE_1#</type>
                <name>#ELEMENT_NAME_1#</name>
            </element>
            ...
            <element>
                <type>#ELEMENT_TYPE_N#</type>
                <name>#ELEMENT_NAME_N#</name>
            </element>
        </elements>
    </pre-waiver>
    <pre-waiver name="#NAME_N#">
       ...
       ...
       ...
    </pre-waiver>
    <waiver name="#NAME_1#" apply-on="#APPLY_ON_MODE#" macro-path="#IS_MACRO_PATH#">
        <status>#STATUS#</status>
        <description>#DESCRIPTION#</description>
        <paths regex="#REGEX_MODE#">
            <path>#PATH_1#</path>
            ...
            <path>#PATH_N#</path>
        </paths>
        <elements regex="#REGEX_MODE#">
            <element>
                <type>#ELEMENT_TYPE_1#</type>
                <name>#ELEMENT_NAME_1#</name>
            </element>
            ...
            <element>
                <type>#ELEMENT_TYPE_N#</type>
                <name>#ELEMENT_NAME_N#</name>
            </element>
        </elements>
        <checks>
            <check>#CHECK_NAME_1#</check>
            ...
            <check>#CHECK_NAME_N#</check>
        </checks>
        <line-ranges>
            <line-range>#LINE_RANGE_1#</line-range>
            ...
            <line-range>#LINE_RANGE_N#</line-range>
        </line-ranges>
        <message-patterns regex="#REGEX_MODE#">
            <message-pattern>#MESSAGE_PATTERN_1</message-pattern>
            ...
            <message-pattern>#MESSAGE_PATTERN_N</message-pattern>
        </message-patterns>
    </waiver>
    <waiver name="#NAME_N#">
       ...
       ...
       ...
    </waiver>
</waivers>

#INCLUDED_WAIVERS_FILE#

  • Waiver files can be included before the waivers defined in the current file.

  • Can be a file. System variables can be used.

#INCLUDED_WAIVERS_FILE_RELATIVE#

  • Can be "true" or "false".

  • When "true" the path of the included file will be considered relative to the folder containing the waivers file.

  • When "false" the path of the included file will be considered either absolute or relative to the current working directory.

#NAME#

  • Must be an unique id of a waiver.

  • This tag is NOT optional and MUST NOT be empty.

#REGEX_MODE#

  • Must be perl or simple. If the attribute regex is not specified then perl is selected. The regex mode is used in all message-pattern tags of this waiver. The simple mode accepts "*" to match any group of characters and "?" to match any single character.

#APPLY_ON_MODE#

  • Must be matched or not-matched. If the attribute apply-on is not specified then matched is selected. The apply-on mode is used to define the scope of the waiver, the status will be applied on the matched hits or on all non matched hits.

#IS_MACRO_PATH#

  • Must be true or false (default). When true, a hit is waived if it is inside a macro defined in a file path that matches one of the specified #PATH#s.

#STATUS#

  • Any value from the following set of values

    • error : hits matched by this waiver will be reported as errors

    • warning : hits matched by this waiver will be reported as warnings

    • info : hits matched by this waiver will be reported as infos

    • disable : hits matched by this waiver will not be stored

  • If two or more waivers cover the same piece of code they will apply in the order they were declared.

  • File waivers are applied after inline waivers

  • Waivers applied on "not-matched" hits will be applied first, followed by "matched" waivers

  • Waivers defining only check names with DISABLE status will prevent that check from running, the check can be enabled only by a similar waiver defining only check names and a different status

  • This node is NOT optional.

#DESCRIPTION#

  • Used in GUI as a description box for the waiver

#PATH#

  • Can be a file or a directory name. System variables or wildcards "*", "?" can be used, but backslashes '\' are always treated as path separators, regardless of the OS. Therefore, you cannot use '\?' and '\*' to escape wildcards.

  • If there is no <path> node defined the waiver applies for all files.

#CHECK_NAME#

  • A waiver defining only the check name with a DISABLE status will prevent that check from running,

  • If there is no <check> node defined the waiver applies for all checks.

#LINE_RANGE#

  • Can be a line number or a line range defined by two numbers separated by ":" character.

  • If there is no <line-range> node defined the waiver applies for the entire file.

#MESSAGE_PATTERN#

  • Must be a valid regular expression (with regards to #REGEX_MODE#) that matches the entire message of the hit

  • In perl regex mode any regular expression construct can be used to match the message, for example .* will match any character any number of times and \Q.*\E will match the exact text ".*", see what regular-expression constructs are supported.

  • Spaces before and after the regular expression will be trimmed (if there is a situation when a begin or end space must be matched use [ ] character set or \s meta character that matches any whitespace)

  • If there is no <message-pattern> node defined the waiver applies for any hit message.

#ELEMENT_TYPE#

  • Can be one of the following: module, interface, package or top.

  • Files containing only such elements and all the files included in the scope of those elements will be waived.

  • For top elements, the design elements instantiated under the specified top module will be waived only if the specified top is found in the sub-hierarchy of the top module defined in the build configuration file. Otherwise, the waiver is applied only on the module described by the waiver.

For example, if the design hierarchy looks like this ( module1 is the declared top in the build configuration):

 module1
   module2
     module3
       module4
   module5

  • A top waiver for module2 will waive failures from module2, module3 and module4.

  • A top waiver for module6 (a module outside the specified hierarchy) will only waive hit from module6.

#ELEMENT_NAME#

  • Must be a valid regular expression (with regards to #REGEX_MODE#) that matches a range of names.

  • Only the elements matching the regular expression will be pre-waived.

Note: If both paths and elements are specified in a pre-waiver the resulting intersection will be applied.

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?