PyMTL4.0 Release

.coveragerc

@@ -0,0 +1,4 @@
+# Disable warnings about could not parsing files because PyMTL generates
+# code (especially for update blocks) on the fly.
+[run]
+disable_warnings = couldnt-parse

.github/workflows/python-package-ci.yml

@@ -23,26 +23,39 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ 3.6, 3.7, 3.8, 3.9 ] # FIXME github recognizes 3.10 as 3.1 lol
+        python-version: [ "3.7", "3.8", "3.9", "3.10", "3.11", "3.12" ]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
     - name: Install Verilator
       run: |
-        wget https://github.com/cornell-brg/verilator-travisci-cache/raw/master/verilator-travis-4.036.tar.gz
-        tar -C ${HOME} -xzf verilator-travis-4.036.tar.gz
+        wget https://github.com/cornell-brg/verilator-travisci-cache/raw/master/verilator-github-actions-5.016.tar.gz
+        tar -C ${HOME} -xzf verilator-github-actions-5.016.tar.gz
+        # We need to create a symlink to verilator/share/verilator/include.
+        # This is because the Verilator binaries are compiled on an EC2
+        # instance, and that the executable contains hard-coded paths which can
+        # only be bypassed by defining $VERILATOR_ROOT. See a similar issue at:
+        # https://github.com/verilator/verilator/issues/4035
+        # But when $VERILATOR_ROOT is present, Verilator assumes a different
+        # directory hierarchy by looking into $VERILATOR_ROOT/include, which is
+        # different from verilator/share/verilator/include. Verilator devs have
+        # mentioned this will be annoying to fix and I don't quite understand
+        # why; my current workaround is to symlink the correct include
+        # directory into the place Verilator is looking at.
+        ln -s ${HOME}/verilator/share/verilator/include ${HOME}/verilator/include
         echo "VERILATOR_ROOT=${HOME}/verilator" >> $GITHUB_ENV
         echo "PYMTL_VERILATOR_INCLUDE_DIR=${HOME}/verilator/share/verilator/include" >> $GITHUB_ENV
         echo "${HOME}/verilator/bin" >> $GITHUB_PATH
 
     - name: Check Verilator
       run: |
         echo ${VERILATOR_ROOT}
+        ls ${VERILATOR_ROOT}/include
         echo ${PYMTL_VERILATOR_INCLUDE_DIR}
         verilator --version
 
@@ -55,8 +68,17 @@ jobs:
 
     - name: Test with pytest
       run: |
-        mkdir build && cd build
-        pytest --cov-report xml --cov=pymtl3 .. --tb=short --hypothesis-profile CI
+        mkdir -p build && cd build
+        # Run all unit tests under pymtl3 directory except for those in the
+        # yosys backend (we run yosys tests in the second run). This is
+        # necessary to avoid using the same component name for different
+        # shared libraries (Verilog and Yosys backend translation result).
+        pytest --cov-config=../.coveragerc --cov-report xml --cov=pymtl3 \
+            ../pymtl3 --ignore=../pymtl3/passes/backends/yosys --tb=short \
+            --hypothesis-profile CI
+        pytest --cov-config=../.coveragerc --cov-report xml --cov=pymtl3 --cov-append \
+            ../pymtl3/passes/backends/yosys --tb=short \
+            --hypothesis-profile CI
 
     - name: Upload code coverage report
       run: |

.gitignore

@@ -7,6 +7,7 @@
 # still have it appear clean to git.
 
 build*/
+dist/
 autom4te.cache/
 .pytest_cache/
 *__pycache__

README.md

@@ -95,9 +95,9 @@ 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.036.tgz
- $ tar -xzvf verilator-4.036.tgz
- $ cd verilator-4.036
+ $ git clone https://github.com/verilator/verilator.git
+ $ cd verilator
+ $ git checkout v5.016
  $ ./configure
  $ make
  $ sudo make install

examples/ex02_cksum/ChecksumRTL.py

@@ -11,8 +11,8 @@
   Date : June 6, 2019
 """
 from pymtl3 import *
-from pymtl3.stdlib.ifcs import RecvIfcRTL, SendIfcRTL
-from pymtl3.stdlib.queues import PipeQueueRTL
+from pymtl3.stdlib.stream.ifcs import IStreamIfc, OStreamIfc
+from pymtl3.stdlib.stream import StreamPipeQueue
 
 #-------------------------------------------------------------------------
 # Step unit
@@ -55,26 +55,26 @@ def construct( s ):
 
     # Interface
 
-    s.recv  = RecvIfcRTL( Bits128 )
-    s.send  = SendIfcRTL( Bits32  )
+    s.istream = IStreamIfc( Bits128 )
+    s.ostream = OStreamIfc( Bits32  )
 
     # Component
 
     s.words = [ Wire( Bits16 ) for _ in range( 8 ) ]
     s.sum1  = Wire( Bits32 )
     s.sum2  = Wire( Bits32 )
 
-    s.in_q  = PipeQueueRTL( Bits128, num_entries=1 )
+    s.in_q  = StreamPipeQueue( Bits128, num_entries=1 )
     s.steps = [ StepUnit() for _ in range( 8 ) ]
 
     # Register input
 
-    connect( s.recv, s.in_q.enq )
+    connect( s.istream, s.in_q.istream )
 
     # Decompose input message into 8 words
 
     for i in range( 8 ):
-      s.words[i] //= s.in_q.deq.ret[i*16:(i+1)*16]
+      s.words[i] //= s.in_q.ostream.msg[i*16:(i+1)*16]
 
     # Connect step units
 
@@ -91,14 +91,14 @@ def construct( s ):
     s.sum2 //= s.steps[-1].sum2_out
 
     @update
-    def up_rtl_send():
-      go = s.in_q.deq.rdy & s.send.rdy
-      s.send.en     @= go
-      s.in_q.deq.en @= go
+    def up_rtl_ostream():
+      go = s.in_q.ostream.val & s.ostream.rdy
+      s.ostream.val @= go
+      s.in_q.ostream.rdy @= go
 
     @update
     def up_rtl_sum():
-      s.send.msg @= ( s.sum2 << 16 ) | s.sum1
+      s.ostream.msg @= ( s.sum2 << 16 ) | s.sum1
 
   def line_trace( s ):
-    return "{}(){}".format( s.recv, s.send )
+    return "{}(){}".format( s.istream, s.ostream )

examples/ex02_cksum/cksum-translate

@@ -3,9 +3,9 @@
 # cksum-translate [options]
 #=========================================================================
 # This script imports the RTL checksum unit from ChecksumRTL.py and
-# translate it into yosys-compatible SystemVerilog. The generated
-# SystemVerilog file will be dumped into the current directory ( if no
-# output directory is specified ) or the specified output directory.
+# translate it into SystemVerilog. The generated SystemVerilog file will
+# be dumped into the current directory ( if no output directory is
+# specified ) or the specified output directory.
 #
 #  -h --help           Display this message
 #
@@ -18,8 +18,8 @@ import argparse
 import os
 import sys
 
-# Import the translation pass from yosys backend
-from pymtl3.passes.backends.yosys import YosysTranslationPass
+# Import the translation pass from verilog backend
+from pymtl3.passes.backends.verilog import VerilogTranslationPass
 
 # Hack to add project root to python path
 cur_dir = os.path.dirname( os.path.abspath( __file__ ) )
@@ -82,20 +82,20 @@ def main():
 
   # Tag the checksum unit as to be translated
 
-  cksum.set_metadata( YosysTranslationPass.enable, True )
+  cksum.set_metadata( VerilogTranslationPass.enable, True )
 
   # Perform translation
 
   success = False
 
   try:
     cksum.elaborate()
-    cksum.apply( YosysTranslationPass() )
+    cksum.apply( VerilogTranslationPass() )
     success = True
   finally:
     if success:
       path = os.getcwd() + \
-             f"/{cksum.get_metadata(YosysTranslationPass.translated_filename)}"
+             f"/{cksum.get_metadata(VerilogTranslationPass.translated_filename)}"
       print("\nTranslation finished successfully!")
       print(f"You can find the generated SystemVerilog file at {path}.")
     else: