VHDLbyHGB

VHDLbyHGB is a Visual Studio Code extension for editing VHDL-Projects.

This Extension is maintained by Jakob Jungreuthmayer, Sonja Schoissengaier and Florian Lucut at University of Applied Sciences Upper Austria - Campus Hagenberg.

Technology

This extension is based on the VHDL-LS Language Server. Pre-compiled binaries for Linux, Windows and MacOS are provided with the extension.

The server can also be loaded from either the system path or Docker depending on the value of the vhdl-by-hgb.vhdlls.languageServer property.

embedded: Use the embedded binary.
user: Use path provided by user in vhdl-by-hgb.vhdlls.languageServerUserPath property.
systemPath: Run vhdl_ls from path.
docker: Use docker image (Only supports files below workspace root)

Usage

The language server needs to know the library mapping of the VHDL files in the project, for this purpose it reads a configuration file in the TOML format named vhdl_ls.toml. The file contains the library mapping of all files within the project and should be located in the workspace root. Files outside of the project without library mapping are checked for syntax errors only.

vhdl_ls will load configuration files in the following order of priority (first to last):

A file named .vhdl_ls.toml in the user home folder.
A file name from the VHDL_LS_CONFIG environment variable.
A file named vhdl_ls.toml in the workspace root.

Settings in later files redefines those from previously loaded files.

Example vhdl_ls.toml

# What standard to use. This is optional and defaults to VHDL2008.
standard = "2008"

# File names are either absolute or relative to the parent folder of the vhdl_ls.toml file
[libraries]

lib2.files = [
  'pkg2.vhd',
]

lib1.files = [
  'pkg1.vhd',
  'tb_ent.vhd'
]

# Wildcards are supported
lib3.files = [
  'test/*.vhd',
  'src/*.vhd',
  'src/*/*.vhd',
]

# Libraries can be marked as third-party to disable some analysis warnings, such as unused declarations
UNISIM.files = [
  'C:\Xilinx\Vivado\2023.1\data\vhdl\src\unisims\unisim_VCOMP.vhd',
]
UNISIM.is_third_party = true

[lint]
unused = 'error' # Upgrade the 'unused' diagnostic to the 'error' severity
unnecessary_work_library = false # Disable linting for the 'library work;' statement

Non-project files

By default, files that are not part of the project are added and analyzed as part of an anonymous library. You can disable this behaviour in the extension-settings by changing the vhdl-by-hgb.vhdlls.nonProjectFiles setting from analyze to ignore. Note that changing this setting requires a restart of the langauge server to become effective.

VHDL-Standard

Define the VHDL revision to use for parsing and analysis with the standard key. The expected value is the year associated the VHDL standard. Supported standards are 1993, 2008 and 2019 where both the long version ("2008") and the short version ("08") can be used. If nothing is specified, 2008 is used.

Lint-Settings

Using the lint table, you can configure the severity of diagnostics or turn of diagnostics altogether.

[!WARNING] You can overwrite every diagnostic error code including syntax or analysis errors using the lint table. However, the intended use-case is for lints only. Overwriting syntax or analysis errors (e.g., error codes unused or syntax) can cause unwanted side effects

Paths

Paths in the vhdl_ls.toml can contain glob patterns (i.e., ../*/). On Unix machines, they can contain environment variables using the $NAME or ${NAME} syntax. On Windows machines, use the %NAME% syntax to substitute environment variables.

Project-Setup

Open your whole VHDL-project as folder in VS-Code
The vhdl_ls.toml will be placed in the root of the project

The language server only starts automatically, if a folder contains a vhdl_ls.toml in its root-directory. Therefore, you have to initialise every project as a VHDL-Project once. This avoids starting the language-server accidentally on projects and getting unwanted error-messages.
By invoking the command VHDLbyHGB.Project.Setup, the opened folder is set up as a VHDL-Project. By default, a vhdl_ls.toml will be generated automatically for you containing the vhdl-files in all subfolders.

The extension offers the following options for generating the vhdl_ls.toml via the property vhdl-by-hgb.vhdlls.toml.generation:

auto

vhdl_ls.toml is generated automatically:

By invoking the command VHDLbyHGB.Verification.SetActiveProject, a verification-project in your vhdl-project can be configured.

Supported Tools:
- VUnit
- HDLRegression
As a consequence of setting an active verification-project, the vhdl_ls.toml will be generated automatically from the source-information from these projects.

manual

vhdl_ls.toml must be generated manually by user e.g. via a custom python-script

LSP-Features

Live syntax and type checking
Finds missing, duplicate and unused declarations
Goto-definition/declaration (also in presence of overloading)
Find-all-references (also in presence of overloading)
Goto-implementation
From component declaration to matching entity by default binding
From entity to matching component declaration by default binding
Hovering symbols reveals more information
Renaming symbols
Finding workspace symbols
Viewing/finding document symbols
Code-Completion:
- Entity

Formatting

Using Command Palette

macOS: CMD + SHIFT + P
Windows: CTRL + SHIFT + P

And type Format Document

Keyboard Shortcuts

macOS: SHIFT + OPTION + F
Windows: SHIFT + ALT + F

If you don't like the default shortcuts, you can rebind editor.action.formatDocument in the keyboard shortcuts menu of VSCode.

Supported Formatters

The property vhdl-by-hgb.formatter lets you choose between one of the following formatters:

vhdl_formatter VHDLFormatter by g2384

The following configuration-options are available:

Key	Default	Values
`vhdl-by-hgb.formatter.insertFinalNewline`	`false`	`true/false`
`vhdl-by-hgb.formatter.replaceByAliases`	`false`	`true/false`
`vhdl-by-hgb.formatter.indentation`	`tabSize`	`String`

`vhdl-by-hgb.formatter.align.mode`	`Local`	`Local/Global`
`vhdl-by-hgb.formatter.align.all`	`false`	`true/false`
`vhdl-by-hgb.formatter.align.port`	`false`	`true/false`
`vhdl-by-hgb.formatter.align.function`	`false`	`true/false`
`vhdl-by-hgb.formatter.align.procedure`	`false`	`true/false`
`vhdl-by-hgb.formatter.align.generic`	`false`	`true/false`
`vhdl-by-hgb.formatter.align.comments`	`false`	`true/false`

`vhdl-by-hgb.formatter.case.keyword`	`UpperCase`	`UpperCase/LowerCase`
`vhdl-by-hgb.formatter.case.typename`	`UpperCase`	`UpperCase/LowerCase`

`vhdl-by-hgb.formatter.newline.port`	`None`	`NewLine/NoNewLine/None`
`vhdl-by-hgb.formatter.newline.then`	`NewLine`	`NewLine/NoNewLine/None`
`vhdl-by-hgb.formatter.newline.semicolon`	`NewLine`	`NewLine/NoNewLine/None`
`vhdl-by-hgb.formatter.newline.else`	`NewLine`	`NewLine/NoNewLine/None`
`vhdl-by-hgb.formatter.newline.generic`	`None`	`NewLine/NoNewLine/None`

`vhdl-by-hgb.formatter.remove.comments`	`false`	`true/false`
`vhdl-by-hgb.formatter.remove.blankLines`	`false`	`true/false`
`vhdl-by-hgb.formatter.remove.reports`	`false`	`true/false`

emacs_vhdl_formatter Emacs-VHDL-Mode-Formatter

emacs is called in batch mode, gets the content of the VHDL file over stdin and returns the formatted code over stdout.

The vhdl-by-hgb.emacs-vhdl-formatter.customEval option allows you to extend the evaluated elisp code. This feature allows you to customize the VHDL style before you format the code. In most cases you want to adjust the vhdl-offsets-alist which defines the indentation for various components. Per default this list contains

((string . -1000)                                -- inside multi-line string
 (block-open . 0)                                -- statement block open
 (block-close . 0)                               -- statement block close
 (statement . 0)                                 -- a VHDL statement
 (statement-cont . vhdl-lineup-statement-cont)   -- a continuation of a VHDL statement
 (statement-block-intro . +)                     -- the first line in a new statement block
 (statement-case-intro . +)                      -- the first line in a case alternative block
 (case-alternative . +)                          -- a case statement alternative clause
 (comment . vhdl-lineup-comment)                 -- a line containing only a comment
 (arglist-intro . +)                             -- the first line in an argument list
 (arglist-cont . 0)                              -- subsequent argument list lines when no
                                                    arguments follow on the same line as
                                                    the arglist opening paren
 (arglist-cont-nonempty . vhdl-lineup-arglist)   -- subsequent argument list lines when at
                                                    least one argument follows on the same
                                                    line as the arglist opening paren
 (arglist-close . vhdl-lineup-arglist)           -- the solo close paren of an argument list
 (entity . 0)                                    -- inside an entity declaration
 (configuration . 0)                             -- inside a configuration declaration
 (package . 0)                                   -- inside a package declaration
 (architecture . 0)                              -- inside an architecture body
 (package-body . 0)                              -- inside a package body
 (context . 0))                                  -- inside a context declaration

Use vhdl-set-offset function to change values in vhdl-offsets-alist. For example to remove the indentation on closing brackets set vhdl-by-hgb.emacs-vhdl-formatter.customEval to

(vhdl-set-offset 'arglist-close 0)

Dynamic Snippets

Dynamic Snippets are Auto-Completion-Items for entity-instantiations using information from the Language Server. For now, Dynamic Snippets have to be updated manually.

This can be done by:

executing the command: VHDLbyHGB.dynamicSnippets
pressing the shortcut: Ctrl+Alt+S(default) / shift+cmd+s(Mac)

The generated snippets can be used by typing entity.

The Snippet format is entity {entity-name} - instantiation.

(Note: This feature was developed before VHDL-LS supported entity-completion. From now on, it serves as an alternative.)

Entity-Converter

The Entity-Converter copies the entity and pastes it in different formats.

The features of the Entity-Converter can be used by:

Context-Menu (Right-Click in code-segment of VHDL-Entity)
Commands (see below)

VHDLbyHGB.copyEntity

Set cursor within the entity declaration.
Run the command. It copies the entity declaration

VHDLbyHGB.pasteAsComponent

Pastes the entity as a component declaration

VHDLbyHGB.pasteAsInstance

Pastes the entity as a instant

VHDLbyHGB.pasteAsEntity

Pastes the entity as a entity

VHDLbyHGB.pasteSignals

Pastes the ports (in, out, inout, buffer) as signals

VHDLbyHGB.pasteConstants

Pastes the generic definitions as constants

Synthesis

The extension allows you to do basic operations on synthesis-projects. Currently, only Quartus is supported but the code is open to implement support for other synthesis-tools.

The synthesis-operations are done with the comands below:

VHDLbyHGB.Synthesis.AddNewProject Create a new synthesis-project

VHDLbyHGB.Synthesis.SetActiveProject Set an already existing synthesis-project as active

VHDLbyHGB.Synthesis.SetTopLevel Set TopLevel for a synthesis-project

VHDLbyHGB.Synthesis.UpdateFiles Update files for a synthes-project based on the configured Top-Level (requiring already having a Top-Level configured)

VHDLbyHGB.Synthesis.Compile Compile synthesis-project

VHDLbyHGB.Synthesis.LaunchGUI launch gui of synthesis-project

VHDLbyHGB.Synthesis.SetDevice set device for synthesis-project (e.g. 5CSEMA5F31C6)

VHDLbyHGB.Synthesis.SetFamily set family for synthesis-project (e.g. Cyclone V)

To execute a command on a synthesis-project, it is required to set an active synthesis-project. All the other commands will be executed on the selected project.

When the extension is loaded, the opened folder is searched recursively for synthesis-projects of supported synthesis-tools.

Verification

VHDLbyHGB uses verification-projects to get project-information.

Supported Tools:

VUnit
HDLRegression

VSCode-TestExplorer

The actual verification is handled in our Verification-Extensions. These extensions will offer you to perform actions directly from within the VSCode-TestExplorer, including:

listing all testcases
running testcases
launching GUI
...

VHDL Snippets

General Snippets

Besides the Snippets from the Language Server, here a some more usable snippets:

Conversionsfunctions Snippets

Snippet	Description
to_int	conversion from numeric to integer
logic_to_stdlv	conversion from logic arithmetic to std_logic_vector
to_stdlv	conversion to std_logic_vector
to_stdulv	conversion to std_ulogic_vector
int_to_sign	conversion from int to signed
int_to_stdlv	conversion from signed numeric to std_logic_vector
int_to_unsign_stdlv	conversion unsigned numeric to std_logic_vector
int_to_unsign	conversion from int to unsigned
stdlv_to_int	conversion from std_logic_vector signed to int
stdlv_unsign_to_int	conversion from std_logic_vector unsigned to int
stdlv_to_sign	conversion from std_logic_vector to signed
stdlv_to_unsign	conversion from std_logic_vector to unsigned
sign_to_int	conversion from signed to integer
sign_to_unsign	conversion from signed to unsigned
unsign_to_sign	conversion from unsigned to signed
bit_to_stdu	conversion from bit to std_ulogic
stdul_to_bit	conversion from std_logic to bit
stdulv_to_bitvec	conversion from bitvector to std_ulogic_vector

Instantiation Snippets

Snippet	Description
entityinst	a basic entity instantiation without any ports or generics
tb \| testbench	a simple VHDL testbench with simple logic

Other Snippets

Snippet	Description
bitvecdec	a bit vector decalration
dec	a decrement statement
fall	using the "falling_edge" function
fsm	a generic fsm model with some cases
header	a simple header comment with title, file, author, dare, reviwe and description
inc	an increment statement
report	a simple report of a message
rise	using the "rising_edge" function
sigdec	a simple signal declaration
sub	a simple subtype declaration
stateproc \| processstate	a simple "State - NextState logic structure
var	a variable declaration
waitf	a "wait for" statement
waito	a "wait on" statement
waitu	a "wait until" statement

VUnit Snippets

Snippet	Description
vunit_tb	a testbench template for VUnit tests (no entities)

Quartus Snippets

Snippet	Description
Single Clock RAM OldData	a generic single clock ram structure from Intel with old data on read-during-write
Single Clock RAM NewData	a generic single clock ram structure from Intel with old data on read-during-write
Single Clock Concurrent RAM	a generic single clock ram structure from Intel with a concurrent signal
Simple Dual RAM	a generic dual clock ram structure from Intel with two clocks
True Dual Port RAM	a generic single clock dual port ram structure from Intel with one clock
Synch ROM 3 AddrBit	a generic single clock rom structure from Intel with an addressbit width of 3
Dual Port ROM with Init-Func	a generic single clock dual port rom structure from Intel with dynamic address and data length and init function

Xilinx Snippets

Xilinx snippets will appear by typing Xilinx: ...

Prerequisites

Verification-Tools(VUnit, HDLRegression...) must be already installed for generating the vhdl_ls.toml with Verification-Projects.
Synthesis-Tools (Quartus...) must be already installed for interacting with Synthesis-Projects.

History

An extension for vhdl_ls already exists in the marketplace: VHDL LS. The mentioned extension only handles the LSP-Setup.

VHDLbyHGB extends the already existing functionality and therefore is more a comprehensive extension, making it easier to set up and work on a VHDL-Project.

Contributing

Contributing in the form of code, documentation, feedback, tutorial, ideas or bug reports is very welcome.

Maintainers:

since 2023:

Configuration

Overview at Tab FEATURE CONTRIBUTIONS in VSCode

Commands

Overview at Tab FEATURE CONTRIBUTIONS in VSCode

You want to improve your workflow for HDL-Projects? Our other extensions will help you with that!

The extensions below will improve your vhdl-verification-experience:

License

This extension is published under the GNU GPL license.

VHDL by HGB

P2L2

VHDLbyHGB

Technology

Usage

Non-project files

VHDL-Standard

Lint-Settings

Paths

Project-Setup

auto

manual

LSP-Features

Formatting

Using Command Palette

Keyboard Shortcuts

Supported Formatters

vhdl_formatter VHDLFormatter by g2384

emacs_vhdl_formatter Emacs-VHDL-Mode-Formatter

Dynamic Snippets

Entity-Converter

Synthesis

Verification

Supported Tools:

VSCode-TestExplorer

VHDL Snippets

General Snippets

Conversionsfunctions Snippets

Instantiation Snippets

Other Snippets

VUnit Snippets

Quartus Snippets

Xilinx Snippets

Prerequisites

History

Contributing

Maintainers:

Configuration

Commands

License

VHDL by HGB

P2L2

VHDLbyHGB

Technology

Usage

Non-project files

VHDL-Standard

Lint-Settings

Paths

Project-Setup

auto

manual

LSP-Features

Formatting

Using Command Palette

Keyboard Shortcuts

Supported Formatters

vhdl_formatter VHDLFormatter by g2384

emacs_vhdl_formatter Emacs-VHDL-Mode-Formatter

Dynamic Snippets

Entity-Converter

Synthesis

Verification

Supported Tools:

VSCode-TestExplorer

VHDL Snippets

General Snippets

Conversionsfunctions Snippets

Instantiation Snippets

Other Snippets

VUnit Snippets

Quartus Snippets

Xilinx Snippets

Prerequisites

History

Contributing

Maintainers:

Configuration

Commands

Related Projects

License