1PyMTL 3 (Mamba) 2========================================================================== 3 4[![Github Action](https://github.com/pymtl/pymtl3/actions/workflows/python-package-ci.yml/badge.svg)](https://github.com/pymtl/pymtl3/actions/workflows/python-package-ci.yml) 5[![Documentation Status](https://readthedocs.org/projects/pymtl3/badge/?version=latest)](https://pymtl3.readthedocs.io/en/latest/?badge=latest) 6[![Codecov Status](https://codecov.io/gh/pymtl/pymtl3/branch/master/graph/badge.svg)](https://codecov.io/gh/pymtl/pymtl3) 7 8PyMTL 3 (Mamba) is the latest version of PyMTL, an open-source 9Python-based hardware generation, simulation, and verification framework with 10multi-level hardware modeling support. The original PyMTL was introduced 11at MICRO-47 in December, 2014. Please note that PyMTL 3 is currently 12**beta** software that is under active development and documentation is 13currently quite sparse. 14 15In June 2019, [Keeping Computer Hardware Fast and Furious: "PyMTL is a fantastic example of what we need to jump-start the open-source hardware ecosystem…It’s a key missing link."](https://research.cornell.edu/news-features/keeping-computer-hardware-fast-and-furious "Link to the article") was featured on Cornell Research. 16 17User Forum 18---------- 19We recommend the user to post on https://groups.google.com/forum/#!forum/pymtl-users to ask questions about using PyMTL 3. The github issues are reserved for development purposes, e.g., bug reports and feature requests. 20 21Related publications 22-------------------------------------------------------------------------- 23 24- Shunning Jiang, Christopher Torng, and Christopher Batten. _"An Open-Source Python-Based Hardware Generation, Simulation, and Verification Framework."_ First Workshop on Open-Source EDA Technology (WOSET'18) held in conjunction with ICCAD-37, Nov. 2018. 25 26- Shunning Jiang, Berkin Ilbeyi, and Christopher Batten. _"Mamba: Closing the Performance Gap in Productive Hardware Development Frameworks."_ 55th ACM/IEEE Design Automation Conf. (DAC-55), June 2018. 27 28- Derek Lockhart, Gary Zibrat, and Christopher Batten. _"PyMTL: A Unified Framework for Vertically Integrated Computer Architecture Research."_ 47th ACM/IEEE Int'l Symp. on Microarchitecture (MICRO-47), Dec. 2014. 29 30License 31-------------------------------------------------------------------------- 32 33PyMTL is offered under the terms of the Open Source Initiative BSD 343-Clause License. More information about this license can be found here: 35 36 - http://choosealicense.com/licenses/bsd-3-clause 37 - http://opensource.org/licenses/BSD-3-Clause 38 39Installation 40------------ 41 42The steps for installing these prerequisites and PyMTL on a fresh Ubuntu 43distribution are shown below. They have been tested with Ubuntu Xenial 18.04. 44 45### Install PyMTL 3 46 47 48**tl; dr** ```pip install pymtl3``` 49 50---- 51 52PyMTL 3 requires Python 3.6+. We highly recommend you work inside a **virtual environment** instead of calling ```sudo pip install```. Starting from Python 3.5, the use of venv is now recommended for creating virtual environments. 53 54``` 55 $ cd <path to where venvs are stored> 56 $ python3 -m venv pymtl3 # you can use whatever Python 3.6+ binary you have 57 $ source pymtl3/bin/activate 58``` 59PyMTL 3 needs to use cffi, so install these packages first. 60 61``` 62 $ sudo apt-get install git python-dev libffi-dev 63``` 64 65PyMTL 3 is available on pypi.org. As a result, you are able to just call ```pip install pymtl3``` to install PyMTL 3. 66 67``` 68 $ pip install pymtl3 69``` 70 71When you relaunch the bash session, you need to re-enable the venv. 72 73``` 74 $ source <path to where venvs are stored>/pymtl3/bin/activate 75``` 76 77When you're done testing/developing but you don't want to close the terminal, you can deactivate the virtualenv: 78 79``` 80 $ deactivate 81``` 82 83 84Additional dependencies include ```verilator```(and ```pkg-config```) when you want to integrate SystemVerilog blackbox into your PyMTL simulation. 85 86### Install Verilator 87 88[Verilator](http://www.veripool.org/wiki/verilator) is an open-source toolchain for compiling SystemVerilog RTL 89models into C++ simulators. You can install Verilator using the 90standard package manager but the version available in the package 91repositories is several years old. This means you will need to build and 92install Verilator from source using the following commands: 93 94``` 95 $ sudo apt-get install git make autoconf g++ libfl-dev bison 96 $ mkdir -p ${HOME}/src 97 $ cd ${HOME}/src 98 $ wget http://www.veripool.org/ftp/verilator-4.036.tgz 99 $ tar -xzvf verilator-4.036.tgz 100 $ cd verilator-4.036 101 $ ./configure 102 $ make 103 $ sudo make install 104``` 105 106Verify that Verilator is on your path as follows: 107 108``` 109 $ cd $HOME 110 $ which verilator 111 $ verilator --version 112``` 113 114PyMTL uses `pkg-config` to find the Verilator source files when 115integrating SystemVerilog blackbox. Install 116`pkg-config` and verify that it is setup correctly as follows: 117 118``` 119 $ sudo apt-get install pkg-config 120 $ pkg-config --print-variables verilator 121``` 122 123If `pkg-config` cannot find information about verilator, then you can 124also explicitly set the following special environment variable: 125 126``` 127 $ export PYMTL_VERILATOR_INCLUDE_DIR="/usr/local/share/verilator/include" 128``` 129 130