chipsalliance · daniellimws · Jul 16, 2020 · Jul 17, 2020
diff --git a/docs/conf.py b/docs/conf.py
@@ -35,6 +35,11 @@
 sys.path.insert(0, os.path.abspath('.'))
 from markdown_code_symlinks import LinkParser, MarkdownSymlinksDomain  # noqa
 
+from sphinx.highlighting import lexers
+from pygments.lexers.hdl import VerilogLexer
+
+lexers['verilog'] = VerilogLexer(tabsize=2)
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

diff --git a/docs/examples/dsp.rst b/docs/examples/dsp.rst
@@ -1,14 +1,20 @@
-.. DSP Based Example Tests
-
 DSP
 ===
 
-.. toctree::
+.. some aliases for the included rst files to use
+
+.. |fig60| replace:: ``Figure 60 - DFF``
+.. _fig60: /examples/vtr/primitive.html#classical-d-flip-flop-test
+
+.. |dsp_combinational| replace:: ``dsp_combinational``
+.. _dsp_combinational: #combinational-dsp
+
+The following shows some DSP-based examples.
 
-   dsp/dsp_combinational.md
-   dsp/dsp_in_registered.md
-   dsp/dsp_out_registered.md
-   dsp/dsp_inout_registered.md
-   dsp/dsp_inout_registered_dualclk.md
-   dsp/dsp_partial_registered.md
-   dsp/dsp_modes.md
+.. include:: ../../tests/dsp/dsp_combinational/README.rst
+.. include:: ../../tests/dsp/dsp_partial_registered/README.rst
+.. include:: ../../tests/dsp/dsp_in_registered/README.rst
+.. include:: ../../tests/dsp/dsp_out_registered/README.rst
+.. include:: ../../tests/dsp/dsp_inout_registered/README.rst
+.. include:: ../../tests/dsp/dsp_inout_registered_dualclk/README.rst
+.. include:: ../../tests/dsp/dsp_modes/README.rst
diff --git a/docs/examples/vtr-examples.rst b/docs/examples/vtr-examples.rst
@@ -3,11 +3,8 @@
 Verilog to Routing
 ==================
 
-Primitive Block Timing Modeling Tutorial
-----------------------------------------
+The following shows some examples taken from the `Verilog to Routing documentation <https://docs.verilogtorouting.org>`_.
 
 .. toctree::
-
-  vtr/lutff-pair.md
-  vtr/full-adder.md
-  vtr/dff.md
+   vtr/primitive.rst
+   vtr/arch.rst
diff --git a/docs/examples/vtr/arch.rst b/docs/examples/vtr/arch.rst
@@ -0,0 +1,8 @@
+Architecture Reference
+======================
+
+The following shows examples taken from the
+`Architecture Reference section <https://docs.verilogtorouting.org/en/latest/arch/reference>`_
+in the `Verilog to Routing documentation <https://docs.verilogtorouting.org>`_.
+
+.. include:: ../../../tests/vtr/lutff-pair/README.rst
diff --git a/docs/examples/vtr/primitive.rst b/docs/examples/vtr/primitive.rst
@@ -0,0 +1,9 @@
+Primitive Block Timing Modeling Tutorial
+========================================
+
+The following shows examples taken from the
+`Primitive Block Timing Modeling Tutorial <https://docs.verilogtorouting.org/en/latest/tutorials/arch/timing_modeling/#>`_
+in the `Verilog to Routing documentation <https://docs.verilogtorouting.org>`_.
+
+.. include:: ../../../tests/vtr/dff/README.rst
+.. include:: ../../../tests/vtr/full-adder/README.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -11,10 +11,10 @@ sphinxcontrib-napoleon
 git+https://github.com/SymbiFlow/sphinxcontrib-markdown-symlinks.git#egg=markdown_code_symlinks
 
 # Verilog diagrams using Yosys + netlistsvg
-git+https://github.com/SymbiFlow/sphinxcontrib-verilog-diagrams.git@dca04723ec07209bd7be3e883e780ca9dd4f271e#egg=sphinxcontrib-verilog-diagrams
+sphinxcontrib-verilog-diagrams
 
 # Module diagrams
-symbolator
+git+https://github.com/SymbiFlow/symbolator.git#egg=symbolator
 
 pycairo
 # vext.gi
diff --git a/tests/dsp/dsp_combinational/README.rst b/tests/dsp/dsp_combinational/README.rst
@@ -0,0 +1,33 @@
+Combinational DSP
++++++++++++++++++
+
+.. symbolator::  ../../tests/dsp/dsp_combinational/dsp_combinational.sim.v
+
+.. verilog-diagram:: ../../tests/dsp/dsp_combinational/dsp_combinational.sim.v
+   :type: netlistsvg
+   :module: DSP_COMBINATIONAL
+
+|
+
+.. no-license::  ../../tests/dsp/dsp_combinational/dsp_combinational.sim.v
+   :language: verilog
+   :caption: tests/dsp/dsp_combinational/dsp_combinational.sim.v
+
+.. no-license:: ../../tests/dsp/dsp_combinational/golden.model.xml
+   :language: xml
+   :caption: tests/dsp/dsp_combinational/golden.model.xml
+
+.. no-license:: ../../tests/dsp/dsp_combinational/golden.pb_type.xml
+   :language: xml
+   :caption: tests/dsp/dsp_combinational/golden.pb_type.xml
+
+Detection of combinational connections
+**************************************
+
+* Output has combinational connection with input
+
+Blackbox detection
+******************
+
+* Model of the leaf ``pb_type`` is generated
+* Leaf ``pb_type`` XML is generated
diff --git a/tests/dsp/dsp_in_registered/README.md b/tests/dsp/dsp_in_registered/README.md
diff --git a/tests/dsp/dsp_in_registered/README.rst b/tests/dsp/dsp_in_registered/README.rst
@@ -0,0 +1,37 @@
+DSP-style block with all inputs registered
+++++++++++++++++++++++++++++++++++++++++++
+
+This uses the model from |fig60|_ and the |dsp_combinational|_ module.
+
+.. symbolator::  ../../tests/dsp/dsp_in_registered/dsp_in_registered.sim.v
+
+.. verilog-diagram:: ../../tests/dsp/dsp_in_registered/dsp_in_registered.sim.v
+   :type: netlistsvg
+   :module: DSP_IN_REGISTERED
+
+|
+
+.. no-license::  ../../tests/dsp/dsp_in_registered/dsp_in_registered.sim.v
+   :language: verilog
+   :caption: tests/dsp/dsp_in_registered/dsp_in_registered.sim.v
+
+.. no-license:: ../../tests/dsp/dsp_in_registered/golden.model.xml
+   :language: xml
+   :caption: tests/dsp/dsp_in_registered/golden.model.xml
+
+.. no-license:: ../../tests/dsp/dsp_in_registered/golden.pb_type.xml
+   :language: xml
+   :caption: tests/dsp/dsp_in_registered/golden.pb_type.xml
+
+Detection of combinational connections
+**************************************
+
+* Output has combinational connection with input
+* ``pack_pattern`` defined on wire connections with ``pack`` attribute
+
+Blackbox detection
+******************
+
+* Model of the leaf ``pb_type`` is generated
+* Leaf ``pb_type`` XML is generated
+* All dependency models and ``pb_type``\ s are included in the output files
diff --git a/tests/dsp/dsp_inout_registered/README.md b/tests/dsp/dsp_inout_registered/README.md
diff --git a/tests/dsp/dsp_inout_registered/README.rst b/tests/dsp/dsp_inout_registered/README.rst
@@ -0,0 +1,37 @@
+DSP-style block with inputs and outputs registered (single clock)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+This uses the model from |fig60|_ and the |dsp_combinational|_ module.
+
+.. symbolator::  ../../tests/dsp/dsp_inout_registered/dsp_inout_registered.sim.v
+
+.. verilog-diagram:: ../../tests/dsp/dsp_inout_registered/dsp_inout_registered.sim.v
+   :type: netlistsvg
+   :module: DSP_INOUT_REGISTERED
+
+|
+
+.. no-license::  ../../tests/dsp/dsp_inout_registered/dsp_inout_registered.sim.v
+   :language: verilog
+   :caption: tests/dsp/dsp_inout_registered/dsp_inout_registered.sim.v
+
+.. no-license:: ../../tests/dsp/dsp_inout_registered/golden.model.xml
+   :language: xml
+   :caption: tests/dsp/dsp_inout_registered/golden.model.xml
+
+.. no-license:: ../../tests/dsp/dsp_inout_registered/golden.pb_type.xml
+   :language: xml
+   :caption: tests/dsp/dsp_inout_registered/golden.pb_type.xml
+
+Detection of combinational connections
+**************************************
+
+* Output has combinational connection with input
+* ``pack_pattern`` defined on wire connections with ``pack`` attribute
+
+Blackbox detection
+******************
+
+* Model of the leaf ``pb_type`` is generated
+* Leaf ``pb_type`` XML is generated
+* All dependency models and ``pb_type``\ s are included in the output files
diff --git a/tests/dsp/dsp_inout_registered_dualclk/README.md b/tests/dsp/dsp_inout_registered_dualclk/README.md
diff --git a/tests/dsp/dsp_inout_registered_dualclk/README.rst b/tests/dsp/dsp_inout_registered_dualclk/README.rst
@@ -0,0 +1,38 @@
+
+DSP-style block with inputs and outputs registered using separate clocks
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+This uses the model from |fig60|_ and the |dsp_combinational|_ module.
+
+.. symbolator::  ../../tests/dsp/dsp_inout_registered_dualclk/dsp_inout_registered_dualclk.sim.v
+
+.. verilog-diagram:: ../../tests/dsp/dsp_inout_registered_dualclk/dsp_inout_registered_dualclk.sim.v
+   :type: netlistsvg
+   :module: DSP_INOUT_REGISTERED_DUALCLK
+
+|
+
+.. no-license::  ../../tests/dsp/dsp_inout_registered_dualclk/dsp_inout_registered_dualclk.sim.v
+   :language: verilog
+   :caption: tests/dsp/dsp_inout_registered_dualclk/dsp_inout_registered_dualclk.sim.v
+
+.. no-license:: ../../tests/dsp/dsp_inout_registered_dualclk/golden.model.xml
+   :language: xml
+   :caption: tests/dsp/dsp_inout_registered_dualclk/golden.model.xml
+
+.. no-license:: ../../tests/dsp/dsp_inout_registered_dualclk/golden.pb_type.xml
+   :language: xml
+   :caption: tests/dsp/dsp_inout_registered_dualclk/golden.pb_type.xml
+
+Detection of combinational connections
+**************************************
+
+* Output has combinational connection with input
+* ``pack_pattern`` defined on wire connections with ``pack`` attribute
+
+Blackbox detection
+******************
+
+* Model of the leaf ``pb_type`` is generated
+* Leaf ``pb_type`` XML is generated
+* All dependency models and ``pb_type``\ s are included in the output files
diff --git a/tests/dsp/dsp_modes/README.md b/tests/dsp/dsp_modes/README.md
diff --git a/tests/dsp/dsp_modes/README.rst b/tests/dsp/dsp_modes/README.rst
@@ -0,0 +1,56 @@
+DSP-style block with different modes
+++++++++++++++++++++++++++++++++++++
+
+The possible modes are
+
+* Combinational only (i.e. |dsp_combinational|_)
+* Register on one input (i.e. |dsp_partial_registered|_)
+* Register on all inputs (i.e. |dsp_in_registered|_)
+* Register on outputs (i.e. |dsp_out_registered|_).
+* Register on both inputs and outputs (with same clock) (i.e. |dsp_inout_registered|_).
+
+.. |dsp_partial_registered| replace:: ``dsp_partial_registered``
+.. _dsp_partial_registered: #dsp-style-block-with-only-one-input-registered
+
+.. |dsp_in_registered| replace:: ``dsp_in_registered``
+.. _dsp_in_registered: #dsp-style-block-with-all-inputs-registered
+
+.. |dsp_out_registered| replace:: ``dsp_out_registered``
+.. _dsp_out_registered: #dsp-style-block-with-outputs-registered
+
+.. |dsp_inout_registered| replace:: ``dsp_inout_registered``
+.. _dsp_inout_registered: #dsp-style-block-with-inputs-and-outputs-registered-single-clock
+
+.. symbolator::  ../../tests/dsp/dsp_modes/dsp_modes.sim.v
+
+.. verilog-diagram:: ../../tests/dsp/dsp_modes/dsp_modes.sim.v
+   :type: netlistsvg
+   :module: DSP_MODES
+
+|
+
+.. no-license::  ../../tests/dsp/dsp_modes/dsp_modes.sim.v
+   :language: verilog
+   :caption: tests/dsp/dsp_modes/dsp_modes.sim.v
+
+.. no-license:: ../../tests/dsp/dsp_modes/golden.model.xml
+   :language: xml
+   :caption: tests/dsp/dsp_modes/golden.model.xml
+
+.. no-license:: ../../tests/dsp/dsp_modes/golden.pb_type.xml
+   :language: xml
+   :caption: tests/dsp/dsp_modes/golden.pb_type.xml
+
+Blackbox detection
+******************
+
+* Model of the leaf ``pb_type`` is generated
+* Leaf ``pb_type`` XML is generated
+* All dependency models and ``pb_type``\ s are included in the output files
+
+Modes generation
+****************
+
+* All the modes from list defined with ``MODES`` attribute
+* Mode setting is included in ``pb_type`` generation (correct part of logic is used)
+* Modes connections are generated correctly