mirror of
https://github.com/YosysHQ/yosys
synced 2025-06-06 06:03:23 +00:00
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`.
This commit is contained in:
Krystine Sherwin
parent
b6e61c16b1
commit
2b270b2270
20 changed files with 197 additions and 118 deletions
|
|
@ -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 ``<MSB_LEFT>:<LSB_LEFT> -
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<name>``. It can later be recalled using ``select @<name>``. In fact, the
|
||||
``@<name>`` expression pushes the stored selection on the stack maintained by
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue