Skip to content

Hierarchy

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

Configuration

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

vhdl-ext supports three different backends to extract the hierarchy (builtin, tree-sitter and ghdl) 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 vhdl-ext-project-alist:

    (setq vhdl-ext-project-alist
      ("axi_if_converter"
       :root "/home/gonz/Repos/larumbe/axi_if_converter"
       :files ("src/top/rtl/global_pkg.vhd"
               "src/misc/clk_div.vhd"
               "src/misc/clk_sync.vhd"
               "src/pattern_counter/rtl/pattern_counter.vhd"
               "src/input_buffer/rtl/input_buffer_pkg.vhd"
               "src/input_buffer/rtl/input_buffer.vhd"
               "src/core_fsm/rtl/core_fsm.vhd"
               "src/axi_lite_regs/rtl/axi_lite_regs.vhd"
               "src/axi_lite_master/rtl/axi_lite_master.vhd"
               "src/core_conv/rtl/core_converter.vhd"
               "src/top/rtl/axi_if_converter.vhd")
       ;; The ones below are used for GHDL-related features
       :worklib "xil_defaultlib"                    ; Defaults to `work' if not set
       :workdir "library/xil_defaultlib"            ; Output compilation directory for worklib
       :lib-search-path ("/opt/ghdl_Xilinx_lib/"))) ; Extra directories to look for compiled libraries

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

    • M-x vhdl-ext-hierarchy-parse RET
    • M-x vhdl-ext-hierarchy-parse-async RET

  • And finally extract it by running:

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

Backends

Builtin

Uses internal Emacs Lisp VHDL parser to generate a database of current project entities to extract the hierarchy.

To configure it:

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

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

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

Tree-sitter

Uses Tree-sitter parser to generate a database of current project in vhdl-ext-project-alist to extract the hierarchy.

  • Pros:

    • Much faster than builtin

  • Cons:

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

GHDL

GHDL is the open-source analyzer, compiler, simulator and (experimental) synthesizer for VHDL. It can be used to elaborate the design and extract the hierarchy.

Installation:

GHDL 4.0.0 or higher is required. It is recommended to download a precompiled image or installing from sources: https://github.com/ghdl/ghdl#getting-ghdl

Using package managers is another alternative but beware that these might provide older versions that will not work.

  • For Ubuntu/Debian:
sudo apt-get install ghdl
ghdl --version

Pros and cons:

  • Pros:

    • Elaborates the design
    • Faster and more reliable

  • Cons:

    • Requires external tool
    • Harder to configure

Configuration

To configure it explicitly:

(setq vhdl-ext-hierarchy-backend 'ghdl)

GHDL backend requires the sources in the alist vhdl-ext-project-alist to be in order, as they are passed as command line arguments to the GHDL process.

vhdl-ext will automatically detect which project of vhdl-ext-project-alist your current buffer belongs to and will extract the hierarchy for the buffer entity. If there are any compilation errors these will be shown in the buffer *ghdl-hier-errors*.

Once it has been analyzed, hierarchy data will be cached and can be further used to instantly retrieve the hierarchy for entities down in the hierarchy.

For example, if you run vhdl-ext-hierarchy-current-buffer on the top entity you will be able to get the hierarchy of any of the entities in the project. However, if you run the command for a subblock, the database will hold data for that subblock and not for the top entity of the project.

To force refreshing of the database simply run the command with the prefix arg:

  • C-u C-c C-v or C-u vhdl-ext-hierarchy-current-buffer RET

Frontends

hierarchy.el

The hierarchy package is integrated into Emacs core since 28.1.

vhdl-ext provides the major mode vhdl-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 vhdl-ext-hierarchy-twidget-nav-open-other-window
  • C-o vhdl-ext-hierarchy-twidget-nav-open-other-window
  • C-j vhdl-ext-hierarchy-twidget-nav-open

Outshine

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

vhdl-ext provides the major mode vhdl-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 vhdl-ext-hierarchy-outshine-nav-hide-sublevels
    • I outline-show-branches
    • ; outline-hide-other
  • Movement
    • u vhdl-ext-hierarchy-outshine-nav-up-heading
    • C-c C-u vhdl-ext-hierarchy-outshine-nav-up-heading
    • n vhdl-ext-hierarchy-outshine-nav-next-visible-heading
    • j vhdl-ext-hierarchy-outshine-nav-next-visible-heading
    • p vhdl-ext-hierarchy-outshine-nav-previous-visible-heading
    • k vhdl-ext-hierarchy-outshine-nav-previous-visible-heading
    • C-c C-n vhdl-ext-hierarchy-outshine-nav-forward-same-level
    • C-c C-p vhdl-ext-hierarchy-outshine-nav-backward-same-level
  • Jump
    • o vhdl-ext-hierarchy-outshine-jump-to-file-other-window
    • C-o vhdl-ext-hierarchy-outshine-jump-to-file-other-window
    • RET vhdl-ext-hierarchy-outshine-jump-to-file
    • C-j vhdl-ext-hierarchy-outshine-jump-to-file
Clone this wiki locally