Docs: changes/todos from JF

docs/source/getting_started/example_synth.rst

@@ -161,8 +161,9 @@ generated from the initial assignment of 0 to the ``addr`` wire.  However, this
 initial assignment is not synthesizable, so this will need to be cleaned up
 before we can generate the physical hardware.  We can do this now by calling
 :cmd:ref:`clean`.  We're also going to call :cmd:ref:`opt_expr` now, which would
-normally be called at the end of :cmd:ref:`proc`.  We can call both commands
+normally be called at the end of :cmd:ref:`proc`.  We can call both commands at
-at the same time by separating them with a colon: :yoscrypt:`opt_expr; clean`.
+the same time by separating them with a colon and space: :yoscrypt:`opt_expr;
+clean`.
 
 .. figure:: /_images/code_examples/fifo/addr_gen_clean.*
    :class: width-helper
@@ -183,10 +184,11 @@ on opt_expr <adv_opt_expr>`.
 
    :doc:`/cmd/clean` can also be called with two semicolons after any command,
    for example we could have called :yoscrypt:`opt_expr;;` instead of
-   :yoscrypt:`opt_expr; clean`.  It is generally beneficial to run
+   :yoscrypt:`opt_expr; clean`.  You may notice some scripts will end each line
-   :cmd:ref:`clean` after each command as a quick way of removing disconnected
+   with ``;;``.  It is beneficial to run :cmd:ref:`clean` before inspecting
-   parts of the circuit which have been left over.  You may notice some scripts
+   intermediate products to remove disconnected parts of the circuit which have
-   will end each line with ``;;``.
+   been left over, and in some cases can reduce the processing required in
+   subsequent commands.
 
 .. todo:: consider a brief glossary for terms like adff
 
@@ -199,9 +201,9 @@ The full example
 ^^^^^^^^^^^^^^^^
 
 Let's now go back and check on our full design by using :yoscrypt:`hierarchy
--check -top fifo`.  By passing the ``-check`` option there we are also
+-check -top fifo`.  By passing the ``-check`` option there we are also telling
-telling the :cmd:ref:`hierarchy` command that if the design includes any
+the :cmd:ref:`hierarchy` command that if the design includes any non-blackbox
-non-blackbox modules without an implementation it should return an error.
+modules without an implementation it should return an error.
 
 Note that if we tried to run this command now then we would get an error.  This
 is because we already removed all of the modules other than ``addr_gen``.  We
@@ -237,8 +239,9 @@ design.  If we know that our design won't run into this issue, we can skip the
    included in the source as :file:`fifo.ys`. There are extra commands being run
    which you don't see, but feel free to try them yourself, or play around with
    different commands.  You can always start over with a clean slate by calling
-   ``exit`` or hitting ``ctrl+c`` (i.e. SIGINT) and re-launching the Yosys
+   ``exit`` or hitting :kbd:`ctrl+d` (i.e. EOF) and re-launching the Yosys
-   interactive terminal.
+   interactive terminal.  :kbd:`ctrl+c` (i.e. SIGINT) will also end the terminal
+   session but will return an error code rather than exiting gracefully.
 
 We can also run :cmd:ref:`proc` now to finish off the full :ref:`synth_begin`.
 Because the design schematic is quite large, we will be showing just the data
@@ -308,9 +311,14 @@ earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`.  We can
 also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr`
 and merged with the ``raddr`` wire feeding into the ``$memrd`` cell.  This wire
 merging happened during the call to :cmd:ref:`clean` which we can see in the
-:ref:`flat_clean`.  Note that in an interactive terminal the outputs of
+:ref:`flat_clean`.
-:cmd:ref:`flatten` and :cmd:ref:`clean` will be combined into a single
+
-:yoterm:`yosys> flatten;;` output.
+.. note:: 
+
+   :cmd:ref:`flatten` and :cmd:ref:`clean` would normally be combined into a
+   single :yoterm:`yosys> flatten;;` output, but they appear separately here as
+   a side effect of using :cmd:ref:`echo` for generating the terminal style
+   output.
 
 Depending on the target architecture, this stage of synthesis might also see
 commands such as :cmd:ref:`tribuf` with the ``-logic`` option and
@@ -490,6 +498,8 @@ expression rewriting, the ``-fine`` option just enables more fine-grain
 optimizations.  Then we perform width reduction a final time and clear the
 selection.
 
+.. todo:: ``ice40_dsp`` is pmgen
+
 Finally we have :cmd:ref:`ice40_dsp`: similar to the :cmd:ref:`memory_dff`
 command we saw in the previous section, this merges any surrounding registers
 into the ``SB_MAC16`` cell.  This includes not just the input/output registers,
@@ -513,9 +523,10 @@ That brings us to the fourth and final part for the iCE40 synthesis flow:
    :name: synth_coarse4
 
 Where before each type of arithmetic operation had its own cell, e.g. ``$add``,
-we now want to extract these into ``$alu`` and ``$macc`` cells which can be
+we now want to extract these into ``$alu`` and ``$macc`` cells which can help
-mapped to hard blocks.  We do this by running :cmd:ref:`alumacc`, which we can
+identify opportunities for reusing logic.  We do this by running
-see produce the following changes in our example design:
+:cmd:ref:`alumacc`, which we can see produce the following changes in our
+example design:
 
 .. literalinclude:: /code_examples/fifo/fifo.out
    :language: doscon
@@ -529,6 +540,10 @@ see produce the following changes in our example design:
 
    ``rdata`` output after :cmd:ref:`alumacc`
 
+Once these cells have been inserted, the call to :cmd:ref:`opt` can combine
+cells which are now identical but may have been missed due to e.g. the
+difference between ``$add`` and ``$sub``.
+
 The other new command in this part is :doc:`/cmd/memory`.  :cmd:ref:`memory` is
 another macro command which we examine in more detail in
 :doc:`/using_yosys/synthesis/memory`.  For this document, let us focus just on
@@ -551,7 +566,9 @@ one for writing (``WR_*``), as well as both ``WR_DATA`` input and ``RD_DATA``
 output.
 
 .. seealso:: Advanced usage docs for
-   :doc:`/using_yosys/synthesis/memory`
+
+   - :doc:`/using_yosys/synthesis/opt`
+   - :doc:`/using_yosys/synthesis/memory`
 
 Final note
 ^^^^^^^^^^

docs/source/getting_started/installation.rst

@@ -86,14 +86,10 @@ Build prerequisites
 ^^^^^^^^^^^^^^^^^^^
 
 A C++ compiler with C++11 support is required as well as some standard tools
-such as GNU Flex, GNU Bison, Make, libffi, and Python3.6 or later.  Some
+such as GNU Flex, GNU Bison, Make and Python.  Some additional tools: readline,
-additional tools: readline, Tcl and zlib; are optional but enabled by default
+libffi, Tcl and zlib; are optional but enabled by default (see
-(see ``ENABLE_*`` settings in Makefile). Xdot (graphviz) is optional unless
+:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the
-using the :cmd:ref:`show` command to display schematics.
+:cmd:ref:`show` command to display schematics.
-
-.. 
-   unclear if libffi is required now or still optional
-   readme says optional, but I can't find a corresponding ENABLE_*
 
 Installing all prerequisites for Ubuntu 20.04:
 

docs/source/introduction.rst

@@ -69,6 +69,8 @@ Things you can't do
 
   - Check out `nextpnr`_ for that
 
+.. todo:: nextpnr for FPGAs, consider mentioning openlane, vpr, coriolis
+
 .. _nextpnr: https://github.com/YosysHQ/nextpnr
 
 The Yosys family
@@ -191,11 +193,6 @@ Benefits of open source HDL synthesis
   workings. They often are ``black boxes``. Yosys is very open about its
   internals and it is easy to observe the different steps of synthesis.
 
-.. note:: Yosys is licensed under the ISC license:
-   Permission to use, copy, modify, and/or distribute this software for any
-   purpose with or without fee is hereby granted, provided that the above
-   copyright notice and this permission notice appear in all copies.
-
 History of Yosys
 ~~~~~~~~~~~~~~~~
 

docs/source/using_yosys/more_scripting/interactive_investigation.rst

@@ -220,7 +220,8 @@ Per default the :cmd:ref:`show` command outputs a temporary dot file and
 launches ``xdot`` to display it. The options ``-format``, ``-viewer`` and
 ``-prefix`` can be used to change format, viewer and filename prefix. Note that
 the ``pdf`` and ``ps`` format are the only formats that support plotting
-multiple modules in one run.
+multiple modules in one run.  The ``dot`` format can be used to output multiple
+modules, however ``xdot`` will raise an error when trying to read them.
 
 In densely connected circuits it is sometimes hard to keep track of the
 individual signal wires. For these cases it can be useful to call