From 2b270b227010b95841527d8452155a54a453f950 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Wed, 15 Nov 2023 17:39:37 +1300 Subject: [PATCH] docs: Tidying image generation Makefiles now have `clean` target. Also fixed top level makefile calls to images directory. More yosys scripts instead of inline yosys commands in makefiles (which also means they can be included in the accompanying document when talking about the image generated). Fixed another couple image generators that were still outputting pdf directly. Fixed some hanging image references which hadn't been updated. Adjusted some text related to images, and included a couple more intermediate images on `memdemo`. --- Makefile | 1 - docs/source/code_examples/intro/Makefile | 6 +- docs/source/code_examples/macc/Makefile | 4 + .../code_examples/macc/macc_simple_test.ys | 14 +-- docs/source/code_examples/scrambler/Makefile | 4 + docs/source/code_examples/selections/Makefile | 20 ++-- .../code_examples/selections/memdemo.ys | 9 ++ .../source/code_examples/selections/select.ys | 4 +- .../source/code_examples/selections/submod.ys | 2 +- .../code_examples/selections/sumprod.ys | 10 ++ docs/source/code_examples/show/Makefile | 11 +- docs/source/code_examples/show/cmos.ys | 17 +++ docs/source/code_examples/synth_flow/Makefile | 3 +- docs/source/code_examples/techmap/Makefile | 4 + docs/source/getting_started/examples.rst | 8 +- .../source/getting_started/typical_phases.rst | 24 ++-- .../interactive_investigation.rst | 18 ++- .../using_yosys/more_scripting/selections.rst | 106 ++++++++++-------- docs/source/using_yosys/yosys_flows.rst | 40 +++---- docs/source/yosys_internals/techmap.rst | 10 +- 20 files changed, 197 insertions(+), 118 deletions(-) create mode 100644 docs/source/code_examples/selections/memdemo.ys create mode 100644 docs/source/code_examples/selections/sumprod.ys create mode 100644 docs/source/code_examples/show/cmos.ys diff --git a/Makefile b/Makefile index 8418aefde..0b8cb96dd 100644 --- a/Makefile +++ b/Makefile @@ -971,7 +971,6 @@ docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS) PHONY: docs/gen_images docs/guidelines docs/usage docs/gen_images: - $(Q) $(MAKE) -C docs/source/_images resources $(Q) $(MAKE) -C docs/source/_images all DOCS_GUIDELINE_FILES := GettingStarted CodingStyle diff --git a/docs/source/code_examples/intro/Makefile b/docs/source/code_examples/intro/Makefile index 3b7bbfe7f..c7507e934 100644 --- a/docs/source/code_examples/intro/Makefile +++ b/docs/source/code_examples/intro/Makefile @@ -6,5 +6,9 @@ DOTS = counter_00.dot counter_01.dot counter_02.dot counter_03.dot dots: $(DOTS) -$(DOTS): counter.v counter.ys mycells.lib +$(DOTS): counter.v counter_outputs.ys mycells.lib $(YOSYS) counter_outputs.ys + +.PHONY: clean +clean: + rm -f *.dot diff --git a/docs/source/code_examples/macc/Makefile b/docs/source/code_examples/macc/Makefile index 27b8166f8..57ba455bb 100644 --- a/docs/source/code_examples/macc/Makefile +++ b/docs/source/code_examples/macc/Makefile @@ -12,3 +12,7 @@ macc_simple_xmap.dot: macc_simple_*.v macc_simple_test.ys macc_xilinx_xmap.dot: macc_xilinx_*.v macc_xilinx_test.ys $(YOSYS) macc_xilinx_test.ys +.PHONY: clean +clean: + rm -f *.dot + diff --git a/docs/source/code_examples/macc/macc_simple_test.ys b/docs/source/code_examples/macc/macc_simple_test.ys index 8d106a28c..70496c057 100644 --- a/docs/source/code_examples/macc/macc_simple_test.ys +++ b/docs/source/code_examples/macc/macc_simple_test.ys @@ -1,10 +1,10 @@ read_verilog macc_simple_test.v hierarchy -check -top test;; -show -prefix macc_simple_test_00a -format pdf -notitle -lib macc_simple_xmap.v +show -prefix macc_simple_test_00a -format dot -notitle -lib macc_simple_xmap.v extract -constports -map macc_simple_xmap.v;; -show -prefix macc_simple_test_00b -format pdf -notitle -lib macc_simple_xmap.v +show -prefix macc_simple_test_00b -format dot -notitle -lib macc_simple_xmap.v ################################################# @@ -12,10 +12,10 @@ design -reset read_verilog macc_simple_test_01.v hierarchy -check -top test;; -show -prefix macc_simple_test_01a -format pdf -notitle -lib macc_simple_xmap.v +show -prefix macc_simple_test_01a -format dot -notitle -lib macc_simple_xmap.v extract -map macc_simple_xmap.v;; -show -prefix macc_simple_test_01b -format pdf -notitle -lib macc_simple_xmap.v +show -prefix macc_simple_test_01b -format dot -notitle -lib macc_simple_xmap.v ################################################# @@ -23,10 +23,10 @@ design -reset read_verilog macc_simple_test_02.v hierarchy -check -top test;; -show -prefix macc_simple_test_02a -format pdf -notitle -lib macc_simple_xmap.v +show -prefix macc_simple_test_02a -format dot -notitle -lib macc_simple_xmap.v extract -map macc_simple_xmap.v;; -show -prefix macc_simple_test_02b -format pdf -notitle -lib macc_simple_xmap.v +show -prefix macc_simple_test_02b -format dot -notitle -lib macc_simple_xmap.v ################################################# @@ -34,4 +34,4 @@ design -reset read_verilog macc_simple_xmap.v hierarchy -check -top macc_16_16_32;; -show -prefix macc_simple_xmap -format pdf -notitle +show -prefix macc_simple_xmap -format dot -notitle diff --git a/docs/source/code_examples/scrambler/Makefile b/docs/source/code_examples/scrambler/Makefile index e1b1d2979..4fdb0610a 100644 --- a/docs/source/code_examples/scrambler/Makefile +++ b/docs/source/code_examples/scrambler/Makefile @@ -6,3 +6,7 @@ dots: scrambler_p01.dot scrambler_p02.dot scrambler_p01.dot scrambler_p02.dot: scrambler.ys scrambler.v $(YOSYS) scrambler.ys + +.PHONY: clean +clean: + rm -f *.dot diff --git a/docs/source/code_examples/selections/Makefile b/docs/source/code_examples/selections/Makefile index 0ec85bb20..06abd2a3e 100644 --- a/docs/source/code_examples/selections/Makefile +++ b/docs/source/code_examples/selections/Makefile @@ -16,17 +16,15 @@ dots: select.dot $(SUMPROD_DOTS) $(MEMDEMO_DOTS) $(SUBMOD_DOTS) select.dot: select.v select.ys $(YOSYS) select.ys -$(SUMPROD_DOTS): sumprod.v - $(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select a:sumstuff; show -format dot -prefix sumprod_00' - $(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select a:sumstuff %x; show -format dot -prefix sumprod_01' - $(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select prod; show -format dot -prefix sumprod_02' - $(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select prod %ci; show -format dot -prefix sumprod_03' - $(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select prod %ci2; show -format dot -prefix sumprod_04' - $(YOSYS) -p 'read_verilog sumprod.v; opt; cd sumprod; select prod %ci3; show -format dot -prefix sumprod_05' +$(SUMPROD_DOTS): sumprod.v sumprod.ys + $(YOSYS) sumprod.ys -$(MEMDEMO_DOTS): memdemo.v - $(YOSYS) -p 'read_verilog memdemo.v; proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_00' - $(YOSYS) -p 'read_verilog memdemo.v; proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_01 y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff' +$(MEMDEMO_DOTS): memdemo.v memdemo.ys + $(YOSYS) memdemo.ys -$(SUBMOD_DOTS): submod.ys memdemo.v +$(SUBMOD_DOTS): memdemo.v submod.ys $(YOSYS) submod.ys + +.PHONY: clean +clean: + rm -rf *.dot diff --git a/docs/source/code_examples/selections/memdemo.ys b/docs/source/code_examples/selections/memdemo.ys new file mode 100644 index 000000000..e240f1621 --- /dev/null +++ b/docs/source/code_examples/selections/memdemo.ys @@ -0,0 +1,9 @@ +read_verilog memdemo.v +prep -top memdemo; memory; opt + +cd memdemo +show -format dot -prefix memdemo_00 +show -format dot -prefix memdemo_01 y %ci2 +show -format dot -prefix memdemo_02 y %ci2:+$dff[Q,D] +show -format dot -prefix memdemo_03 y %ci2:-[CLK] %ci2 +show -format dot -prefix memdemo_04 y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff diff --git a/docs/source/code_examples/selections/select.ys b/docs/source/code_examples/selections/select.ys index 565ce90a3..e9a775f1f 100644 --- a/docs/source/code_examples/selections/select.ys +++ b/docs/source/code_examples/selections/select.ys @@ -1,6 +1,6 @@ read_verilog select.v -hierarchy -check -top test -proc; opt +prep -top test + cd test select -set cone_a state_a %ci*:-$dff select -set cone_b state_b %ci*:-$dff diff --git a/docs/source/code_examples/selections/submod.ys b/docs/source/code_examples/selections/submod.ys index 29ad61076..c252153c6 100644 --- a/docs/source/code_examples/selections/submod.ys +++ b/docs/source/code_examples/selections/submod.ys @@ -1,5 +1,5 @@ read_verilog memdemo.v -proc; opt; memory; opt +prep -top memdemo; memory; opt cd memdemo select -set outstage y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff diff --git a/docs/source/code_examples/selections/sumprod.ys b/docs/source/code_examples/selections/sumprod.ys new file mode 100644 index 000000000..1e687fa4e --- /dev/null +++ b/docs/source/code_examples/selections/sumprod.ys @@ -0,0 +1,10 @@ +read_verilog sumprod.v +prep -top sumprod +cd sumprod + +show -format dot -prefix sumprod_00 a:sumstuff +show -format dot -prefix sumprod_01 a:sumstuff %x +show -format dot -prefix sumprod_02 prod +show -format dot -prefix sumprod_03 prod %ci +show -format dot -prefix sumprod_04 prod %ci2 +show -format dot -prefix sumprod_05 prod %ci3 diff --git a/docs/source/code_examples/show/Makefile b/docs/source/code_examples/show/Makefile index 18da74d6a..c57012f92 100644 --- a/docs/source/code_examples/show/Makefile +++ b/docs/source/code_examples/show/Makefile @@ -11,13 +11,14 @@ CMOS_DOTS := $(addsuffix .dot,$(CMOS)) dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS) splice.dot: splice.v - $(YOSYS) -p 'read_verilog splice.v; proc; opt; show -format dot -prefix splice' + $(YOSYS) -p 'prep -top splice_demo; show -format dot -prefix splice' splice.v $(EXAMPLE_DOTS): example.v example.ys $(YOSYS) example.ys -cmos_00.dot: cmos.v - $(YOSYS) -p 'read_verilog cmos.v; techmap; abc -liberty ../intro/mycells.lib;; show -format dot -prefix cmos_00' +$(CMOS_DOTS): cmos.v cmos.ys + $(YOSYS) cmos.ys -cmos_01.dot: cmos.v - $(YOSYS) -p 'read_verilog cmos.v; techmap; splitnets -ports; abc -liberty ../intro/mycells.lib;; show -lib ../intro/mycells.v -format dot -prefix cmos_01' +.PHONY: clean +clean: + rm -rf *.dot diff --git a/docs/source/code_examples/show/cmos.ys b/docs/source/code_examples/show/cmos.ys new file mode 100644 index 000000000..7158de1d0 --- /dev/null +++ b/docs/source/code_examples/show/cmos.ys @@ -0,0 +1,17 @@ +# pitfall +read_verilog cmos.v +prep -top cmos_demo +techmap +abc -liberty ../intro/mycells.lib;; +show -format dot -prefix cmos_00 + +# reset +design -reset + +# fixed output +read_verilog cmos.v +prep -top cmos_demo +techmap +splitnets -ports +abc -liberty ../intro/mycells.lib;; +show -lib ../intro/mycells.v -format dot -prefix cmos_01 diff --git a/docs/source/code_examples/synth_flow/Makefile b/docs/source/code_examples/synth_flow/Makefile index 25763ef03..804f6da37 100644 --- a/docs/source/code_examples/synth_flow/Makefile +++ b/docs/source/code_examples/synth_flow/Makefile @@ -16,6 +16,7 @@ dots: $(DOTS) %.dot: %.v %.ys $(YOSYS) -p 'script $*.ys; show -notitle -prefix $* -format dot' +.PHONY: clean clean: - rm -f $(DOTS) + rm -f *.dot diff --git a/docs/source/code_examples/techmap/Makefile b/docs/source/code_examples/techmap/Makefile index 531fab085..e4e0ac745 100644 --- a/docs/source/code_examples/techmap/Makefile +++ b/docs/source/code_examples/techmap/Makefile @@ -18,3 +18,7 @@ mulshift.dot: mulshift_* addshift.dot: addshift_* $(YOSYS) addshift_test.ys + +.PHONY: clean +clean: + rm -f *.dot diff --git a/docs/source/getting_started/examples.rst b/docs/source/getting_started/examples.rst index 8fecb4985..5e1b0e429 100644 --- a/docs/source/getting_started/examples.rst +++ b/docs/source/getting_started/examples.rst @@ -106,7 +106,7 @@ Step 1 Result: -.. figure:: /_images/res/PRESENTATION_Intro/counter_00.* +.. figure:: /_images/code_examples/intro/counter_00.* :class: width-helper Step 2 @@ -118,7 +118,7 @@ Step 2 Result: -.. figure:: /_images/res/PRESENTATION_Intro/counter_01.* +.. figure:: /_images/code_examples/intro/counter_01.* :class: width-helper Step 3 @@ -130,7 +130,7 @@ Step 3 Result: -.. figure:: /_images/res/PRESENTATION_Intro/counter_02.* +.. figure:: /_images/code_examples/intro/counter_02.* :class: width-helper Step 4 @@ -142,5 +142,5 @@ Step 4 Result: -.. figure:: /_images/res/PRESENTATION_Intro/counter_03.* +.. figure:: /_images/code_examples/intro/counter_03.* :class: width-helper diff --git a/docs/source/getting_started/typical_phases.rst b/docs/source/getting_started/typical_phases.rst index d04419ec1..2fce9215c 100644 --- a/docs/source/getting_started/typical_phases.rst +++ b/docs/source/getting_started/typical_phases.rst @@ -94,10 +94,10 @@ Example :language: yoscrypt :caption: ``docs/source/code_examples/synth_flow/proc_01.ys`` -.. figure:: /_images/res/PRESENTATION_ExSyn/proc_01.* +.. figure:: /_images/code_examples/synth_flow/proc_01.* :class: width-helper -.. figure:: /_images/res/PRESENTATION_ExSyn/proc_02.* +.. figure:: /_images/code_examples/synth_flow/proc_02.* :class: width-helper .. literalinclude:: /code_examples/synth_flow/proc_02.v @@ -108,7 +108,7 @@ Example :language: yoscrypt :caption: ``docs/source/code_examples/synth_flow/proc_02.ys`` -.. figure:: /_images/res/PRESENTATION_ExSyn/proc_03.* +.. figure:: /_images/code_examples/synth_flow/proc_03.* :class: width-helper .. literalinclude:: /code_examples/synth_flow/proc_03.ys @@ -145,12 +145,12 @@ The command :cmd:ref:`clean` can be used as alias for :cmd:ref:`opt_clean`. And .. code-block:: yoscrypt - proc; opt; memory; opt_expr;; fsm;; + hierarchy; proc; opt; memory; opt_expr;; fsm;; Example ^^^^^^^ -.. figure:: /_images/res/PRESENTATION_ExSyn/opt_01.* +.. figure:: /_images/code_examples/synth_flow/opt_01.* :class: width-helper .. literalinclude:: /code_examples/synth_flow/opt_01.ys @@ -161,7 +161,7 @@ Example :language: verilog :caption: ``docs/source/code_examples/synth_flow/opt_01.v`` -.. figure:: /_images/res/PRESENTATION_ExSyn/opt_02.* +.. figure:: /_images/code_examples/synth_flow/opt_02.* :class: width-helper .. literalinclude:: /code_examples/synth_flow/opt_02.ys @@ -172,7 +172,7 @@ Example :language: verilog :caption: ``docs/source/code_examples/synth_flow/opt_02.v`` -.. figure:: /_images/res/PRESENTATION_ExSyn/opt_03.* +.. figure:: /_images/code_examples/synth_flow/opt_03.* :class: width-helper .. literalinclude:: /code_examples/synth_flow/opt_03.ys @@ -183,7 +183,7 @@ Example :language: verilog :caption: ``docs/source/code_examples/synth_flow/opt_03.v`` -.. figure:: /_images/res/PRESENTATION_ExSyn/opt_04.* +.. figure:: /_images/code_examples/synth_flow/opt_04.* :class: width-helper .. literalinclude:: /code_examples/synth_flow/opt_04.v @@ -246,7 +246,7 @@ For example: Example ^^^^^^^ -.. figure:: /_images/res/PRESENTATION_ExSyn/memory_01.* +.. figure:: /_images/code_examples/synth_flow/memory_01.* :class: width-helper .. literalinclude:: /code_examples/synth_flow/memory_01.ys @@ -257,7 +257,7 @@ Example :language: verilog :caption: ``docs/source/code_examples/synth_flow/memory_01.v`` -.. figure:: /_images/res/PRESENTATION_ExSyn/memory_02.* +.. figure:: /_images/code_examples/synth_flow/memory_02.* :class: width-helper .. literalinclude:: /code_examples/synth_flow/memory_02.v @@ -315,7 +315,7 @@ Finally the :cmd:ref:`fsm_map` command can be used to convert the (optimized) The :cmd:ref:`techmap` command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. figure:: /_images/res/PRESENTATION_ExSyn/techmap_01.* +.. figure:: /_images/code_examples/synth_flow/techmap_01.* :class: width-helper The :cmd:ref:`techmap` command replaces cells with implementations given as @@ -386,7 +386,7 @@ Example :language: yoscrypt :caption: ``docs/source/code_examples/synth_flow/abc_01.ys`` -.. figure:: /_images/res/PRESENTATION_ExSyn/abc_01.* +.. figure:: /_images/code_examples/synth_flow/abc_01.* :class: width-helper Other special-purpose mapping commands diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 5b312d4e1..fe78c66c5 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -130,7 +130,7 @@ when the individual bits of of a signal vector are accessed. :class: width-helper :name: splice_dia - Output of ``yosys -p 'proc; opt; show' splice.v`` + Output of ``yosys -p 'prep -top splice_demo; show' splice.v`` The key elements in understanding this circuit diagram are of course the boxes with round corners and rows labeled ``: - @@ -152,7 +152,7 @@ Gate level netlists ^^^^^^^^^^^^^^^^^^^ :numref:`first_pitfall` shows two common pitfalls when working with designs -mapped to a cell library: +mapped to a cell library: .. figure:: /_images/code_examples/show/cmos_00.* :class: width-helper @@ -160,6 +160,13 @@ mapped to a cell library: A half-adder built from simple CMOS gates, demonstrating common pitfalls when using :cmd:ref:`show` + +.. literalinclude:: /code_examples/show/cmos.ys + :language: yoscrypt + :start-after: pitfall + :end-at: cmos_00 + :name: pitfall_code + :caption: Generating :numref:`first_pitfall` First, Yosys did not have access to the cell library when this diagram was generated, resulting in all cell ports defaulting to being inputs. This is why @@ -174,6 +181,13 @@ individual bits, resulting in an unnecessary complex diagram. Effects of :cmd:ref:`splitnets` command and of providing a cell library on design in :numref:`first_pitfall` +.. literalinclude:: /code_examples/show/cmos.ys + :language: yoscrypt + :start-after: fixed + :end-at: cmos_01 + :name: pitfall_avoided + :caption: Generating :numref:`second_pitfall` + For :numref:`second_pitfall`, Yosys has been given a description of the cell library as Verilog file containing blackbox modules. There are two ways to load cell descriptions into Yosys: First the Verilog file for the cell library can be diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index 879ceb7e8..eb3f66d6c 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -177,6 +177,8 @@ selected wire it selects all cells connected to the wire and vice versa. So Output of ``show a:sumstuff %x`` on :numref:`sumprod` +.. _selecting_logic_cones: + Selecting logic cones ^^^^^^^^^^^^^^^^^^^^^ @@ -231,16 +233,29 @@ and/or ports. This can be achieved using additional patterns that can be appended to the ``%ci`` action. Lets consider :numref:`memdemo_src`. It serves no purpose other than being a -non-trivial circuit for demonstrating some of the advanced Yosys features. +non-trivial circuit for demonstrating some of the advanced Yosys features. This +code is available in ``docs/source/code_examples/selections`` of the Yosys +source repository. .. literalinclude:: /code_examples/selections/memdemo.v - :caption: Demo circuit for demonstrating some advanced Yosys features + :caption: ``memdemo.v`` :name: memdemo_src :language: verilog -We synthesize the circuit using ``proc; opt; memory; opt`` and change to the -``memdemo`` module with ``cd memdemo``. If we type :cmd:ref:`show` now we see -the diagram shown in :numref:`memdemo_00`. +The script ``memdemo.ys`` is used to generate the images included here. Let's +look at the first section: + +.. literalinclude:: /code_examples/selections/memdemo.ys + :caption: Synthesizing :ref:`memdemo_src` + :name: memdemo_ys + :language: yoscrypt + :end-at: opt + +This loads :numref:`memdemo_src` and synthesizes the included module. Note that +this code can be copied and run directly in a Yosys command line session, +provided ``memdemo.v`` is in the same directory. We can now change to the +``memdemo`` module with ``cd memdemo``, and call :cmd:ref:`show` to see the +diagram in :numref:`memdemo_00`. .. figure:: /_images/code_examples/selections/memdemo_00.* :class: width-helper @@ -248,13 +263,19 @@ the diagram shown in :numref:`memdemo_00`. Complete circuit diagram for the design shown in :numref:`memdemo_src` -But maybe we are only interested in the tree of multiplexers that select the -output value. In order to get there, we would start by just showing the output -signal and its immediate predecessors: +.. todo:: :ref:`memdemo_01` and :ref:`memdemo_02` are the same, probably change + the example so they aren't. -.. code-block:: yoscrypt +There's a lot going on there, but maybe we are only interested in the tree of +multiplexers that select the output value. Let's start by just showing the +output signal, ``y``, and its immediate predecessors. Remember `Selecting logic +cones`_ from above, we can use :yoscrypt:`show y %ci2`: - show y %ci2 +.. figure:: /_images/code_examples/selections/memdemo_01.* + :class: width-helper + :name: memdemo_01 + + Output of :yoscrypt:`show y %ci2` From this we would learn that ``y`` is driven by a ``$dff cell``, that ``y`` is connected to the output port ``Q``, that the ``clk`` signal goes into the @@ -262,12 +283,14 @@ connected to the output port ``Q``, that the ``clk`` signal goes into the wire into the input ``D`` of the flip-flop cell. As we are not interested in the clock signal we add an additional pattern to the -``%ci`` action, that tells it to only follow ports ``Q`` and ``D`` of ``$dff`` -cells: +``%ci`` action :yoscrypt:`show y %ci2:+$dff[Q,D]`, that tells it to only follow +ports ``Q`` and ``D`` of ``$dff`` cells: -.. code-block:: yoscrypt - - show y %ci2:+$dff[Q,D] +.. figure:: /_images/code_examples/selections/memdemo_02.* + :class: width-helper + :name: memdemo_02 + + Output of :yoscrypt:`show y %ci2:+$dff[Q,D]` To add a pattern we add a colon followed by the pattern to the ``%ci`` action. The pattern itself starts with ``-`` or ``+``, indicating if it is an include or @@ -275,43 +298,32 @@ exclude pattern, followed by an optional comma separated list of cell types, followed by an optional comma separated list of port names in square brackets. Since we know that the only cell considered in this case is a ``$dff`` cell, we -could as well only specify the port names: - -.. code-block:: yoscrypt - - show y %ci2:+[Q,D] - -Or we could decide to tell the ``%ci`` action to not follow the ``CLK`` input: - -.. code-block:: yoscrypt - - show y %ci2:-[CLK] - -.. figure:: /_images/code_examples/selections/memdemo_01.* - :class: width-helper - :name: memdemo_01 - - Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff`` +could as well only specify the port names, :yoscrypt:`show y %ci2:+[Q,D]`. Or we +could decide to tell the ``%ci`` action to not follow the ``CLK`` input, +:yoscrypt:`show y %ci2:-[CLK]`. Next we would investigate the next logic level by adding another ``%ci2`` to the -command: +command, :yoscrypt:`show y %ci2:-[CLK] %ci2`: -.. code-block:: yoscrypt - - show y %ci2:-[CLK] %ci2 +.. figure:: /_images/code_examples/selections/memdemo_03.* + :class: width-helper + :name: memdemo_03 + + Output of :yoscrypt:`show y %ci2:-[CLK] %ci2` From this we would learn that the next cell is a ``$mux`` cell and we would add -additional pattern to narrow the selection on the path we are interested. In the -end we would end up with a command such as +an additional pattern to narrow the selection on the path we are interested. In +the end we would end up with a command such as :yoscrypt:`show y %ci2:+$dff[Q,D] +%ci*:-$mux[S]:-$dff` in which the first ``%ci`` jumps over the initial d-type +flip-flop and the 2nd action selects the entire input cone without going over +multiplexer select inputs and flip-flop cells. The diagram produced by this +command is shown in :numref:`memdemo_04`. -.. code-block:: yoscrypt - - show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff - -in which the first ``%ci`` jumps over the initial d-type flip-flop and the 2nd -action selects the entire input cone without going over multiplexer select -inputs and flip-flop cells. The diagram produces by this command is shown in -:numref:`memdemo_01`. +.. figure:: /_images/code_examples/selections/memdemo_04.* + :class: width-helper + :name: memdemo_04 + + Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff`` Similar to ``%ci`` exists an action ``%co`` to select output cones that accepts the same syntax for pattern and repetition. The ``%x`` action mentioned @@ -350,6 +362,8 @@ on the stack. Storing and recalling selections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. todo:: reflow for not presentation + The current selection can be stored in memory with the command ``select -set ``. It can later be recalled using ``select @``. In fact, the ``@`` expression pushes the stored selection on the stack maintained by diff --git a/docs/source/using_yosys/yosys_flows.rst b/docs/source/using_yosys/yosys_flows.rst index 88e7a1479..b73ee59db 100644 --- a/docs/source/using_yosys/yosys_flows.rst +++ b/docs/source/using_yosys/yosys_flows.rst @@ -41,12 +41,12 @@ The extract pass .. todo:: add/expand supporting text -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_simple_test_00a.* +.. figure:: /_images/code_examples/macc/macc_simple_test_00a.* :class: width-helper before `extract` -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_simple_test_00b.* +.. figure:: /_images/code_examples/macc/macc_simple_test_00b.* :class: width-helper after `extract` @@ -70,20 +70,20 @@ The extract pass :language: verilog :caption: ``docs/source/code_examples/macc/macc_simple_test_01.v`` -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_simple_test_01a.* +.. figure:: /_images/code_examples/macc/macc_simple_test_01a.* :class: width-helper -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_simple_test_01b.* +.. figure:: /_images/code_examples/macc/macc_simple_test_01b.* :class: width-helper .. literalinclude:: /code_examples/macc/macc_simple_test_02.v :language: verilog :caption: ``docs/source/code_examples/macc/macc_simple_test_02.v`` -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_simple_test_02a.* +.. figure:: /_images/code_examples/macc/macc_simple_test_02a.* :class: width-helper -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_simple_test_02b.* +.. figure:: /_images/code_examples/macc/macc_simple_test_02b.* :class: width-helper The wrap-extract-unwrap method @@ -169,10 +169,10 @@ Unwrapping adders: ``macc_xilinx_unwrap_map.v`` :lines: 1-6 :caption: ``test1`` of ``docs/source/code_examples/macc/macc_xilinx_test.v`` -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test1a.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test1a.* :class: width-helper -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test1b.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test1b.* :class: width-helper .. literalinclude:: /code_examples/macc/macc_xilinx_test.v @@ -180,15 +180,15 @@ Unwrapping adders: ``macc_xilinx_unwrap_map.v`` :lines: 8-13 :caption: ``test2`` of ``docs/source/code_examples/macc/macc_xilinx_test.v`` -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test2a.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test2a.* :class: width-helper -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test2b.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test2b.* :class: width-helper Wrapping in ``test1``: -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test1b.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test1b.* :class: width-helper .. code:: yoscrypt @@ -200,12 +200,12 @@ Wrapping in ``test1``: -unsigned $__add_wrapper \ Y Y_WIDTH ;; -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test1c.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test1c.* :class: width-helper Wrapping in ``test2``: -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test2b.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test2b.* :class: width-helper .. code:: yoscrypt @@ -217,7 +217,7 @@ Wrapping in ``test2``: -unsigned $__add_wrapper \ Y Y_WIDTH ;; -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test2c.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test2c.* :class: width-helper Extract in ``test1``: @@ -235,10 +235,10 @@ Extract in ``test1``: -map %__macc_xilinx_xmap \ -swap $__add_wrapper A,B ;; -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test1c.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test1c.* :class: width-helper -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test1d.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test1d.* :class: width-helper Extract in ``test2``: @@ -256,18 +256,18 @@ Extract in ``test2``: -map %__macc_xilinx_xmap \ -swap $__add_wrapper A,B ;; -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test2c.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test2c.* :class: width-helper -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test2d.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test2d.* :class: width-helper Unwrap in ``test2``: -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test2d.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test2d.* :class: width-helper -.. figure:: /_images/res/PRESENTATION_ExAdv/macc_xilinx_test2e.* +.. figure:: /_images/code_examples/macc/macc_xilinx_test2e.* :class: width-helper .. code:: yoscrypt diff --git a/docs/source/yosys_internals/techmap.rst b/docs/source/yosys_internals/techmap.rst index a2f360a2c..3bbda4c38 100644 --- a/docs/source/yosys_internals/techmap.rst +++ b/docs/source/yosys_internals/techmap.rst @@ -134,7 +134,7 @@ Mapping OR3X1 :language: verilog :caption: ``docs/source/code_examples/techmap/red_or3x1_map.v`` -.. figure:: /_images/res/PRESENTATION_ExAdv/red_or3x1.* +.. figure:: /_images/code_examples/techmap/red_or3x1.* :class: width-helper .. literalinclude:: /code_examples/techmap/red_or3x1_test.ys @@ -160,7 +160,7 @@ Conditional techmap Example: -.. figure:: /_images/res/PRESENTATION_ExAdv/sym_mul.* +.. figure:: /_images/code_examples/techmap/sym_mul.* :class: width-helper .. literalinclude:: /code_examples/techmap/sym_mul_map.v @@ -199,7 +199,7 @@ Scripting in map modules Example: -.. figure:: /_images/res/PRESENTATION_ExAdv/mymul.* +.. figure:: /_images/code_examples/techmap/mymul.* :class: width-helper .. literalinclude:: /code_examples/techmap/mymul_map.v @@ -229,7 +229,7 @@ Handling constant inputs Example: -.. figure:: /_images/res/PRESENTATION_ExAdv/mulshift.* +.. figure:: /_images/code_examples/techmap/mulshift.* :class: width-helper .. literalinclude:: /code_examples/techmap/mulshift_map.v @@ -260,7 +260,7 @@ Handling shorted inputs Example: -.. figure:: /_images/res/PRESENTATION_ExAdv/addshift.* +.. figure:: /_images/code_examples/techmap/addshift.* :class: width-helper .. literalinclude:: /code_examples/techmap/addshift_map.v