Docs: Update internal cells to autoref

docs/source/using_yosys/more_scripting/interactive_investigation.rst

@@ -81,7 +81,7 @@ internal representation of the decision-trees and synchronization events
 modelled in a Verilog ``always``-block. The label reads ``PROC`` followed by a
 unique identifier in the first line and contains the source code location of the
 original ``always``-block in the second line. Note how the multiplexer from the
-``?:``-expression is represented as a ``$mux`` cell but the multiplexer from the
+``?:``-expression is represented as a `$mux` cell but the multiplexer from the
 ``if``-statement is yet still hidden within the process.
 
 The :cmd:ref:`proc` command transforms the process from the first diagram into a
@@ -117,7 +117,7 @@ leads us to the third diagram:
    
 Here we see that the :cmd:ref:`opt` command not only has removed the artifacts
 left behind by :cmd:ref:`proc`, but also determined correctly that it can remove
-the first ``$mux`` cell without changing the behavior of the circuit.
+the first `$mux` cell without changing the behavior of the circuit.
 
 Break-out boxes for signal vectors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/source/using_yosys/more_scripting/selections.rst

@@ -105,7 +105,7 @@ The :cmd:ref:`select` command is actually much more powerful than it might seem
 at first glance. When it is called with multiple arguments, each argument is
 evaluated and pushed separately on a stack. After all arguments have been
 processed it simply creates the union of all elements on the stack. So
-:yoscrypt:`select t:$add a:foo` will select all ``$add`` cells and all objects
+:yoscrypt:`select t:$add a:foo` will select all `$add` cells and all objects
 with the ``foo`` attribute set:   
 
 .. literalinclude:: /code_examples/selections/foobaraddsub.v
@@ -126,7 +126,7 @@ ineffective way of selecting the interesting part of the design. Special
 arguments can be used to combine the elements on the stack. For example the
 ``%i`` arguments pops the last two elements from the stack, intersects them, and
 pushes the result back on the stack. So :yoscrypt:`select t:$add a:foo %i` will
-select all ``$add`` cells that have the ``foo`` attribute set:
+select all `$add` cells that have the ``foo`` attribute set:
 
 .. code-block::
    :caption: Output for command ``select t:$add a:foo %i -list`` on :numref:`foobaraddsub`
@@ -220,7 +220,7 @@ The following sequence of diagrams demonstrates this step-wise expansion:
    Output of :yoscrypt:`show prod %ci %ci %ci` on :numref:`sumprod`
 
 Notice the subtle difference between :yoscrypt:`show prod %ci` and
-:yoscrypt:`show prod %ci %ci`.  Both images show the ``$mul`` cell driven by
+:yoscrypt:`show prod %ci %ci`.  Both images show the `$mul` cell driven by
 some inputs ``$3_Y`` and ``c``.  However it is not until the second image,
 having called ``%ci`` the second time, that :cmd:ref:`show` is able to
 distinguish between ``$3_Y`` being a wire and ``c`` being an input.  We can see
@@ -296,7 +296,7 @@ cones`_ from above, we can use :yoscrypt:`show y %ci2`:
    
    Output of :yoscrypt:`show y %ci2`
 
-From this we would learn that ``y`` is driven by a ``$dff cell``, that ``y`` is
+From this we would learn that ``y`` is driven by a `$dff` cell, that ``y`` is
 connected to the output port ``Q``, that the ``clk`` signal goes into the
 ``CLK`` input port of the cell, and that the data comes from an auto-generated
 wire into the input ``D`` of the flip-flop cell (indicated by the ``$`` at the
@@ -313,7 +313,7 @@ inputs. To add a pattern we add a colon followed by the pattern to the ``%ci``
 action. The pattern itself starts with ``-`` or ``+``, indicating if it is an
 include or exclude pattern, followed by an optional comma separated list of cell
 types, followed by an optional comma separated list of port names in square
-brackets.  In this case, we want to exclude the ``S`` port of the ``$mux`` cell
+brackets.  In this case, we want to exclude the ``S`` port of the `$mux` cell
 type with :yoscrypt:`show y %ci5:-$mux[S]`:
 
 .. figure:: /_images/code_examples/selections/memdemo_03.*
@@ -334,7 +334,7 @@ multiplexer select inputs and flip-flop cells:
    Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff``
 
 Or we could use :yoscrypt:`show y %ci*:-[CLK,S]:+$dff:+$mux` instead, following
-the input cone all the way but only following ``$dff`` and ``$mux`` cells, and
+the input cone all the way but only following `$dff` and `$mux` cells, and
 ignoring any ports named ``CLK`` or ``S``:
 
 .. TODO:: pending discussion on whether rule ordering is a bug or a feature

docs/source/using_yosys/synthesis/cell_libs.rst

@@ -98,8 +98,8 @@ our internal cell library will be mapped to:
    :name: mycells-lib
    :caption: :file:`mycells.lib`
 
-Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``,
-``$_OR_``, ``$_XOR_``, and ``$_MUX_`` with an assortment of dff memory types.
+Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`,
+`$_OR_`, `$_XOR_`, and `$_MUX_` with an assortment of dff memory types.
 :ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``,
 ``NOR``, and ``DFF``.  Mapping between these is performed with the commands
 :cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows:

docs/source/using_yosys/synthesis/fsm.rst

@@ -24,12 +24,12 @@ following description:
 
 -  Does not already have the ``\fsm_encoding`` attribute.
 -  Is not an output of the containing module.
--  Is driven by single ``$dff`` or ``$adff`` cell.
--  The ``\D``-Input of this ``$dff`` or ``$adff`` cell is driven by a
+-  Is driven by single `$dff` or `$adff` cell.
+-  The ``\D``-Input of this `$dff` or `$adff` cell is driven by a
    multiplexer tree that only has constants or the old state value on its
    leaves.
 -  The state value is only used in the said multiplexer tree or by simple
-   relational cells that compare the state value to a constant (usually ``$eq``
+   relational cells that compare the state value to a constant (usually `$eq`
    cells).
 
 This heuristic has proven to work very well. It is possible to overwrite it by
@@ -64,9 +64,11 @@ information is determined:
 The state registers (and asynchronous reset state, if applicable) is simply
 determined by identifying the driver for the state signal.
 
-From there the ``$mux-tree`` driving the state register inputs is recursively
+.. todo:: Figure out what `$mux-tree` should actually be.
+
+From there the `$mux-tree` driving the state register inputs is recursively
 traversed. All select inputs are control signals and the leaves of the
-``$mux-tree`` are the states. The algorithm fails if a non-constant leaf that is
+`$mux-tree` are the states. The algorithm fails if a non-constant leaf that is
 not the state signal itself is found.
 
 The list of control outputs is initialized with the bits from the state signal.
@@ -99,18 +101,18 @@ create a transition table. For each state:
 
 6. If step 4 was successful: Emit transition
 
-Finally a ``$fsm`` cell is created with the generated transition table and added
+Finally a `$fsm` cell is created with the generated transition table and added
 to the module. This new cell is connected to the control signals and the old
 drivers for the control outputs are disconnected.
 
 FSM optimization
 ~~~~~~~~~~~~~~~~
 
-The :cmd:ref:`fsm_opt` pass performs basic optimizations on ``$fsm`` cells (not
+The :cmd:ref:`fsm_opt` pass performs basic optimizations on `$fsm` cells (not
 including state recoding). The following optimizations are performed (in this
 order):
 
--  Unused control outputs are removed from the ``$fsm`` cell. The attribute
+-  Unused control outputs are removed from the `$fsm` cell. The attribute
    ``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is
    used to determine which control outputs are unused.
 

docs/source/using_yosys/synthesis/memory.rst

@@ -75,7 +75,7 @@ For example:
     techmap -map my_memory_map.v
     memory_map
 
-:cmd:ref:`memory_libmap` attempts to convert memory cells (``$mem_v2`` etc) into
+:cmd:ref:`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into
 hardware supported memory using a provided library (:file:`my_memory_map.txt` in the
 example above).  Where necessary, emulation logic is added to ensure functional
 equivalence before and after this conversion. :yoscrypt:`techmap -map
@@ -171,10 +171,10 @@ In general, you can expect the automatic selection process to work roughly like
 
 This process can be overridden by attaching a ram_style attribute to the memory:
 
-- `(* ram_style = "logic" *)` selects FF RAM
-- `(* ram_style = "distributed" *)` selects LUT RAM
-- `(* ram_style = "block" *)` selects block RAM
-- `(* ram_style = "huge" *)` selects huge RAM
+- ``(* ram_style = "logic" *)`` selects FF RAM
+- ``(* ram_style = "distributed" *)`` selects LUT RAM
+- ``(* ram_style = "block" *)`` selects block RAM
+- ``(* ram_style = "huge" *)`` selects huge RAM
 
 It is an error if this override cannot be realized for the given target.
 

docs/source/using_yosys/synthesis/opt.rst

@@ -31,7 +31,7 @@ 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.
 In some cases this pass can also optimize cells with some constant inputs.
 
-.. table:: Const folding rules for ``$_AND_`` cells as used in :cmd:ref:`opt_expr`.
+.. table:: Const folding rules for `$_AND_` cells as used in :cmd:ref:`opt_expr`.
    :name: tab:opt_expr_and
    :align: center
 
@@ -54,7 +54,7 @@ In some cases this pass can also optimize cells with some constant inputs.
    ========= ========= ===========
 
 :numref:`Table %s <tab:opt_expr_and>` shows the replacement rules used for
-optimizing an ``$_AND_`` gate. The first three rules implement the obvious const
+optimizing an `$_AND_` gate. The first three rules implement the obvious const
 folding rules. Note that 'any' might include dynamic values calculated by other
 parts of the circuit. The following three lines propagate undef (X) states.
 These are the only three cases in which it is allowed to propagate an undef
@@ -66,18 +66,18 @@ substitutions are possible they are performed first, in the hope that the 'any'
 will change to an undef value or a 1 and therefore the output can be set to
 undef.
 
-The last two lines simply replace an ``$_AND_`` gate with one constant-1 input
+The last two lines simply replace an `$_AND_` gate with one constant-1 input
 with a buffer.
 
 Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit
-wide ``$eq`` and ``$ne`` cells with buffers or not-gates if one input is
+wide `$eq` and `$ne` cells with buffers or not-gates if one input is
 constant.  Equality checks may also be reduced in size if there are redundant
 bits in the arguments (i.e. bits which are constant on both inputs).  This can,
 for example, result in a 32-bit wide constant like ``255`` being reduced to the
 8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in
 :ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`.
 
-The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing ``$mux``
+The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing `$mux`
 cells, as these cells are often used to model decision-trees and breaking these
 trees can interfere with other optimizations.
 
@@ -100,7 +100,7 @@ identifies cells with identical inputs and replaces them with a single instance
 of the cell.
 
 The option ``-nomux`` can be used to disable resource sharing for multiplexer
-cells (``$mux`` and ``$pmux``.) This can be useful as it prevents multiplexer
+cells (`$mux` and `$pmux`.) This can be useful as it prevents multiplexer
 trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
 possible optimizations.
 
@@ -141,16 +141,16 @@ Simplifying large MUXes and AND/OR gates - :cmd:ref:`opt_reduce`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is a simple optimization pass that identifies and consolidates identical
-input bits to ``$reduce_and`` and ``$reduce_or`` cells. It also sorts the input
-bits to ease identification of shareable ``$reduce_and`` and ``$reduce_or``
+input bits to `$reduce_and` and `$reduce_or` cells. It also sorts the input
+bits to ease identification of shareable `$reduce_and` and `$reduce_or`
 cells in other passes.
 
 This pass also identifies and consolidates identical inputs to multiplexer
-cells. In this case the new shared select bit is driven using a ``$reduce_or``
+cells. In this case the new shared select bit is driven using a `$reduce_or`
 cell that combines the original select bits.
 
-Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of
-``$reduce_or`` cells to single large ``$reduce_and`` or ``$reduce_or`` cells.
+Lastly this pass consolidates trees of `$reduce_and` cells and trees of
+`$reduce_or` cells to single large `$reduce_and` or `$reduce_or` cells.
 
 These three simple optimizations are performed in a loop until a stable result
 is produced.
@@ -160,7 +160,7 @@ Merging mutually exclusive cells with shared inputs - :cmd:ref:`opt_share`
 
 This pass identifies mutually exclusive cells of the same type that:
    a. share an input signal, and
-   b. drive the same ``$mux``, ``$_MUX_``, or ``$pmux`` multiplexing cell,
+   b. drive the same `$mux`, `$_MUX_`, or `$pmux` multiplexing cell,
 
 allowing the cell to be merged and the multiplexer to be moved from
 multiplexing its output to multiplexing the non-shared input signals.
@@ -176,14 +176,14 @@ multiplexing its output to multiplexing the non-shared input signals.
 
    Before and after :cmd:ref:`opt_share`
 
-When running :cmd:ref:`opt` in full, the original ``$mux`` (labeled ``$3``) is
+When running :cmd:ref:`opt` in full, the original `$mux` (labeled ``$3``) is
 optimized away by :cmd:ref:`opt_expr`.
 
 Performing DFF optimizations - :cmd:ref:`opt_dff`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and
-``$adff`` cells) with a constant data input and replaces them with a constant
+This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and
+`$adff` cells) with a constant data input and replaces them with a constant
 driver.  It can also merge clock enables and synchronous reset multiplexers,
 removing unused control inputs.