verilog-ext.el - SystemVerilog Extensions for Emacs

This package provides some extensions on top of the great Emacs verilog-mode:

• Tree-sitter powered verilog-ts-mode
• Improve syntax highlighting
• Find definitions and references
• Auto-completion with dot and scope completion
• Hierarchy extraction and navigation
• LSP configuration for lsp-mode and eglot
• Support for many linters via flycheck
• Beautify modules and instances
• Code navigation functions for RTL and Verification environments
• Extended collection of templates via yasnippet and hydra
• Code formatter via apheleia
• Compilation with colored errors/warnings and jump to file/line
• Improve imenu entries: detect instances, classes and methods
• Enhanced support for which-func
• Code folding via hideshow
• Highlight and align typedefs
• Auto-configure time-stamp
• Auto-convert block end comments to names
• Port connection utilities

Installation

MELPA

verilog-ext and verilog-ts-mode are available on MELPA. verilog-ext includes verilog-ts-mode as a dependency.

straight.el

To install it via straight with use-package:

(straight-use-package 'use-package)
(use-package verilog-ext)

Basic config

The most basic configuration just requires choosing which features you want to load, setup the minor-mode and add it as a hook for verilog-mode. By default all features are enabled:

;; Can also be set through `M-x RET customize-group RET verilog-ext':
;;  - Verilog Ext Feature List (provides info of different features)
;; Comment out/remove the ones you do not need
(setq verilog-ext-feature-list
      '(font-lock
        xref
        capf
        hierarchy
        eglot
        lsp
        flycheck
        beautify
        navigation
        template
        formatter
        compilation
        imenu
        which-func
        hideshow
        typedefs
        time-stamp
        block-end-comments
        ports))
(verilog-ext-mode-setup)
(add-hook 'verilog-mode-hook #'verilog-ext-mode)
;; To use `verilog-ts-mode' as the default major-mode also add the line below:
(add-to-list 'auto-mode-alist '("\\.s?vh?\\'" . verilog-ts-mode))

If installed and loaded via use-package:

(use-package verilog-ext
  :after verilog-mode
  :demand
  :hook ((verilog-mode . verilog-ext-mode))
  :init
   ;; Can also be set through `M-x RET customize-group RET verilog-ext':
   ;;  - Verilog Ext Feature List (provides info of different features)
   ;; Comment out/remove the ones you do not need
  (setq verilog-ext-feature-list
        '(font-lock
          xref
          capf
          hierarchy
          eglot
          lsp
          flycheck
          beautify
          navigation
          template
          formatter
          compilation
          imenu
          which-func
          hideshow
          typedefs
          time-stamp
          block-end-comments
          ports))
  :config
  (verilog-ext-mode-setup))

;; To use `verilog-ts-mode' as the default major-mode also add the lines below:
(use-package verilog-ts-mode
  :mode (("\\.s?vh?\\'" . verilog-ts-mode))

Workspace

verilog-ext relies on the concept of a workspace to select which files will be analyzed for navigation, completion, hierarchy extraction, compilation directory, etc...

For example, to analyze all the files inside a Git repo but excluding some 3rd party vendor libraries:

(setq verilog-ext-workspace-ignore-dirs '("/path/to/my/repo/lib1" "/path/to/my/repo/lib2"))
(setq verilog-ext-workspace-ignore-files '("/path/to/my/repo/lib3/lib_file.sv"))

To analyze only files inside rtl/tb directories inside a Git repo, plus a couple of specific ones in other directory:

(setq verilog-ext-workspace-dirs '("/path/to/my/repo/src/rtl" "/path/to/my/repo/src/tb"))
(setq verilog-ext-workspace-extra-files '("/path/to/my/repo/misc/specific_file1.sv" "/path/to/my/repo/misc/specific_file2.sv"))

To override the value of workspace root inside a Git repo:

(setq verilog-ext-workspace-root-dir "/path/to/my/overriden/workspace/root")

Keybindings

Enabling of verilog-ext-mode minor-mode creates the following keybindings:

• Features:

  • C-c C-l verilog-ext-formatter-run
  • C-c <f5> verilog-ext-workspace-compile
  • C-c C-p verilog-ext-preprocess
  • C-c C-f verilog-ext-flycheck-mode
  • C-c C-t verilog-ext-hydra/body
  • C-c C-v verilog-ext-hierarchy-current-buffer
  • C-<tab> verilog-ext-hs-toggle-hiding

• Code beautifying

  • C-M-i verilog-ext-beautify-block-at-point-indent
  • C-c C-b verilog-ext-beautify-module-at-point

• Dwim navigation

  • C-M-a verilog-ext-nav-beg-of-defun-dwim
  • C-M-e verilog-ext-nav-end-of-defun-dwim
  • C-M-d verilog-ext-nav-down-dwim
  • C-M-u verilog-ext-nav-up-dwim
  • C-M-p verilog-ext-nav-prev-dwim
  • C-M-n verilog-ext-nav-next-dwim

• Module at point

  • C-c M-. verilog-ext-jump-to-module-at-point-def
  • C-c M-? verilog-ext-jump-to-module-at-point-ref

• Jump to parent module

  • C-M-. verilog-ext-workspace-jump-to-parent-module

• Port connections

  • C-c C-c c verilog-ext-ports-clean-blanks
  • C-c C-c t verilog-ext-ports-toggle-connect
  • C-c C-c r verilog-ext-ports-connect-recursively

• Syntax table override functions:

  • TAB verilog-ext-tab
  • M-d verilog-ext-kill-word
  • M-f verilog-ext-forward-word
  • M-b verilog-ext-backward-word
  • C-<backspace> verilog-ext-backward-kill-word

Features

Tree-sitter

The package verilog-ts-mode provides syntax highlighting, indentation and a backend for hierarchy extraction, definitions and references navigation, and some other features implemented in verilog-ext. Using tree-sitter as a backend is recommended as it is much faster and efficient than internal Emacs lisp parsing.

verilog-ts-mode is derived from verilog-mode making AUTOs and other utilities still available.

For more information see the wiki.

Syntax highlighting

For configuration information, see the wiki.

Find definitions and references

verilog-ext provides a builtin xref backend to navigate definitions and references of the workspace.

For configuration information, see the wiki.

Auto-completion

Complete with tags from current workspace. Supports dot and scope completion for module signals, class attributes and methods.

For configuration information, see the wiki.

Hierarchy extraction

Hierarchy extraction of module at current buffer.

For configuration information, see the wiki.

Language Server Protocol

Auto-configure various SystemVerilog language servers for lsp-mode and eglot:

• hdl_checker
• svlangserver
• verible
• svls
• veridian

For configuration instructions, see the wiki

Linting

Support via flycheck for the following linters:

• Verilator
• Icarus Verilog
• Verible
• Slang
• Svlint
• Surelog
• Cadence HAL

For configuration and usage instructions, see the wiki

Beautify instances

Indent and align parameters and ports of RTL instances.

Interactive functions:

• verilog-ext-beautify-module-at-point: C-c C-b
• verilog-ext-beautify-current-buffer

Batch-mode functions:

• verilog-ext-beautify-files
• verilog-ext-beautify-dir-files

Navigation

Features:

• Context aware dwim functions for RTL/Verification environments
• Navigate instances inside a module
• Jump to definition/references of module at point
• Jump to parent module

For detailed info see the wiki.

Templates

Select among snippets that cover most frequently used SystemVerilog constructs:

Insert instances in current module from file:

Create basic testbench environment from DUT file:

UVM Agent template:

Functions:

• verilog-ext-hydra/body: C-c C-t

Code formatter

Code-formatter setup via apheleia and verible-verilog-format.

See configuration in the wiki.

Compilation

Provides functions to perform compilations with syntax highlighting and jump to error, buffer preprocessing and makefile development:

• verilog-ext-workspace-compile: C-c <f5>
• verilog-ext-preprocess: C-c C-p
• verilog-ext-workspace-makefile-create
• verilog-ext-workspace-makefile-compile

See configuration in the wiki.

Imenu

Support detection of instances and methods inside classes.

Instances:

Methods:

Find more information here.

Which-func

Enhanced which-func support: show current block/instance at point in the mode-line

Code folding

Code folding via hideshow: C-<tab>

Typedefs

Add support for syntax-higlighting and alignment via verilog-pretty-declarations of user defined types and classes.

For configuration see wiki

Time-stamp

Automatic update of header timestamp after file saving.

• verilog-ext-time-stamp-mode

For configuration see wiki

Block-end comments

Auto convert block comments to names after file saving.

• verilog-ext-block-end-comments-to-names-mode

Port connections

Toggle connections of ports under instance at point

• verilog-ext-ports-toggle-connect: C-c C-c t
• verilog-ext-ports-connect-recursively: C-c C-c r
• verilog-ext-ports-clean-blanks: C-c C-c c

Misc

Wrapper functions to stop cursor at underscores without breaking indentation

• verilog-ext-forward-word: M-f
• verilog-ext-backward-word: M-b
• verilog-ext-kill-word: M-d
• verilog-ext-backward-kill-word: C-<backspace> and M-DEL

Contributing

Contributions are welcome! Just stick to common Elisp conventions and run the ERT suite after testing your changes and before submitting a new PR.

For new functionality add new ERT tests if possible.

Consider sponsoring to help maintaining the project and for the development of new features. Thank you!

ERT Tests setup

To run the whole ERT test suite change directory to the verilog-ext root and run the test target:

$ cd ~/.emacs.d/verilog-ext
$ make

To run a subset of tests (e.g. navigation):

$ cd ~/.emacs.d/verilog-ext
$ make subset TESTS=navigation

Other packages

• vhdl-ext: VHDL Extensions for Emacs
  • Analog package to edit VHDL sources
• fpga: FPGA & ASIC Utilities for Emacs
  • Utilities for tools of major vendors of FPGA & ASIC
• wavedrom-mode: Wavedrom integration for Emacs
  • Edit and render WaveJSON files to create timing diagrams
• vunit-mode: VUnit Mode for Emacs
  • Integration of VUnit workflow.