mirror of https://github.com/YosysHQ/yosys.git
Docs: reworking scripting_intro
Now comes *after* example_synth, with references back to it. Includes some minor adjustment to the `fifo.ys` script to better demonstrate the `select` command. Still needs an updated section on `show`. Also includes some other minor updates.
This commit is contained in:
Krystine Sherwin
parent
74d2c918cd
commit
14b7c581fa
|
|
@ -27,7 +27,36 @@ Removing unused module `$abstract\fifo'.
|
|||
Removing unused module `$abstract\addr_gen'.
|
||||
Removed 2 unused modules.
|
||||
|
||||
yosys> select -set new_cells t:*
|
||||
yosys> select -module addr_gen
|
||||
|
||||
yosys [addr_gen]> select -list
|
||||
addr_gen
|
||||
addr_gen/$1\addr[7:0]
|
||||
addr_gen/$add$fifo.v:20$3_Y
|
||||
addr_gen/$eq$fifo.v:17$2_Y
|
||||
addr_gen/$0\addr[7:0]
|
||||
addr_gen/addr
|
||||
addr_gen/rst
|
||||
addr_gen/clk
|
||||
addr_gen/en
|
||||
addr_gen/$add$fifo.v:20$3
|
||||
addr_gen/$eq$fifo.v:17$2
|
||||
addr_gen/$proc$fifo.v:0$4
|
||||
addr_gen/$proc$fifo.v:13$1
|
||||
|
||||
yosys [addr_gen]> select t:*
|
||||
|
||||
yosys [addr_gen]*> select -list
|
||||
addr_gen/$add$fifo.v:20$3
|
||||
addr_gen/$eq$fifo.v:17$2
|
||||
|
||||
yosys [addr_gen]*> select -set new_cells %
|
||||
|
||||
yosys [addr_gen]*> select -clear
|
||||
|
||||
yosys> select -list addr_gen/t:*
|
||||
addr_gen/$add$fifo.v:20$3
|
||||
addr_gen/$eq$fifo.v:17$2
|
||||
|
||||
yosys> show -color maroon3 @new_cells -color cornflowerblue p:* -notitle -format dot -prefix addr_gen_hier
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,12 @@ read_verilog -defer fifo.v
|
|||
# turn command echoes on to use the log output as a console session
|
||||
echo on
|
||||
hierarchy -top addr_gen
|
||||
select -set new_cells t:*
|
||||
select -module addr_gen
|
||||
select -list
|
||||
select t:*
|
||||
select -list
|
||||
select -set new_cells %
|
||||
select -clear
|
||||
show -color maroon3 @new_cells -color cornflowerblue p:* -notitle -format dot -prefix addr_gen_hier
|
||||
|
||||
# ========================================================
|
||||
|
|
|
|||
|
|
@ -86,6 +86,8 @@ start mapping to hardware we will still need to load them later.
|
|||
Yosys from the source directory, this will be the ``share`` folder in the
|
||||
same directory.
|
||||
|
||||
.. _addr_gen_example:
|
||||
|
||||
The addr_gen module
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -115,6 +117,7 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy
|
|||
:start-at: yosys> hierarchy -top addr_gen
|
||||
:end-before: yosys> select
|
||||
:caption: :yoscrypt:`hierarchy -top addr_gen` output
|
||||
:name: hierarchy_output
|
||||
|
||||
Our ``addr_gen`` circuit now looks like this:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,5 +7,5 @@ Getting started with Yosys
|
|||
:maxdepth: 3
|
||||
|
||||
installation
|
||||
scripting_intro
|
||||
example_synth
|
||||
scripting_intro
|
||||
|
|
|
|||
|
|
@ -1,116 +1,91 @@
|
|||
Scripting in Yosys
|
||||
------------------
|
||||
|
||||
.. TODO:: logical consistency, esp with example_synth
|
||||
On the previous page we went through a synthesis script, running each command in
|
||||
the interactive Yosys shell. On this page, we will be introducing the script
|
||||
file format and how you can make your own synthesis scripts.
|
||||
|
||||
Yosys reads and processes commands from synthesis scripts, command line
|
||||
arguments and an interactive command prompt. Yosys commands consist of a command
|
||||
name and an optional whitespace separated list of arguments. Commands are
|
||||
terminated using the newline character or a semicolon (;). Empty lines and lines
|
||||
starting with the hash sign (#) are ignored. Also see :doc:`example_synth`.
|
||||
Yosys script files typically use the ``.ys`` extension and contain a set of
|
||||
commands for Yosys to run sequentially. These commands are the same ones we
|
||||
were using on the previous page like :cmd:ref:`read_verilog` and
|
||||
:cmd:ref:`hierarchy`. As with the interactive shell, each command consists of
|
||||
the command name, and an optional whitespace separated list of arguments.
|
||||
Commands are terminated with the newline character, or by a semicolon (;).
|
||||
Empty lines, and lines starting with the hash sign (#), are ignored.
|
||||
|
||||
The command :cmd:ref:`help` can be used to access the command reference manual,
|
||||
with ``help <command>`` providing details for a specific command. ``yosys -H``
|
||||
or ``yosys -h <command>`` will do the same outside of an interactive prompt.
|
||||
The entire reference manual is also available here at :doc:`/cmd_ref`.
|
||||
The synthesis starter script
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Example commands
|
||||
~~~~~~~~~~~~~~~~
|
||||
.. role:: yoscrypt(code)
|
||||
:language: yoscrypt
|
||||
|
||||
Commands for design navigation and investigation:
|
||||
All of the images and console output used in
|
||||
:doc:`/getting_started/example_synth` were generated by Yosys, using Yosys
|
||||
script files found in ``docs/source/code_examples/fifo``. If you haven't
|
||||
already, let's take a look at some of those script files now.
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
.. literalinclude:: /code_examples/fifo/fifo.ys
|
||||
:language: yoscrypt
|
||||
:lineno-match:
|
||||
:start-at: echo on
|
||||
:end-before: design -reset
|
||||
:caption: A section of ``fifo.ys``, generating the images used for :ref:`addr_gen_example`
|
||||
:name: fifo-ys
|
||||
|
||||
cd # a shortcut for 'select -module <name>'
|
||||
ls # list modules or objects in modules
|
||||
dump # print parts of the design in RTLIL format
|
||||
show # generate schematics using graphviz
|
||||
select # modify and view the list of selected objects
|
||||
The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable
|
||||
command echoes on. This is how we generated the code listing for
|
||||
:ref:`hierarchy_output`. Turning command echoes on prints the ``yosys>
|
||||
hierarchy -top addr_gen`` line, making the output look the same as if it were an
|
||||
interactive terminal. :yoscrypt:`hierarchy -top addr_gen` is of course the
|
||||
command we were demonstrating, including the output text and an image of the
|
||||
design schematic after running it.
|
||||
|
||||
Commands for executing scripts or entering interactive mode:
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
|
||||
shell # enter interactive command mode
|
||||
history # show last interactive commands
|
||||
script # execute commands from script file
|
||||
tcl # execute a TCL script file
|
||||
|
||||
Commands for reading and elaborating the design:
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
|
||||
read_rtlil # read modules from RTLIL file
|
||||
read_verilog # read modules from Verilog file
|
||||
hierarchy # check, expand and clean up design hierarchy
|
||||
|
||||
|
||||
Commands for high-level synthesis:
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
|
||||
proc # translate processes to netlists
|
||||
fsm # extract and optimize finite state machines
|
||||
memory # translate memories to basic cells
|
||||
opt # perform simple optimizations
|
||||
|
||||
|
||||
Commands for technology mapping:
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
|
||||
techmap # generic technology mapper
|
||||
abc # use ABC for technology mapping
|
||||
dfflibmap # technology mapping of flip-flops
|
||||
hilomap # technology mapping of constant hi- and/or lo-drivers
|
||||
iopadmap # technology mapping of i/o pads (or buffers)
|
||||
flatten # flatten design
|
||||
|
||||
Commands for writing the results:
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
|
||||
write_blif # write design to BLIF file
|
||||
write_btor # write design to BTOR file
|
||||
write_edif # write design to EDIF netlist file
|
||||
write_rtlil # write design to RTLIL file
|
||||
write_spice # write design to SPICE netlist file
|
||||
write_verilog # write design to Verilog file
|
||||
|
||||
|
||||
Script-Commands for standard synthesis tasks:
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
|
||||
synth # generic synthesis script
|
||||
synth_xilinx # synthesis for Xilinx FPGAs
|
||||
|
||||
|
||||
Commands for model checking:
|
||||
|
||||
.. code-block:: yoscrypt
|
||||
|
||||
sat # solve a SAT problem in the circuit
|
||||
miter # automatically create a miter circuit
|
||||
scc # detect strongly connected components (logic loops)
|
||||
We briefly touched on :cmd:ref:`select` when it came up in
|
||||
:cmd:ref:`synth_ice40`, but let's look at it more now.
|
||||
|
||||
Selections intro
|
||||
~~~~~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. todo:: reorder text for logical consistency
|
||||
The :cmd:ref:`select` command is used to modify and view the list of selected
|
||||
objects:
|
||||
|
||||
Most commands can operate not only on the entire design but also specifically on
|
||||
selected parts of the design. For example the command :cmd:ref:`dump` will print
|
||||
all selected objects in the current design while ``dump foobar`` will only print
|
||||
the module ``foobar`` and ``dump *`` will print the entire design regardless of
|
||||
the current selection.
|
||||
.. literalinclude:: /code_examples/fifo/fifo.out
|
||||
:language: doscon
|
||||
:start-at: yosys> select
|
||||
:end-before: yosys> show
|
||||
|
||||
.. code:: yoscrypt
|
||||
When we call :yoscrypt:`select -module addr_gen` we are changing the currently
|
||||
active selection from the whole design, to just the ``addr_gen`` module. Notice
|
||||
how this changes the ``yosys`` at the start of each command to ``yosys
|
||||
[addr_gen]``? This indicates that any commands we run at this point will *only*
|
||||
operate on the ``addr_gen`` module. When we then call :yoscrypt:`select -list`
|
||||
we get a list of all objects in the ``addr_gen`` module, including the module
|
||||
itself, as well as all of the wires, inputs, outputs, processes, and cells.
|
||||
|
||||
dump */t:$add %x:+[A] */w:* %i
|
||||
Next we perform another selection, :yoscrypt:`select t:*`. The ``t:`` part
|
||||
signifies we are matching on the *cell type*, and the ``*`` means to match
|
||||
anything. For this (very simple) selection, we are trying to find all of the
|
||||
cells, regardless of their type. The active selection is now shown as
|
||||
``[addr_gen]*``, indicating some sub-selection of the ``addr_gen`` module. This
|
||||
gives us the ``$add`` and ``$eq`` cells, which we want to highlight for the
|
||||
:ref:`addr_gen_hier` image.
|
||||
|
||||
We can assign a name to a selection with :yoscrypt:`select -set`. In our case
|
||||
we are using the name ``new_cells``, and telling it to use the current
|
||||
selection, indicated by the ``%`` symbol. Then we clear the selection so that
|
||||
the following commands can operate on the full design. While we split that out
|
||||
for this document, we could have done the same thing in a single line by calling
|
||||
:yoscrypt:`select -set new_cells addr_gen/t:*`. If we know we only have the one
|
||||
module in our design, we can even skip the `addr_gen/` part. Looking further
|
||||
down :ref:`the fifo.ys code <fifo-ys>` we can see this with :yoscrypt:`select
|
||||
-set new_cells t:$mux t:*dff`. We can also see in that command that selections
|
||||
don't have to be limited to a single statement.
|
||||
|
||||
Many commands also support an optional ``[selection]`` argument which can be
|
||||
used to override the currently selected objects. We could, for example, call
|
||||
:yoscrypt:`clean addr_gen` to have :cmd:ref:`clean` operate on *just* the
|
||||
``addr_gen`` module.
|
||||
|
||||
The selection mechanism is very powerful. For example the command above will
|
||||
print all wires that are connected to the ``\A`` port of a ``$add`` cell.
|
||||
Detailed documentation of the select framework can be found under
|
||||
:doc:`/using_yosys/more_scripting/selections` or in the command reference at
|
||||
:doc:`/cmd/select`.
|
||||
|
|
@ -118,6 +93,8 @@ Detailed documentation of the select framework can be found under
|
|||
The show command
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. TODO:: scripting_intro/show section
|
||||
|
||||
The :cmd:ref:`show` command requires a working installation of `GraphViz`_ and
|
||||
`xdot`_ for generating the actual circuit diagrams. Below is an example of how
|
||||
this command can be used, showing the changes in the generated circuit at
|
||||
|
|
|
|||
|
|
@ -26,6 +26,8 @@ to run this pass after each major step in the synthesis script. As listed in
|
|||
Constant folding and simple expression rewriting - :cmd:ref:`opt_expr`
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index`
|
||||
|
||||
This pass performs constant folding on the internal combinational cell types
|
||||
described in :doc:`/yosys_internals/formats/cell_library`. This means a cell
|
||||
with all constant inputs is replaced with the constant value this cell drives.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ Flows, command types, and order
|
|||
Command order
|
||||
-------------
|
||||
|
||||
.. TODO:: check text is coherent
|
||||
.. todo:: More surrounding text (esp as it relates to command order)
|
||||
|
||||
Intro to coarse-grain synthesis
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -42,6 +42,8 @@ The extract pass
|
|||
.. todo:: add/expand supporting text, also mention custom pattern matching and
|
||||
pmgen
|
||||
|
||||
Example code can be found in ``docs/source/code_examples/macc/``.
|
||||
|
||||
.. literalinclude:: /code_examples/macc/macc_simple_test.ys
|
||||
:language: yoscrypt
|
||||
:lines: 1-2
|
||||
|
|
@ -62,15 +64,15 @@ The extract pass
|
|||
|
||||
.. literalinclude:: /code_examples/macc/macc_simple_test.v
|
||||
:language: verilog
|
||||
:caption: ``docs/source/code_examples/macc/macc_simple_test.v``
|
||||
:caption: ``macc_simple_test.v``
|
||||
|
||||
.. literalinclude:: /code_examples/macc/macc_simple_xmap.v
|
||||
:language: verilog
|
||||
:caption: ``docs/source/code_examples/macc/macc_simple_xmap.v``
|
||||
:caption: ``macc_simple_xmap.v``
|
||||
|
||||
.. literalinclude:: /code_examples/macc/macc_simple_test_01.v
|
||||
:language: verilog
|
||||
:caption: ``docs/source/code_examples/macc/macc_simple_test_01.v``
|
||||
:caption: ``macc_simple_test_01.v``
|
||||
|
||||
.. figure:: /_images/code_examples/macc/macc_simple_test_01a.*
|
||||
:class: width-helper
|
||||
|
|
@ -80,7 +82,7 @@ The extract pass
|
|||
|
||||
.. literalinclude:: /code_examples/macc/macc_simple_test_02.v
|
||||
:language: verilog
|
||||
:caption: ``docs/source/code_examples/macc/macc_simple_test_02.v``
|
||||
:caption: ``macc_simple_test_02.v``
|
||||
|
||||
.. figure:: /_images/code_examples/macc/macc_simple_test_02a.*
|
||||
:class: width-helper
|
||||
|
|
@ -95,14 +97,15 @@ Often a coarse-grain element has a constant bit-width, but can be used to
|
|||
implement operations with a smaller bit-width. For example, a 18x25-bit multiplier
|
||||
can also be used to implement 16x20-bit multiplication.
|
||||
|
||||
A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method:
|
||||
A way of mapping such elements in coarse grain synthesis is the
|
||||
wrap-extract-unwrap method:
|
||||
|
||||
wrap
|
||||
Identify candidate-cells in the circuit and wrap them in a cell with a
|
||||
constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same
|
||||
parameters as the original cell, so the information about the original width
|
||||
of the ports is preserved. Then use the ``connwrappers`` command to connect up
|
||||
the bit-extended in- and outputs of the wrapper cells.
|
||||
of the ports is preserved. Then use the :cmd:ref:`connwrappers` command to
|
||||
connect up the bit-extended in- and outputs of the wrapper cells.
|
||||
|
||||
extract
|
||||
Now all operations are encoded using the same bit-width as the coarse grain
|
||||
|
|
@ -117,7 +120,8 @@ Example: DSP48_MACC
|
|||
|
||||
This section details an example that shows how to map MACC operations of
|
||||
arbitrary size to MACC cells with a 18x25-bit multiplier and a 48-bit adder
|
||||
(such as the Xilinx DSP48 cells).
|
||||
(such as the Xilinx DSP48 cells). Source code can be found in
|
||||
``docs/source/code_examples/macc/``.
|
||||
|
||||
Preconditioning: ``macc_xilinx_swap_map.v``
|
||||
|
||||
|
|
@ -127,27 +131,27 @@ Make sure ``A`` is the smaller port on all multipliers
|
|||
|
||||
.. literalinclude:: /code_examples/macc/macc_xilinx_swap_map.v
|
||||
:language: verilog
|
||||
:caption: ``docs/source/code_examples/macc/macc_xilinx_swap_map.v``
|
||||
:caption: ``macc_xilinx_swap_map.v``
|
||||
|
||||
Wrapping multipliers: ``macc_xilinx_wrap_map.v``
|
||||
|
||||
.. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v
|
||||
:language: verilog
|
||||
:lines: 1-46
|
||||
:caption: ``docs/source/code_examples/macc/macc_xilinx_wrap_map.v``
|
||||
:caption: ``macc_xilinx_wrap_map.v``
|
||||
|
||||
Wrapping adders: ``macc_xilinx_wrap_map.v``
|
||||
|
||||
.. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v
|
||||
:language: verilog
|
||||
:lines: 48-89
|
||||
:caption: ``docs/source/code_examples/macc/macc_xilinx_wrap_map.v``
|
||||
:caption: ``macc_xilinx_wrap_map.v``
|
||||
|
||||
Extract: ``macc_xilinx_xmap.v``
|
||||
|
||||
.. literalinclude:: /code_examples/macc/macc_xilinx_xmap.v
|
||||
:language: verilog
|
||||
:caption: ``docs/source/code_examples/macc/macc_xilinx_xmap.v``
|
||||
:caption: ``macc_xilinx_xmap.v``
|
||||
|
||||
... simply use the same wrapping commands on this module as on the design to
|
||||
create a template for the :cmd:ref:`extract` command.
|
||||
|
|
@ -157,19 +161,19 @@ Unwrapping multipliers: ``macc_xilinx_unwrap_map.v``
|
|||
.. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v
|
||||
:language: verilog
|
||||
:lines: 1-30
|
||||
:caption: ``docs/source/code_examples/macc/macc_xilinx_unwrap_map.v``
|
||||
:caption: ``$__mul_wrapper`` module in ``macc_xilinx_unwrap_map.v``
|
||||
|
||||
Unwrapping adders: ``macc_xilinx_unwrap_map.v``
|
||||
|
||||
.. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v
|
||||
:language: verilog
|
||||
:lines: 32-61
|
||||
:caption: ``docs/source/code_examples/macc/macc_xilinx_unwrap_map.v``
|
||||
:caption: ``$__add_wrapper`` module in ``macc_xilinx_unwrap_map.v``
|
||||
|
||||
.. literalinclude:: /code_examples/macc/macc_xilinx_test.v
|
||||
:language: verilog
|
||||
:lines: 1-6
|
||||
:caption: ``test1`` of ``docs/source/code_examples/macc/macc_xilinx_test.v``
|
||||
:caption: ``test1`` of ``macc_xilinx_test.v``
|
||||
|
||||
.. figure:: /_images/code_examples/macc/macc_xilinx_test1a.*
|
||||
:class: width-helper
|
||||
|
|
@ -180,7 +184,7 @@ Unwrapping adders: ``macc_xilinx_unwrap_map.v``
|
|||
.. literalinclude:: /code_examples/macc/macc_xilinx_test.v
|
||||
:language: verilog
|
||||
:lines: 8-13
|
||||
:caption: ``test2`` of ``docs/source/code_examples/macc/macc_xilinx_test.v``
|
||||
:caption: ``test2`` of ``macc_xilinx_test.v``
|
||||
|
||||
.. figure:: /_images/code_examples/macc/macc_xilinx_test2a.*
|
||||
:class: width-helper
|
||||
|
|
|
|||
|
|
@ -16,12 +16,11 @@ language.
|
|||
|
||||
The AST Frontend then compiles the AST to Yosys's main internal data format, the
|
||||
RTL Intermediate Language (RTLIL). A more detailed description of this format is
|
||||
given in the next section.
|
||||
|
||||
.. TODO:: what next section
|
||||
given in :doc:`/yosys_internals/formats/rtlil_rep`.
|
||||
|
||||
There is also a text representation of the RTLIL data structure that can be
|
||||
parsed using the RTLIL Frontend.
|
||||
parsed using the RTLIL Frontend which is described in
|
||||
:doc:`/yosys_internals/formats/rtlil_text`.
|
||||
|
||||
The design data may then be transformed using a series of passes that all
|
||||
operate on the RTLIL representation of the design.
|
||||
|
|
|
|||
Loading…
Reference in New Issue