.. _Ruleset File Examples:

Ruleset File Examples
---------------------


.. code-block:: xml
   :caption: Example 1 - Ruleset with two categories


   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
      <category
          name="Architecture"
          description="Rules that inspect the environment architecture" >
         <rule
            id="ARIN"
            name="ARAI"
            title="Agent Instantiation"
            description="Verify that all agents are properly instantiated ..."
         />
      </category>
      <category
           name="Sequences" >
         <rule
            id="SQSD"
            severity="INFO"
            name="SQSD"
            title="Sub-sequencers in Virtual Sequencers"
            description="Verify that all virtual sequencers have sub-sequencers ..."
         />
         <rule
            id="MSUA"
            severity="WARNING"
            name="MSUA"
            title="Use Print() for Printing"
            description="It is recommended to use the field macro automation..."
         />
      </category>
      <category name="XVM Build Phase">
         <rule id="SVTB.7.14.0" name="Build Calls Super" title="Always call super.build_phase()" description="An overridden uvm_component.build_phase() must call super.build_phase().">
            <property key="baseClass" value="uvm_pkg::uvm_component" />
            <property key="methodName" value="build_phase" />
         </rule>
      </category>
   </ruleset>

.. code-block:: xml
   :caption: Example 2 - Ruleset with XVM rules configured as UVM and all failures reported as warnings

   <?xml version="1.0" encoding="UTF-8"?>
   <ruleset library="uvm" version="2">
      <configuration>
         <architecture>
            <component
                type="AGENT"
                base-class="uvm_agent"
            />
            <component
                type="CONFIGURATION_OBJECT"
                name-pattern=".*_cfg"
            />
            <component
                type="DRIVER"
                base-class="uvm_driver"
                name-pattern=".*driver"
            />
            <component
                type="ENVIRONMENT"
                base-class="no_class_at_all"
                name-pattern="environment"
            />
            <component
                type="MONITOR"
                base-class="ubus_slave_monitor"
                name-pattern=".*monitor"
              />
            <component
                type="SCOREBOARD"
                base-class="uvm_scoreboard"
              />
         </architecture>
         <skip-file name-pattern=".*_seq.svh"/>
         <skip-element name-pattern=".*_word_seq|.*_byte_seq"/>
         <failed severity="WARNING"/>
      </configuration>
      <category name="Names">
         <rule
             id="XVM.2.2.1"
             title="Driver Class Name"
         />
         <rule
             id="XVM.2.3.1"
             title="Monitor Class Name"
         />
         <rule
             id="XVM.2.4.1"
             title="Sequencer Class Name"
         />
         <rule
             id="XVM.2.6.1"
             title="Agent Class Name"
         />
         <rule
             id="XVM.2.7.1"
             title="Environment Class Name"
         />
         <rule
             id="XVM.2.8.2"
             title="Test Class Name"
         />
      </category >
   </ruleset>
  
 
.. code-block:: xml
   :caption: Example 3 - Ruleset with author name annotated on failures using git blame and including the source code in HTML format

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
      <configuration>
         <annotation name="Author" show-in="filters, details, table" type="git" git-field="author" />
         <include-html-code />
      </configuration>
      <category
          name="Architecture"
          description="Rules that inspect the environment architecture" >
         <rule
             id="ARIN"
             name="ARAI"
             title="Agent Instantiation"
             description="Verify that all agents are properly instantiated ..."
         />
      </category>
   </ruleset>

.. code-block:: xml
   :caption: Example 4 - Ruleset with description-append and value-append parameters

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
      <category name="Checks for class members comment">
         <rule
            id="SVTB.25.6.6.0"
            name="Class members comment"
            description-append="Use this for validating type parameters comment."/>
               <property
                  key="memberKinds"
                  value-append="type_parameter"
               />
         </rule>
      </category>
   </ruleset>

.. code-block:: xml
   :caption: Example 5 - Ruleset with HTML code in description-append

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
      <category name="Factory Override">
         <rule
            id="XVM.2.8.5"
            description-append="See @html@&#60;a href=&#34;https://www.accellera.org/downloads/standards/uvm&#34;&#62;UVM documentation&#60;/a&#62;@html@."
         />
      </category>
   </ruleset>

.. code-block:: xml
   :caption: Example 6 - Ruleset with effort levels

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
      <configuration>
         <effort-levels>
            <effort level="default" time="10s" />
            <effort level="low" time="1m 30s" />
            <effort level="high" time="1h 10m 10s" />
         </effort-levels>
      </configuration>
      <category name="XVM Factory Override">
         <rule
           id="XVM.2.8.5"
           title="Set type overrides only in the build phase method"
           effort-level="low"
         />
         <rule
            id="XVM.5.2.1.1"
            title="Factory override methods must use compatible override types"
            effort-level="high"
         />
         <rule
            id="XVM.5.2.1.2"
            title="Factory overrides must be called before any create call"
         />
      </category>
   </ruleset>

.. code-block:: xml
   :caption: Example 7 - Ruleset with timeout for session and checks

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
      <configuration>
         <timeout
            check="10"
            session="50"
         />
      </configuration>
      <category name="Dead Code">
         <rule
            id="SVTB.31.1.0"
            title="Unused element"
            timeout="15"
            >
               <property
                  key="analyzeTypeParameterAccess"
                  value="true"
                  />
               <property
                  key="skipPublicAPI"
                  value="true"
                  />
               <property
                  key="skipPublicFunctionArguments"
                  value="true"
                  />
               <property
                  key="skipProtectedAPI"
                  value="true"
                  />
         </rule>
         <rule
            id="SVTB.31.2.0"
            title="Unused macro"
            />
      </category>
   </ruleset>

.. warning::

    Pre-waiver support from ruleset file is deprecated and will be removed in a future release.

.. code-block:: xml
   :caption: Example 8 - Ruleset with pre-waivers specified

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
      <category name="XVM Factory Override">
         <rule 
            id="XVM.5.2.1.2"
            name="UVM.5.2.1.2 on everything from folder1 except for the sub2 folder"
            >
               <pre-waiver
                  include-path=".*/folder1/.*" 
                  exclude-path=".*/folder1/sub2/.*"
                  />
         </rule>
         <rule 
            id="XVM.5.2.1.2"
            name="UVM.5.2.1.2 on everything except for sub1 and sub3 folders"
            >
               <pre-waiver
                  exclude-path=".*/sub1/.*, .*/sub3/.*"
                  />
         </rule>
         <rule 
            id="XVM.5.2.1.2" 
            name="UVM.5.2.1.2 only on sub1 and sub3 folders"
            >
               <pre-waiver
                  include-path=".*/sub1/.*, .*/sub3/.*"
                  />
         </rule>
      </category>
   </ruleset>
   
.. code-block:: xml
   :caption: Example 9 - Ruleset with included rules

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
     <include since="2022-01-01" />
     <include labels="PERFORMANCE, DESIGN" />
   </ruleset>

.. code-block:: xml
   :caption: Example 10 - Ruleset with overriden configuration
   
   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <ruleset version="2">
     <include file="path_to_ruleset_file" />
     <override-configuration>
         <timeout
            check="10"
            session="50"
         />
      </override-configuration>
   </ruleset>

.. note::

	If the "override-configuration" element is used, any other "configuration" element will be completely ignored. This can be useful if you
	want to include the categories of other rulesets without including their respective configurations.
