mirror of https://github.com/YosysHQ/yosys.git
Docs: interactive investigation
More `literalinclude` and references to source. Adding `example_show.ys` and `example_lscd.ys`. Rename `example_00` et al to `example_first` et al. Also some other minor tidying.
This commit is contained in:
Krystine Sherwin
parent
9fe3dcda78
commit
646ff6d32d
|
|
@ -2,13 +2,13 @@ PROGRAM_PREFIX :=
|
|||
|
||||
YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
|
||||
|
||||
EXAMPLE = example_00 example_01 example_02
|
||||
EXAMPLE = example_first example_second example_third
|
||||
EXAMPLE_DOTS := $(addsuffix .dot,$(EXAMPLE))
|
||||
|
||||
CMOS = cmos_00 cmos_01
|
||||
CMOS_DOTS := $(addsuffix .dot,$(CMOS))
|
||||
|
||||
dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS)
|
||||
dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS) example.out
|
||||
|
||||
splice.dot: splice.v
|
||||
$(YOSYS) -p 'prep -top splice_demo; show -format dot -prefix splice' splice.v
|
||||
|
|
@ -16,6 +16,9 @@ splice.dot: splice.v
|
|||
$(EXAMPLE_DOTS): example.v example.ys
|
||||
$(YOSYS) example.ys
|
||||
|
||||
example.out: example_lscd.ys example.v
|
||||
$(YOSYS) $< -l $@ -Q -T
|
||||
|
||||
$(CMOS_DOTS): cmos.v cmos.ys
|
||||
$(YOSYS) cmos.ys
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,54 @@
|
|||
|
||||
-- Executing script file `example_lscd.ys' --
|
||||
|
||||
1. Executing Verilog-2005 frontend: example.v
|
||||
Parsing Verilog input from `example.v' to AST representation.
|
||||
Generating RTLIL representation for module `\example'.
|
||||
Successfully finished Verilog frontend.
|
||||
echo on
|
||||
|
||||
yosys> ls
|
||||
|
||||
1 modules:
|
||||
example
|
||||
|
||||
yosys> cd example
|
||||
|
||||
yosys [example]> ls
|
||||
|
||||
8 wires:
|
||||
$0\y[1:0]
|
||||
$add$example.v:5$2_Y
|
||||
$ternary$example.v:5$3_Y
|
||||
a
|
||||
b
|
||||
c
|
||||
clk
|
||||
y
|
||||
|
||||
2 cells:
|
||||
$add$example.v:5$2
|
||||
$ternary$example.v:5$3
|
||||
|
||||
1 processes:
|
||||
$proc$example.v:3$1
|
||||
|
||||
yosys [example]> dump $2
|
||||
|
||||
|
||||
attribute \src "example.v:5.22-5.27"
|
||||
cell $add $add$example.v:5$2
|
||||
parameter \Y_WIDTH 2
|
||||
parameter \B_WIDTH 1
|
||||
parameter \A_WIDTH 1
|
||||
parameter \B_SIGNED 0
|
||||
parameter \A_SIGNED 0
|
||||
connect \Y $add$example.v:5$2_Y
|
||||
connect \B \b
|
||||
connect \A \a
|
||||
end
|
||||
|
||||
yosys [example]> cd ..
|
||||
|
||||
yosys> echo off
|
||||
echo off
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
read_verilog example.v
|
||||
show -format dot -prefix example_00
|
||||
show -format dot -prefix example_first
|
||||
proc
|
||||
show -format dot -prefix example_01
|
||||
show -format dot -prefix example_second
|
||||
opt
|
||||
show -format dot -prefix example_02
|
||||
show -format dot -prefix example_third
|
||||
|
|
|
|||
|
|
@ -0,0 +1,8 @@
|
|||
read_verilog example.v
|
||||
echo on
|
||||
ls
|
||||
cd example
|
||||
ls
|
||||
dump $2
|
||||
cd ..
|
||||
echo off
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
read_verilog example.v
|
||||
show -pause # first
|
||||
proc
|
||||
show -pause # second
|
||||
opt
|
||||
show -pause # third
|
||||
|
|
@ -15,12 +15,16 @@ in the circuit diagrams generated by it.
|
|||
A simple circuit
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
:numref:`example_v` below provides the Verilog code for a simple circuit which
|
||||
we will use to demonstrate the usage of :cmd:ref:`show` in a simple setting.
|
||||
:ref:`example_v` below provides the Verilog code for a simple circuit which we
|
||||
will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. The
|
||||
code used is included in the Yosys code base under
|
||||
`docs/source/code_examples/show`_.
|
||||
|
||||
.. _docs/source/code_examples/show: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/show
|
||||
|
||||
.. literalinclude:: /code_examples/show/example.v
|
||||
:language: Verilog
|
||||
:caption: ``docs/source/code_examples/show/example.v``
|
||||
:caption: ``example.v``
|
||||
:name: example_v
|
||||
|
||||
The Yosys synthesis script we will be running is included as
|
||||
|
|
@ -30,22 +34,24 @@ Enter key. Using :yoscrypt:`show -pause` also allows the user to enter an
|
|||
interactive shell to further investigate the circuit before continuing
|
||||
synthesis.
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
:caption: ``docs/source/code_examples/show/example.ys``
|
||||
.. literalinclude:: /code_examples/show/example_show.ys
|
||||
:language: yoscrypt
|
||||
:caption: ``example_show.ys``
|
||||
:name: example_ys
|
||||
|
||||
read_verilog example.v
|
||||
show -pause # first
|
||||
proc
|
||||
show -pause # second
|
||||
opt
|
||||
show -pause # third
|
||||
|
||||
This script, when executed, will show the design after each of the three
|
||||
synthesis commands. We will now look at each of these diagrams and explain what
|
||||
is shown.
|
||||
|
||||
.. figure:: /_images/code_examples/show/example_00.*
|
||||
.. note::
|
||||
|
||||
The images uses in this document are generated from the ``example.ys`` file,
|
||||
rather than ``example_show.ys``. ``example.ys`` outputs the schematics as
|
||||
``.dot`` files rather than displaying them directly. You can view these
|
||||
images yourself by running ``yosys example.ys`` and then ``xdot
|
||||
example_first.dot`` etc.
|
||||
|
||||
.. figure:: /_images/code_examples/show/example_first.*
|
||||
:class: width-helper
|
||||
|
||||
Output of the first :cmd:ref:`show` command in :numref:`example_ys`
|
||||
|
|
@ -59,7 +65,7 @@ prefixed with a dollar sign. For more details on the internal cell library, see
|
|||
:doc:`/yosys_internals/formats/cell_library`.
|
||||
|
||||
Constants are shown as ellipses with the constant value as label. The syntax
|
||||
``<bit_width>'<bits>`` is used for for constants that are not 32-bit wide and/or
|
||||
``<bit_width>'<bits>`` is used for constants that are not 32-bit wide and/or
|
||||
contain bits that are not 0 or 1 (i.e. ``x`` or ``z``). Ordinary 32-bit
|
||||
constants are written using decimal numbers.
|
||||
|
||||
|
|
@ -77,7 +83,7 @@ original ``always``-block in the second line. Note how the multiplexer from the
|
|||
The :cmd:ref:`proc` command transforms the process from the first diagram into a
|
||||
multiplexer and a d-type flip-flop, which brings us to the second diagram:
|
||||
|
||||
.. figure:: /_images/code_examples/show/example_01.*
|
||||
.. figure:: /_images/code_examples/show/example_second.*
|
||||
:class: width-helper
|
||||
|
||||
Output of the second :cmd:ref:`show` command in :numref:`example_ys`
|
||||
|
|
@ -99,11 +105,11 @@ call :cmd:ref:`clean` before calling :cmd:ref:`show`.
|
|||
In this script we directly call :cmd:ref:`opt` as the next step, which finally
|
||||
leads us to the third diagram:
|
||||
|
||||
.. figure:: /_images/code_examples/show/example_02.*
|
||||
.. figure:: /_images/code_examples/show/example_third.*
|
||||
:class: width-helper
|
||||
:name: example_out
|
||||
|
||||
Output of the third :cmd:ref:`show` command in :numref:`example_ys`
|
||||
Output of the third :cmd:ref:`show` command in :ref:`example_ys`
|
||||
|
||||
Here we see that the :cmd:ref:`proc` command not only has removed the artifacts
|
||||
left behind by :cmd:ref:`proc`, but also determined correctly that it can remove
|
||||
|
|
@ -256,39 +262,16 @@ For most cases, the shell will start with the whole design selected (i.e. when
|
|||
the synthesis script does not already narrow the selection). The command
|
||||
:cmd:ref:`ls` can now be used to create a list of all modules. The command
|
||||
:cmd:ref:`cd` can be used to switch to one of the modules (type ``cd ..`` to
|
||||
switch back). Now the `ls` command lists the objects within that module.
|
||||
:numref:`lscd` below demonstrates this using the ``example.v`` from
|
||||
`A simple circuit`_
|
||||
switch back). Now the :cmd:ref:`ls` command lists the objects within that
|
||||
module. This is demonstrated below using ``example.v`` from `A simple circuit`_:
|
||||
|
||||
.. TODO:: update yosys output with $ternary$example.v$3
|
||||
|
||||
.. code-block:: none
|
||||
:caption: Demonstration of :cmd:ref:`ls` and :cmd:ref:`cd` having run ``yosys example.v``
|
||||
.. literalinclude:: /code_examples/show/example.out
|
||||
:language: doscon
|
||||
:start-at: yosys> ls
|
||||
:end-before: yosys [example]> dump
|
||||
:caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running ``yosys example.v``
|
||||
:name: lscd
|
||||
|
||||
yosys> ls
|
||||
|
||||
1 modules:
|
||||
example
|
||||
|
||||
yosys> cd example
|
||||
|
||||
yosys [example]> ls
|
||||
|
||||
7 wires:
|
||||
$0\y[1:0]
|
||||
$add$example.v:5$2_Y
|
||||
a
|
||||
b
|
||||
c
|
||||
clk
|
||||
y
|
||||
|
||||
3 cells:
|
||||
$add$example.v:5$2
|
||||
$procdff$7
|
||||
$procmux$5
|
||||
|
||||
When a module is selected using the :cmd:ref:`cd` command, all commands (with a
|
||||
few exceptions, such as the ``read_`` and ``write_`` commands) operate only on
|
||||
the selected module. This can also be useful for synthesis scripts where
|
||||
|
|
@ -308,25 +291,21 @@ Usually all interactive work is done with one module selected using the
|
|||
start with ``b`` from all modules whose names start with ``a``.
|
||||
|
||||
The :cmd:ref:`dump` command can be used to print all information about an
|
||||
object. For example ``dump $2`` will print :numref:`dump2`. This can for example
|
||||
be useful to determine the names of nets connected to cells, as the net-names
|
||||
are usually suppressed in the circuit diagram if they are auto-generated.
|
||||
object. For example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd
|
||||
example` above:
|
||||
|
||||
.. code-block:: RTLIL
|
||||
:caption: Output of ``dump $2`` using ``example.v`` from `A simple circuit`_
|
||||
.. literalinclude:: /code_examples/show/example.out
|
||||
:language: RTLIL
|
||||
:start-after: yosys [example]> dump
|
||||
:end-before: yosys [example]> cd
|
||||
:dedent:
|
||||
:caption: Output of :yoscrypt:`dump $2` after :numref:`lscd`
|
||||
:name: dump2
|
||||
|
||||
attribute \src "example.v:5"
|
||||
cell $add $add$example.v:5$2
|
||||
parameter \A_SIGNED 0
|
||||
parameter \A_WIDTH 1
|
||||
parameter \B_SIGNED 0
|
||||
parameter \B_WIDTH 1
|
||||
parameter \Y_WIDTH 2
|
||||
connect \A \a
|
||||
connect \B \b
|
||||
connect \Y $add$example.v:5$2_Y
|
||||
end
|
||||
This can for example be useful to determine the names of nets connected to
|
||||
cells, as the net-names are usually suppressed in the circuit diagram if they
|
||||
are auto-generated. Note that the output is in the RTLIL representation,
|
||||
described in :doc:`/yosys_internals/formats/rtlil_rep`.
|
||||
|
||||
Interactive Design Investigation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
|
|||
|
|
@ -141,10 +141,10 @@ See :doc:`/cmd/select` for the full list.
|
|||
Expanding selections
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The listing in :numref:`sumprod` uses the Yosys non-standard ``{... *}`` syntax
|
||||
to set the attribute ``sumstuff`` on all cells generated by the first assign
|
||||
statement. (This works on arbitrary large blocks of Verilog code an can be used
|
||||
to mark portions of code for analysis.)
|
||||
:numref:`sumprod` uses the Yosys non-standard ``{... *}`` syntax to set the
|
||||
attribute ``sumstuff`` on all cells generated by the first assign statement.
|
||||
(This works on arbitrary large blocks of Verilog code and can be used to mark
|
||||
portions of code for analysis.)
|
||||
|
||||
.. literalinclude:: /code_examples/selections/sumprod.v
|
||||
:caption: Another test module for operations on selections
|
||||
|
|
|
|||
Loading…
Reference in New Issue