This repository is a collection of HDL related tools.
NOTE: These tools are at a usable state however they are still intensively developed and thus they are currently only recommended to be used by early adopters and people interested in contributing to the development.
I am interested in collaboration with other people especially regarding semantic analysis of VHDL.
- This project aims to provide a fully featured open source VHDL parser that is easy to integrate into other tools.
- A design goal of the parser is to be able to recover from errors such that it is useful for building a language server.
- Analysis order must be automatically computed such that the user does not have to maintain a compile order.
- Comments will be part of the AST to support document generation.
- Separate parsing from semantic analysis to allow code formatting on non-semantically correct code.
- Almost all of VHDL-2008 is parsed, enough to parse the most popular VHDL projects on GitHub:
- https://github.com/inforichland/freezing-spice (Contains one file with actual syntax error)
- https://github.com/BG2BKK/img_process_vhdl (Contains one file with actual syntax error)
- Also parses IEEE/IEEE_2008/VITAL_95/VITAL_2000
- Good performance, can parse 440k lines of code (all repos above) in 500 ms on my laptop which is 45.5 MB/s of parsing throughput.
- Provides nice error messages such as:
error: Expected 'use', 'type', 'subtype', 'shared', 'constant', 'signal', 'variable', 'file', 'component', 'attribute', 'alias', 'impure', 'function', 'procedure', 'package' or 'for' --> example.vhd:19 | 17 | package pkg2 is 18 | constant foo : natural := 22; 19 --> error | ~~~~~ 20 | end package; 21 |
- The parser is a using hand written recursive descent since VHDL is not suitable for parser generators.
- Error recovery is still very rudimentary.
- Semantic analysis is ongoing work, currently checks for:
- Legal primary/secondary design unit combinations
- Duplicate design units
- Secondary units without primary unit
- Duplicate definitions in declarative parts
- Forbids overloaded name to co-exist with non-overloaded name
- Missing full constant for deferred constant
- Missing full type for deferred type
- Missing body for protected type and vice versa
- Missing declarations in type marks of most subtype indications
- Comments not part of AST yet.
Trying it out
The VHDL parser has a command line demonstrator which will parse a list of files and print information about the parse results. The command line tool currently only serves as a demonstrator and has no intended usability at this point.
> cd rust_hdl/ > cargo build --release > cargo run --bin vhdl_parser uart_rx.vhd uart_tx.vhd Showing design units from uart_rx.vhd entity uart_rx with 1 generics with 6 ports with 6 concurrent statements architecture a of uart_rx with 1 declarations with 2 concurrent statements Showing design units from uart_tx.vhd entity uart_tx with 1 generics with 5 ports with 6 concurrent statements architecture a of uart_tx with 1 declarations with 2 concurrent statements
VHDL Language Server
- A complete VHDL language server protocol implementation with diagnostics, navigate to symbol, find all references etc.
- Publishes diagnosics based on parse errors and warnings as well as semantic analysis.
- Usable today to get full live syntax error checking.
- Only full document sync
Trying it out
The language server has a command line binary
vhdl_ls which implements a stdio based language server.
This repository includes a medium sized example project which can be used to trying out the language server.
> cd rust_hdl > cargo build --release
The language server uses a configuration file in the TOML format named
The file contains the library mapping of all files within the project. Files outside of the project without library mapping are checked for syntax errors only.
# 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' ]
Use in emacs
Add the following to your
(require 'lsp-mode) (lsp-define-stdio-client lsp-vhdl-mode "VHDL" (lsp-make-traverser "vhdl_ls.toml") '("<PATH_TO_RUST_HDL>/target/release/vhdl_ls")) (require 'lsp-ui) (add-hook 'lsp-mode-hook 'lsp-ui-mode) (add-hook 'vhdl-mode-hook 'flycheck-mode) (add-hook 'vhdl-mode-hook 'lsp-vhdl-mode-enable)
Using the language server in
emacs with the
eglot language server package it is enough to simply add the following line to your
(require 'eglot) (add-to-list 'eglot-server-programs '(vhdl-mode . ("<PATH_TO_RUST_HDL>/target/release/vhdl_ls")))
Use in Atom
Use in VSCode
My hope is that other people will be interested in this project and contribute.
Some rules for collaboration:
- Contributions will have to assign copyright to me. Copyright is not about attribution or recognition it is about legal control of a project. Having several independent copyright holders in a project makes future changes difficult.
- I will add a list of notable contributors to the project to assign recognition.
- Quality is a priorty. Code has to be elegant and well tested.
Collaboration is also hard, you have to communicate with other people to do something coordinated together. Thus to collaborate we need to spend some time discussing what, why and how in GitHub issues or on the chat channel before diving in to the coding. This ensures that we work in the same direction.
The tools within this repository have been written in the Rust programming language, thus the name
The Rust programming language was choosen over Python, C or C++ as the best suited language to write the tools in.
The main advantages are;
- Excellent performance
- Strong modern type system
- Good libraries and tools
- Strong community and momentum
To install rust and its build tool cargo: https://rustup.rs/