docs: Improving tests display in documentation. * Fixing the `make tests-lists` to understand directories. * Adding top level `rst` file. * Improving DSP documentation. Signed-off-by: Tim 'mithro' Ansell <me@mith.ro>
diff --git a/docs/.gitignore b/docs/.gitignore index 41489e9..012e41f 100644 --- a/docs/.gitignore +++ b/docs/.gitignore
@@ -1,3 +1,3 @@ venv _build -tests/*.md +tests/**/*.md
diff --git a/docs/Makefile b/docs/Makefile index 4881ff6..7ee149c 100644 --- a/docs/Makefile +++ b/docs/Makefile
@@ -30,22 +30,18 @@ # Update fuzzer / minitest markdown links. tests-links: @mkdir -p $(MAKEDIR)/tests - @cd $(MAKEDIR)/tests && rm -f *.md + @cd $(MAKEDIR)/tests && find -name '*.md' -delete && find -type d -empty -delete @cd $(MAKEDIR)/tests && \ - for i in ../../tests/*; do \ - n=$$(basename $$i | sed -e's/^[0-9][0-9][0-9]-//'); \ - if [ ! -d $$i ]; then \ - continue; \ + 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; \ + if [ ! -d $$D ]; then \ + mkdir -p $$D; \ fi; \ - if [ -e $$i/README.md ]; then \ - echo "Linking $$i/README.md"; \ - ln -s $$i/README.md $${n}.md; \ - else \ - echo "Missing $$i/README.md"; \ - fi; \ + ln -sf $$(realpath $$S --relative-to=$$D) $$O; \ done -links: tests-links +links: @true .PHONY: tests-links links
diff --git a/docs/index.rst b/docs/index.rst index f419b60..8ca1248 100644 --- a/docs/index.rst +++ b/docs/index.rst
@@ -9,43 +9,10 @@ .. _V2X: http://symbiflow-v2x.readthedocs.io/ .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :glob: :caption: Tests - Verilog to Routing Examples - - Primitive Block Timing Modeling Tutorial - - tests/fig28-lutff-pair.md - - tests/fig41-full-adder.md - - tests/fig42-dff.md - - Clock Example - - FlipFlop Examples - - tests/clocks/dff_comb_one_clock.md - - tests/clocks/dff_one_clock.md - - tests/clocks/dff_two_clocks.md - - Input Clocks - - tests/clocks/input_attr_clock.md - - tests/clocks/input_named_clk.md - - tests/clocks/input_named_rdclk.md - - Output Clocks - - tests/clocks/output_attr_clock.md - - tests/clocks/output_named_clk.md - - tests/clocks/output_named_rdclk.md - - Multiple Clocks - - tests/clocks/multiple_inputs_named_clk.md - - tests/clocks/multiple_outputs_named_clk.md - - Carry Example - - tests/carry.md - - DSP Examples - - tests/dsp_combinational.md - - tests/dsp_in_registered.md - - tests/dsp_out_registered.md - - tests/dsp_inout_registered.md - - tests/dsp_inout_registered_dualclk.md - - tests/dsp_partial_registered.md - - tests/dsp_modes.md - - tests/** + tests/vtr-examples.rst + tests/clocks.rst + tests/dsp.rst
diff --git a/docs/tests/clocks.rst b/docs/tests/clocks.rst new file mode 100644 index 0000000..a2ab418 --- /dev/null +++ b/docs/tests/clocks.rst
@@ -0,0 +1,40 @@ +.. Clock Example Tests + +Clock Examples +============== + +FlipFlop Examples +----------------- + +.. toctree:: + + clocks/dff_comb_one_clock.md + clocks/dff_comb_one_clock.md + clocks/dff_one_clock.md + clocks/dff_two_clocks.md + +Input Clocks +------------ + +.. toctree:: + + clocks/input_attr_clock.md + clocks/input_named_clk.md + clocks/input_named_rdclk.md + +Output Clocks +------------- + +.. toctree:: + + clocks/output_attr_clock.md + clocks/output_named_clk.md + clocks/output_named_rdclk.md + +Multiple Clocks +--------------- + +.. toctree:: + + clocks/multiple_inputs_named_clk.md + clocks/multiple_outputs_named_clk.md
diff --git a/docs/tests/dsp.rst b/docs/tests/dsp.rst new file mode 100644 index 0000000..6fb30c7 --- /dev/null +++ b/docs/tests/dsp.rst
@@ -0,0 +1,14 @@ +.. DSP Based Example Tests + +DSP Examples +============ + +.. toctree:: + + 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
diff --git a/docs/tests/vtr-examples.rst b/docs/tests/vtr-examples.rst new file mode 100644 index 0000000..ebec334 --- /dev/null +++ b/docs/tests/vtr-examples.rst
@@ -0,0 +1,13 @@ +.. Examples from the Verilog to Routing documentation / tutorials. + +Verilog to Routing Examples +=========================== + +Primitive Block Timing Modeling Tutorial +---------------------------------------- + +.. toctree:: + + vtr/fig28-lutff-pair.md + vtr/fig41-full-adder.md + vtr/fig42-dff.md
diff --git a/tests/dsp/dsp_combinational/README.md b/tests/dsp/dsp_combinational/README.md index cd31b4f..f565755 100644 --- a/tests/dsp/dsp_combinational/README.md +++ b/tests/dsp/dsp_combinational/README.md
@@ -1,9 +1,4 @@ -# `dsp_combinational` tests - -This directory contains test for the blackbox detection for the -`v2x_to_model.py` and `v2x_to_pb_type` tools. - -Model from this test is used by other dsp tests +# `dsp_combinational` test ## Detection of combinational connections @@ -11,6 +6,6 @@ ## Blackbox detection - - [ ] model of the leaf pb\_type is generated - - [ ] leaf pb\_type xml is generated + - [ ] 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 index 70ffab9..c40ab3f 100644 --- a/tests/dsp/dsp_in_registered/README.md +++ b/tests/dsp/dsp_in_registered/README.md
@@ -1,18 +1,18 @@ -# `dsp_in_registered` tests +# `dsp_in_registered` test -This directory contains test for the `v2x_to_model.py` and `v2x_to_pb_type` tools. -The tests use model from fig42-dff and dps\_combinational tests. -Those tests should check the following features: +Test for "DSP style" block with all inputs registered. +The tests use model from [`fig42-dff`](FIXME) and +[`dsp_combinational`](../dsp_combinational/README.md) tests. ## Detection of combinational connections - [ ] output has combinational connection with input - - [ ] pack\_pattern defined on wire connections with `pack` attribute + - [ ] `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\_types are included in the output files + - [ ] 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 index 8e053df..b66befe 100644 --- a/tests/dsp/dsp_inout_registered/README.md +++ b/tests/dsp/dsp_inout_registered/README.md
@@ -1,18 +1,20 @@ -# `dsp_inout_registered` tests +# `dsp_inout_registered` test -This directory contains test for the `v2x_to_model.py` and `v2x_to_pb_type` tools. -The tests use model from fig42-dff and dps\_combinational tests. -Those tests should check the following features: +Test for "DSP style" block with both input and output is registered (using a +single clock). + +The tests use model from [`fig42-dff`](FIXME) and +[`dsp_combinational`](../dsp_combinational/README.md) tests. ## Detection of combinational connections - [ ] output has combinational connection with input - - [ ] pack\_pattern defined on wire connections with `pack` attribute + - [ ] `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\_types are included in the output files + - [ ] 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 index 35c81b3..f5baa0e 100644 --- a/tests/dsp/dsp_inout_registered_dualclk/README.md +++ b/tests/dsp/dsp_inout_registered_dualclk/README.md
@@ -1,18 +1,19 @@ -# `dsp_inout_registered_dualclk` tests +# `dsp_inout_registered_dualclk` test -This directory contains test for the `v2x_to_model.py` and `v2x_to_pb_type` tools. -The tests use model from fig42-dff and dps\_combinational tests. -Those tests should check the following features: +Test for "DSP style" block with both input and output is registered using +separate clocks. +The tests use model from [`fig42-dff`](FIXME) and +[`dsp_combinational`](../dsp_combinational/README.md) tests. ## Detection of combinational connections - [ ] output has combinational connection with input - - [ ] pack\_pattern defined on wire connections with `pack` attribute + - [ ] `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\_types are included in the output files + - [ ] 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 index f40e36b..d0e25c7 100644 --- a/tests/dsp/dsp_modes/README.md +++ b/tests/dsp/dsp_modes/README.md
@@ -1,17 +1,39 @@ -# `dsp_modes` tests +# `dsp_modes` test -This directory contains test for the `v2x_to_model.py` and `v2x_to_pb_type` tools. -The tests use models from other DSP test. -Those tests should check the following features: +Test for "DSP style" block with multiple different modes. + +The modes possible are; + + * Combinational only + (IE [`dsp_combinational`](../dsp_combinational/README.md)). + + * Register on one input + (IE [`dsp_partial_registered`](../dsp_partial_registered/README.md)). + + * Register on all inputs + (IE [`dsp_in_registered`](../dsp_in_registered/README.md)). + + * Register on outputs + (IE [`dsp_out_registered`](../dsp_out_registered/README.md)). + + * Register on both inputs and outputs (with same clock) + (IE [`dsp_inout_registered`](../dsp_inout_registered/README.md)). + + * Register on both inputs and outputs (with independent clocks) + (IE [`dsp_inout_registered_dualclk`](../dsp_inout_registered_dualclk/README.md)). + + * Register on both inputs and outputs (with independent clocks) + (IE [`dsp_inout_registered_dualclk`](../dsp_inout_registered_dualclk/README.md)). + ## Blackbox detection - - [ ] model of the leaf pb\_type is generated - - [ ] leaf pb\_type xml is generated - - [ ] all dependency models and pb\_types are included in the output files + - [ ] 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) + - [ ] mode setting is included in `pb_type` generation (correct part of logic is used) - [ ] modes connections are generated correctly
diff --git a/tests/dsp/dsp_out_registered/README.md b/tests/dsp/dsp_out_registered/README.md index f0811bf..27c46e2 100644 --- a/tests/dsp/dsp_out_registered/README.md +++ b/tests/dsp/dsp_out_registered/README.md
@@ -1,18 +1,19 @@ -# `dsp_out_registered` tests +# `dsp_out_registered` test -This directory contains test for the `v2x_to_model.py` and `v2x_to_pb_type` tools. -The tests use model from fig42-dff and dps\_combinational tests. -Those tests should check the following features: +Test for "DSP style" block with outputs registered. + +The tests use model from [`fig42-dff`](FIXME) and +[`dsp_combinational`](../dsp_combinational/README.md) tests. ## Detection of combinational connections - [ ] output has combinational connection with input - - [ ] pack\_pattern defined on wire connections with `pack` attribute + - [ ] `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\_types are included in the output files + - [ ] 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_partial_registered/README.md b/tests/dsp/dsp_partial_registered/README.md index 1de3cea..7fd5d26 100644 --- a/tests/dsp/dsp_partial_registered/README.md +++ b/tests/dsp/dsp_partial_registered/README.md
@@ -1,18 +1,18 @@ -# `dsp_partial_registered` tests +# `dsp_partial_registered` test -This directory contains test for the `v2x_to_model.py` and `v2x_to_pb_type` tools. -The tests use model from fig42-dff and dps\_combinational tests. -Those tests should check the following features: +Test for "DSP style" block with one input registered. +The tests use model from [`fig42-dff`](FIXME) and +[`dsp_combinational`](../dsp_combinational/README.md) tests. ## Detection of combinational connections - [ ] output has combinational connection with input - - [ ] pack\_pattern defined on wire connections with `pack` attribute + - [ ] `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\_types are included in the output files + - [ ] 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