diff --git a/docs/source/code_examples/fifo/fifo.out b/docs/source/code_examples/fifo/fifo.out
index 30236a7ab..d18fce14b 100644
--- a/docs/source/code_examples/fifo/fifo.out
+++ b/docs/source/code_examples/fifo/fifo.out
@@ -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
diff --git a/docs/source/code_examples/fifo/fifo.ys b/docs/source/code_examples/fifo/fifo.ys
index b89361e75..0584285ea 100644
--- a/docs/source/code_examples/fifo/fifo.ys
+++ b/docs/source/code_examples/fifo/fifo.ys
@@ -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
# ========================================================
diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst
index e1cc257db..811c39a28 100644
--- a/docs/source/getting_started/example_synth.rst
+++ b/docs/source/getting_started/example_synth.rst
@@ -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:
diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst
index a3c4a265b..51628c67f 100644
--- a/docs/source/getting_started/index.rst
+++ b/docs/source/getting_started/index.rst
@@ -7,5 +7,5 @@ Getting started with Yosys
:maxdepth: 3
installation
- scripting_intro
example_synth
+ scripting_intro
diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst
index 4ce038e91..d4d809fbd 100644
--- a/docs/source/getting_started/scripting_intro.rst
+++ b/docs/source/getting_started/scripting_intro.rst
@@ -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
diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst
index fb75c9fa1..0ba108131 100644
--- a/docs/source/using_yosys/synthesis/opt.rst
+++ b/docs/source/using_yosys/synthesis/opt.rst
@@ -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.
diff --git a/docs/source/using_yosys/yosys_flows.rst b/docs/source/using_yosys/yosys_flows.rst
index 040ef5a4c..5bca90ade 100644
--- a/docs/source/using_yosys/yosys_flows.rst
+++ b/docs/source/using_yosys/yosys_flows.rst
@@ -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
diff --git a/docs/source/yosys_internals/flow/overview.rst b/docs/source/yosys_internals/flow/overview.rst
index ae07e6f1f..f7589df03 100644
--- a/docs/source/yosys_internals/flow/overview.rst
+++ b/docs/source/yosys_internals/flow/overview.rst
@@ -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.