playhdl

You can think about playhdl as EdaPlayground, but which is CLI-based and uses simulators on your local machine.

It gives you ability to simulate tiny snippets of HDL code in several commands without any headache related to vast tool guides, command-line arguments and etc.:

playhdl init sv
playhdl run modelsim

Features

playhdl is written in pure Python without any external dependencies, so it is easy to use it in any environment (laptop, server, etc.), where Python 3.8+ is available.

It supports various project types (HDL languages + libraries) and many simulators:

	verilog	sv	sv_uvm12	vhdl
modelsim	✔️	✔️
xcelium	✔️	✔️
verilator	✔️	✔️
icarus	✔️	✔️
vcs	✔️	✔️	✔️
vivado	✔️	✔️	✔️

Quick start

• Install the latest stable release (Python 3.8+ is required):

python -m pip install -U playhdl

• Setup settings file $HOME/.playhdl/settings.json with a list of all automatically-discoverd simulators. Edit file manually to add undiscovered ones. This have to be done only once.

playhdl setup

• Initialize project file playhdl.json and template testbench in the current directory. Project file contains specific commands to be executed for compilation and simulation processes. Edit it manually to tweak tool arguments if required.

playhdl init sv # this will create ready-to-simulate tb.sv

• Run simulation in one of the supported simulators for this project (language):

playhdl run icarus
# to open waves after simulation
playhdl run icarus --waves

Tool command guide

To get general help and command list:

playhdl -h

To get help about specific command

playhdl <command> -h

setup command

Settings of the tool are stored in the JSON file under $HOME/.playhdl directory.

To create $HOME/.playhdl/settings.json run

playhdl setup

It will try to find all supported simulators and fill the json. If you have multiple versions of simulators or some of them were not found, add them manually to your settings file.

Settings file structure:

{
    "tools": {
        "<tool_uid>": {
            "kind": "<tool_kind>",
            "bin_dir": "<path_to_bin>",
            "env": {},
            "extras": {}
        }
    }
}

All tools settings are located in a dictionary under "tools" key.

Every tool has it is own tool_uid, which is just a string with any unique name, e.g. "modelsim", "verilator5", "my_secret_simulator".

Valid "kind" must be provided:

• "modelsim"
• "xcelium"
• "verilator"
• "icarus"
• "vcs"
• "vivado"

Other fields:

• "bin_dir" - a string with a path to a directory with executable files
• "env" - a dictionary with additional enviroment variables (keys and values are strings)
• "extras" - a dictionary with extra values for a specific simulator kind

Extras for "vcs" kind:

• "gui" - "verdi" or "dve" select default GUI for VCS

init command

This command creates JSON project file playhdl.json and HDL testbench in the current directory.

playhdl init <mode>

Where <mode> is one of the supported project modes:

• verilog - Verilog-2001
• sv - SystemVerilog-2017
• sv_uvm12 - SystemVerilog-2017 + UVM 1.2
• vhdl - VHDL-93

Project file is filled with scripts for all suitable simulators for the selected mode. It's internal structure:

{
    "tools": {
        "<tool_uid>": {
            "build": [
                "<cmd0>",
                "<cmd1>",
                "<cmd2>"
            ],
            "sim": [
                "<cmd>"
            ],
            "waves": [
                "<cmd>"
            ]
        }
    }
}

There are three categories of commands:

• "build" - commands needed to compile and elaborate sources
• "sim" - commands needed to run simulation
• "waves" - commands needed to open waves for analysis

Any command can be customized for specific needs.

run command

This command runs CLI-mode simulation in a specific simulator according to project file

playhdl run <tool_uid>

Argument --waves can be added to open waves for analysis after simulation ends

playhdl run <tool_uid> --waves

info command

This command just prints some useful information:

• all tools specified in your settings file
• current compatibility table between project mode and simulator

playhdl info

Developer guide

Install poetry

python -m pip install -U poetry

Setup virtual environment

make setup-dev

You can specify Python version to use

make setup-dev PYTHON_VERSION=3.9

To run playhdl from sources

poetry run playhdl <args>

Makefile provides additional ways to interact with project:

• make format - auto-format all sources
• make check-format - check current formatting of sources
• make lint - perform linting
• make type - perform type checking
• make test - run all tests
• make pre-commit - shorthand for combination of check-format, lint, type, test

Miscellaneous

Offline install

For an offline install you have several options of how to get wheel:

• build locally using poetry

python -m pip install -U poetry
poetry build

• download .whl from PyPi

python -m pip download playhdl

Then you can use pip to install it on an offline machine:

python -m pip install <wheel_file_name>.whl