Merge pull request #393 from pllab/verilog-import-from-blif

Convenience function for importing Verilog into PyRTL via the Yosys/BLIF workflow

Author: mdko

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/importexport.py

@@ -9,6 +9,11 @@
 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
@@ -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
@@ -427,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.
 

tests/test_importexport.py

@@ -1505,7 +1505,7 @@ def test_verilog_check_valid_name_bad(self):
         self.assert_invalid_name('a' * 2000)
 
 
-class TestVerilog(unittest.TestCase):
+class TestVerilogOutput(unittest.TestCase):
     def setUp(self):
         pyrtl.reset_working_block()
         # To compare textual consistency, need to make
@@ -1607,6 +1607,91 @@ def test_existing_reset_wire_without_add_reset(self):
         self.assertEqual(buffer.getvalue(), verilog_custom_reset)
 
 
+verilog_input_counter = """\
+module counter (clk, rst, en, count);
+
+    input clk, rst, en;
+    output reg [3:0] count;
+
+    always @(posedge clk)
+        if (rst)
+            count <= 4'd0;
+        else if (en)
+            count <= count + 4'd1;
+
+endmodule
+"""
+
+verilog_input_multi_module = """\
+module foo (a, b, o);
+
+    input a, b;
+    output [1:0] o;
+    assign o = a + b;
+
+endmodule
+
+module top (clk, o);
+    input clk;
+    reg a, b;
+    output [1:0] o;
+    foo f1(a, b, o);
+
+    always @(posedge clk)
+    begin
+        a <= ~a;
+        b <= ~b;
+    end
+endmodule
+"""
+
+
+class TestVerilogInput(unittest.TestCase):
+    def setUp(self):
+        import subprocess
+        try:
+            version = subprocess.check_output(['yosys', '--version'])
+        except OSError:
+            raise unittest.SkipTest('Testing Verilog input requires yosys')
+        pyrtl.reset_working_block()
+
+    def test_import_counter(self):
+        pyrtl.input_from_verilog(verilog_input_counter)
+        sim = pyrtl.Simulation()
+        sim.step_multiple({'rst': '10000', 'en': '01111'})
+        self.assertEqual(sim.tracer.trace['count'], [0, 0, 1, 2, 3])
+
+    def test_import_small(self):
+        pyrtl.input_from_verilog(verilog_output_small)
+        sim = pyrtl.Simulation()
+        sim.step({})
+        self.assertEqual(sim.tracer.trace['o'][0], 0b1100011100110)
+
+    def test_import_counter_with_reset(self):
+        pyrtl.input_from_verilog(verilog_output_counter_sync_reset)
+        sim = pyrtl.Simulation()
+        sim.step_multiple({'rst': '1000'})
+        self.assertEqual(sim.tracer.trace['o'], [0, 2, 3, 4])
+
+    def test_import_multi_module_specified_module(self):
+        # Import foo module because occurs first in file
+        pyrtl.input_from_verilog(verilog_input_multi_module, toplevel="foo")
+        sim = pyrtl.Simulation()
+        sim.step_multiple({'a': '0011', 'b': '0101'})
+        self.assertEqual(sim.tracer.trace['o'], [0, 1, 1, 2])
+
+    def test_import_multi_module_auto_select_top_module(self):
+        pyrtl.input_from_verilog(verilog_input_multi_module)
+        sim = pyrtl.Simulation()
+        sim.step_multiple(nsteps=5)
+        self.assertEqual(sim.tracer.trace['o'], [0, 2, 0, 2, 0])
+
+    def test_error_import_bad_file(self):
+        with self.assertRaisesRegex(pyrtl.PyrtlError,
+                                    "input_from_verilog expecting either open file or string"):
+            pyrtl.input_from_verilog(3)
+
+
 verilog_testbench = """\
 module tb();
     reg clk;