python2verilog 0.5.0

Converts a subset of python generator functions into synthesizable sequential SystemVerilog

python2verilog

• This tool facilitates the conversion of select Python functions (including generators!) into synthesizable sequential SystemVerilog
• Ideal for quickly translating higher-level "CPU code" into hardware descriptions for use on FPGAs, without needing to interface with or including a CPU in the design
• Testbenches can be automatically generated if the user uses the function within their Python code or provides explicit test cases

from python2verilog import verilogify

@verilogify
def hrange(base, limit, step):
    i = base
    while i < limit:
        yield i
        i += step
print(list(hrange(0, 10, 3)))

A live transpile demo can be found here.

Specifications

Some constrains on Python functions include:

• Supports only signed integral input/output and operations
• Must be a pure function

Unsupported Python paradigms include but are not limited to the following:

• Global (nonlocal) variables, instead declare them within the function with minimal overhead
• Keyword parameters and default arguments, instead use explicit positional arguments

Usage and Installation

Try it in Google Collab or check out examples/!

python3 -m pip install --upgrade pip

python3 -m pip install python2verilog

Tested Generations

You may find the output of the integration testing as a Github Artifact available for download.

For Developers

To setup pre-commit, run pre-commit install.

Github Issues are used for tracking.

Sphinx is used for the docs. Follow the sphinx workflow to generate a local copy.

Development

Setup

For most up-to-date information, refer to the pytest workflow or the packaging workflow.

A Ubuntu environment (WSL2 works too, make sure to have the repo on the Ubuntu partition, as os.mkfifo is used to avoid writing to disk)

Steps

source ./build.sh venv
./build.sh all
pre-commit install

For automatic Verilog simulation and testing, install Icarus Verilog and its dependencies with

sudo apt install expect
# This adds `iverilog` to PATH
git submodule update --init
./extern/iverilog_setup.sh

The online simulator EDA Playground can be used as a subsitute if you manually copy-paste the module and testbench files to it.

Running Tests

Run Python tests with pytest. Run rust tests with cargo test.

CLI arguments for test configuration can be found in tests/conftest.py.

Use ./clean.sh to remove gitignored and generated files.

Troubleshooting

cargo test Errors

• error: linker `cc` not found
  • On Ubuntu run sudo apt install build-essential
• /usr/bin/ld: cannot find -lpython3.10: No such file or directory
  • On Ubuntu 22.04 run sudo apt install libpython3.10-dev

Flamegraph

cargo install flamegraph

sudo apt install linux-tools-common linux-tools-generic linux-tools-`uname -r`

sudo sysctl kernel.perf_event_paranoid=0

CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph --unit-test tohdl-tests -- verilog::module::test::odd_fib
CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph --test loops

Will need to set PERF env var for flamegraph if running in WSL from this stackoverflow answer.