Videos

  Overview Video [1:25]

V4P Cheat-Sheet

Toggle all chapters


V4P supports a separate set of preferences for each root-/workspace-folder. The configuration file can either be INI-based (recommended) or JSON-based. The file must be named config.v4p or .config.v4p and be located
  • directly in your root-/workspace-folders (this one has priority)
  • in the .vscode subdirectory of any root-/workspace folder

Per Root-Folder configs are useful as you sometimes will have projects that combine various sub-projects with possibly different coding styles, library assignments and settings.

INI-based config files
JSON-based config files


In order to better handle various global settings, V4P also support an optional Master Config. This is an ordinary config file which can be located in any of the following locations, and must be named config.v4p or .config.v4p:
  • At the location specified by the environment variable V4P_MASTER_CONFIG
  • In your Home folder (/home/<user> or C:\Users\<user>)
  • In the folder pointed to by environment variable HOME
If present, a Master Config can define default library mappings for common folders (eg, simulation libraries like OSVVM), exclude patterns, and common settings. A local config file, if present, always has precedence if there are any conflicting settings.



You can find a detailed description of  »Glob-Patterns on Wikipedia. However, I am supporting the list enhancement (curly braces, see examples).

Remarks

  • As the MasterConfig is not part of any specific project/workspace/root-folder, the glob-patterns therein should be 'absolute' (i.e., start with **/)
  • Root-folder specific Glob-patterns are always relative to that specific root-folder
  • Glob-Patterns are case-sensitive (also in Windows)
The following table shows a couple of glob-patterns with exemplary matches and mismatches for the given patterns. Notice that in these example we assume that the patterns are defined in a config.v4p of some root-folder <r>
Glob Matches Mismatch
*/src/?.vhd <r>/a/src/b.vhd<r>/abc/src/1.vhd <r>/a/src/.vhd <r>/a/src/file.vhd <r>/a/b/src/a.vhd
**/src or
**/src/*.*
<r>/src/a.vhd <r>/a/b/src/abc.vhd <r>/src/a/a.vhd
**/src/** <r>/a/b/src/c/d <r>/src/a.vhd <r>/src/d/e.vhd <r>/dst/a.vhd
*.vhd? <r>/file.vhdl <r>/file.vhdA <r>/file.vhd <r>/file.VHDL
*.{vhd,vhdl} <r>/file.vhdl <r>/file.vhd <r>/file.VHDL
file[A-G].vhd <r>/fileA.vhd <r>/fileD.vhd <r>/fileH.vhd <r>/filea.vhd <r>/file.vhd
file{[A-G],[1-3]}.vhd <r>/fileA.vhd <r>/file2.vhd <r>/fileH.vhd <r>/fileA1.vhd
a/{b,[cd],e/*/f}/*.vhd <r>/a/b/c.vhd <r>/a/d/c.vhd <r>/a/e/e1/f/c.vhd <r>/a/cd/c.vhd <r>/a/e/f/c.vhd



Assign libraries to design files: You can specify a comma-separated list of libraries for each design file or sets of files. Files are specified as  »Glob-Pattern as shown in the example above. The Glob-patterns are case sensitive (also in Windows).

Usually there is only one library per file, but multiple libraries might be useful for files that are shared by various projects and therefore belong to potentially different libraries.

The libraries section does not add files to the project! It rather defines library assignments for existing files. Use symlinks to add external files (or add the entire folders to the workspace).

Example:



Exclude design files from parsing: In addition to Visual Studio Code's exclude list, you can provide a separate list of excludes for each root-folder. The files are specified as  »Glob-Pattern and will not be parsed or analyzed by V4P if they are assigned with true. The Glob-patterns are case sensitive (also in Windows).

Example:



Define specific preferences for the corresponding root-folder.

Undefined settings are assumed as @inherit. It is therefore not necessary to explicitly declare entries as inherited.

There are two special assignments that can always be used:
  • @default: Uses the value from V4P's default settings. The list below shows the default value for each setting.
  • @inherit: Uses the value from the Master Config (if present), otherwise V4P's default.
V4p.Settings.Basics.TopLevelEntities
V4p.Settings.Basics.LogSeverity
V4p.Settings.Basics.LicenseFile
V4p.Settings.Formatting.StandardLibraryStyle
V4p.Settings.Formatting.KeywordStyle
V4p.Settings.Formatting.EndIdentifiers
V4p.Settings.Formatting.AlignSequentialAssignments
V4p.Settings.Formatting.Newlines.[ProtectedKeyword|RecordKeyword|UnitsKeyword]
V4p.Settings.Formatting.Newlines.WhenChoices
V4p.Settings.Formatting.Indentation.UseTabs
V4p.Settings.Formatting.Indentation.TabWidth
V4p.Settings.Formatting.Indentation.<*>
V4p.Settings.Completion.ShowKeywords
V4p.Settings.Completion.ShowUncommon
V4p.Settings.Completion.ShowEnums
V4p.Settings.Completion.ShowVendorSymbols
V4p.Settings.Completion.ShowVendorSnippets
V4p.Settings.HoverInfo.ShowLibraries
V4p.Settings.HoverInfo.ShowLocation
V4p.Settings.HoverInfo.ResolveStdTypes
V4p.Settings.HoverInfo.ResolveTypes
V4p.Settings.HoverInfo.ShowAllOverloads
V4p.Settings.ParameterHelp.Instances
V4p.Settings.StutterMode.Enabled
V4p.Settings.StutterMode.HorizontalLineWidth
V4p.Settings.ErrorChecker.MissingAssociations.IgnoreInstanceOutputs
V4p.Settings.ErrorChecker.MissingAssociations.IgnoreInstanceInputsWithDefaultValues
V4p.Settings.ErrorChecker.SymbolUnused.IgnoreLoopVariables
V4p.Settings.ErrorChecker.SymbolUnused.AttributesReadValue

Example:



The [ignores] section is an alternative to Meta Comments, e.g. if your company forbids tool specific comments as part of your source code. In this section you can define warning messages for specific symbols which shall be ignored by the error checker. The syntax is as follows:

glob-pattern-file @ glob-pattern-symbol = "msg1,msg2"

glob-pattern-file defines a (case sensitive) GLOB pattern to match any source file(s).

glob-pattern-symbol defines a (case insensitive) GLOB pattern to match any symbol within the set of source files. You can use unqualified, partially qualified or fully qualified symbol names with wildcards.

"msg1,msg2" is a comma-separated list of error/warning names or error-warning codes (see table below) which are to be ignored for the matched symbols.

To improve readability, the parts left and right of the equality sign = can be put inside double quotes. A detailed description of the supported errors/warnings can be found in Meta Comments.

Code Name
w-301 missing-association
w-302 never-written
w-303 never-read
e-202 not-found
Example:




V4P comes with a pre-installed, 30-day trial license (full feature set, no restrictions, commercial use). After the trial period, you have to purchase a license on my website. The file must be named license.v4p or .license.v4p, and must be located in any of the following locations:
  • At the location specified by the environment variable V4P_LICENSE_FILE
  • In your Home folder (/home/<user> or C:\Users\<user>)
  • In the folder pointed to by environment variable HOME
  • In any of your Root Folders
  • In any of your config.v4p files (even in the Master Config), point to the location of the license file: V4p.Settings.Basics.LicenseFile=<path>


Feature Description Default Shortcut
Renaming Allows semantically correct renaming of signals, variables, functions, entities, etc. F2
Code Formatting (full) Formats the entire source file according to the V4p.Settings.Formatting settings. Shift+Alt+F
Find All References Finds all references of a given identifier in the entire project. The results are shown in a separate side panel view. Shift+Alt+F12
Find All Sources Finds all sources/drivers of the signal/variable below the cursor. Right-click Menu
Go To References Finds all references of a given identifier in the entire project. Shift+F12
Syntax Highlighting Code highlighting according to VHDL 2008 syntax: Keywords, symbols, strings, identifiers, etc.
Semantic Highlighting Code highlighting according to semantic analysis: Types, signals, ports, constants, etc. editor.semanticHighlighting.enabled must be enabled in Visual Studio Code.
Type-time Syntax Checking On-the-fly syntax checking and highlighting. Output in Visual Studio Code's Problems Panel.
Type-time Semantic Checking Performs error/warning checks during design entry. Supported checks:
  • Symbol not defined
  • Signal vs. Variable assignment operator
  • Symbol already defined
  • End-Label does not match
  • Missing association in instances
  • Symbol cannot be target of assignment
  • Symbol is never written
  • Symbol is never read
You can enable/disable warnings per file or per symbol using MetaComments. See the MetaComments section for details.

You can configure V4P's error-checking behavior in various ways. See V4p.Settings.ErrorChecker in the Configuration Files section.

Stutter Mode If enabled (V4p.Settings.StutterMode.Enabled), stutter mode as known from EMACS can be used. editor.formatOnType must be enabled in Visual Studio Code. The following shortcuts are supported:
  • '' (two single quotes) → " (double quote)
  • ;; : 
  • ;;; := 
  • .. => 
  • ,, <= 
  • [(
  • [[[
  • ])
  • ]]]
  • -------------- (horizontal line according to V4p.Settings.StutterMode.HorizontalLineWidth
Parameter Help Brings up a tooltip with parameter help for (possibly overloaded) functions/procedures/components/instances. Highlights the current parameter and provides type information. Ctrl+Shift+Space
Smart Indentation Automatically sets the indent of new code lines according to formatting rules. See also Section Preferences.
Code Completion/Autocomplete Context sensitive code completion (for defined signals, types, entites, etc.), according to code completion rules. See also Section Preferences. Ctrl+Space
Block Selection Keyboard Very handy block/column-selection mode of Visual Studio Code. Ctrl+Alt+Shift+Cursors
Block Selection Mouse Use the middle mouse button for block-selection mode with the mouse. Middle Mouse Button
Increase Indent Increases the indent of the currently selected code lines. Tab
Decrease Indent Decreases the indent of the currently selected code lines. Shift+Tab
Hover Info / Quickinfo Show Hover Info for symbol at cursor. Usually you just hover the mouse over an item. Ctrl+K+Ctrl+I
Expression Evaluator For constants and generics, V4P displays the actual value of the symbol as part of the hover info, whereever possible. Ctrl+K+Ctrl+I
Number Conversion Converts numbers to different bases. Just hover the mouse over a number. Ctrl+K+Ctrl+I
Comment Lines Comments the current/selected lines (line commenting). Ctrl+K+Ctrl+C
Uncomment Lines Uncomments the current/selected lines (line commenting). Ctrl+K+Ctrl+U
Toggle Line Comment Toggle line comment for the current/selected lines. Ctrl+/
Toggle Block Comment Toggle block comment for the current selected. Shift+Alt+A
Copy Line Down Copys the current line / current selection and inserts it below Shift+Alt+Down
Copy Line Up Copys the current line / current selection and inserts it above Shift+Alt+Up
Code Snippets Snippets are part of code completion. All snippets start with a short prefix, followed by '-'. For some snippets, an identifier after the minus further defines the snippet (eg, for instances). Snippets respect your formatting settings, see also Section Preferences. editor.suggest.showSnippets must be enabled in Visual Studio Code. The following snippets are defined:
  • if-: if cond then ... end if;
  • ife-: if cond then ... else ... end if;
  • sl-: std_logic
  • slv-: std_logic_vector
  • slvr-: std_logic_vector( range )
  • sul-: std_ulogic
  • sulv-: std_ulogic_vector
  • sulvr-: std_ulogic_vector( range )
  • o-: (others => '0')
  • oo-: (others => '...')
  • s-: signed
  • sr-: signed( range )
  • ts-: to_signed(...)
  • u-: unsigned
  • ur-: unsigned( range )
  • tu-: to_unsigned(...)
  • arch-: Architecture template
  • entarch-: Entity with architecture template
  • ent-: Entity template
  • comp-: Component template
  • const-: Template for a constant definition
  • func-: Function template
  • proc-: Procedure template
  • sig-: Signal declaration template
  • var-: Variable declaration template
  • sha-: Shared Variable declaration template
  • rec-: Record type declaration template
  • prot-: Protected type declaration template
  • protbdy-: Protected type body definition template
  • pkg-: Package head declaration template
  • pkgfull-: Package head and body template
  • p-: Process template
  • genif-: Generate IF template
  • genfor-: Generate FOR template
  • gencase-: Generate CASE template
Specific Snippets
  • i-name: Create an instance of the given entity/component. The instance is created with all generic maps and port maps according to the module's definition.
  • cs-name: Create a case statement for the given signal/variable (of enumeration type). The case statement is created with all enumeration values.
*-
Code Snippets (Forward) When in snippet insertion mode, use this shortcut to move to the next field (and probably show the suggestions list). Tab
Code Snippets (Backward) When in snippet insertion mode, use this shortcut to move to the previous field (and commit the current value for previous, and probably show the suggestions list). Shift+Tab
Code Snippets (Leave) When in snippet insertion mode, use this shortcut to leave snippet mode. Shift+Escape
Code Snippets (Leave) When in snippet insertion mode, use this shortcut to leave snippet mode. Escape
Code Actions Context sensitive code actions are available. They are indicated with a light bulp icon and can also be activated with a shortcut. The following features are supported:
  • Insert missing instance associations
  • Insert missing instance associations and also create local signals for the newly created associations
  • Create signal declarations for unknown instance associations
Ctrl+.



Feature Description Default Shortcut
Find All References Finds all references of a given identifier in the entire project, shows the results in 'References' Activity Bar. Shift+Alt+F12
Find All Sources Finds all sources/drivers of the signal/variable below the cursor. The results are shown in a separate side panel view. Right-click Menu
Go To References Finds all references of a given identifier in the entire project, shows the results in an inline window with code preview. Shift+F12
Navigate Forward Move forward to an already visited location. Alt+Right
Navigate Backward Move backward to a previously visited location. Alt+Left
Code Folding Collapse certain code blocks for better overview and navigation efficiency (processes, function, entities, classes, methods, records, instances, ...). editor.folding must be enabled in Visual Studio Code.
Goto Definition Jumps to the definition of the current item (if different from its declaration, eg. package body or function implementation). F12
Goto Declaration Jumps to the declaration of the current item (if different from its definition, eg. package head or function declaration in package head).
Goto Type Definition Jumps to the type of the current item, eg. the type of the signal/variable/constant. For components, jumps to the respective entity declaration
Libraries View Located in the HDL Panel of the activiy bar. Shows hierarchical view of all libraries and packages / entities / symbols therein. Manual refresh
Design Hierarchy View Located in the HDL Panel of the activiy bar. Shows hierarchical view of the entire workspace. You can use V4p.Settings.Basics.TopLevelEntities to define one or multiple top-level entities. Manual refresh
Document Outline Provides a hierarchical outline for the current document, e.g. subroutines, instances, signals, processes, etc.



The activity bar provides access to several very useful features and information panels.

HDL Panel

  • Commands: Easy access to all commands. Notice that they are also accessible through the Command Palette ctrl+shift+p.
  • Library Hierarchy: Hierarchical view of all libraries with their respective packages, entities, architectures, etc.
  • Design Hierarchy: Hierarchical view of your entire design workspace. You can define multiple top-level entities
  • Search Results for 'Find all Sources'

Explorer Panel
  • Document Outline: Provides a concise hierarchical overview for the current document, such as entities, blocks, instances, signals, processes, subroutines, etc.


General Description
Meta-Comments can be used to (temporarily) disable warnings/errors. This is achieved by putting a meta comment inside your source code. See below for syntax and examples. Alternatively, you can use the [ignores] section in your config.v4p in case you don't want to add tool specific comment to your source code. See also [ignores]-Section (config.v4p)
  • Disable warnings for specific symbols or for the entire file
  • You can use the warning-code or the warning-name interchangeably
  • Meta-Comments for ignore are valid in the line they are declared only. It is a handy shortcut to disable warnings for specific symbols. Usually, this is the one you want
  • Meta-Comments for enable|disable are valid starting with the line they are defined in until the end of file (or until a new comment for the respective feature is found)
  • Meta-Comments are limited to the file they are declared in
  • Meta-Comments are generally evaluated at the location of declaration of a symbol only, if not stated otherwise
Syntax
Meta-Comments are only available for line comments (ie, starting with --) and have the following syntax:
-- v4p (enable|disable|ignore) warning-list [symbol-list]
  • The warning-list is a comma-separated list of warnings to enable/disable. You can either use the warnings code or name, as defined by the table below
  • The symbol-list is an optional comma-separated list of symbol names for which the rule shall be applied. If it is empty, all symbols are effected. It does not support wildcards
List of Errors/Warnings

Code Name Description
w-301 missing-association Warning that indicates that there are signals defined in an entity/component which do not have an association in the given instance.
w-302 never-written Warning that indicates that a symbol was declared but no value has ever been assigned to it.
w-303 never-read Warning that indicates that a symbol was declared but its value has never been written.
e-202 not-found Error that indicates that a symbol has not been declared. This meta-comment must be used at the location where the error occurs
Examples
  1: architecture rtl of ent is
  2:   -- v4p disable never-written,never-read s2,s3           /* also matches "s2" of "proc1()"                            */
  3:   signal s1, s2, s3: integer; 
  4:   signal s4, s5, s6: integer; -- v4p disable never-written/* disable for all syms starting here (including s4, s5, s6) */
  5:   signal s7, s8    : integer; -- v4p ignore w-302         /* ignore warning w-302 for symbols IN THIS LINE ONLY        */
  6:   procedure proc1(s2, s5: out integer) is 
  7:   begin 
  8:   end procedure;
  9:   -- v4p enable w-302,never-read                          /* reenable warnings for all syms starting here              */
 10:   component comp is
 11:     port (
 12:       clk, rst: in std_logic;
 13:       -- v4p disable missing-association dbg              /* generally disable for "dbg" of all instances of component */
 14:       d1, dbg: out std_logic   
 15:     );
 16:   end component;
 17: begin
 18:   -- v4p disable missing-association comp_inst            /* do not check entire instance comp_inst                    */
 19:   -- v4p disable missing-association comp_inst.d1         /* just do not check "d1" of this specific instance comp_inst*/
 20:   comp_inst: comp
 21:     port map (clk, rst);
 22:   -- v4p disable not-found unknown                        /* ignore the fact that "unknown" is not found in the scope  */
 23:   unknown_inst: unknown
 24:     port map (clk, rst);
 25: end architecture; 



Name Description
v4p.version Displays the current version and build date
v4p.license Displays information about all found licenses
v4p.license.renew Opens the website to renew your current license
v4p.license.mac Opens the website to update your MAC addresses
v4p.reload Reloads the workspace, especially reloads the config.v4p files. Does not reparse the .vhd files
v4p.logfile Opens the logfile in Visual Studio Code
v4p.thirdparty Displays licensing and copyright information about Third Party software used in V4P
v4p.settings Displays detailed information about V4P's configuration (libraries, excludes, settings, ignores)
v4p.masterconfig Opens (or creates) MasterConfig, by default in home-directory
v4p.version Displays the current version and build date
v4p.eula Show End User License Agreement
v4p.fileinfo Show detailed information about all files in the workspace, including code statistics
v4p.cheatsheet Opens the CheatSheet of V4P in the browser
v4p.stats Shows code statistics (lines of code, comments, empty lines) in a table for all files
v4p.demo Opens a demo project in Visual Studio Code



Shortcut Value Remarks
[ctrl]+[,]   editor.formatOnType Enable Required for VHDL/V4P specific (smart) indentation
[ctrl]+[,]   editor.folding Enable Required for VHDL/V4P specific code folding
[ctrl]+[,]   editor.foldingStrategy Auto Required for VHDL/V4P specific code folding
[ctrl]+[,]   editor.suggest.showSnippets Enable Required, enables VHDL/V4P specific snippets
[ctrl]+[,]   editor.semanticHighlighting.enabled True, ConfiguredByTheme Required, needed for semantic token highlighting. The color theme must support semantic highlighting!
[ctrl]+[,]   editor.showFoldingControls Always Optional, disallow the folding controls to disappear
[ctrl]+[,]   editor.minimap.enabled Enable Optional, shows the mini-map next to the scrollbar. Very useful.
[ctrl]+[,]   editor.minimap.showSlider Always Optional, disallow the minimap slider to disappear
[ctrl]+[,]   editor.minimap.size Fit Optional, fit the minimap to show the preview of the entire file
[ctrl]+[,]   editor.snippetSuggestions top, bottom or inline Optional, define the snippets' position inside the code-completion list
[ctrl]+[,]   editor.wordBasedSuggestions Disable Recommended, avoid code-completion suggestions from Visual Studio Code. Only show V4P's code-completion suggestions.