Skip to content

Hierarchy

Jump to bottom
Gonzalo Larumbe edited this page Dec 19, 2023 · 22 revisions

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 tree-sitter backend will be chosen if available. Otherwise it will fall back on the builtin backend. The hierarchy.el frontend will be always the default.

Example usage:

  • First setup the variable verilog-ext-project-alist:

    (setq verilog-ext-project-alist
      `(("ucontroller"
         :root "/home/gonz/Repos/larumbe/ucontroller"
         :files ("src/pkg/global_pkg.sv"
                 "src/alu/rtl/alu.sv"
                 "src/misc/rtl/bin2bcd.sv"
                 "src/cpu/rtl/cpu.sv"
                 "src/dma/rtl/dma.sv"
                 "src/dma/rtl/dma_arbiter.sv"
                 "src/dma/rtl/dma_rx.sv"
                 "src/dma/rtl/dma_tx.sv"
                 "src/uart/rtl/fifo_wrapper.sv"
                 "src/ram/rtl/gp_ram.sv"
                 "src/ram/rtl/ram.sv"
                 "src/top/rtl/ram_arbiter.sv"
                 "src/ram/rtl/regs_ram.sv"
                 "src/uart/rtl/sreg.sv"
                 "src/uart/rtl/uart.sv"
                 "src/uart/rtl/uart_rx.sv"
                 "src/uart/rtl/uart_tx.sv"
                 "src/top/rtl/ucontroller.sv"
                 "src/uart/tb/fifo_generator_0_sim_netlist.v"
                 "src/top/tb/tb_clocks.sv"
                 "src/top/tb/tb_program.sv"
                 "src/top/tb/tb_top.sv"
                 "src/dma/tb/tb_dma.sv"
                 "src/alu/tb/tb_alu.sv"
                 "src/misc/tb/tb_bin2bcd.sv"
                 "src/cpu/tb/tb_cpu.sv"
                 "src/ram/tb/tb_ram.sv"
                 "src/uart/tb/tb_uart.sv")
         :ignore-files ("src/uart/tb/fifo_generator_0_sim_netlist.v")
         :compile-cmd "make tb_top" ; command used to compile current project
         ;; `vhier' related properties
         :command-file nil       ; vhier command file
         :lib-search-path nil))) ; list of dirs to look for include directories or libraries

  • Second, analyze the hierarchy of your project visiting top file module buffer and running one of these two commands:

    • M-x verilog-ext-hierarchy-parse RET
    • M-x verilog-ext-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 project modules to extract the hierarchy.

It is also needed to set the variable vhdl-ext-project-alist for file parsing and analyze project modules through one of these commands:

  • M-x verilog-ext-hierarchy-parse RET
  • M-x verilog-ext-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)

Tree-sitter

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

  • Pros:

    • Much faster than builtin

  • Cons:

(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

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 only at the list of files included in verilog-ext-project-alist. If you also want to include the list of current Verilog open buffers and their corresponding directories to search for modules, simply set the customizable variable verilog-ext-hierarchy-vhier-use-open-buffers to non-nil.

In case there is some missing module or an error related with compilation order, you might need to set the verilog-ext-project-alist property :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-project-alist
        `(("ucontroller"
           :root "/home/gonz/Repos/larumbe/ucontroller"
           :files ("src/pkg/global_pkg.sv"
           ;; ...
           ;; ...
           ;; `vhier' related properties
           :command-file "commands.f" ; vhier command file
           :lib-search-path nil)))    ; list of dirs to look for include directories or libraries

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
Clone this wiki locally