PyMTL is an open-source, Python-based framework for multi-level hardware modeling. It was introduced at MICRO-47 in December, 2014.

DEPRECATION NOTE: We will not be maintaining this PyMTL version 2 repo. We are instead working very hard on the new PyMTL3 version 3 repo pymtl3. PyMTLv3 has been significantly rewritten to improve both the performance and productivity of FL, CL, and RTL modeling. While we will still provide limited support for PyMTLv2, we encourage new users to start experimenting with PyMTLv3. Also note that PyMTLv2 only works with Python 2.7 (which will not be maintained past January 1, 2020). PyMTLv3 takes advantage of many new and exciting Python 3.6+ features.

Tutorials

If you are interested in learning more about the PyMTL framework, we recommend you take a look at two tutorials that have been developed for Cornell ECE 4750. This is a course on computer architecture targeting seniors and first-year graduate students. Throughout the semester, students gradually design, implement, test, and evaluate a basic multicore system capable of running simple parallel applications at the register-transfer level. This year, students are using the PyMTL framework for all functional-level modeling and testing. Students have the option of using PyMTL or Verilog for the RTL design portion of the lab assignments. The first tutorial focuses on the PyMTL framework, while the second tutorial illustrates how PyMTL's Verilog import feature can enable applying PyMTL's powerful functional-level and testing features to RTL designs written in Verilog.

• PyMTL Hardware Modeling Framework Tutorial (github)
• Verilog Hardware Description Language Tutorial (github)

We have also developed tutorials specifically on PyMTL CL modeling, integrating PyMTL with the Xilinx Vivado High-Level Synthesis (HLS) tool, and using PyMTL to drive a Synopys-based ASIC EDA toolflow.

• PyMTL CL Modeling Tutorial (github)
• PyMTL/HLS Tutorial (github)
• PyMTL-Based ASIC Toolflow Tutorial

License

PyMTL is offered under the terms of the Open Source Initiative BSD 3-Clause License. More information about this license can be found here:

• http://choosealicense.com/licenses/bsd-3-clause
• http://opensource.org/licenses/BSD-3-Clause

Publications

If you use PyMTL in your research, please cite our MICRO'14 paper:

  @inproceedings{lockhart-pymtl-micro2014,
    title     = {PyMTL: A Unified Framework for Vertically Integrated
                 Computer Architecture Research},
    author    = {Derek Lockhart and Gary Zibrat and Christopher Batten},
    booktitle = {47th IEEE/ACM Int'l Symp. on Microarchitecture (MICRO)},
    month     = {Dec},
    year      = {2014},
    pages     = {280--292},
    doi       = {10.1109/MICRO.2014.50},
  }

Installation

PyMTL requires Python2.7 and has the following additional prerequisites:

• verilator, pkg-config
• git, Python headers, and libffi
• virtualenv

The steps for installing these prerequisites and PyMTL on a fresh Ubuntu distribution are shown below. They have been tested with Ubuntu Trusty 14.04.

Install Verilator

Verilator is an open-source toolchain for compiling Verilog RTL models into C++ simulators. PyMTL uses Verilator for both Verilog translation and Verilog import. You can install Verilator using the standard package manager but the version available in the package repositories is several years old. This means you will need to build and install Verilator from source using the following commands:

 % sudo apt-get install git make autoconf g++ libfl-dev bison
 % mkdir -p ${HOME}/src
 % cd ${HOME}/src
 % wget http://www.veripool.org/ftp/verilator-4.008.tgz
 % tar -xzvf verilator-4.008.tgz
 % cd verilator-4.008
 % ./configure
 % make
 % sudo make install

Verify that Verilator is on your path as follows:

 % cd $HOME
 % which verilator
 % verilator --version

PyMTL uses pkg-config to find the Verilator source files when performing both Verilog translation and Verilog import. Install pkg-config and verify that it is setup correctly as follows:

 % sudo apt-get install pkg-config
 % pkg-config --print-variables verilator

If pkg-config cannot find information about verilator, then you can also explicitly set the following special environment variable:

 % export PYMTL_VERILATOR_INCLUDE_DIR="/usr/local/share/verilator/include"

Install git, Python headers, and libffi

We need to install the Python headers and libffi in order to be able to install the cffi Python package. cffi provides an elegant way to call C functions from Python, and PyMTL uses cffi to call C code generated by Verilator. We will use git to grab the PyMTL source. The following commands will install the appropriate packages:

 % sudo apt-get install git python-dev libffi-dev

Install virtualenv

While not strictly necessary, we strongly recommend using virtualenv to install PyMTL and the Python packages that PyMTL depends on. virtualenv enables creating isolated Python environments. The following commands will install virtualenv:

 % sudo apt-get install python-virtualenv

Now we can use the virtualenv command to create a new virtual environment for PyMTL, and then we can use the corresponding activate script to activate the new virtual environment:

 % mkdir ${HOME}/venvs
 % virtualenv --python=python2.7 ${HOME}/venvs/pymtl
 % source ${HOME}/venvs/pymtl/bin/activate

Install PyMTL

We can now use git to clone the PyMTL repo, and pip to install PyMTL and its dependencies. Note that we use pip in editable mode so that we can actively work in the PyMTL git repo.

 % mkdir -p ${HOME}/vc/git-hub/cornell-brg
 % cd ${HOME}/vc/git-hub/cornell-brg
 % git clone https://github.com/cornell-brg/pymtl.git
 % pip install --editable ./pymtl
 % pip install --upgrade pytest

Testing

Before running any tests, we first create a build directory inside the PyMTL repo to hold any temporary files generated during simulation:

 % mkdir -p ${HOME}/vc/git-hub/cornell-brg/pymtl/build
 % cd ${HOME}/vc/git-hub/cornell-brg/pymtl/build

All Python simulation tests can be easily run using py.test (warning: there are a lot of tests!):

 % py.test ..

The Verilog simulation tests are only executed if the --test-verilog flag is provided. For Verilog testing to work, PyMTL requires that Verilator is on your PATH and that the PYMTL_VERILATOR_INCLUDE_DIR environment:

 % py.test .. --test-verilog

When you're done testing/developing, you can deactivate the virtualenv::

 % deactivate