Add flatten option tests

This commit adds a basic test for the flatten option in the
verilog-diagram directive.

Signed-off-by: Robert Winkler <rwinkler@antmicro.com>

Author: rw1nkler

.travis.yml

@@ -21,6 +21,10 @@ jobs:
       script:
         - cd tests && python3 -m unittest test.TestYosysScript
 
+      name: "Test :flatten: option"
+      script:
+        - cd tests && python3 -m unittest test.TestFlatten
+
     - stage: Tests
       name: "Test verilog_diagram_yosys config variable"
       script:

tests/code/verilog/fullAdder.v

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2020  The SymbiFlow Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+`include "halfAdder.v"
+
+module fullAdder (
+  output wire cout, s,
+  input wire cin, x, y
+);
+  wire c1, c2, s1;
+
+  halfAdder h1(c1, s1, x, y);
+  halfAdder h2(c2, s, cin, s1);
+
+  assign cout = c1 | c2;
+
+endmodule

tests/code/verilog/halfAdder.v

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2020  The SymbiFlow Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+module halfAdder (
+  output wire c, s,
+  input wire x, y
+);
+
+  assign s = x ^ y;
+  assign c = x & y;
+
+endmodule

tests/test.py

@@ -117,6 +117,7 @@ def test_yosys_script(self):
             app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
             app.build(force_all=True)
 
+
 class TestYosysType(TestBase):
 
     TEST_CASE_NAME = "TestYowasp"
@@ -190,6 +191,7 @@ def test_yosys_path(self):
             app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
             app.build(force_all=True)
 
+
 class TestNMigen(TestBase):
 
     TEST_CASE_NAME = "TestNMigen"
@@ -216,6 +218,7 @@ def test_yosys_script(self):
             app = Sphinx(buildername="html", warningiserror=True, **sphinx_dirs)
             app.build(force_all=True)
 
+
 class TestRTLIL(TestBase):
 
     TEST_CASE_NAME = "TestRTLIL"
@@ -273,5 +276,33 @@ def test_yosys_script(self):
             app.build(force_all=True)
 
 
+class TestFlatten(TestBase):
+
+    TEST_CASE_NAME = "TestFlatten"
+    TEST_CASE_BUILD_DIR = os.path.join("build", TEST_CASE_NAME)
+
+    def test_yosys_script(self):
+        TEST_NAME = "test_flatten"
+        TEST_BUILD_DIR = os.path.join("build", self.TEST_CASE_NAME, TEST_NAME)
+        TEST_FILES = [
+            "test_flatten/test_flatten.rst",
+            "code/verilog/fullAdder.v",
+            "code/verilog/halfAdder.v"
+        ]
+        TEST_JINJA_DICT = {
+            "hdl_diagrams_path": "'{}'".format(HDL_DIAGRAMS_PATH),
+            "master_doc": "'test_flatten'",
+            "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)
+
+
 if __name__ == '__main__':
     unittest.main()

tests/test_flatten/test_flatten.rst

@@ -0,0 +1,119 @@
+Test Flatten Option
+===================
+
+This test checks whether the ``:flatten:`` option in the ``verilog-diagram``
+directive works as intended. The ``:flatten:`` option is used to resolve
+the black boxes created by Yosys in place of instantiated modules.
+With this option enabled Yosys will convert everything into low-level logic
+where only basic logic cells and basic FPGA primitives will be used.
+
+Netlistsvg Diagram
+------------------
+
+Here is the diagram of a half-adder with its RST code::
+
+   .. verilog-diagram:: halfAdder.v
+      :type: netlistsvg
+      :module: halfAdder
+
+.. verilog-diagram:: halfAdder.v
+   :type: netlistsvg
+   :module: halfAdder
+
+The diagram below has been created without the ``:flatten:`` option::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: netlistsvg
+      :module: fullAdder
+
+.. verilog-diagram:: fullAdder.v
+   :type: netlistsvg
+   :module: fullAdder
+
+The diagram below has been created using the ``:flatten:`` option.
+You can see that the ``halfAdder`` black box is substituted by the appropriate
+logic elements::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: netlistsvg
+      :module: fullAdder
+      :flatten:
+
+.. verilog-diagram:: fullAdder.v
+   :type: netlistsvg
+   :module: fullAdder
+   :flatten:
+
+Yosys BlackBox Diagram
+----------------------
+
+Here is the diagram of a half-adder with its RST code::
+
+   .. verilog-diagram:: halfAdder.v
+      :type: yosys-blackbox
+      :module: halfAdder
+
+.. verilog-diagram:: halfAdder.v
+   :type: yosys-blackbox
+   :module: halfAdder
+
+The diagram below has been created without the ``:flatten:`` option::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: yosys-blackbox
+      :module: fullAdder
+
+.. verilog-diagram:: fullAdder.v
+   :type: yosys-blackbox
+   :module: fullAdder
+
+The diagram below has been created using the ``:flatten:`` option.
+You can see that the ``halfAdder`` black box is substituted by the appropriate
+logic elements::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: yosys-blackbox
+      :module: fullAdder
+      :flatten:
+
+.. verilog-diagram:: fullAdder.v
+   :type: yosys-blackbox
+   :module: fullAdder
+   :flatten:
+
+Yosys AIG Diagram
+-----------------
+
+Here is the diagram of a half-adder with its RST code::
+
+   .. verilog-diagram:: halfAdder.v
+      :type: yosys-aig
+      :module: halfAdder
+
+.. verilog-diagram:: halfAdder.v
+   :type: yosys-aig
+   :module: halfAdder
+
+The diagram below has been created without the ``:flatten:`` option::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: yosys-aig
+      :module: fullAdder
+
+.. verilog-diagram:: fullAdder.v
+   :type: yosys-aig
+   :module: fullAdder
+
+The diagram below has been created using the ``:flatten:`` option.
+You can see that the ``halfAdder`` black box is substituted by the appropriate
+logic elements::
+
+   .. verilog-diagram:: fullAdder.v
+      :type: yosys-aig
+      :module: fullAdder
+      :flatten:
+
+.. verilog-diagram:: fullAdder.v
+   :type: yosys-aig
+   :module: fullAdder
+   :flatten: