yosys/docs/source/getting_started/scripting_intro.rst

Scripting in Yosys
------------------

.. TODO: copypaste

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. See :ref:`sec:typusecase` for an
example synthesis script.

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

Example commands
~~~~~~~~~~~~~~~~

Commands for design navigation and investigation:

.. code-block:: yoscrypt

    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

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)

Selections intro
~~~~~~~~~~~~~~~~

Most commands can operate not only on the entire design but also specifically on
selected parts of the design. For example the command 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.

.. code:: yoscrypt

	dump */t:$add %x:+[A] \*/w:\* %i

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