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.

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
 

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
 
 # ========================================================

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:
 

docs/source/getting_started/index.rst

@@ -7,5 +7,5 @@ Getting started with Yosys
    :maxdepth: 3
 
    installation
-   scripting_intro
    example_synth
+   scripting_intro

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
+Yosys script files typically use the ``.ys`` extension and contain a set of
-arguments and an interactive command prompt. Yosys commands consist of a command
+commands for Yosys to run sequentially.  These commands are the same ones we
-name and an optional whitespace separated list of arguments. Commands are
+were using on the previous page like :cmd:ref:`read_verilog` and
-terminated using the newline character or a semicolon (;). Empty lines and lines
+:cmd:ref:`hierarchy`.  As with the interactive shell, each command consists of
-starting with the hash sign (#) are ignored. Also see :doc:`example_synth`.
+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,
+The synthesis starter script
-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
+.. 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>'
+The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable
-    ls                   # list modules or objects in modules
+command echoes on.  This is how we generated the code listing for
-    dump                 # print parts of the design in RTLIL format
+:ref:`hierarchy_output`.  Turning command echoes on prints the ``yosys>
-    show                 # generate schematics using graphviz
+hierarchy -top addr_gen`` line, making the output look the same as if it were an
-    select               # modify and view the list of selected objects
+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:
+We briefly touched on :cmd:ref:`select` when it came up in
-
+:cmd:ref:`synth_ice40`, but let's look at it more now.
-.. 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
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
 
-.. 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
+.. literalinclude:: /code_examples/fifo/fifo.out
-selected parts of the design. For example the command :cmd:ref:`dump` will print
+   :language: doscon
-all selected objects in the current design while ``dump foobar`` will only print
+   :start-at: yosys> select
-the module ``foobar`` and ``dump *`` will print the entire design regardless of
+   :end-before: yosys> show
-the current selection.
 
-.. 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

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.

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
+  of the ports is preserved. Then use the :cmd:ref:`connwrappers` command to
-  the bit-extended in- and outputs of the wrapper cells.
+  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

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.
+given in :doc:`/yosys_internals/formats/rtlil_rep`.
-
-.. TODO:: what next section
 
 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.