mirror of https://github.com/YosysHQ/yosys.git
143 lines
6.1 KiB
ReStructuredText
143 lines
6.1 KiB
ReStructuredText
Scripting in Yosys
|
|
------------------
|
|
|
|
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 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 synthesis starter script
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. role:: yoscrypt(code)
|
|
:language: yoscrypt
|
|
|
|
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.
|
|
|
|
.. 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
|
|
|
|
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.
|
|
|
|
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
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
The :cmd:ref:`select` command is used to modify and view the list of selected
|
|
objects:
|
|
|
|
.. literalinclude:: /code_examples/fifo/fifo.out
|
|
:language: doscon
|
|
:start-at: yosys> select
|
|
:end-before: yosys> show
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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`.
|
|
|
|
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
|
|
different stages of the yosys tool flow.
|
|
|
|
.. _GraphViz: http://www.graphviz.org/
|
|
|
|
.. _xdot: https://github.com/jrfonseca/xdot.py
|
|
|
|
.. literalinclude:: /code_examples/show/example.ys
|
|
:language: yoscrypt
|
|
:caption: docs/source/code_examples/show/example.ys
|
|
|
|
.. literalinclude:: /code_examples/show/example.v
|
|
:language: Verilog
|
|
:caption: docs/source/code_examples/show/example.v
|
|
|
|
.. role:: yoscrypt(code)
|
|
:language: yoscrypt
|
|
|
|
.. figure:: /_images/code_examples/show/example_first.*
|
|
:class: width-helper
|
|
|
|
``example_first`` - shown after :yoscrypt:`read_verilog example.v`
|
|
|
|
.. figure:: /_images/code_examples/show/example_second.*
|
|
:class: width-helper
|
|
|
|
``example_second`` - shown after :yoscrypt:`proc`
|
|
|
|
.. figure:: /_images/code_examples/show/example_third.*
|
|
:class: width-helper
|
|
|
|
``example_third`` - shown after :yoscrypt:`opt`
|
|
|
|
A circuit diagram is generated for the design in its current state. Various
|
|
options can be used to change the appearance of the circuit diagram, set the
|
|
name and format for the output file, and so forth. When called without any
|
|
special options, it saves the circuit diagram in a temporary file and launches
|
|
``xdot`` to display the diagram. Subsequent calls to show re-use the ``xdot``
|
|
instance (if still running).
|
|
|
|
For more information on the :cmd:ref:`show` command, including a guide on what
|
|
the different symbols represent, see :ref:`interactive_show` and the
|
|
:doc:`/using_yosys/more_scripting/interactive_investigation` page.
|