Hierarchy

Configuration

First make sure that hierarchy has been included in verilog-ext-feature-list before running verilog-ext-mode-setup.

verilog-ext supports three different backends to extract the hierarchy (builtin, tree-sitter and vhier) and two different frontends to display it (hierarchy.el and outshine).

By default the builtin backend with the hierarchy.el frontend will be chosen.

Example usage:

• First setup workspace and proper variable values:

  ;; These are the default values, unless vhier is in the $PATH
  (setq verilog-ext-hierarchy-backend 'builtin)
  (setq verilog-ext-hierarchy-frontend 'hierarchy)

• Second, analyze the hierarchy of your workspace by one of these two methods:

  • M-x verilog-ext-workspace-hierarchy-parse RET
  • M-x verilog-ext-workspace-hierarchy-parse-async RET

• And finally extract it by running:

  • C-c C-v verilog-ext-hierarchy-current-buffer

Backends

Builtin

Uses internal Emacs lisp SystemVerilog parser to generate a database of current workspace modules to extract the hierarchy. This is the default backend unless vhier binary is in the $PATH.

It is needed to set workspace variables for file parsing and analyze project modules through one of these methods:

• M-x verilog-ext-workspace-hierarchy-parse RET
• M-x verilog-ext-workspace-hierarchy-parse-async RET

A hierarchy database will be created and cached so that it is kept for future sessions.

• Pros:

  • Easy to setup

• Cons:

  • Slower for large projects
  • Does not perform elaboration (e.g will not expand generate blocks)

To configure it explicitly:

(setq verilog-ext-hierarchy-backend 'builtin)

If you need to override the default search of current workspace files:

(setq verilog-ext-hierarchy-builtin-dirs '("/my/dir/to/analyze1" "/my/dir/to/analyze2""))

Tree-sitter

Uses Tree-sitter parser to generate a database of current workspace modules to extract the hierarchy.

• Pros:

  • Much faster than builtin

• Cons:

  • Requires setting up tree-sitter
  • Does not perform elaboration (e.g will not expand generate blocks)

(setq verilog-ext-hierarchy-backend 'tree-sitter)

Verilog-Perl vhier

Verilog-Perl vhier is a mature tool that reads the Verilog files passed on the command line and outputs a tree of all of the filenames, modules, and cells referenced by that file.

Installation:

• For Ubuntu/Debian:

sudo apt-get install libverilog-perl

• Others: https://github.com/veripool/verilog-perl#installation

Pros and cons:

• Pros:

  • Elaborates the design
  • Faster and more reliable

• Cons:

  • Requires external tool
  • Harder to configure

Configuration

To configure it explicitly:

(setq verilog-ext-hierarchy-backend 'vhier)

By default verilog-ext-hierarchy-current-buffer with the vhier backend will look at the list of current Verilog open buffers and their corresponding directories to search for modules. In case there is some missing module or an error related with compilation order, you can customize the variable verilog-ext-hierarchy-vhier-command-file and set a command file that can include a list of the files/includes used for hierarchy extraction, according to vhier syntax. E.g:

(setq verilog-ext-hierarchy-vhier-command-file "~/my-verilog-project/commands.f")

And being the content of commands.f:

-y ~/my-verilog-project/some-not-found-dir
~/my-verilog-project/src/my_pkg.sv
+define+SYNTHESIS+0

Frontends

hierarchy.el

The hierarchy package is integrated into Emacs core since 28.1.

verilog-ext provides the major mode verilog-ext-hierarchy-twidget-nav-mode to navigate the hierarchy with the following keybindings:

• SPC widget-button-press
• C-n widget-forward
• n widget-forward
• j widget-forward
• C-p widget-backward
• p widget-backward
• k widget-backward
• o verilog-ext-hierarchy-twidget-nav-open-other-window
• C-o verilog-ext-hierarchy-twidget-nav-open-other-window
• C-j verilog-ext-hierarchy-twidget-nav-open

Outshine

The outshine package brings the look and feel of Org Mode to other major modes.

verilog-ext provides the major mode verilog-ext-hierarchy-outshine-nav-mode to navigate the hierarchy with the following keybindings:

• Hide/Show
  • a outline-show-all
  • i outline-show-children
  • h outline-show-children
  • l verilog-ext-hierarchy-outshine-nav-hide-sublevels
  • I outline-show-branches
  • ; outline-hide-other
• Movement
  • u verilog-ext-hierarchy-outshine-nav-up-heading
  • C-c C-u verilog-ext-hierarchy-outshine-nav-up-heading
  • n verilog-ext-hierarchy-outshine-nav-next-visible-heading
  • j verilog-ext-hierarchy-outshine-nav-next-visible-heading
  • p verilog-ext-hierarchy-outshine-nav-previous-visible-heading
  • k verilog-ext-hierarchy-outshine-nav-previous-visible-heading
  • C-c C-n verilog-ext-hierarchy-outshine-nav-forward-same-level
  • C-c C-p verilog-ext-hierarchy-outshine-nav-backward-same-level
• Jump
  • o verilog-ext-hierarchy-outshine-jump-to-file-other-window
  • C-o verilog-ext-hierarchy-outshine-jump-to-file-other-window
  • RET verilog-ext-hierarchy-outshine-jump-to-file
  • C-j verilog-ext-hierarchy-outshine-jump-to-file