Merge branch 'development' of https://github.com/UCSBarchlab/PyRTL into development

Author: timsherwood

pyrtl/__init__.py

@@ -92,6 +92,7 @@
 from .visualization import net_graph
 
 # import from and export to file format routines
+from .importexport import input_from_verilog
 from .importexport import output_to_verilog
 from .importexport import OutputToVerilog
 from .importexport import output_verilog_testbench

pyrtl/compilesim.py

@@ -137,7 +137,7 @@ def step_multiple(self, provided_inputs={}, expected_outputs={}, nsteps=None,
 
         :param provided_inputs: a dictionary mapping wirevectors to their values for N steps
         :param expected_outputs: a dictionary mapping wirevectors to their expected values
-            for N steps
+            for N steps; use '?' to indicate you don't care what the value at that step is
         :param nsteps: number of steps to take (defaults to None, meaning step for each
             supplied input value)
         :param file: where to write the output (if there are unexpected outputs detected)
@@ -214,7 +214,10 @@ def step_multiple(self, provided_inputs={}, expected_outputs={}, nsteps=None,
             self.step({w: int(v[i]) for w, v in provided_inputs.items()})
 
             for expvar in expected_outputs.keys():
-                expected = int(expected_outputs[expvar][i])
+                expected = expected_outputs[expvar][i]
+                if expected == '?':
+                    continue
+                expected = int(expected)
                 actual = self.inspect(expvar)
                 if expected != actual:
                     failed.append((i, expvar, expected, actual))

pyrtl/corecircuits.py

@@ -436,7 +436,10 @@ def bitfield_update(w, range_start, range_end, newvalue, truncating=False):
         w = bitfield_update(w, 20, 23, 0x7)  # sets bits 20, 21, 22 to 1
         w = bitfield_update(w, 20, 23, 0x6)  # sets bit 20 to 0, bits 21 and 22 to 1
         w = bitfield_update(w, 20, None, 0x7)  # assuming w is 32 bits, sets bits 31..20 = 0x7
-        w = bitfield_update(w, -1, None, 0x1)  # set the LSB (bit) to 1
+        w = bitfield_update(w, -1, None, 0x1)  # set the MSB (bit) to 1
+        w = bitfield_update(w, None, -1, 0x9)  # set the bits before the MSB (bit) to 9
+        w = bitfield_update(w, None, 1, 0x1)  # set the LSB (bit) to 1
+        w = bitfield_update(w, 1, None, 0x9)  # set the bits after the LSB (bit) to 9
     """
     from .corecircuits import concat_list
 
@@ -482,8 +485,8 @@ def bitfield_update_set(w, update_set, truncating=False):
         w = bitfield_update_set(w, {
                 (20, 23):    0x6,      # sets bit 20 to 0, bits 21 and 22 to 1
                 (26, None):  0x7,      # assuming w is 32 bits, sets bits 31..26 to 0x7
-                (-1, None):  0x0       # set the LSB (bit) to 0
-                })
+                (None, 1):   0x0,      # set the LSB (bit) to 0
+            })
     """
     w = as_wires(w)
     # keep a list of bits that are updated to find overlaps

pyrtl/importexport.py

@@ -9,11 +9,16 @@
 from __future__ import print_function, unicode_literals
 import re
 import collections
+import tempfile
+import os
+import subprocess
+import six
+import sys
 
 from .pyrtlexceptions import PyrtlError, PyrtlInternalError
 from .core import working_block, _NameSanitizer
 from .wire import WireVector, Input, Output, Const, Register, next_tempvar_name
-from .corecircuits import concat_list
+from .corecircuits import concat_list, rtl_all, rtl_any
 from .memory import RomBlock
 from .passes import two_way_concat, one_bit_selects
 
@@ -108,10 +113,11 @@ def input_from_blif(blif, block=None, merge_io_vectors=True, clock_name='clk', t
     wires will be Input wires of the block. This holds similarly for Outputs.
 
     This assumes the following:
-      * The BLIF has been flattened and there is only a single module
       * There is only one single shared clock and reset
       * Output is generated by Yosys with formals in a particular order
 
+    It currently supports multi-module (unflattened) BLIF, though we recommend importing a
+    flattened BLIF with a single module when possible.
     It currently ignores the reset signal (which it assumes is input only to the flip flops).
     """
     import pyparsing
@@ -315,26 +321,42 @@ def twire(w):
         elif command['cover_list'].asList() == ['11', '1']:
             output_wire = twire(netio[2])
             output_wire <<= twire(netio[0]) & twire(netio[1])  # and gate
-        elif command['cover_list'].asList() == ['00', '1']:
-            output_wire = twire(netio[2])
-            output_wire <<= ~ (twire(netio[0]) | twire(netio[1]))  # nor gate
         elif command['cover_list'].asList() == ['1-', '1', '-1', '1']:
             output_wire = twire(netio[2])
             output_wire <<= twire(netio[0]) | twire(netio[1])  # or gate
+        elif command['cover_list'].asList() == ['0-', '1', '-0', '1']:
+            output_wire = twire(netio[2])
+            output_wire <<= twire(netio[0]).nand(twire(netio[1]))  # nand gate
         elif command['cover_list'].asList() == ['10', '1', '01', '1']:
             output_wire = twire(netio[2])
             output_wire <<= twire(netio[0]) ^ twire(netio[1])  # xor gate
-        elif command['cover_list'].asList() == ['1-0', '1', '-11', '1']:
-            output_wire = twire(netio[3])
-            output_wire <<= (twire(netio[0]) & ~ twire(netio[2])) \
-                | (twire(netio[1]) & twire(netio[2]))   # mux
-        elif command['cover_list'].asList() == ['-00', '1', '0-0', '1']:
-            output_wire = twire(netio[3])
-            output_wire <<= (~twire(netio[1]) & ~twire(netio[2])) \
-                | (~twire(netio[0]) & ~twire(netio[2]))
         else:
-            raise PyrtlError('Blif file with unknown logic cover set "%s"'
-                             '(currently gates are hard coded)' % command['cover_list'])
+            # Although the following is fully generic and thus encompasses all of the
+            # special cases after the simple wire case above, we leave the above in because
+            # they are commonly found and lead to a slightly cleaner (though equivalent) netlist,
+            # because we can use nand/xor primitives, or avoid the extra fluff of concat/select
+            # wires that might be created implicitly as part of rtl_all/rtl_any.
+            def convert_val(ix, val):
+                wire = twire(netio[ix])
+                if val == '0':
+                    wire = ~wire
+                return wire
+
+            cover = command['cover_list'].asList()
+            output_wire = twire(netio[-1])
+            conjunctions = []
+            while cover:
+                if len(cover) < 2:
+                    raise PyrtlError('BLIF file with malformed cover set "%s" '
+                                     % command['cover_list'])
+                input_plane, output_plane, cover = cover[0], cover[1], cover[2:]
+                if output_plane != '1':
+                    raise PyrtlError('Off-set found in the output plane of BLIF cover set "%s" '
+                                     '(only on-sets are supported)' % command['cover_list'])
+                conj = rtl_all(*[convert_val(ix, val) for ix, val
+                                 in enumerate(input_plane) if val != '-'])
+                conjunctions.append(conj)
+            output_wire <<= rtl_any(*conjunctions)
 
     def extract_flop(subckt, command):
 
@@ -411,6 +433,89 @@ def instantiate(subckt):
 #
 
 
+def input_from_verilog(verilog, clock_name='clk', toplevel=None, leave_in_dir=None, block=None):
+    """ Read an open Verilog file or string as input via Yosys conversion, updating the block.
+
+    :param verilog: An open Verilog file to read
+    :param clock_name: The name of the clock (defaults to 'clk')
+    :param toplevel: Name of top-level module to instantiate; if None, defaults to first model
+        defined in the Verilog file
+    :param bool leave_in_dir: If True, save the intermediate BLIF file created in
+        the given directory
+    :param block: The block where the logic will be added
+
+    Note: This function is essentially a wrapper for `input_from_blif()`, with the added convenience
+    of turning the Verilog into BLIF for import for you. This function passes a set of commands to
+    Yosys as a script that normally produces BLIF files that can be successuflly imported into
+    PyRTL via `input_from_blif()`. If the Yosys conversion fails here, we recommend you create your
+    own custom Yosys script to try and produce BLIF yourself.  Then you can import BLIF directly via
+    `input_from_blif()`.
+    """
+
+    # Dev Notes:
+    # 1) We pass in an open file or string to keep the same API as input_from_blif (even though
+    #    we are essentially putting that Verilog code back in a file for Yosys to operate on).
+    # 2) The Yosys script does not have a call to `flatten`, since we now have support for
+    #    multi-module BLIFs. `flatten` replaces the .subckt (i.e. the module inclusions) with their
+    #    actual contents, so if things aren't working for some reason, add this command for help.
+    # 3) The Yosys script *does* have a call to `setundef -zero -undriven`, which we use to set
+    #    undriven nets to 0; we do this so PyRTL doesn't complain about used but undriven wires.
+
+    try:
+        verilog_string = verilog.read()
+    except AttributeError:
+        if isinstance(verilog, six.string_types):
+            verilog_string = verilog
+        else:
+            raise PyrtlError('input_from_verilog expecting either open file or string')
+
+    block = working_block(block)
+
+    # Create a temporary Verilog file
+    temp_vd, tmp_verilog_path = tempfile.mkstemp(prefix='pyrtl_verilog', suffix='.v',
+                                                 dir=leave_in_dir, text=True)
+    with open(tmp_verilog_path, 'w') as f:
+        f.write(verilog_string)
+
+    # Create a temporary BLIF file
+    temp_bd, tmp_blif_path = tempfile.mkstemp(prefix='pyrtl_blif', suffix='.blif',
+                                              dir=leave_in_dir, text=True)
+
+    yosys_arg_template = (
+        "-p "
+        "read_verilog %s; "
+        "synth %s; "
+        "setundef -zero -undriven; "
+        "opt; "
+        "write_blif %s; "
+    )
+
+    yosys_arg = yosys_arg_template % (tmp_verilog_path,
+                                      ('-top ' + toplevel) if toplevel is not None else '-auto-top',
+                                      tmp_blif_path)
+
+    try:
+        os.close(temp_vd)
+        os.close(temp_bd)
+        # call yosys on the script, and grab the output
+        _yosys_output = subprocess.check_output(['yosys', yosys_arg])
+        with open(tmp_blif_path) as blif:
+            input_from_blif(blif, block=block, clock_name=clock_name, top_model=toplevel)
+    except (subprocess.CalledProcessError, ValueError) as e:
+        print('Error with call to yosys...', file=sys.stderr)
+        print('---------------------------------------------', file=sys.stderr)
+        print(str(e.output).replace('\\n', '\n'), file=sys.stderr)
+        print('---------------------------------------------', file=sys.stderr)
+        raise PyrtlError('Yosys callfailed')
+    except OSError as e:
+        print('Error with call to yosys...', file=sys.stderr)
+        raise PyrtlError('Call to yosys failed (not installed or on path?)')
+    finally:
+        os.remove(tmp_verilog_path)
+        if leave_in_dir is None:
+            os.remove(tmp_blif_path)
+
+
 def output_to_verilog(dest_file, add_reset=True, block=None):
     """ A function to walk the block and output it in Verilog format to the open file.
 
@@ -432,6 +537,11 @@ def output_to_verilog(dest_file, add_reset=True, block=None):
     file = dest_file
     internal_names = _VerilogSanitizer('_ver_out_tmp_')
 
+    if add_reset:  # True or 'asynchronous'
+        if block.get_wirevector_by_name('rst') is not None:
+            raise PyrtlError("Found a user-defined wire named 'rst'. Pass in "
+                             "'add_reset=False' to use your existing reset logic.")
+
     for wire in block.wirevector_set:
         internal_names.make_valid_string(wire.name)
 
@@ -672,7 +782,7 @@ def _to_verilog_footer(file):
 
 
 def output_verilog_testbench(dest_file, simulation_trace=None, toplevel_include=None,
-                             vcd="waveform.vcd", cmd=None, block=None):
+                             vcd="waveform.vcd", cmd=None, add_reset=True, block=None):
     """ Output a Verilog testbench for the block/inputs used in the simulation trace.
 
     :param dest_file: an open file to which the test bench will be printed.
@@ -692,6 +802,16 @@ def output_verilog_testbench(dest_file, simulation_trace=None, toplevel_include=
         specific values out during testbench evaluation (e.g. cmd='$display("%d", out);'
         will instruct the testbench to print the value of 'out' every cycle which can then
         be compared easy with a reference).
+    :param add_reset: If reset logic should be added. Allowable options are:
+        False (meaning no reset logic is added), True (default, for adding synchronous
+        reset logic), and 'asynchronous' (for adding asynchronous reset logic).
+        The value passed in here should match the argument passed to `output_to_verilog()`.
+    :param block: Block containing design to test.
+
+    If `add_reset` is not False, a `rst` wire is added and will passed as an input to the
+    instantiated toplevel module. The `rst` wire will be held low in the testbench, because
+    initialization here occurs via the `initial` block. It is provided for consistency with
+    `output_to_verilog()`.
 
     The test bench does not return any values.
 
@@ -707,8 +827,18 @@ def output_verilog_testbench(dest_file, simulation_trace=None, toplevel_include=
             output_verilog_testbench(fp, sim.tracer, vcd=None, cmd='$display("%d", out);')
 
     """
+    if not isinstance(add_reset, bool):
+        if add_reset != 'asynchronous':
+            raise PyrtlError("Invalid add_reset option %s. Acceptable options are "
+                             "False, True, and 'asynchronous'")
+
     block = working_block(block)
 
+    if add_reset:  # True or 'asynchronous'
+        if block.get_wirevector_by_name('rst') is not None:
+            raise PyrtlError("Found a user-defined wire named 'rst'. Pass in "
+                             "'add_reset=False' to use your existing reset logic.")
+
     inputs, outputs, registers, wires, memories = _verilog_block_parts(block)
 
     ver_name = _VerilogSanitizer('_ver_out_tmp_')
@@ -760,6 +890,8 @@ def default_value():
 
     # Declare all block inputs as reg
     print('    reg clk;', file=dest_file)
+    if add_reset:
+        print('    reg rst;', file=dest_file)
     for w in name_sorted(inputs):
         print('    reg{:s} {:s};'.format(_verilog_vector_decl(w), ver_name[w.name]),
               file=dest_file)
@@ -775,6 +907,8 @@ def default_value():
 
     # Instantiate logic block
     io_list = ['clk'] + name_list(name_sorted(inputs)) + name_list(name_sorted(outputs))
+    if add_reset:
+        io_list.insert(1, 'rst')
     io_list_str = ['.{0:s}({0:s})'.format(w) for w in io_list]
     print('    toplevel block({:s});\n'.format(', '.join(io_list_str)), file=dest_file)
 
@@ -792,6 +926,8 @@ def default_value():
 
     # Initialize clk, and all the registers and memories
     print('        clk = 0;', file=dest_file)
+    if add_reset:
+        print('        rst = 0;', file=dest_file)
     for r in name_sorted(registers):
         print('        block.%s = %d;' % (ver_name[r.name], init_regvalue(r)), file=dest_file)
     for m in sorted(memories, key=lambda m: m.id):

pyrtl/passes.py

@@ -31,9 +31,12 @@ def optimize(update_working_block=True, block=None, skip_sanity_check=False):
     """
     Return an optimized version of a synthesized hardware block.
 
-    :param Boolean update_working_block: Don't copy the block and optimize the
-        new block
+    :param bool update_working_block: Don't copy the block and optimize the
+        new block (defaults to True)
     :param Block block: the block to optimize (defaults to working block)
+    :param bool skip_sanity_check: Don't perform sanity checks on the block
+        before/during/after the optimization passes (defaults to False).
+        Sanity checks will always be performed if in debug mode.
 
     Note:
     optimize works on all hardware designs, both synthesized and non synthesized
@@ -45,8 +48,8 @@ def optimize(update_working_block=True, block=None, skip_sanity_check=False):
     with set_working_block(block, no_sanity_check=True):
         if (not skip_sanity_check) or _get_debug_mode():
             block.sanity_check()
-        _remove_wire_nets(block)
-        _remove_slice_nets(block)
+        _remove_wire_nets(block, skip_sanity_check)
+        _remove_slice_nets(block, skip_sanity_check)
         constant_propagation(block, True)
         _remove_unlistened_nets(block)
         common_subexp_elimination(block)
@@ -73,7 +76,7 @@ def find_producer(self, item):
             return item
 
 
-def _remove_wire_nets(block):
+def _remove_wire_nets(block, skip_sanity_check=False):
     """ Remove all wire nodes from the block. """
 
     wire_src_dict = _ProducerList()
@@ -100,10 +103,11 @@ def _remove_wire_nets(block):
     for dead_wirevector in wire_removal_set:
         block.remove_wirevector(dead_wirevector)
 
-    block.sanity_check()
+    if (not skip_sanity_check) or _get_debug_mode():
+        block.sanity_check()
 
 
-def _remove_slice_nets(block):
+def _remove_slice_nets(block, skip_sanity_check=False):
     """ Remove all unneeded slice nodes from the block.
 
     Unneeded here means that the source and destination wires of a slice net are exactly
@@ -161,7 +165,8 @@ def is_net_slicing_entire_wire(net):
         del block.wirevector_by_name[dead_wirevector.name]
         block.wirevector_set.remove(dead_wirevector)
 
-    block.sanity_check()
+    if (not skip_sanity_check) or _get_debug_mode():
+        block.sanity_check()
 
 
 def constant_propagation(block, silence_unexpected_net_warnings=False):