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.
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)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):
.vhdl_ls.toml
in the user home folder.VHDL_LS_CONFIG
environment variable.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
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.
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.
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
orsyntax
) can cause unwanted side effects
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.
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
:
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:
As a consequence of setting an active verification-project, the vhdl_ls.toml
will be generated automatically
from the source-information from these projects.
vhdl_ls.toml
must be generated manually by user e.g. via a custom python-scriptCMD
+ SHIFT
+ P
CTRL
+ SHIFT
+ P
And type Format Document
SHIFT
+ OPTION
+ F
SHIFT
+ ALT
+ F
If you don't like the default shortcuts, you can rebind editor.action.formatDocument
in the keyboard shortcuts menu of VSCode.
The property vhdl-by-hgb.formatter
lets you choose between one of the following formatters:
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 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 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:
VHDLbyHGB.dynamicSnippets
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.)
The Entity-Converter copies the entity and pastes it in different formats.
The features of the Entity-Converter can be used by:
VHDLbyHGB.copyEntity
VHDLbyHGB.pasteAsComponent
VHDLbyHGB.pasteAsInstance
VHDLbyHGB.pasteAsEntity
VHDLbyHGB.pasteSignals
VHDLbyHGB.pasteConstants
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.
VHDLbyHGB uses verification-projects to get project-information.
The actual verification is handled in our Verification-Extensions. These extensions will offer you to perform actions directly from within the VSCode-TestExplorer, including:
Besides the Snippets from the Language Server, here a some more usable 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 |
Snippet | Description |
---|---|
entityinst | a basic entity instantiation without any ports or generics |
tb | testbench | a simple VHDL testbench with simple logic |
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 |
Snippet | Description |
---|---|
vunit_tb | a testbench template for VUnit tests (no entities) |
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 will appear by typing Xilinx: ...
vhdl_ls.toml
with Verification-Projects.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 in the form of code, documentation, feedback, tutorial, ideas or bug reports is very welcome.
since 2023:
FEATURE CONTRIBUTIONS
in VSCodeFEATURE CONTRIBUTIONS
in VSCodeYou 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:
This extension is published under the GNU GPL license.