Configuring

VSG can use a configuration file to alter it’s behavior and/or include a list of files to analyze. This is accomplished by passing JSON and/or YAML file(s) through the –configuration command line argument. This is the basic form of a configuration file in JSON:

{
    "file_list":[
      "fifo.vhd",
      "$PATH_TO_FILE/spi_master.vhd",
      "$OTHER_PATH/src/*.vhd",
      "source/spi.vhd": {
        "rule": {
          "ruleId_ruleNumber":"blah"
      }
    ],
    "local_rules":"$DIRECTORY_PATH",
    "rule":{
        "global":{
            "attributeName":"AttributeValue"
        },
        "ruleId_ruleNumber":{
            "attributeName":"AttributeValue"
        }
    }
}

This is the basic form of a configuration file in YAML:

---
file_list:
  - fifo.vhd
  - source/spi.vhd:
      rule:
        ruleId_ruleNumber:
          attributeName: AttributeValue
  - $PATH_TO_FILE/spi_master.vhd
  - $OTHER_PATH/src/*.vhd
local_rules: $DIRECTORY_PATH
rule:
  global:
    attributeName: AttributeValue
  ruleId_ruleNumber:
    attributeName: AttributeValue
...

It is not required to have file_list, local_rules, and rule defined in the configuration file. Any combination can be defined, and the order does not matter.

Note

All examples of configurations in this documentation use JSON. However, YAML can be used instead.

file_list

The file_list is a list of files that will be analyzed. Environment variables will expanded. File globbing is also supported. The Environment variables will be expanded before globbing occurs. This option can be useful when running VSG over multiple files.

Rule configurations can be specified for each file by following the format of the rule configuration.

local_rules

Local rules can be defined on the command line or in a configuration file. If they are defined in both locations, the configuration will take precedence.

rule

Any attribute of any rule can be configured. Using global will set the attribute for every rule. Each rule is addressable by using it’s unique ruleId and ruleNumber combination. For example, whitespace_006 or port_010.

Note

If global and unique attributes are set at the same time, the unique attribute will take precedence.

Here are a list of attributes that can be altered for each rule:

Attribute	Values	Description
indentSize	Integer	Sets the number of spaces for each indent level.
phase	Integer	Sets the phase the rule will run in.
disable	Boolean	If set to True, the rule will not run.
fixable	Boolean	If set to False, the violation will not be fixed

Reporting Single Rule Configuration

The configuration for a single rule can be reported using the -rc option:

$ vsg -rc entity_001
{
  "rule": {
    "entity_001": {
      "indentSize": 2,
      "phase": 4,
      "disable": false,
      "fixable": true
    }
  }
}

VSG will print the configuration for the rule given in a JSON format. This configuration can be altered and added to a configuration file.

Reporting Configuration for All Rules

Every rule configuration can be report and saved to a file using the -oc option:

$ vsg -oc configuration.json

The output file will be in JSON format and can be modified and passed back to VSG using the -c option.

Rule Configuration Priorities

There are three ways to configure a rule. From least to highest priority are:

• [rule][global]
• [rule][<identifier>]
• [file_list][<filename>][rule][<identifier>].

If the same rule is defined in all three locations as in the example below, then the final setting will be equal to the highest priority.

{
  "file_list":[
    "entity.vhd":{
      "rule":{
        "length_001":{
          "disable": true
        }
      }
   },
   "architecture.vhd",
   "package.vhd"
  ],
  "rule":{
    "global":{
      "disable": true
    },
    "rule": {
      "length_001":{
        "disable": false
    }
  }
}

In this example configuration, all rules are disabled by the global configuration. Then rule length_001 is enabled for the files architecture.vhd, package.vhd and entity.vhd by the rule configuration. Then rule length_001 is disabled for the file entity.vhd.

Example: Disabling a rule

Below is an example of a JSON file which disables the rule entity_004

{
    "rule":{
        "entity_004":{
            "disable":true
        }
    }
}

Use the configuration with the –configuration command line argument:

$ vsg -f RAM.vhd --configuration entity_004_disable.json

Example: Setting the indent increment size for a single rule

The indent increment size is the number of spaces an indent level takes. It can be configured on an per rule basis…

{
    "rule":{
        "entity_004":{
            "indentSize":4
        }
    }
}

Example: Setting the indent increment size for all rules

Configure the indent size for all rules by setting the global attribute.

{
    "rule":{
        "global":{
            "indentSize":4
        }
    }
}

Configuring Uppercase and Lowercase Rules

There are several rules that enforce either uppercase or lowercase. The default for all such rules is lowercase. The decision was motivated by the fact, that the VHDL language is case insensitive. Having the same default for all case rules also results in less documentation and code to maintain. The default value for each of these case rules can be overridden using a configuration.

Overriding Default Lowercase Enforcement

The default lowercase setting can be changed using a configuration.

For example the rule constant_002 can be changed to enforce uppercase using the following configuration:

---

rule :
  constant_002 :
     case : 'upper'

Changing Multiple Case Rules

If there are a lot of case rules you want to change, you can use the global option to reduce the size of the configuration. For example, if you want to uppercase everything except the entity name, you could write the following configuration:

---

rule :
  global :
    case : 'upper'
  entity_008 :
    case : 'lower'

Configuring Prefix and Suffix Rules

There are several rules that enforce specific prefixes/suffixes in different name identifiers. It is noted, in the documentation, what are the default prefixes/suffixes for each such rule.

All prefix/suffix rules are disabled by default. The default prefixes/suffixes for each of these rules can be overridden using a configuration.

Overriding Default Prefixes/Suffixes Enforcement

The default setting can be changed using a configuration. For example, the rule port_025 defaults to following suffixes: [‘_I’, ‘_O’, ‘_IO’]. We can use the following configuration to change allowed suffixes:

---

 rule :
     port_025:
         # Each prefix/suffix rule needs to be enabled explicitly.
         disable: false
         suffixes: ['_i', '_o']

The rule variable_012 defaults to following prefix: [‘v_’]. We can use the following configuration to change allowed prefix:

---

 rule :
     variable_012:
         # Each prefix/suffix rule needs to be enabled explicitly.
         disable: false
         prefixes: ['var_']

Configuring Number of Signals in Signal Declaration

VHDL allows of any number of signals to be declared within a single signal declaration. While this may be allowed, in practice there are limits impossed by the designers. Limiting the number of signals declared improves the readability of VHDL code.

The default number of signals allowed, 2, can be set by configuring rule signal_015.

Overriding Number of Signals

The default setting can be changed using a configuration. We can use the following configuration to change the number of signals allowed to 1.

---

rule :
  signal_015 :
     consecutive : 1

Configuring the Maximum Line Length

Limiting the line length of the VHDL code can improve readability. Code that exceeds the editor window is more difficult to read.

The default line length is 120, and can be set by configuring rule length_001.

Overriding Line Length

The default setting can be changed using a configuration. We can use the following configuration to change the line length to 180.

---

rule :
  length_001 :
     length : 180

Configuring Keyword Alignment Rules

There are several rules that enforce alignment for a group of lines based on the keywords such as ‘after’, ‘<=’ etc. Some of the configurations are available in all keyword alignment rules, while others are rule specific.

Common Keyword Alignment Configuration

Following configuration options can be independently changed for each of the keyword alignment rules.

1. compact_alignment - if set to True it enforces single space before alignment keyword in the line with the longest part before the keyword. Otherwise the alignment occurs to the keyword maximum column. By default set to True.

   Violation

   signal sig_short   : std_logic;
   signal sig_very_long      : std_logic;
   

   Fix (compact_alignment = True)

   signal sig_short     : std_logic;
   signal sig_very_long : std_logic;
   

   Fix (compact_alignment = False)

   signal sig_short          : std_logic;
   signal sig_very_long      : std_logic;
   

2. blank_line_ends_group - if set to True any blank line encountered in the VHDL file ends the group of lines that should be aligned and starts new group. By default set to True.

   Violation

   signal wr_en : std_logic;
   signal rd_en   : std_logic;
   
   constant c_short_period : time;
   constant c_long_period : time;
   

   Fix (blank_line_ends_group = True)

   signal wr_en   : std_logic;
   signal rd_en   : std_logic;
   
   constant c_short_period : time;
   constant c_long_period  : time;
   

   Fix (blank_line_ends_group = False)

   signal wr_en            : std_logic;
   signal rd_en            : std_logic;
   
   constant c_short_period : time;
   constant c_long_period  : time;
   

3. comment_line_ends_group - if set to True any purely comment line in the VHDL file ends the group of lines that should be aligned and starts new group. By default set to True.

   Violation

   port (
       sclk_i : in std_logic;
       pclk_i : in std_logic;
       rst_i : in std_logic;
       ---- serial interface ----
       spi_ssel_o : out std_logic;
       spi_sck_o : out std_logic;
       spi_mosi_o : out std_logic;
       spi_miso_i : in std_logic
   );
   

   Fix (comment_line_ends_group = True)

   port (
       sclk_i : in std_logic;
       pclk_i : in std_logic;
       rst_i  : in std_logic;
       ---- serial interface ----
       spi_ssel_o : out std_logic;
       spi_sck_o  : out std_logic;
       spi_mosi_o : out std_logic;
       spi_miso_i : in std_logic
   );
   

   Fix (comment_line_ends_group = False)

   port (
       sclk_i     : in std_logic;
       pclk_i     : in std_logic;
       rst_i      : in std_logic;
       ---- serial interface ----
       spi_ssel_o : out std_logic;
       spi_sck_o  : out std_logic;
       spi_mosi_o : out std_logic;
       spi_miso_i : in std_logic
   );
   

Note

As all keyword alignment rules have above configurations they are not mentioned in the documentation for each rule.

Rule Specific Keyword Alignment Configuration

1. separate_generic_port_alignment - if set to True alignment within the generic declarative/mapping part is separated from alignment within the port declarative/mapping part. By default set to True.

   Violation

   generic (
       g_width : positive;
       g_output_delay : positive
   );
   port (
       clk_i : in std_logic;
       data_i : in std_logic;
       data_o : in std_logic
   );
   

   Fix (separate_generic_port_alignment = True)

   generic (
       g_width        : positive;
       g_output_delay : positive
   );
   port (
       clk_i  : in std_logic;
       data_i : in std_logic;
       data_o : in std_logic
   );
   

   Fix (separate_generic_port_alignment = False)

   generic (
       g_width        : positive;
       g_output_delay : positive
   );
   port (
       clk_i          : in std_logic;
       data_i         : in std_logic;
       data_o         : in std_logic
   );
   

2. if_control_statements_end_group - if set to True any line with if control statement ends the group of lines that should be aligned and starts new group. By default set to True.

   Violation

   if condition = '1' then
       data_valid <= '1';
       data <= '1';
   else
       data_valid <= '0';
       hold_transmission <= '1';
   end if;
   

   Fix (if_control_statements_end_group = True)

   if condition = '1' then
       data_valid <= '1';
       data       <= '1';
   else
       data_valid        <= '0';
       hold_transmission <= '1';
   end if;
   

   Fix (if_control_statements_end_group = False)

   if condition = '1' then
       data_valid        <= '1';
       data              <= '1';
   else
       data_valid        <= '0';
       hold_transmission <= '1';
   end if;
   

3. case_control_statements_end_group - if set to True any line with case control statement ends the group of lines that should be aligned and starts new group. By default set to True.

   Violation

   case A is
       when A =>
           X <= F;
           XY <= G;
           XYZ <= H;
       when B =>
           a <= I;
           ab <= h;
           c <= a;
       when others =>
         null;
   end case
   

   Fix (case_control_statements_end_group = True)

   case A is
       when A =>
           X   <= F;
           XY  <= G;
           XYZ <= H;
       when B =>
           a  <= I;
           ab <= h;
           c  <= a;
       when others =>
           null;
   end case
   

   Fix (case_control_statements_end_group = False)

   case A is
       when A =>
           X   <= F;
           XY  <= G;
           XYZ <= H;
       when B =>
           a   <= I;
           ab  <= h;
           c   <= a;
       when others =>
           null;
   end case
   

Note

If given keyword alignment rule has any of the above keyword alignment specific configuration, then it is explicitly noted in the documentation of this rule.

The default value for each of these case rules can be overridden using a configuration.

Multiple configurations

More than one configuration can be passed using the –configuration option. This can be useful in two situations:

1. Block level configurations
2. Multilevel rule configurations

The priority of the configurations is from right to left. The last configuration has the highest priority. This is true for all configuration parameters except file_list.

Block level configurations

Many code bases are large enough to be broken into multiple sub blocks. A single configuration can be created and maintained for each subblock. This allows each subblock to be analyzed independently.

When the entire code base needs be analyzed, all the subblock configurations can be passed to VSG. This reduces the amount of external scripting required.

config_1.json

{
    "file_list":[
      "fifo.vhd",
      "source/spi.vhd",
      "$PATH_TO_FILE/spi_master.vhd",
      "$OTHER_PATH/src/*.vhd"
    ]
}

config_2.json

{
    "file_list":[
      "dual_port_fifo.vhd",
      "flash_interface.vhd",
      "$PATH_TO_FILE/ddr.vhd"
    ]
}

Both configuration files can be processed by vsg with the following command:

$ vsg --configuration config_1.json config_2.json

Multilevel rule configurations

Some code bases may require rule adjustments that apply to all the files along with rule adjustments against individual files. Use multiple configurations to accomplish this. One configuration can handle code base wide adjustments. A second configuration can target individual files. VSG will combine any number of configurations to provide a unique set of rules for any file.

config_1.json

{
    "rule":{
        "entity_004":{
            "disable":true
        },
        "entity_005":{
            "disable":true
        },
        "global":{
            "indentSize":2
        }
    }
}

config_2.json

{
    "rule":{
        "entity_004":{
            "disable":false,
            "indentSize":4
        }
    }
}

Both configuration files can be processed by VSG with the following command:

$ vsg --configuration config_1.json config_2.json -f fifo.vhd

VSG will combine the two configurations into this equivalent configuration…

{
    "rule":{
        "entity_004":{
            "disable":false,
            "indentSize":4
        },
        "entity_005":{
            "disable":true
        },
        "global":{
            "indentSize":2
        }
    }
}

…and run on the file fifo.vhd.