mirror of
https://github.com/YosysHQ/yosys
synced 2025-04-25 10:05:33 +00:00
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
8 changed files with 139 additions and 120 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue