Skip to content

suoto/hdl_checker

Repository files navigation

HDL Checker

PyPI version Linux Unit tests Build status codecov Join the chat at https://gitter.im/suoto/hdl_checker Mentioned in Awesome Computer Architecture Analytics

HDL Checker is a language server that wraps VHDL/Verilg/SystemVerilog tools that aims to reduce the boilerplate code needed to set things up. It supports Language Server Protocol or a custom HTTP interface; can infer library VHDL files likely belong to, besides working out mixed language dependencies, compilation order, interpreting some compilers messages and providing some (limited) static checks.


Installation

pip3 install hdl-checker --upgrade

or

pip3 install hdl-checker --user --upgrade

Note: Make sure you can run hdl_checker --version, especially if using PIP with the --user option.

Editor support

VS Code

Install the HDL Checker VSCode client on VS Code.

Vim/NeoVim

ALE supports HDL Checker out of the box.

Using coc.nvim

Following coc.nvim custom language server setup, add this to your coc.nvim configuration file:

{
    "languageserver": {
        "hdlChecker": {
            "command": "hdl_checker",
            "args": [
                "--lsp"
            ],
            "filetypes": [
                "vhdl",
                "verilog",
                "systemverilog"
            ]
        }
    }
}

Using NeoVim's native language server

This requires nvim-lspconfig.

lua << EOF
-- Only define once
if not require'lspconfig.configs'.hdl_checker then
  require'lspconfig.configs'.hdl_checker = {
    default_config = {
    cmd = {"hdl_checker", "--lsp", };
    filetypes = {"vhdl", "verilog", "systemverilog"};
      root_dir = function(fname)
        -- will look for the .hdl_checker.config file in parent directory, a
        -- .git directory, or else use the current directory, in that order.
        local util = require'lspconfig'.util
        return util.root_pattern('.hdl_checker.config')(fname) or util.find_git_ancestor(fname) or util.path.dirname(fname)
      end;
      settings = {};
    };
  }
end

require'lspconfig'.hdl_checker.setup{}

EOF

Add HDL Checker to the server commands:

let g:LanguageClient_serverCommands = {
\   'vhdl': ['hdl_checker', '--lsp'],
\   'verilog': ['hdl_checker', '--lsp'],
\   'systemverilog': ['hdl_checker', '--lsp'],
\}

Please note that this will start one server per language

Emacs

Add this to your Emacs config file

(require 'use-package)
(setq lsp-vhdl-server-path "~/.local/bin/hdl_checker") ; only needed if hdl_checker is not already on the PATH
(custom-set-variables
  '(lsp-vhdl-server 'hdl-checker))
(use-package lsp-mode
  :config (add-hook 'vhdl-mode-hook 'lsp))

Usage

HDL Checker server can be started via hdl_checker command. Use hdl_checker --help for more info on how to use it.

$ hdl_checker -h
usage: hdl_checker [-h] [--host HOST] [--port PORT] [--lsp]
             [--attach-to-pid ATTACH_TO_PID] [--log-level LOG_LEVEL]
             [--log-stream LOG_STREAM] [--stdout STDOUT]
             [--stderr STDERR] [--version]

optional arguments:
  -h, --help            show this help message and exit
  --host HOST           [HTTP] Host to serve
  --port PORT           [HTTP] Port to serve
  --lsp                 Starts the server in LSP mode. Defaults to false
  --attach-to-pid ATTACH_TO_PID
                        [HTTP, LSP] Stops the server if given PID is not
                        active
  --log-level LOG_LEVEL
                        [HTTP, LSP] Logging level
  --log-stream LOG_STREAM
                        [HTTP, LSP] Log file, defaults to stdout when in HTTP
                        or a temporary file named hdl_checker_log_pid<PID>.log when
                        in LSP mode
  --stdout STDOUT       [HTTP] File to redirect stdout to. Defaults to a
                        temporary file named hdl_checker_stdout_pid<PID>.log
  --stderr STDERR       [HTTP] File to redirect stdout to. Defaults to a
                        temporary file named hdl_checker_stderr_pid<PID>.log
  --version, -V         Prints hdl_checker version and exit

Third-party tools

HDL Checker supports

Configuring HDL Checker

See the Setting up a new project section on the wiki.

LSP server

HDL Checker has beta support for Language Server Protocol. To start in LSP mode:

hdl_checker --lsp

On a Linux system, log file will be at /tmp/hdl_checker_log_pid<PID_NUMBER>.log and /tmp/hdl_checker_stderr_pid<PID_NUMBER>.log.

As a language server, HDL Checker will provide

  • Diagnostics
  • Hover information
    • Dependencies: will report which path and library have been assigned
    • Design units: will report the compilation sequence and libraries
  • Go to definition of dependencies

HTTP server

HDL Checker can be used in HTTP server mode also:

hdl_checker

Please note that this mode does not use LSP over http to communicate. Request/response API is not yet available and is going to be deprecated in the future. A reference implementation can be found in vim-hdl

Testing

HDL Checker uses a docker container to run tests. If you wish to run them, clone this repository and on the root folder run

./run_tests.sh

The container used for testing is suoto/hdl_checker_test

Supported systems

System CI CI status
Linux Yes Linux Unit tests
Windows Yes Build status

Style checking

Style checks are independent of a third-party compiler. Checking includes:

  • Unused signals, constants, generics, shared variables, libraries, types and attributes
  • Comment tags (FIXME, TODO, XXX)

Notice that currently the unused reports has caveats, namely declarations with the same name inherited from a component, function, procedure, etc. In the following example, the signal rdy won't be reported as unused in spite of the fact it is not used.

signal rdy, refclk, rst : std_logic;
...

idelay_ctrl_u : idelay_ctrl
    port map (rdy    => open,
              refclk => refclk,
              rst    => rst);

Issues

You can use the issue tracker for bugs, feature request and so on.

License

This software is licensed under the GPL v3 license.

Notice

Mentor Graphics®, ModelSim® and their respective logos are trademarks or registered trademarks of Mentor Graphics, Inc.

Intel® and its logo is a trademark or registered trademark of Intel Corporation.

Xilinx® and its logo is a trademark or registered trademark of Xilinx, Inc.

HDL Checker's author has no connection or affiliation to any of the trademarks mentioned or used by this software.