Skip to content

Latest commit

 

History

History
215 lines (128 loc) · 7.02 KB

README.md

File metadata and controls

215 lines (128 loc) · 7.02 KB
Raw

Parvaj

Version Available As AppImage Available As Phar Available At AUR package

Easy and fast (both in the sense of performance and development speed) VHDL simulation tool, integrating GHDL and GTKWave.

Features

  • Easy:

    • 💡 Zero-configuration by default. Go ahead and simulate your design!

    • ☕ Easy to use. You don't need to remember or look for dependencies everytime, Parvaj does it for you. You wouldn't even need to know most of the GHDL command-line options.

    • ☔ Simple installation process, by providing AppImage and Phar files.

  • Fast:

    • ⛽ Speed up your development. Don't get your hands dirty by invoking GHDL and GTKWave manually; use the simple simulate command instead to do all the steps for you.

    • ⚡ The tool itself is designed to have good performance. It uses a proper cache mechanism for this. Although it uses regex patterns for major tasks, thanks to fast PHP regex engine, you wouldn't notice slowdowns.

  • Semi-intelligent:

    • 🔥 Automatic detection of dependencies. Forget about what depends on what.

    • 🧠 After finding where a unit (e.g. entity) lives, Parvaj remembers it. Don't worry, it is smart enough to check if it was moved around or was renamed. Just use it!

Let's Install!

Note: Currently, we only cover and support Linux distributions (feel free to add support for other platforms as well).

There are four methods to install Parvaj:

In doubt? See Which one to use?.

Use the AppImage Bundle

Requirements

  • GHDL
  • GTKWave

Having a Linux distribution, installing these should be easy:

Fedora-based 
sudo dnf install ghdl gtkwave
Arch-based

GTKWave can be installed through Pacman and GHDL through AUR:

sudo pacman -S gtkwave
yay -S ghdl-gcc-git
Debian-based (e.g. Ubuntu) 
sudo apt install ghdl gtkwave

Getting It

  1. Download latest Parvaj AppImage.

    wget https://github.com/machitgarha/parvaj/releases/latest/download/parvaj-x86_64.AppImage

    Note: The AppImage does not provide a GUI, so double-clicking it does nothing.

  2. Make it executable.

    chmod +x parvaj-x86_64.AppImage

  3. Put it somewhere in your $PATH.

    # Supposing ~/.local/bin is in your $PATH
mv parvaj-x86_64.AppImage ~/.local/bin/parvaj

  4. Done! Make sure the installation was successful:

    parvaj

Throughout this document, it is supposed you installed Parvaj using this method.

How to Use?

The primary Parvaj command is simulate. It simulates a test-bench for you, given its name. Yes, it is really that simple!

For example, to simulate a test-bench named test_multiplexer_2_to_1 (note that it's the name of the test-bench, not its file path), run:

# Or even shorter:
parvaj s test_multiplexer_2_to_1

Note that, for the simulate command to work, you must be in the project root, not one of its sub-paths. It might be annoying for some, but not implemented yet (#2).

Options

You may also want to use some of the GHDL's simulation options, or the options provided by Parvaj. You can use the command help to see the list of available options:

parvaj help simulate
# Or:
parvaj simulate --help

Examples

  • With --workdir, you can change the working directory (which is build/ by default):

    parvaj simulate test_multiplexer_2_to_1 --workdir=obj/
# The order does not matter:
parvaj simulate --workdir=obj/ test_multiplexer_2_to_1

  • With --option or -o, you may pass arbitrary simulation options to GHDL:

    parvaj simulate test_clock_generator -o stop-time=3ns -o vcd-nodate

    Hint: stop-time option is useful when your test-bench doesn't end in a finite period of time and could be run infinitely. In this case, you must inform GHDL to limit the simulation time to a specific period, e.g. 3ns; otherwise, the simulation (i.e. elab-running phase) will never stop.

Other Commands

Although Parvaj is designed to work mostly config-free, you can configure a few things using the config command:

  • gtkwave.cmdline: If set, this command is used to run GTKWave. This is useful if you want to use a different application for viewing waveforms, or having problems with the default invocation command.

    For instance, on MacOS, you can set it to open.

  • ghdl.version: GHDL version should be auto-detected, but this sets its major version.

Example

Some MacOS users cannot invoke GTKWave directly from the command-line using gtkwave command. In this case, the fix is to use open command.

You can set it like the following:

parvaj config gtkwave.cmdline open

Want to make sure it was set?

parvaj config gtkwave.cmdline
# Output: open

Want to unset it (i.e. reset it to the default value)?

parvaj config gtkwave.cmdline ""

Platform Support

Tested platforms include:

  • Fedora 28+
  • Ubuntu 18.04+

Parvaj should work on Linux-based platforms, and also generally Unix-like ones (e.g. OS X, Windows WSL).

It should run on Windows as well, but not properly tested. By the way, it might be harder to install GHDL on Windows than WSL.

Contributions? Of Course!

Feel free to open an issue or create a pull request. You can also consider the to-do list below.

But hey, contribution can be simpler than that: Recommend Parvaj to your friends, if you liked it!

Donations

If you live in Iran, you can make donations here. Otherwise, open an issue telling why you cannot donate from the outside. :)

License

AGPL 3.0