tianrui-wei/verilog-ext

Verilog Extensions for Emacs

verilog-ext.el - SystemVerilog Extensions for Emacs

This package includes some extensions on top of the great Emacs verilog-mode.

• Tree-sitter support (requires Emacs 29)
• Improve syntax highlighting
• Hierarchy extraction and navigation
• LSP configuration for lsp-mode and eglot
• Support for many linters via flycheck
• Improve imenu entries: detect instances, classes and methods
• Code navigation functions for RTL and Verification environments
• Beautify modules and instances
• Extended collection of custom and yasnippet templates insertion via hydra
• Many additional misc utilities

Installation

Requirements

Verilog-mode

Latest verilog-mode version is required since verilog-ext relies on much of its functionality to work correctly. Using straight and use-package:

(straight-use-package 'use-package)
(use-package verilog-mode
  :straight (:repo "veripool/verilog-mode"))

For other installation methods refer to verilog-mode installation options.

Binaries and Emacs Lisp packages

verilog-ext makes use of several binaries as backend engines to support IDE-like functionality. In addition, some third party Emacs Lisp packages serve as frontends for those binaries.

List of required binaries:

• Definitions and references navigation: global, gtags, universal-ctags, python, pygments
• Jump to parent module: ag, ripgrep
• Hierarchy extraction: vhier
• Linting: verilator, iverilog, verible-verilog-lint, slang, svlint, xrun/hal
• LSP: hdl_checker, svlangserver, verible-verilog-ls, svls, veridian

Installation of required Emacs-lisp packages:

(use-package projectile)
(use-package ggtags)
(use-package ag)
(use-package ripgrep)
(use-package company)
(use-package yasnippet)
(use-package hydra)
(use-package outshine)
(use-package flycheck)
(use-package apheleia)
(use-package lsp-mode)
(use-package eglot)

verilog-ext

straight.el

For the time being verilog-ext is still work in progress and is not yet available at MELPA. To install it via straight:

(straight-use-package 'use-package)
(use-package
    :straight (:repo "gmlarumbe/verilog-ext"))

Manually

$ cd ~/.emacs.d
$ git clone https://github.com/gmlarumbe/verilog-ext

And add the following snippet to your .emacs or init.el:

(add-to-list 'load-path (expand-file-name "~/.emacs.d/verilog-ext"))
(require 'verilog-ext)

tree-sitter

Requires Emacs 29, installation of tree-sitter and Verilog grammar.

To install tree-sitter there are different options:

• Via npm
• Manually:

$ git clone https://github.com/tree-sitter/tree-sitter.git
$ cd tree-sitter
$ make && sudo make install

Installation of grammar can be automated through the script:

$ .github/scripts/install-ts-grammar.sh

That will install libtree-sitter-verilog.so at $HOME/.emacs.d/tree-sitter.

Basic config

By default verilog-ext does not create any keybindings. Following snippet shows a configuration example with use-package:

(use-package verilog-ext
  :straight (:host github :repo "gmlarumbe/verilog-ext")
  :after verilog-mode
  :demand
  :bind (:map verilog-mode-map
         ;; Default keys override
         ("TAB"           . verilog-ext-electric-verilog-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
         ("M-i"           . verilog-ext-imenu-list)
         ("C-c C-p"       . verilog-ext-preprocess)
         ("C-c C-f"       . verilog-ext-flycheck-mode-toggle)
         ("C-c C-t"       . verilog-ext-hydra/body)
         ("C-c C-v"       . verilog-ext-vhier-current-file)
         ;; Code beautifying
         ("C-M-i"         . verilog-ext-indent-block-at-point)
         ("C-c b"         . verilog-ext-module-at-point-beautify)
         ;; 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 navigation
         ("C-M-."         . verilog-ext-jump-to-parent-module)
         ;; Port connections
         ("C-c c"         . verilog-ext-toggle-connect-port)
         ("C-c C-c"       . verilog-ext-connect-ports-recursively))
  :init
  (setq verilog-ext-snippets-dir "~/.emacs.d/straight/repos/verilog-ext/snippets")
  (setq verilog-ext-flycheck-eldoc-toggle t)
  (setq verilog-ext-flycheck-verible-rules '("-line-length"))
  :config
  (verilog-ext-flycheck-set-linter 'verilog-verible)
  (verilog-ext-add-snippets))

Features

Tree-sitter

The package includes the major-mode verilog-ts-mode for syntax highligting and indentation. There is some WIP, e.g. Imenu or navigation functions.

Syntax highlighting

Font-lock based improved fontification.

verilog-mode	verilog-ext

Hierarchy extraction

Extract hierarchy of module at current buffer via Verilog-Perl vhier. Visualize with outline-minor-mode and outshine.

Functions:

• verilog-ext-vhier-current-file for hierarchy extraction
• vhier-outshine-mode for hierarchy navigation

Language Server Protocol

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

• hdl_checker
• svlangserver
• verible
• svls
• veridian

Functions:

• verilog-ext-lsp-set-server
• verilog-ext-eglot-set-server

Linting

Support via flycheck for the following linters:

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

Functions:

• verilog-ext-flycheck-mode-toggle: enable/disable current linter. Select linter with prefix-arg/(C-u).

Imenu

Support detection of instances and methods inside classes.

Instances	Methods

• imenu-list is a recommended package to visualize different levels of nesting in the hierarchy.

Navigation

Instance navigation

Navigate through instances inside a module forward/backwards. Jump to parent module via ag/ripgrep.

Functions:

• verilog-ext-find-module-instance-fwd
• verilog-ext-find-module-instance-bwd
• verilog-ext-jump-to-parent-module
• verilog-ext-instance-at-point

Jump to definition/reference

Jump to definition/reference of module at point via ggtags and xref.

Functions:

• verilog-ext-jump-to-module-at-point
• verilog-ext-jump-to-module-at-point-def
• verilog-ext-jump-to-module-at-point-ref

Dwim

Context aware functions (do what I mean) depending on the file being edited. Modules (RTL) navigate through instances while classes (Verification) navigate through methods/defuns.

Functions:

• verilog-ext-nav-down-dwim
• verilog-ext-nav-up-dwim
• verilog-ext-nav-beg-of-defun-dwim
• verilog-ext-nav-end-of-defun-dwim
• verilog-ext-nav-next-dwim
• verilog-ext-nav-prev-dwim

Beautify instances

Indent and align parameters and ports, interactively and in batch.

Functions:

• verilog-ext-module-at-point-beautify
• verilog-ext-beautify-current-buffer
• verilog-ext-beautify-files
• verilog-ext-beautify-files-current-dir

Snippets

• Select between snippets that cover most frequently used SystemVerilog constructs:

  

• Insert instances in current module from file:

  

• Create basic testbench environment from DUT file:

  

Functions:

• verilog-ext-hydra/body

Misc

• Code formatter setup via apheleia

  • verilog-ext-code-formatter-setup

• Preprocess files based on binary: verilator, iverilog or vppreproc

  • verilog-ext-preprocess

• Setup company to complete with verilog keywords

• Wrapper functions to stop cursor at underscores without breaking indentation

  • verilog-ext-forward-word
  • verilog-ext-backward-word
  • verilog-ext-kill-word
  • verilog-ext-backward-kill-word

• Typedef handling for syntax-higlighting and alignment via verilog-pretty-declarations

  • verilog-ext-typedef-project-update

• Toggle connections of ports under instance at point

  • verilog-ext-toggle-connect-port
  • verilog-ext-connect-ports-recursively
  • verilog-ext-clean-port-blanks

• Timestamp mode updating (after setting header timestamp regexp)

  • verilog-ext-time-stamp-mode

• Auto convert block comments to names:

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

• Makefile based development:

  • verilog-ext-makefile-create
  • verilog-ext-makefile-compile

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.

ERT Tests setup

To run the ERT test suite change directory to the verilog-ext root and run the ert-tests.sh script:

$ cd ~/.emacs.d/verilog-ext
$ .github/scripts/ert-tests.sh

If there is a missing dependency, check the file .github/scripts/setup-env.sh used by GitHub Actions to configure your environment.