Skip to main content

playhdl

Tests & Checks PyPI version

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:

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

Metadata

Release files for playhdl 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for playhdl 0.2.1
File Size Uploaded Provenance Actions
playhdl-0.2.1.tar.gz 15.3 kB Without provenance Details for playhdl-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for playhdl 0.2.1
File Interpreter ABI Platform Actions
playhdl-0.2.1-py3-none-any.whl Python 3 none any Details for playhdl-0.2.1-py3-none-any.whl

Total release size: 31.8 kB

Release files / playhdl-0.2.1.tar.gz

Download URL playhdl-0.2.1.tar.gz
Size 15.3 kB
Tags Source
SHA-256 checksum
How to use checksums
958bafc4a2b9c4b0ae52d284ea988840599af8f51737cf86899ac756180607d7
BLAKE2b-256 checksum
How to use checksums
c82cbbb623bc1570f9a5ad19fc88a060a59c8e8387228d41b64bc34aafb1e7b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.3.1 CPython/3.8.15 Linux/5.15.0-1024-azure

Release files / playhdl-0.2.1-py3-none-any.whl

Download URL playhdl-0.2.1-py3-none-any.whl
Size 16.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
166740c40a8b086fb618d80d36057430dfaa96e2c8e3c4b0ae68328db96c5b2c
BLAKE2b-256 checksum
How to use checksums
f32f93e5a143aa91b7da940243358f79e82aaa81ed7239913a1066499597b5d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.3.1 CPython/3.8.15 Linux/5.15.0-1024-azure

Security for playhdl 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page