Update documentation for clock examples Signed-off-by: Daniel Lim Wee Soong <weesoong.lim@gmail.com>
diff --git a/docs/tests/clocks.rst b/docs/tests/clocks.rst index 68e741b..bd33ad6 100644 --- a/docs/tests/clocks.rst +++ b/docs/tests/clocks.rst
@@ -3,38 +3,8 @@ Clock Examples ============== -Autodetection clock from flipflop ---------------------------------- - .. toctree:: - - clocks/dff_one_clock.md - clocks/dff_two_clocks.md - -.. include:: ../../tests/clocks/dff_comb_one_clock/README.rst - -Manual Input Clock ------------------- - -.. toctree:: - - clocks/input_attr_clock.md - clocks/input_named_clk.md - clocks/input_named_rdclk.md - -Manual Output Clock -------------------- - -.. 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 + clocks/autodetection.rst + clocks/manual_input.rst + clocks/manual_output.rst + clocks/multiple.rst
diff --git a/docs/tests/clocks/autodetection.rst b/docs/tests/clocks/autodetection.rst new file mode 100644 index 0000000..3c0bd24 --- /dev/null +++ b/docs/tests/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/tests/clocks/manual_input.rst b/docs/tests/clocks/manual_input.rst new file mode 100644 index 0000000..994d15a --- /dev/null +++ b/docs/tests/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/tests/clocks/manual_output.rst b/docs/tests/clocks/manual_output.rst new file mode 100644 index 0000000..cfb98fe --- /dev/null +++ b/docs/tests/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/tests/clocks/multiple.rst b/docs/tests/clocks/multiple.rst new file mode 100644 index 0000000..29677c6 --- /dev/null +++ b/docs/tests/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/tests/clocks/dff_comb_one_clock/README.rst b/tests/clocks/dff_comb_one_clock/README.rst index d1bcf97..8661b73 100644 --- a/tests/clocks/dff_comb_one_clock/README.rst +++ b/tests/clocks/dff_comb_one_clock/README.rst
@@ -1,9 +1,14 @@ 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 +.. literalinclude:: ../../../tests/clocks/dff_comb_one_clock/dff_comb_one_clock.sim.v :language: verilog + +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 \ No newline at end of file
diff --git a/tests/clocks/dff_one_clock/README.rst b/tests/clocks/dff_one_clock/README.rst new file mode 100644 index 0000000..fabe944 --- /dev/null +++ b/tests/clocks/dff_one_clock/README.rst
@@ -0,0 +1,14 @@ +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 + +.. literalinclude:: ../../../tests/clocks/dff_one_clock/dff_one_clock.sim.v + :language: verilog + +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
diff --git a/tests/clocks/dff_two_clocks/README.rst b/tests/clocks/dff_two_clocks/README.rst new file mode 100644 index 0000000..c31723e --- /dev/null +++ b/tests/clocks/dff_two_clocks/README.rst
@@ -0,0 +1,14 @@ +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 + +.. literalinclude:: ../../../tests/clocks/dff_two_clocks/dff_two_clocks.sim.v + :language: verilog + +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
diff --git a/tests/clocks/input_attr_clock/README.rst b/tests/clocks/input_attr_clock/README.rst new file mode 100644 index 0000000..dd48e6a --- /dev/null +++ b/tests/clocks/input_attr_clock/README.rst
@@ -0,0 +1,14 @@ +Manually set input as clock by setting the CLOCK attribute ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The following shows that `input wire a` is given the `(* CLOCK *)` attribute. + +.. symbolator:: ../../../tests/clocks/input_attr_clock/input_attr_clock.sim.v + +.. literalinclude:: ../../../tests/clocks/input_attr_clock/input_attr_clock.sim.v + :language: verilog + +As such, the `is_clock` attribute of the `a` port is set to 1. + +.. literalinclude:: ../../../tests/clocks/input_attr_clock/golden.model.xml + :language: xml \ No newline at end of file
diff --git a/tests/clocks/input_attr_not_clock/README.rst b/tests/clocks/input_attr_not_clock/README.rst new file mode 100644 index 0000000..22180a1 --- /dev/null +++ b/tests/clocks/input_attr_not_clock/README.rst
@@ -0,0 +1,14 @@ +Force input as regular input by setting the CLOCK attribute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +`input wire a` should be detected as a clock because it drives the flip flop. However, it has the attribute CLOCK set to 0 which should force it to be a regular input. + +.. symbolator:: ../../../tests/clocks/input_attr_not_clock/input_attr_not_clock.sim.v + +.. literalinclude:: ../../../tests/clocks/input_attr_not_clock/input_attr_not_clock.sim.v + :language: verilog + +As such, the `is_clock` attribute of the `a` port is not set. + +.. literalinclude:: ../../../tests/clocks/input_attr_not_clock/golden.model.xml + :language: xml \ No newline at end of file
diff --git a/tests/clocks/input_named_clk/README.rst b/tests/clocks/input_named_clk/README.rst new file mode 100644 index 0000000..efbd6be --- /dev/null +++ b/tests/clocks/input_named_clk/README.rst
@@ -0,0 +1,14 @@ +Set input as clock by name (clk) ++++++++++++++++++++++++++++++++++++ + +An input wire can be set as a clock by assigning `clk` as its name. + +.. symbolator:: ../../../tests/clocks/input_named_clk/input_named_clk.sim.v + +.. literalinclude:: ../../../tests/clocks/input_named_clk/input_named_clk.sim.v + :language: verilog + +As such, the `is_clock` attribute of the `clk` port is set to 1, without needing to set anything else in the verilog code. + +.. literalinclude:: ../../../tests/clocks/input_named_clk/golden.model.xml + :language: xml \ No newline at end of file
diff --git a/tests/clocks/input_named_regex/README.rst b/tests/clocks/input_named_regex/README.rst new file mode 100644 index 0000000..e55f79a --- /dev/null +++ b/tests/clocks/input_named_regex/README.rst
@@ -0,0 +1,14 @@ +Set input as clock by name (regex) ++++++++++++++++++++++++++++++++++++ + +An input wire can be set as a clock by having `clk` in its name (case insensitive). + +.. symbolator:: ../../../tests/clocks/input_named_regex/input_named_regex.sim.v + +.. literalinclude:: ../../../tests/clocks/input_named_regex/input_named_regex.sim.v + :language: verilog + +As such, the `is_clock` attribute of wires with a variation of `clk` in their name is set to 1. + +.. literalinclude:: ../../../tests/clocks/input_named_regex/golden.model.xml + :language: xml \ No newline at end of file
diff --git a/tests/clocks/multiple_inputs_named_clk/README.rst b/tests/clocks/multiple_inputs_named_clk/README.rst new file mode 100644 index 0000000..8bdcd76 --- /dev/null +++ b/tests/clocks/multiple_inputs_named_clk/README.rst
@@ -0,0 +1,14 @@ +Set inputs as clock by name (multiple clock inputs) ++++++++++++++++++++++++++++++++++++++++++++++++++++ + +`input wire rdclk` and `input wire wrclk` have `clk` in their names, hence are recognized as clock inputs by v2x. + +.. symbolator:: ../../../tests/clocks/multiple_inputs_named_clk/multiple_inputs_named_clk.sim.v + +.. literalinclude:: ../../../tests/clocks/multiple_inputs_named_clk/multiple_inputs_named_clk.sim.v + :language: verilog + +As such, the `is_clock` attribute of the `rdclk` and `wrclk` ports are set to 1. + +.. literalinclude:: ../../../tests/clocks/multiple_inputs_named_clk/golden.model.xml + :language: xml \ No newline at end of file
diff --git a/tests/clocks/multiple_outputs_named_clk/README.rst b/tests/clocks/multiple_outputs_named_clk/README.rst new file mode 100644 index 0000000..3376756 --- /dev/null +++ b/tests/clocks/multiple_outputs_named_clk/README.rst
@@ -0,0 +1,14 @@ +Set outputs as clock by name (multiple clock outputs) ++++++++++++++++++++++++++++++++++++++++++++++++++++ + +`output wire rdclk` and `output wire wrclk` have `clk` in their names, hence are recognized as clock inputs by v2x. + +.. symbolator:: ../../../tests/clocks/multiple_outputs_named_clk/multiple_outputs_named_clk.sim.v + +.. literalinclude:: ../../../tests/clocks/multiple_outputs_named_clk/multiple_outputs_named_clk.sim.v + :language: verilog + +As such, the `is_clock` attribute of the `rdclk` and `wrclk` ports are set to 1. + +.. literalinclude:: ../../../tests/clocks/multiple_outputs_named_clk/golden.model.xml + :language: xml \ No newline at end of file
diff --git a/tests/clocks/output_attr_clock/README.rst b/tests/clocks/output_attr_clock/README.rst new file mode 100644 index 0000000..05f9946 --- /dev/null +++ b/tests/clocks/output_attr_clock/README.rst
@@ -0,0 +1,14 @@ +Manually set output as clock by setting the CLOCK attribute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The following shows that `output wire o` is given the `(* CLOCK *)` attribute. + +.. symbolator:: ../../../tests/clocks/output_attr_clock/output_attr_clock.sim.v + +.. literalinclude:: ../../../tests/clocks/output_attr_clock/output_attr_clock.sim.v + :language: verilog + +As such, the `is_clock` attribute of the `o` port is set to 1. + +.. literalinclude:: ../../../tests/clocks/output_attr_clock/golden.model.xml + :language: xml \ No newline at end of file
diff --git a/tests/clocks/output_named_clk/README.rst b/tests/clocks/output_named_clk/README.rst new file mode 100644 index 0000000..9cb2878 --- /dev/null +++ b/tests/clocks/output_named_clk/README.rst
@@ -0,0 +1,14 @@ +Set output as clock by name (clk) ++++++++++++++++++++++++++++++++++++ + +An output wire can be set as a clock by assigning `clk` as its name. + +.. symbolator:: ../../../tests/clocks/output_named_clk/output_named_clk.sim.v + +.. literalinclude:: ../../../tests/clocks/output_named_clk/output_named_clk.sim.v + :language: verilog + +As such, the `is_clock` attribute of the `clk` output port is set to 1. + +.. literalinclude:: ../../../tests/clocks/output_named_clk/golden.model.xml + :language: xml \ No newline at end of file