PyMTL is an open-source, Python-based framework for multi-level hardware modeling. It was introduced at MICRO-47 in December, 2014. Please note that PyMTL is currently alpha software that is under active development and documentation is currently quite sparse. We have recently received funding from the National Science Foundation under Award #1512937 to improve PyMTL performance, documentation, and reference models. Please stay tuned over the next few months.
Cornell ECE 4750
Cornell ECE 4750 students should note that we are using the PyMTL version on the ece4750 branch. If you would like to browse the PyMTL source code or install PyMTL on your own machine you must use the ece4750 branch.
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. Note that to complete these tutorials you will need to install the PyMTL version on the ece4750 branch.
- http://www.csl.cornell.edu/courses/ece4750/handouts/ece4750-tut3-pymtl.pdf
- http://www.csl.cornell.edu/courses/ece4750/handouts/ece4750-tut4-verilog.pdf
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:
Publications
If you use PyMTL in your research, please cite our MICRO'15 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
- 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. The following commands will build and install Verilator from source:
% sudo apt-get install git make autoconf g++ flex bison
% mkdir -p ${HOME}/src
% cd ${HOME}/src
% wget http://www.veripool.org/ftp/verilator-3.876.tgz
% tar -xzvf verilator-3.876
% cd verilator-3.876
% ./configure
% make
% sudo make install
% export PYMTL_VERILATOR_INCLUDE_DIR="/usr/local/share/verilator/include"
The PYMTL_VERILATOR_INCLUDE_DIR
environment variable is used to tell
PyMTL where to find the various Verilator source files when performing
both Verilog translation and Verilog import.
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 git+https://github.com/cornell-brg/pymtl.git
% pip install --editable ./pymtl
NOTE: If you are a Cornell ECE 4750 student and setting up your own development environment, you must install the ece4750 branch like this:
% mkdir -p ${HOME}/vc/git-hub/cornell-brg
% cd ${HOME}/vc/git-hub/cornell-brg
% git clone git+https://github.com/cornell-brg/pymtl.git@ece4750
% pip install --editable ./pymtl
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