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 ` 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.