Merge pull request #55 from antmicro/yowasp

Continuation: Use yowasp_yosys instead of system-installed yosys

Author: rw1nkler

.travis.yml

@@ -22,6 +22,12 @@ jobs:
         - source env/conda/bin/activate sphinxcontrib-verilog-diagrams
         - cd tests && python3 -m unittest test.TestYosysScript
 
+    - stage: Tests
+      name: "Test verilog_diagram_yosys config variable"
+      script:
+        - source env/conda/bin/activate sphinxcontrib-verilog-diagrams
+        - cd tests && python3 -m unittest test.TestYosysType
+
     - stage: Build
       name: "Build"
       script:

README.rst

@@ -82,6 +82,20 @@ Required
 .. |yosys| replace:: ``yosys``
 .. _yosys: https://github.com/YosysHQ/yosys
 
+By default, ``verilog-diagram`` uses the ``yowasp-yosys`` package provided in PyPI.
+It can be installed by running ``pip install -r requirements.txt``.
+However, you could also use Yosys that is installed on your system,
+or point to the specific Yosys binary using ``verilog_diagram_yosys`` variable
+in the Sphinx ``conf.py`` file:
+
+To use Yosys that is available in your system, use the following setting::
+
+    verilog_diagram_yosys = "system"
+
+If you want to point to the specific Yosys binary, provide the path to the program::
+
+    verilog_diagram_yosys = "<path-to-Yosys>"
+
 Optional
 ~~~~~~~~
 

requirements.txt

@@ -2,6 +2,8 @@ setuptools
 docutils
 sphinx
 
+yowasp-yosys>=0.9.post4547.dev9
+
 # Needed to upload to PyPi
 twine
 

sphinxcontrib_verilog_diagrams/__init__.py

@@ -160,6 +160,13 @@ class VerilogDiagram(Directive):
         'caption': directives.unchanged,
     }
 
+    global_variable_options = {
+        "verilog_diagram_output_format": ["svg", "png"],
+        "verilog_diagram_skin": ["default"],  # or path
+        "verilog_diagram_yosys_script": ["default"],  # or path
+        "verilog_diagram_yosys": ["yowasp", "system"]  # or path
+    }
+
     def run(self):
         # type: () -> List[nodes.Node]
 
@@ -229,19 +236,38 @@ def run(self):
         return [node]
 
 
-def run_yosys(src, cmd):
-    ycmd = "yosys -p '{cmd}' {src}".format(src=src, cmd=cmd)
-    print("Running yosys:", ycmd)
-    subprocess.check_output(ycmd, shell=True)
+def run_yosys(src, cmd, yosys='yowasp'):
+    if yosys == 'yowasp':
+        import yowasp_yosys
+        ycmd = ["-q", "-p", "{}".format(cmd), src]
+        print("Running YoWASP yosys: {}".format(ycmd))
+        yowasp_yosys.run_yosys(ycmd)
+    elif yosys == 'system':
+        ycmd = "yosys -p '{cmd}' {src}".format(src=src, cmd=cmd)
+        print("Running yosys: {}".format(ycmd))
+        subprocess.check_output(ycmd, shell=True)
+    else:
+        ycmd = "{yosys} -p '{cmd}' {src}".format(yosys=yosys, src=src, cmd=cmd)
+        print("Running yosys: {}".format(ycmd))
+        subprocess.check_output(ycmd, shell=True)
+
+
+def diagram_yosys(ipath, opath, module='top', flatten=False,
+                  yosys_script='default', yosys='yowasp'):
 
+    # Assertions
 
-def diagram_yosys(ipath, opath, module='top', flatten=False, yosys_script='default'):
     assert path.exists(ipath), 'Input file missing: {}'.format(ipath)
     assert not path.exists(opath), 'Output file exists: {}'.format(opath)
+    yosys_options = VerilogDiagram.global_variable_options["verilog_diagram_yosys"]
+    assert yosys in yosys_options or os.path.exists(yosys), "Invalid verilog_diagram_yosys value!"
     if yosys_script != 'default':
         assert path.exists(yosys_script), 'Yosys script file missing: {}'.format(yosys_script)
     oprefix, oext = path.splitext(opath)
     assert oext.startswith('.'), oext
+
+    # Diagram generation
+
     oext = oext[1:]
 
     if flatten:
@@ -254,12 +280,21 @@ def diagram_yosys(ipath, opath, module='top', flatten=False, yosys_script='defau
     else:
         yosys_script_cmd = "script {}".format(yosys_script)
 
-    run_yosys(
-        src=ipath,
-        cmd = """\
-prep -top {top} {flatten}; cd {top}; {script}; show -format {fmt} -prefix {oprefix}
-""".format(top=module, flatten=flatten, fmt=oext, oprefix=oprefix, script=yosys_script_cmd).strip(),
-    )
+    yosys_cmd = "prep -top {top} {flatten}; cd {top}; {script}; show -format {fmt} -prefix {oprefix}".format(
+        top=module,
+        flatten=flatten,
+        fmt=oext,
+        oprefix=oprefix,
+        script=yosys_script_cmd
+    ).strip()
+    run_yosys(ipath, yosys_cmd, yosys)
+
+    if yosys == 'yowasp':
+        # somehow yowasp_yosys fails to execute `dot` to convert the dot file to svg,
+        # which works on native yosys, perhaps a limitation with wasm
+        svgdata = subprocess.check_output(["dot", "-Tsvg", "{}.dot".format(oprefix)])
+        with open("{}.svg".format(oprefix), "wb") as img:
+            img.write(svgdata)
 
     assert path.exists(opath), 'Output file {} was not created!'.format(oopath)
     print('Output file created: {}'.format(opath))
@@ -268,7 +303,7 @@ def run_netlistsvg(ipath, opath, skin='default'):
     assert path.exists(ipath), 'Input file missing: {}'.format(ipath)
     assert not path.exists(opath), 'Output file exists: {}'.format(opath)
     if skin != 'default':
-       assert path.exists(skin), 'Skin file missing: {}'.format(skin)
+        assert path.exists(skin), 'Skin file missing: {}'.format(skin)
 
     netlistsvg_cmd = "netlistsvg {ipath} -o {opath}".format(ipath=ipath, opath=opath)
     if skin != 'default':
@@ -281,15 +316,23 @@ def run_netlistsvg(ipath, opath, skin='default'):
     print('netlistsvg - Output file created: {}'.format(opath))
 
 
-def diagram_netlistsvg(ipath, opath, module='top', flatten=False, yosys_script='default', skin='default'):
+def diagram_netlistsvg(ipath, opath, module='top', flatten=False,
+                       yosys_script='default', skin='default', yosys='yowasp'):
+    # Assertions
+
     assert path.exists(ipath), 'Input file missing: {}'.format(ipath)
     assert not path.exists(opath), 'Output file exists: {}'.format(opath)
+    yosys_options = VerilogDiagram.global_variable_options["verilog_diagram_yosys"]
+    assert yosys in yosys_options or os.path.exists(yosys), "Invalid verilog_diagram_yosys value!"
     if yosys_script != 'default':
         assert path.exists(yosys_script), 'Yosys script file missing: {}'.format(yosys_script)
     if skin != 'default':
         assert path.exists(skin), 'Skin file missing: {}'.format(skin)
     oprefix, oext = path.splitext(opath)
     assert oext.startswith('.'), oext
+
+    # Diagram generation
+
     oext = oext[1:]
 
     if flatten:
@@ -306,11 +349,14 @@ def diagram_netlistsvg(ipath, opath, module='top', flatten=False, yosys_script='
     if path.exists(ojson):
         os.remove(ojson)
 
-    run_yosys(
-        src=ipath,
-        cmd = """\
-prep -top {top} {flatten}; cd {top}; {script}; write_json {ojson}
-""".format(top=module, flatten=flatten, ojson=ojson, script=yosys_script_cmd).strip())
+    yosys_cmd = """prep -top {top} {flatten}; cd {top}; {script}; write_json {compat} {ojson}""".format(
+        top=module,
+        flatten=flatten,
+        ojson=ojson,
+        script=yosys_script_cmd,
+        compat="-compat-int" if yosys == 'yowasp' else ""
+    ).strip()
+    run_yosys(ipath, yosys_cmd, yosys)
     assert path.exists(ojson), 'Output file {} was not created!'.format(ojson)
 
     run_netlistsvg(ojson, opath, skin)
@@ -336,14 +382,31 @@ def render_diagram(self, code, options, format, skin, yosys_script):
     yosys_script = options['yosys_script'] if options['yosys_script'] is not None else yosys_script
     skin = options['skin'] if options['skin'] is not None else skin
 
+    yosys = self.builder.config.verilog_diagram_yosys
+    yosys_options = VerilogDiagram.global_variable_options["verilog_diagram_yosys"]
+    if yosys not in yosys_options and not os.path.exists(yosys):
+        raise VerilogDiagramError("Yosys not found!")
+    else:
+        yosys = yosys if yosys in yosys_options else os.path.realpath(yosys)
+
     diagram_type = options['type']
     if diagram_type.startswith('yosys'):
         assert diagram_type.startswith('yosys-'), diagram_type
         diagram_yosys(
-            verilog_path, outfn, module=options['module'], flatten=options['flatten'], yosys_script=yosys_script)
+            verilog_path,
+            outfn,
+            module=options['module'],
+            flatten=options['flatten'],
+            yosys_script=yosys_script,
+            yosys=yosys)
     elif diagram_type == 'netlistsvg':
         diagram_netlistsvg(
-            verilog_path, outfn, module=options['module'], flatten=options['flatten'], skin=skin)
+            verilog_path,
+            outfn,
+            module=options['module'],
+            flatten=options['flatten'],
+            skin=skin,
+            yosys=yosys)
     else:
         raise Exception('Invalid diagram type "%s"' % diagram_type)
         #raise self.severe(\n' %
@@ -486,5 +549,5 @@ def setup(app):
     app.add_config_value('verilog_diagram_output_format', 'svg', 'html')
     app.add_config_value('verilog_diagram_skin', 'default', 'html')
     app.add_config_value('verilog_diagram_yosys_script', 'default', 'html')
+    app.add_config_value('verilog_diagram_yosys', 'yowasp', 'html')
     return {'version': '1.0', 'parallel_read_safe': True}
-

tests/test.py

@@ -10,6 +10,7 @@
 
 VERILOG_DIAGRAMS_PATH = os.path.abspath("..")
 
+## Helpers
 
 def get_sphinx_dirs(test_build_dir):
     sphinx_dirs = {
@@ -29,8 +30,37 @@ def generate_sphinx_config(test_build_dir, **jinja_dict):
         template = env.get_template("conf.py.template")
         template.stream(**jinja_dict).dump(fd)
 
+## Base class for tests
 
-class TestSkins(unittest.TestCase):
+class TestBase(unittest.TestCase):
+
+    def print_test_header(self, case_name, test_name):
+        print("")
+        print("# ---------------------------------------------------------- #")
+        print("# TEST CASE: {}".format(case_name))
+        print("# TEST NAME: {}".format(test_name))
+        print("# ---------------------------------------------------------- #")
+        print("")
+
+    def prepare_test(self, test_name, test_build_dir, test_files, **test_jinja_dict):
+        self.print_test_header(self.TEST_CASE_NAME, test_name)
+
+        # Create the TestCase build directory
+        os.makedirs(test_build_dir, exist_ok=True)
+
+        # Generate a Sphinx config
+        generate_sphinx_config(test_build_dir, **test_jinja_dict)
+
+        # Copy the test files
+        for src in test_files:
+            src_basename = os.path.basename(src)
+            dst = os.path.join(test_build_dir, src_basename)
+            shutil.copyfile(src, dst)
+
+
+## Test cases
+
+class TestSkins(TestBase):
 
     TEST_CASE_NAME = "TestSkins"
     TEST_CASE_BUILD_DIR = os.path.join("build", TEST_CASE_NAME)
@@ -50,17 +80,7 @@ def test_netlistsvg_diagram(self):
             "custom_variables": "verilog_diagram_skin = os.path.realpath('skin-purple.svg')"
         }
 
-        # Create the TestCase build directory
-        os.makedirs(TEST_BUILD_DIR, exist_ok=True)
-
-        # Generate a Sphinx config
-        generate_sphinx_config(TEST_BUILD_DIR, **TEST_JINJA_DICT)
-
-        # Copy the test files
-        for src in TEST_FILES:
-            src_basename = os.path.basename(src)
-            dst = os.path.join(TEST_BUILD_DIR, src_basename)
-            shutil.copyfile(src, dst)
+        self.prepare_test(TEST_NAME, TEST_BUILD_DIR, TEST_FILES, **TEST_JINJA_DICT)
 
         # Run the Sphinx
         sphinx_dirs = get_sphinx_dirs(TEST_BUILD_DIR)
@@ -69,7 +89,7 @@ def test_netlistsvg_diagram(self):
             app.build(force_all=True)
 
 
-class TestYosysScript(unittest.TestCase):
+class TestYosysScript(TestBase):
 
     TEST_CASE_NAME = "TestYosysScript"
     TEST_CASE_BUILD_DIR = os.path.join("build", TEST_CASE_NAME)
@@ -89,24 +109,86 @@ def test_yosys_script(self):
             "custom_variables": "verilog_diagram_yosys_script = os.path.realpath('yosys_script.ys')"
         }
 
-        # Create the TestCase build directory
-        os.makedirs(TEST_BUILD_DIR, exist_ok=True)
+        self.prepare_test(TEST_NAME, TEST_BUILD_DIR, TEST_FILES, **TEST_JINJA_DICT)
 
-        # Generate a Sphinx config
-        generate_sphinx_config(TEST_BUILD_DIR, **TEST_JINJA_DICT)
+        # Run the Sphinx
+        sphinx_dirs = get_sphinx_dirs(TEST_BUILD_DIR)
+        with docutils_namespace():
+            app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
+            app.build(force_all=True)
 
-        # Copy the test files
-        for src in TEST_FILES:
-            src_basename = os.path.basename(src)
-            dst = os.path.join(TEST_BUILD_DIR, src_basename)
-            shutil.copyfile(src, dst)
+class TestYosysType(TestBase):
+
+    TEST_CASE_NAME = "TestYowasp"
+    TEST_CASE_BUILD_DIR = os.path.join("build", TEST_CASE_NAME)
+
+    def test_yosys_yowasp(self):
+        TEST_NAME = "test_yosys_yowasp"
+        TEST_BUILD_DIR = os.path.join("build", self.TEST_CASE_NAME, TEST_NAME)
+        TEST_FILES = [
+            "test_yosys_type/test_yosys_yowasp.rst",
+            "verilog/adder.v"
+        ]
+        TEST_JINJA_DICT = {
+            "verilog_diagrams_path": "'{}'".format(VERILOG_DIAGRAMS_PATH),
+            "master_doc": "'test_yosys_yowasp'",
+            "custom_variables": ""
+        }
+
+        self.prepare_test(TEST_NAME, TEST_BUILD_DIR, TEST_FILES, **TEST_JINJA_DICT)
+
+        # Run the Sphinx
+        sphinx_dirs = get_sphinx_dirs(TEST_BUILD_DIR)
+        with docutils_namespace():
+            app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
+            app.build(force_all=True)
+
+    @unittest.skipIf(shutil.which('yosys') is None, 'Skipping test_yosys_system. Yosys is not installed!')
+    def test_yosys_system(self):
+        TEST_NAME = "test_yosys_system"
+        TEST_BUILD_DIR = os.path.join("build", self.TEST_CASE_NAME, TEST_NAME)
+        TEST_FILES = [
+            "test_yosys_type/test_yosys_system.rst",
+            "verilog/adder.v"
+        ]
+        TEST_JINJA_DICT = {
+            "verilog_diagrams_path": "'{}'".format(VERILOG_DIAGRAMS_PATH),
+            "master_doc": "'test_yosys_system'",
+            "custom_variables": "verilog_diagram_yosys = 'system'"
+        }
+
+        self.prepare_test(TEST_NAME, TEST_BUILD_DIR, TEST_FILES, **TEST_JINJA_DICT)
 
         # Run the Sphinx
         sphinx_dirs = get_sphinx_dirs(TEST_BUILD_DIR)
         with docutils_namespace():
             app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
             app.build(force_all=True)
 
+    @unittest.skipIf(shutil.which('yosys') is None, 'Skipping test_yosys_path. Yosys is not installed!')
+    def test_yosys_path(self):
+        TEST_NAME = "test_yosys_path"
+        TEST_BUILD_DIR = os.path.join("build", self.TEST_CASE_NAME, TEST_NAME)
+        TEST_FILES = [
+            "test_yosys_type/test_yosys_path.rst",
+            "verilog/adder.v"
+        ]
+
+        yosys_path = shutil.which("yosys")
+
+        TEST_JINJA_DICT = {
+            "verilog_diagrams_path": "'{}'".format(VERILOG_DIAGRAMS_PATH),
+            "master_doc": "'test_yosys_path'",
+            "custom_variables": "verilog_diagram_yosys = '{}'".format(yosys_path)
+        }
+
+        self.prepare_test(TEST_NAME, TEST_BUILD_DIR, TEST_FILES, **TEST_JINJA_DICT)
+
+        # Run the Sphinx
+        sphinx_dirs = get_sphinx_dirs(TEST_BUILD_DIR)
+        with docutils_namespace():
+            app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
+            app.build(force_all=True)
 
 if __name__ == '__main__':
     unittest.main()