Merge pull request #42 from daniellimws/docs-clock

Update documentation for clock examples
chipsalliance · Jun 16, 2020 · 5a8fb0d · 5a8fb0d
2 parents fce6235 + 722bf49
commit 5a8fb0d
Show file tree

Hide file tree

Showing 28 changed files with 293 additions and 174 deletions.
diff --git a/README.md b/README.md
diff --git a/README.rst b/README.rst
@@ -1,5 +1,5 @@
-SymbiFlow Verilog to VtR XML (v2x)
-===================================
+Verilog to Routing XML file generation from Verilog (`python-symbiflow-v2x`)
+=============================================================================
 
 
 .. image:: https://readthedocs.org/projects/python-symbiflow-v2x/badge/?version=latest

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,5 +1,5 @@
 env
 _build
-tests/**/*.md
-tests/**/*.svg
-tests/**/*.png
+examples/**/*.md
+examples/**/*.svg
+examples/**/*.png
diff --git a/docs/Makefile b/docs/Makefile
@@ -15,7 +15,7 @@ MAKEDIR := $(dir $(lastword $(MAKEFILE_LIST)))
 # You can set these variables from the command line.
 SPHINXOPTS      =
 SPHINXBUILD     = [ -e env/bin/activate ] && source env/bin/activate; sphinx-build
-SPHINXAUTOBUILD = [ -e env/bin/activate ] && source env/bin/activate; sphinx-autobuild
+SPHINXAUTOBUILD = [ -e env/bin/activate ] && source env/bin/activate; sphinx-autobuild --watch $(MAKEDIR)../tests
 SPHINXPROJ      = SymbiFlowV2X
 SOURCEDIR       = .
 BUILDDIR        = _build
@@ -62,9 +62,9 @@ env:
 
 # Update fuzzer / minitest markdown links.
 tests-links:
-	@mkdir -p $(MAKEDIR)/tests
-	@cd $(MAKEDIR)/tests && find -name '*.md' -delete && find -type d -empty -delete
-	@cd $(MAKEDIR)/tests && \
+	@mkdir -p $(MAKEDIR)/examples
+	@cd $(MAKEDIR)/examples && find -name '*.md' -delete && find -type d -empty -delete
+	@cd $(MAKEDIR)/examples && \
 		for I in $$(cd ../../tests/ ; find -name '*.md' | sort); do \
 			F=$$(dirname $$I); D=$$(dirname $$F); N=$$(basename $$F); \
 			S=../../tests/$$I; O=$$D/$$N.md; \
@@ -73,7 +73,7 @@ tests-links:
 			fi; \
 			ln -sf $$(realpath $$S --relative-to=$$D) $$O; \
 		done
-	@cd $(MAKEDIR)/tests && \
+	@cd $(MAKEDIR)/examples && \
 		for I in $$(cd ../../tests/ ; find -name '*.svg' -o -name '*.png' | sort); do \
 			F=$$(dirname $$I); D=$$(dirname $$F); N=$$(basename $$I); \
 			S=../../tests/$$I; O=$$D/$$N; \

diff --git a/docs/environment.yml b/docs/environment.yml
@@ -14,8 +14,7 @@ dependencies:
 # ReadTheDoc dependencies
 - mock
 - pillow
-- sphinx
-- sphinx_rtd_theme
+- sphinx=2.4.4
 # Packages installed from PyPI
 - pip:
   - -r file:requirements.txt
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,10 @@
+Examples
+========
+
+Here we have examples on how v2x converts a Verilog module to its corresponding model.xml and pb_type.xml files. These examples are taken from the `v2x test cases <https://github.com/SymbiFlow/python-symbiflow-v2x/tree/master/tests>`_.
+
+.. toctree::
+
+   examples/clocks.rst
+   examples/dsp.rst
+   examples/vtr-examples.rst
diff --git a/docs/examples/clocks.rst b/docs/examples/clocks.rst
@@ -0,0 +1,12 @@
+.. Clock Example Tests
+
+Clock
+=====
+
+There are various ways for an input or output port to be detected as a clock by v2x. Here are examples on ways to do so.
+
+.. toctree::
+   clocks/autodetection.rst
+   clocks/manual_input.rst
+   clocks/manual_output.rst
+   clocks/multiple.rst
diff --git a/docs/examples/clocks/autodetection.rst b/docs/examples/clocks/autodetection.rst
@@ -0,0 +1,6 @@
+Autodetection of clock from flipflop
+====================================
+
+.. include:: ../../../tests/clocks/dff_one_clock/README.rst
+.. include:: ../../../tests/clocks/dff_comb_one_clock/README.rst
+.. include:: ../../../tests/clocks/dff_two_clocks/README.rst
diff --git a/docs/examples/clocks/manual_input.rst b/docs/examples/clocks/manual_input.rst
@@ -0,0 +1,7 @@
+Manually set inputs as clock
+============================
+
+.. include:: ../../../tests/clocks/input_attr_clock/README.rst
+.. include:: ../../../tests/clocks/input_attr_not_clock/README.rst
+.. include:: ../../../tests/clocks/input_named_clk/README.rst
+.. include:: ../../../tests/clocks/input_named_regex/README.rst
diff --git a/docs/examples/clocks/manual_output.rst b/docs/examples/clocks/manual_output.rst
@@ -0,0 +1,5 @@
+Manually set outputs as clock
+=============================
+
+.. include:: ../../../tests/clocks/output_attr_clock/README.rst
+.. include:: ../../../tests/clocks/output_named_clk/README.rst
diff --git a/docs/examples/clocks/multiple.rst b/docs/examples/clocks/multiple.rst
@@ -0,0 +1,5 @@
+Multiple clocks
+===============
+
+.. include:: ../../../tests/clocks/multiple_inputs_named_clk/README.rst
+.. include:: ../../../tests/clocks/multiple_outputs_named_clk/README.rst
diff --git a/docs/tests/dsp.rst → docs/examples/dsp.rst b/docs/tests/dsp.rst → docs/examples/dsp.rst
@@ -1,7 +1,7 @@
 .. DSP Based Example Tests
 
-DSP Examples
-============
+DSP
+===
 
 .. toctree::
 

diff --git a/docs/tests/vtr-examples.rst → docs/examples/vtr-examples.rst b/docs/tests/vtr-examples.rst → docs/examples/vtr-examples.rst
@@ -1,7 +1,7 @@
 .. Examples from the Verilog to Routing documentation / tutorials.
 
-Verilog to Routing Examples
-===========================
+Verilog to Routing
+==================
 
 Primitive Block Timing Modeling Tutorial
 ----------------------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -5,12 +5,4 @@
    :glob:
    :hidden:
 
-   tests/vtr-examples.rst
-   tests/dsp.rst
-
-.. toctree::
-   :maxdepth: 3
-   :glob:
-   :hidden:
-
-   tests/clocks.rst
+   examples.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,10 +1,8 @@
 git+http://github.com/SymbiFlow/sphinx_materialdesign_theme.git@master#egg=sphinx_symbiflow_theme
 
 docutils
-sphinx
 sphinx-autobuild
 
-breathe
 recommonmark
 sphinx-markdown-tables
 sphinxcontrib-napoleon

diff --git a/docs/tests/clocks.rst b/docs/tests/clocks.rst
diff --git a/tests/clocks/dff_comb_one_clock/README.rst b/tests/clocks/dff_comb_one_clock/README.rst
@@ -1,9 +1,23 @@
 D-Flipflop with combinational logic
 +++++++++++++++++++++++++++++++++++
 
-`input wire a` should be detected as a clock because it drives the flip flop.
+The following shows a combinational logic design driven by a clock. ``input wire a`` should be detected as a clock because it drives the flip flop.
 
-.. symbolator:: ../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
+.. symbolator:: ../../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
 
-.. literalinclude:: ../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
+.. verilog-diagram:: ../../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
+   :type: netlistsvg
+   :module: BLOCK
+
+|
+
+.. literalinclude:: ../../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
    :language: verilog
+   :start-after:  */
+   :caption: tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v
+
+The ``is_clock`` attribute of the ``a`` port is set to 1, and the ports ``b``, ``c`` and ``d`` have their ``clock`` attribute set to ``a``.
+
+.. literalinclude:: ../../../tests/clocks/dff_comb_one_clock/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/dff_comb_one_clock/golden.model.xml
diff --git a/tests/clocks/dff_one_clock/README.rst b/tests/clocks/dff_one_clock/README.rst
@@ -0,0 +1,23 @@
+D-Flipflop with one clock
++++++++++++++++++++++++++
+
+The following shows a simple D-flip flop driven by one clock. ``input wire a`` should be detected as a clock because it drives the flip flop.
+
+.. symbolator:: ../../../tests/clocks/dff_one_clock/dff_one_clock.sim.v
+
+.. verilog-diagram:: ../../../tests/clocks/dff_one_clock/dff_one_clock.sim.v
+   :type: netlistsvg
+   :module: BLOCK
+
+|
+
+.. literalinclude:: ../../../tests/clocks/dff_one_clock/dff_one_clock.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/dff_one_clock/dff_one_clock.sim.v
+
+As you can see in the generated model, the ``is_clock`` attribute of the ``a`` port is set to 1, while the ``b`` and ``c`` ports have their ``clock`` attribute set to ``a``.
+
+.. literalinclude:: ../../../tests/clocks/dff_one_clock/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/dff_one_clock/golden.model.xml
diff --git a/tests/clocks/dff_two_clocks/README.rst b/tests/clocks/dff_two_clocks/README.rst
@@ -0,0 +1,23 @@
+D-Flipflop with two clocks
+++++++++++++++++++++++++++
+
+``input wire c1`` and ``input wire c2`` should be detected as clocks because they drive the flip flop.
+
+.. symbolator:: ../../../tests/clocks/dff_two_clocks/dff_two_clocks.sim.v
+
+.. verilog-diagram:: ../../../tests/clocks/dff_two_clocks/dff_two_clocks.sim.v
+   :type: netlistsvg
+   :module: BLOCK
+
+|
+
+.. literalinclude:: ../../../tests/clocks/dff_two_clocks/dff_two_clocks.sim.v
+   :language: verilog
+   :start-after: */
+   :caption: tests/clocks/dff_two_clocks/dff_two_clocks.sim.v
+
+The ``is_clock`` attribute of the ``c1`` and ``c2`` ports are set to 1, and the ports ``a``, ``b``, ``c``, ``o1`` and ``o2`` have their ``clock`` attribute set to the respective clocks they are driven by.
+
+.. literalinclude:: ../../../tests/clocks/dff_two_clocks/golden.model.xml
+   :language: xml
+   :caption: tests/clocks/dff_two_clocks/golden.model.xml
diff --git a/tests/clocks/dff_two_clocks/golden.model.xml b/tests/clocks/dff_two_clocks/golden.model.xml
@@ -2,11 +2,11 @@
 <models>
   <model name="BLOCK">
     <input_ports>
-      <port clock="c1" combinational_sink_ports="o1" name="a"/>
-      <port clock="c2 c1" combinational_sink_ports="o2 o1" name="b"/>
-      <port clock="c2" combinational_sink_ports="o2" name="c"/>
-      <port is_clock="1" name="c1"/>
-      <port is_clock="1" name="c2"/>
+      <port name="a" combinational_sink_ports="o1" clock="c1"/>
+      <port name="b" combinational_sink_ports="o2 o1" clock="c2 c1"/>
+      <port name="c" combinational_sink_ports="o2" clock="c2"/>
+      <port name="c1" is_clock="1"/>
+      <port name="c2" is_clock="1"/>
     </input_ports>
     <output_ports>
       <port clock="c1" name="o1"/>