- {# end of custom part #}
- {% if not furo_hide_toc %}
-
-
- {{ _("On this page") }}
-
-
-
-
- {{ toc }}
-
-
- {% endif %}
-
-{% endblock %}
-
\ No newline at end of file
diff --git a/docs/source/appendix.rst b/docs/source/appendix.rst
deleted file mode 100644
index 0b0a2d15b5d..00000000000
--- a/docs/source/appendix.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-Appendix
-========
-
-.. toctree::
- :maxdepth: 2
- :includehidden:
-
- appendix/primer
- appendix/auxlibs
- appendix/auxprogs
-
- bib
-
-.. toctree::
- :maxdepth: 1
- :includehidden:
-
- cmd_ref
diff --git a/docs/source/appendix/auxlibs.rst b/docs/source/appendix/auxlibs.rst
index 321cb52c4d1..8c78ed6b3d2 100644
--- a/docs/source/appendix/auxlibs.rst
+++ b/docs/source/appendix/auxlibs.rst
@@ -29,7 +29,7 @@ ezSAT
The files in ``libs/ezsat`` provide a library for simplifying generating CNF
formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT
-library is written by C. Wolf. It is used by the :cmd:ref:`sat` pass (see
+library is written by C. Wolf. It is used by the `sat` pass (see
:doc:`/cmd/sat`).
fst
@@ -37,22 +37,22 @@ fst
``libfst`` files from `gtkwave`_ are included in ``libs/fst`` to support
reading/writing signal traces from/to the GTKWave developed FST format. This is
-primarily used in the :cmd:ref:`sim` command.
+primarily used in the `sim` command.
.. _gtkwave: https://github.com/gtkwave/gtkwave
json11
------
-For reading/writing designs from/to JSON, :cmd:ref:`read_json` and
-:cmd:ref:`write_json` should be used. For everything else there is the `json11
+For reading/writing designs from/to JSON, `read_json` and
+`write_json` should be used. For everything else there is the `json11
library`_:
json11 is a tiny JSON library for C++11, providing JSON parsing and
serialization.
-This library is used for outputting machine-readable statistics (:cmd:ref:`stat`
-with ``-json`` flag), using the RPC frontend (:cmd:ref:`connect_rpc`), and the
+This library is used for outputting machine-readable statistics (`stat`
+with ``-json`` flag), using the RPC frontend (`connect_rpc`), and the
yosys-witness ``yw`` format.
.. _json11 library: https://github.com/dropbox/json11
@@ -61,7 +61,7 @@ MiniSAT
-------
The files in ``libs/minisat`` provide a high-performance SAT solver, used by the
-:cmd:ref:`sat` command.
+`sat` command.
SHA1
----
diff --git a/docs/source/appendix/env_vars.rst b/docs/source/appendix/env_vars.rst
index 26cc37c8133..69e86c922ad 100644
--- a/docs/source/appendix/env_vars.rst
+++ b/docs/source/appendix/env_vars.rst
@@ -3,7 +3,7 @@ Yosys environment variables
``HOME``
Yosys command history is stored in :file:`$HOME/.yosys_history`. Graphics
- (from :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this
+ (from `show` and `viz` commands) will output to this
directory by default. This environment variable is also used in some cases
for resolving filenames with :file:`~`.
diff --git a/docs/source/yosys_internals/formats/rtlil_text.rst b/docs/source/appendix/rtlil_text.rst
similarity index 98%
rename from docs/source/yosys_internals/formats/rtlil_text.rst
rename to docs/source/appendix/rtlil_text.rst
index 8b5c1068120..2c7a82d190c 100644
--- a/docs/source/yosys_internals/formats/rtlil_text.rst
+++ b/docs/source/appendix/rtlil_text.rst
@@ -223,8 +223,8 @@ Cells
Declares a cell, with zero or more attributes, with the given identifier and
type in the enclosing module.
-Cells perform functions on input signals. See
-:doc:`/yosys_internals/formats/cell_library` for a detailed list of cell types.
+Cells perform functions on input signals. See :doc:`/cell_index` for a detailed
+list of cell types.
.. code:: BNF
diff --git a/docs/source/cell/gate_comb_combined.rst b/docs/source/cell/gate_comb_combined.rst
new file mode 100644
index 00000000000..1a1f548cc89
--- /dev/null
+++ b/docs/source/cell/gate_comb_combined.rst
@@ -0,0 +1,53 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Combinatorial cells (combined)
+------------------------------
+
+These cells combine two or more combinatorial cells (simple) into a single cell.
+
+.. table:: Cell types for gate level combinatorial cells (combined)
+
+ ======================================= =============
+ Verilog Cell Type
+ ======================================= =============
+ :verilog:`Y = A & ~B` `$_ANDNOT_`
+ :verilog:`Y = A | ~B` `$_ORNOT_`
+ :verilog:`Y = ~((A & B) | C)` `$_AOI3_`
+ :verilog:`Y = ~((A | B) & C)` `$_OAI3_`
+ :verilog:`Y = ~((A & B) | (C & D))` `$_AOI4_`
+ :verilog:`Y = ~((A | B) & (C | D))` `$_OAI4_`
+ :verilog:`Y = ~(S ? B : A)` `$_NMUX_`
+ (see below) `$_MUX4_`
+ (see below) `$_MUX8_`
+ (see below) `$_MUX16_`
+ ======================================= =============
+
+The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and
+correspond to the following Verilog code:
+
+.. code-block:: verilog
+ :force:
+
+ // $_MUX4_
+ assign Y = T ? (S ? D : C) :
+ (S ? B : A);
+ // $_MUX8_
+ assign Y = U ? T ? (S ? H : G) :
+ (S ? F : E) :
+ T ? (S ? D : C) :
+ (S ? B : A);
+ // $_MUX16_
+ assign Y = V ? U ? T ? (S ? P : O) :
+ (S ? N : M) :
+ T ? (S ? L : K) :
+ (S ? J : I) :
+ U ? T ? (S ? H : G) :
+ (S ? F : E) :
+ T ? (S ? D : C) :
+ (S ? B : A);
+
+.. autocellgroup:: comb_combined
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/gate_comb_simple.rst b/docs/source/cell/gate_comb_simple.rst
new file mode 100644
index 00000000000..f45e64496d0
--- /dev/null
+++ b/docs/source/cell/gate_comb_simple.rst
@@ -0,0 +1,26 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Combinatorial cells (simple)
+----------------------------
+
+.. table:: Cell types for gate level combinatorial cells (simple)
+
+ ======================================= =============
+ Verilog Cell Type
+ ======================================= =============
+ :verilog:`Y = A` `$_BUF_`
+ :verilog:`Y = ~A` `$_NOT_`
+ :verilog:`Y = A & B` `$_AND_`
+ :verilog:`Y = ~(A & B)` `$_NAND_`
+ :verilog:`Y = A | B` `$_OR_`
+ :verilog:`Y = ~(A | B)` `$_NOR_`
+ :verilog:`Y = A ^ B` `$_XOR_`
+ :verilog:`Y = ~(A ^ B)` `$_XNOR_`
+ :verilog:`Y = S ? B : A` `$_MUX_`
+ ======================================= =============
+
+.. autocellgroup:: comb_simple
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/gate_other.rst b/docs/source/cell/gate_other.rst
new file mode 100644
index 00000000000..bac26094e8e
--- /dev/null
+++ b/docs/source/cell/gate_other.rst
@@ -0,0 +1,8 @@
+Other gate-level cells
+----------------------
+
+.. autocellgroup:: gate_other
+ :caption: Other gate-level cells
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/gate_reg_ff.rst b/docs/source/cell/gate_reg_ff.rst
new file mode 100644
index 00000000000..2a31a3f090f
--- /dev/null
+++ b/docs/source/cell/gate_reg_ff.rst
@@ -0,0 +1,231 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Flip-flop cells
+---------------
+
+The cell types `$_DFF_N_` and `$_DFF_P_` represent d-type flip-flops.
+
+.. table:: Cell types for basic flip-flops
+
+ ======================================= =============
+ Verilog Cell Type
+ ======================================= =============
+ :verilog:`always @(negedge C) Q <= D` `$_DFF_N_`
+ :verilog:`always @(posedge C) Q <= D` `$_DFF_P_`
+ ======================================= =============
+
+The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The
+values in the table for these cell types relate to the following Verilog code
+template.
+
+.. code-block:: verilog
+ :force:
+
+ always @(CLK_EDGE C)
+ if (EN == EN_LVL)
+ Q <= D;
+
+
+.. table:: Cell types for gate level logic networks (FFs with enable)
+ :name: tab:CellLib_gates_dffe
+
+ ================== ============= ============
+ :math:`ClkEdge` :math:`EnLvl` Cell Type
+ ================== ============= ============
+ :verilog:`negedge` ``0`` `$_DFFE_NN_`
+ :verilog:`negedge` ``1`` `$_DFFE_NP_`
+ :verilog:`posedge` ``0`` `$_DFFE_PN_`
+ :verilog:`posedge` ``1`` `$_DFFE_PP_`
+ ================== ============= ============
+
+The cell types ``$_DFF_[NP][NP][01]_`` implement d-type flip-flops with
+asynchronous reset. The values in the table for these cell types relate to the
+following Verilog code template, where ``RST_EDGE`` is ``posedge`` if
+``RST_LVL`` if ``1``, and ``negedge`` otherwise.
+
+.. code-block:: verilog
+ :force:
+
+ always @(CLK_EDGE C, RST_EDGE R)
+ if (R == RST_LVL)
+ Q <= RST_VAL;
+ else
+ Q <= D;
+
+The cell types ``$_SDFF_[NP][NP][01]_`` implement d-type flip-flops with
+synchronous reset. The values in the table for these cell types relate to the
+following Verilog code template:
+
+.. code-block:: verilog
+ :force:
+
+ always @(CLK_EDGE C)
+ if (R == RST_LVL)
+ Q <= RST_VAL;
+ else
+ Q <= D;
+
+.. table:: Cell types for gate level logic networks (FFs with reset)
+ :name: tab:CellLib_gates_adff
+
+ ================== ============== ============== ===========================
+ :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` Cell Type
+ ================== ============== ============== ===========================
+ :verilog:`negedge` ``0`` ``0`` `$_DFF_NN0_`, `$_SDFF_NN0_`
+ :verilog:`negedge` ``0`` ``1`` `$_DFF_NN1_`, `$_SDFF_NN1_`
+ :verilog:`negedge` ``1`` ``0`` `$_DFF_NP0_`, `$_SDFF_NP0_`
+ :verilog:`negedge` ``1`` ``1`` `$_DFF_NP1_`, `$_SDFF_NP1_`
+ :verilog:`posedge` ``0`` ``0`` `$_DFF_PN0_`, `$_SDFF_PN0_`
+ :verilog:`posedge` ``0`` ``1`` `$_DFF_PN1_`, `$_SDFF_PN1_`
+ :verilog:`posedge` ``1`` ``0`` `$_DFF_PP0_`, `$_SDFF_PP0_`
+ :verilog:`posedge` ``1`` ``1`` `$_DFF_PP1_`, `$_SDFF_PP1_`
+ ================== ============== ============== ===========================
+
+The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with
+asynchronous reset and enable. The values in the table for these cell types
+relate to the following Verilog code template, where ``RST_EDGE`` is ``posedge``
+if ``RST_LVL`` if ``1``, and ``negedge`` otherwise.
+
+.. code-block:: verilog
+ :force:
+
+ always @(CLK_EDGE C, RST_EDGE R)
+ if (R == RST_LVL)
+ Q <= RST_VAL;
+ else if (EN == EN_LVL)
+ Q <= D;
+
+The cell types ``$_SDFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with
+synchronous reset and enable, with reset having priority over enable. The values
+in the table for these cell types relate to the following Verilog code template:
+
+.. code-block:: verilog
+ :force:
+
+ always @(CLK_EDGE C)
+ if (R == RST_LVL)
+ Q <= RST_VAL;
+ else if (EN == EN_LVL)
+ Q <= D;
+
+The cell types ``$_SDFFCE_[NP][NP][01][NP]_`` implement d-type flip-flops with
+synchronous reset and enable, with enable having priority over reset. The values
+in the table for these cell types relate to the following Verilog code template:
+
+.. code-block:: verilog
+ :force:
+
+ always @(CLK_EDGE C)
+ if (EN == EN_LVL)
+ if (R == RST_LVL)
+ Q <= RST_VAL;
+ else
+ Q <= D;
+
+
+.. table:: Cell types for gate level logic networks (FFs with reset and enable)
+ :name: tab:CellLib_gates_adffe
+
+ ================== ============== ============== ============= =================================================
+ :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` :math:`EnLvl` Cell Type
+ ================== ============== ============== ============= =================================================
+ :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFE_NN0N_`, `$_SDFFE_NN0N_`, `$_SDFFCE_NN0N_`
+ :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFE_NN0P_`, `$_SDFFE_NN0P_`, `$_SDFFCE_NN0P_`
+ :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFE_NN1N_`, `$_SDFFE_NN1N_`, `$_SDFFCE_NN1N_`
+ :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFE_NN1P_`, `$_SDFFE_NN1P_`, `$_SDFFCE_NN1P_`
+ :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFE_NP0N_`, `$_SDFFE_NP0N_`, `$_SDFFCE_NP0N_`
+ :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFE_NP0P_`, `$_SDFFE_NP0P_`, `$_SDFFCE_NP0P_`
+ :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFE_NP1N_`, `$_SDFFE_NP1N_`, `$_SDFFCE_NP1N_`
+ :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFE_NP1P_`, `$_SDFFE_NP1P_`, `$_SDFFCE_NP1P_`
+ :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFE_PN0N_`, `$_SDFFE_PN0N_`, `$_SDFFCE_PN0N_`
+ :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFE_PN0P_`, `$_SDFFE_PN0P_`, `$_SDFFCE_PN0P_`
+ :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFE_PN1N_`, `$_SDFFE_PN1N_`, `$_SDFFCE_PN1N_`
+ :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFE_PN1P_`, `$_SDFFE_PN1P_`, `$_SDFFCE_PN1P_`
+ :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFE_PP0N_`, `$_SDFFE_PP0N_`, `$_SDFFCE_PP0N_`
+ :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFE_PP0P_`, `$_SDFFE_PP0P_`, `$_SDFFCE_PP0P_`
+ :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFE_PP1N_`, `$_SDFFE_PP1N_`, `$_SDFFCE_PP1N_`
+ :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFE_PP1P_`, `$_SDFFE_PP1P_`, `$_SDFFCE_PP1P_`
+ ================== ============== ============== ============= =================================================
+
+The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with
+asynchronous set and reset. The values in the table for these cell types relate
+to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if
+``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` if
+``SET_LVL`` if ``1``, ``negedge`` otherwise.
+
+.. code-block:: verilog
+ :force:
+
+ always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S)
+ if (R == RST_LVL)
+ Q <= 0;
+ else if (S == SET_LVL)
+ Q <= 1;
+ else
+ Q <= D;
+
+.. table:: Cell types for gate level logic networks (FFs with set and reset)
+ :name: tab:CellLib_gates_dffsr
+
+ ================== ============== ============== ==============
+ :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` Cell Type
+ ================== ============== ============== ==============
+ :verilog:`negedge` ``0`` ``0`` `$_DFFSR_NNN_`
+ :verilog:`negedge` ``0`` ``1`` `$_DFFSR_NNP_`
+ :verilog:`negedge` ``1`` ``0`` `$_DFFSR_NPN_`
+ :verilog:`negedge` ``1`` ``1`` `$_DFFSR_NPP_`
+ :verilog:`posedge` ``0`` ``0`` `$_DFFSR_PNN_`
+ :verilog:`posedge` ``0`` ``1`` `$_DFFSR_PNP_`
+ :verilog:`posedge` ``1`` ``0`` `$_DFFSR_PPN_`
+ :verilog:`posedge` ``1`` ``1`` `$_DFFSR_PPP_`
+ ================== ============== ============== ==============
+
+The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with
+asynchronous set and reset and enable. The values in the table for these cell
+types relate to the following Verilog code template, where ``RST_EDGE`` is
+``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is
+``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise.
+
+.. code-block:: verilog
+ :force:
+
+ always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S)
+ if (R == RST_LVL)
+ Q <= 0;
+ else if (S == SET_LVL)
+ Q <= 1;
+ else if (E == EN_LVL)
+ Q <= D;
+
+
+.. table:: Cell types for gate level logic networks (FFs with set and reset and enable)
+ :name: tab:CellLib_gates_dffsre
+
+ ================== ============== ============== ============= ================
+ :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` :math:`EnLvl` Cell Type
+ ================== ============== ============== ============= ================
+ :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFSRE_NNNN_`
+ :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFSRE_NNNP_`
+ :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFSRE_NNPN_`
+ :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFSRE_NNPP_`
+ :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFSRE_NPNN_`
+ :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFSRE_NPNP_`
+ :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFSRE_NPPN_`
+ :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFSRE_NPPP_`
+ :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFSRE_PNNN_`
+ :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFSRE_PNNP_`
+ :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFSRE_PNPN_`
+ :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFSRE_PNPP_`
+ :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFSRE_PPNN_`
+ :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFSRE_PPNP_`
+ :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFSRE_PPPN_`
+ :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFSRE_PPPP_`
+ ================== ============== ============== ============= ================
+
+.. todo:: flip-flops with async load, ``$_ALDFFE?_[NP]{2,3}_``
+
+.. autocellgroup:: reg_ff
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/gate_reg_latch.rst b/docs/source/cell/gate_reg_latch.rst
new file mode 100644
index 00000000000..bb01bc74c71
--- /dev/null
+++ b/docs/source/cell/gate_reg_latch.rst
@@ -0,0 +1,105 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Latch cells
+-----------
+
+The cell types `$_DLATCH_N_` and `$_DLATCH_P_` represent d-type latches.
+
+.. table:: Cell types for basic latches
+
+ ======================================= =============
+ Verilog Cell Type
+ ======================================= =============
+ :verilog:`always @* if (!E) Q <= D` `$_DLATCH_N_`
+ :verilog:`always @* if (E) Q <= D` `$_DLATCH_P_`
+ ======================================= =============
+
+The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset.
+The values in the table for these cell types relate to the following Verilog
+code template:
+
+.. code-block:: verilog
+ :force:
+
+ always @*
+ if (R == RST_LVL)
+ Q <= RST_VAL;
+ else if (E == EN_LVL)
+ Q <= D;
+
+.. table:: Cell types for gate level logic networks (latches with reset)
+ :name: tab:CellLib_gates_adlatch
+
+ ============= ============== ============== ===============
+ :math:`EnLvl` :math:`RstLvl` :math:`RstVal` Cell Type
+ ============= ============== ============== ===============
+ ``0`` ``0`` ``0`` `$_DLATCH_NN0_`
+ ``0`` ``0`` ``1`` `$_DLATCH_NN1_`
+ ``0`` ``1`` ``0`` `$_DLATCH_NP0_`
+ ``0`` ``1`` ``1`` `$_DLATCH_NP1_`
+ ``1`` ``0`` ``0`` `$_DLATCH_PN0_`
+ ``1`` ``0`` ``1`` `$_DLATCH_PN1_`
+ ``1`` ``1`` ``0`` `$_DLATCH_PP0_`
+ ``1`` ``1`` ``1`` `$_DLATCH_PP1_`
+ ============= ============== ============== ===============
+
+The cell types ``$_DLATCHSR_[NP][NP][NP]_`` implement d-type latches with set
+and reset. The values in the table for these cell types relate to the following
+Verilog code template:
+
+.. code-block:: verilog
+ :force:
+
+ always @*
+ if (R == RST_LVL)
+ Q <= 0;
+ else if (S == SET_LVL)
+ Q <= 1;
+ else if (E == EN_LVL)
+ Q <= D;
+
+.. table:: Cell types for gate level logic networks (latches with set and reset)
+ :name: tab:CellLib_gates_dlatchsr
+
+ ============= ============== ============== =================
+ :math:`EnLvl` :math:`SetLvl` :math:`RstLvl` Cell Type
+ ============= ============== ============== =================
+ ``0`` ``0`` ``0`` `$_DLATCHSR_NNN_`
+ ``0`` ``0`` ``1`` `$_DLATCHSR_NNP_`
+ ``0`` ``1`` ``0`` `$_DLATCHSR_NPN_`
+ ``0`` ``1`` ``1`` `$_DLATCHSR_NPP_`
+ ``1`` ``0`` ``0`` `$_DLATCHSR_PNN_`
+ ``1`` ``0`` ``1`` `$_DLATCHSR_PNP_`
+ ``1`` ``1`` ``0`` `$_DLATCHSR_PPN_`
+ ``1`` ``1`` ``1`` `$_DLATCHSR_PPP_`
+ ============= ============== ============== =================
+
+The cell types ``$_SR_[NP][NP]_`` implement sr-type latches. The values in the
+table for these cell types relate to the following Verilog code template:
+
+.. code-block:: verilog
+ :force:
+
+ always @*
+ if (R == RST_LVL)
+ Q <= 0;
+ else if (S == SET_LVL)
+ Q <= 1;
+
+.. table:: Cell types for gate level logic networks (SR latches)
+ :name: tab:CellLib_gates_sr
+
+ ============== ============== ==========
+ :math:`SetLvl` :math:`RstLvl` Cell Type
+ ============== ============== ==========
+ ``0`` ``0`` `$_SR_NN_`
+ ``0`` ``1`` `$_SR_NP_`
+ ``1`` ``0`` `$_SR_PN_`
+ ``1`` ``1`` `$_SR_PP_`
+ ============== ============== ==========
+
+.. autocellgroup:: reg_latch
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/index_gate.rst b/docs/source/cell/index_gate.rst
new file mode 100644
index 00000000000..c9decc04594
--- /dev/null
+++ b/docs/source/cell/index_gate.rst
@@ -0,0 +1,25 @@
+.. _sec:celllib_gates:
+
+Gate-level cells
+----------------
+
+For gate level logic networks, fixed function single bit cells are used that do
+not provide any parameters.
+
+Simulation models for these cells can be found in the file
+:file:`techlibs/common/simcells.v` in the Yosys source tree.
+
+In most cases gate level logic networks are created from RTL networks using the
+techmap pass. The flip-flop cells from the gate level logic network can be
+mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass.
+The combinatorial logic cells can be mapped to physical cells from a Liberty
+file via ABC using the abc pass.
+
+.. toctree::
+ :maxdepth: 2
+
+ /cell/gate_comb_simple
+ /cell/gate_comb_combined
+ /cell/gate_reg_ff
+ /cell/gate_reg_latch
+ /cell/gate_other
diff --git a/docs/source/cell/index_word.rst b/docs/source/cell/index_word.rst
new file mode 100644
index 00000000000..409e20d2637
--- /dev/null
+++ b/docs/source/cell/index_word.rst
@@ -0,0 +1,30 @@
+Word-level cells
+----------------
+
+Most of the RTL cells closely resemble the operators available in HDLs such as
+Verilog or VHDL. Therefore Verilog operators are used in the following sections
+to define the behaviour of the RTL cells.
+
+Note that all RTL cells have parameters indicating the size of inputs and
+outputs. When passes modify RTL cells they must always keep the values of these
+parameters in sync with the size of the signals connected to the inputs and
+outputs.
+
+Simulation models for the RTL cells can be found in the file
+:file:`techlibs/common/simlib.v` in the Yosys source tree.
+
+.. toctree::
+ :maxdepth: 2
+
+ /cell/word_unary
+ /cell/word_binary
+ /cell/word_mux
+ /cell/word_reg
+ /cell/word_mem
+ /cell/word_fsm
+ /cell/word_arith
+ /cell/word_logic
+ /cell/word_spec
+ /cell/word_formal
+ /cell/word_debug
+ /cell/word_wire
diff --git a/docs/source/cell/properties.rst b/docs/source/cell/properties.rst
new file mode 100644
index 00000000000..30c58ee51f2
--- /dev/null
+++ b/docs/source/cell/properties.rst
@@ -0,0 +1,21 @@
+Cell properties
+---------------
+
+.. cell:defprop:: is_evaluable
+
+ These cells are able to be used in conjunction with the `eval` command. Some
+ passes, such as `opt_expr`, may also be able to perform additional
+ optimizations on cells which are evaluable.
+
+.. cell:defprop:: x-aware
+
+ Some passes will treat these cells as the non 'x' aware cell. For example,
+ during synthesis `$eqx` will typically be treated as `$eq`.
+
+.. cell:defprop:: x-output
+
+ These cells can produce 'x' output even if all inputs are defined. For
+ example, a `$div` cell with divisor (``B``) equal to zero has undefined
+ output.
+
+Refer to the :ref:`propindex` for the list of cells with a given property.
diff --git a/docs/source/cell/word_arith.rst b/docs/source/cell/word_arith.rst
new file mode 100644
index 00000000000..49070814add
--- /dev/null
+++ b/docs/source/cell/word_arith.rst
@@ -0,0 +1,50 @@
+Coarse arithmetics
+------------------
+
+.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells.
+
+The `$macc` cell type represents a generalized multiply and accumulate
+operation. The cell is purely combinational. It outputs the result of summing up
+a sequence of products and other injected summands.
+
+.. code-block::
+
+ Y = 0 +- a0factor1 * a0factor2 +- a1factor1 * a1factor2 +- ...
+ + B[0] + B[1] + ...
+
+The A port consists of concatenated pairs of multiplier inputs ("factors"). A
+zero length factor2 acts as a constant 1, turning factor1 into a simple summand.
+
+In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long.
+
+.. code-block::
+
+ struct A {
+ u(CONFIG.mul_info[0].factor1_len) a0factor1;
+ u(CONFIG.mul_info[0].factor2_len) a0factor2;
+ u(CONFIG.mul_info[1].factor1_len) a1factor1;
+ u(CONFIG.mul_info[1].factor2_len) a1factor2;
+ ...
+ };
+
+The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. The
+CONFIG parameter carries the following information:
+
+.. code-block::
+
+ struct CONFIG {
+ u4 num_bits;
+ struct mul_info {
+ bool is_signed;
+ bool is_subtract;
+ u(num_bits) factor1_len;
+ u(num_bits) factor2_len;
+ }[num_ports];
+ };
+
+B is an array of concatenated 1-bit-wide unsigned integers to also be summed up.
+
+.. autocellgroup:: arith
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst
new file mode 100644
index 00000000000..5e1e6cd1972
--- /dev/null
+++ b/docs/source/cell/word_binary.rst
@@ -0,0 +1,91 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Binary operators
+~~~~~~~~~~~~~~~~
+
+All binary RTL cells have two input ports ``A`` and ``B`` and one output port
+``Y``. They also have the following parameters:
+
+``A_SIGNED``
+ Set to a non-zero value if the input ``A`` is signed and therefore should be
+ sign-extended when needed.
+
+``A_WIDTH``
+ The width of the input port ``A``.
+
+``B_SIGNED``
+ Set to a non-zero value if the input ``B`` is signed and therefore should be
+ sign-extended when needed.
+
+``B_WIDTH``
+ The width of the input port ``B``.
+
+``Y_WIDTH``
+ The width of the output port ``Y``.
+
+.. table:: Cell types for binary operators with their corresponding Verilog expressions.
+
+ ======================= =============== ======================= ===========
+ Verilog Cell Type Verilog Cell Type
+ ======================= =============== ======================= ===========
+ :verilog:`Y = A & B` `$and` :verilog:`Y = A ** B` `$pow`
+ :verilog:`Y = A | B` `$or` :verilog:`Y = A < B` `$lt`
+ :verilog:`Y = A ^ B` `$xor` :verilog:`Y = A <= B` `$le`
+ :verilog:`Y = A ~^ B` `$xnor` :verilog:`Y = A == B` `$eq`
+ :verilog:`Y = A << B` `$shl` :verilog:`Y = A != B` `$ne`
+ :verilog:`Y = A >> B` `$shr` :verilog:`Y = A >= B` `$ge`
+ :verilog:`Y = A <<< B` `$sshl` :verilog:`Y = A > B` `$gt`
+ :verilog:`Y = A >>> B` `$sshr` :verilog:`Y = A + B` `$add`
+ :verilog:`Y = A && B` `$logic_and` :verilog:`Y = A - B` `$sub`
+ :verilog:`Y = A || B` `$logic_or` :verilog:`Y = A * B` `$mul`
+ :verilog:`Y = A === B` `$eqx` :verilog:`Y = A / B` `$div`
+ :verilog:`Y = A !== B` `$nex` :verilog:`Y = A % B` `$mod`
+ ``N/A`` `$shift` ``N/A`` `$divfloor`
+ ``N/A`` `$shiftx` ``N/A`` `$modfloor`
+ ======================= =============== ======================= ===========
+
+The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl` and
+`$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl` cells
+implement the same operation. All four of these cells interpret the second
+operand as unsigned, and require ``B_SIGNED`` to be zero.
+
+Two additional shift operator cells are available that do not directly
+correspond to any operator in Verilog, `$shift` and `$shiftx`. The `$shift` cell
+performs a right logical shift if the second operand is positive (or unsigned),
+and a left logical shift if it is negative. The `$shiftx` cell performs the same
+operation as the `$shift` cell, but the vacated bit positions are filled with
+undef (x) bits, and corresponds to the Verilog indexed part-select expression.
+
+For the binary cells that output a logical value (`$logic_and`, `$logic_or`,
+`$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when the ``Y_WIDTH``
+parameter is greater than 1, the output is zero-extended, and only the least
+significant bit varies.
+
+Division and modulo cells are available in two rounding modes. The original
+`$div` and `$mod` cells are based on truncating division, and correspond to the
+semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and
+`$modfloor` cells represent flooring division and flooring modulo, the latter of
+which corresponds to the ``%`` operator in Python. See the following table for a
+side-by-side comparison between the different semantics.
+
+.. table:: Comparison between different rounding modes for division and modulo cells.
+
+ +-----------+--------+-----------+-----------+-----------+-----------+
+ | Division | Result | Truncating | Flooring |
+ +-----------+--------+-----------+-----------+-----------+-----------+
+ | | | $div | $mod | $divfloor | $modfloor |
+ +===========+========+===========+===========+===========+===========+
+ | -10 / 3 | -3.3 | -3 | -1 | -4 | 2 |
+ +-----------+--------+-----------+-----------+-----------+-----------+
+ | 10 / -3 | -3.3 | -3 | 1 | -4 | -2 |
+ +-----------+--------+-----------+-----------+-----------+-----------+
+ | -10 / -3 | 3.3 | 3 | -1 | 3 | -1 |
+ +-----------+--------+-----------+-----------+-----------+-----------+
+ | 10 / 3 | 3.3 | 3 | 1 | 3 | 1 |
+ +-----------+--------+-----------+-----------+-----------+-----------+
+
+.. autocellgroup:: binary
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_debug.rst b/docs/source/cell/word_debug.rst
new file mode 100644
index 00000000000..92c753dbe7d
--- /dev/null
+++ b/docs/source/cell/word_debug.rst
@@ -0,0 +1,138 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Debugging cells
+---------------
+
+The `$print` cell is used to log the values of signals, akin to (and
+translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It
+has the following parameters:
+
+``FORMAT``
+ The internal format string. The syntax is described below.
+
+``ARGS_WIDTH``
+ The width (in bits) of the signal on the ``ARGS`` port.
+
+``TRG_ENABLE``
+ True if triggered on specific signals defined in ``TRG``; false if triggered
+ whenever ``ARGS`` or ``EN`` change and ``EN`` is 1.
+
+If ``TRG_ENABLE`` is true, the following parameters also apply:
+
+``TRG_WIDTH``
+ The number of bits in the ``TRG`` port.
+
+``TRG_POLARITY``
+ For each bit in ``TRG``, 1 if that signal is positive-edge triggered, 0 if
+ negative-edge triggered.
+
+``PRIORITY``
+ When multiple `$print` or `$check` cells fire on the same trigger, they
+ execute in descending priority order.
+
+Ports:
+
+``TRG``
+ The signals that control when this `$print` cell is triggered.
+
+ If the width of this port is zero and ``TRG_ENABLE`` is true, the cell is
+ triggered during initial evaluation (time zero) only.
+
+``EN``
+ Enable signal for the whole cell.
+
+``ARGS``
+ The values to be displayed, in format string order.
+
+.. autocellgroup:: debug
+ :members:
+ :source:
+ :linenos:
+
+Format string syntax
+~~~~~~~~~~~~~~~~~~~~
+
+The format string syntax resembles Python f-strings. Regular text is passed
+through unchanged until a format specifier is reached, starting with a ``{``.
+
+Format specifiers have the following syntax. Unless noted, all items are
+required:
+
+``{``
+ Denotes the start of the format specifier.
+
+size
+ Signal size in bits; this many bits are consumed from the ``ARGS`` port by
+ this specifier.
+
+``:``
+ Separates the size from the remaining items.
+
+justify
+ ``>`` for right-justified, ``<`` for left-justified.
+
+padding
+ ``0`` for zero-padding, or a space for space-padding.
+
+width\ *?*
+ (optional) The number of characters wide to pad to.
+
+base
+ * ``b`` for base-2 integers (binary)
+ * ``o`` for base-8 integers (octal)
+ * ``d`` for base-10 integers (decimal)
+ * ``h`` for base-16 integers (hexadecimal)
+ * ``c`` for ASCII characters/strings
+ * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and
+ :verilog:`$realtime`)
+
+For integers, this item may follow:
+
+``+``\ *?*
+ (optional, decimals only) Include a leading plus for non-negative numbers.
+ This can assist with symmetry with negatives in tabulated output.
+
+signedness
+ ``u`` for unsigned, ``s`` for signed. This distinction is only respected
+ when rendering decimals.
+
+ASCII characters/strings have no special options, but the signal size must be
+divisible by 8.
+
+For simulation time, the signal size must be zero.
+
+Finally:
+
+``}``
+ Denotes the end of the format specifier.
+
+Some example format specifiers:
+
++ ``{8:>02hu}`` - 8-bit unsigned integer rendered as hexadecimal,
+ right-justified, zero-padded to 2 characters wide.
++ ``{32:< 15d+s}`` - 32-bit signed integer rendered as decimal, left-justified,
+ space-padded to 15 characters wide, positive values prefixed with ``+``.
++ ``{16:< 10hu}`` - 16-bit unsigned integer rendered as hexadecimal,
+ left-justified, space-padded to 10 characters wide.
++ ``{0:>010t}`` - simulation time, right-justified, zero-padded to 10 characters
+ wide.
+
+To include literal ``{`` and ``}`` characters in your format string, use ``{{``
+and ``}}`` respectively.
+
+It is an error for a format string to consume more or less bits from ``ARGS``
+than the port width.
+
+Values are never truncated, regardless of the specified width.
+
+Note that further restrictions on allowable combinations of options may apply
+depending on the backend used.
+
+For example, Verilog does not have a format specifier that allows zero-padding a
+string (i.e. more than 1 ASCII character), though zero-padding a single
+character is permitted.
+
+Thus, while the RTLIL format specifier ``{8:>02c}`` translates to ``%02c``,
+``{16:>02c}`` cannot be represented in Verilog and will fail to emit. In this
+case, ``{16:> 02c}`` must be used, which translates to ``%2s``.
diff --git a/docs/source/cell/word_formal.rst b/docs/source/cell/word_formal.rst
new file mode 100644
index 00000000000..6bfa196567b
--- /dev/null
+++ b/docs/source/cell/word_formal.rst
@@ -0,0 +1,31 @@
+Formal verification cells
+-------------------------
+
+.. role:: yoscrypt(code)
+ :language: yoscrypt
+
+.. note::
+
+ Some front-ends may not support the generic `$check` cell, in such cases
+ calling :yoscrypt:`chformal -lower` will convert each `$check` cell into it's
+ equivalent. See `chformal` for more.
+
+.. todo:: Describe formal cells
+
+ `$check`, `$assert`, `$assume`, `$live`, `$fair`, `$cover`, `$equiv`,
+ `$initstate`, `$anyconst`, `$anyseq`, `$anyinit`, `$allconst`, and `$allseq`.
+
+ Also `$ff` and `$_FF_` cells.
+
+.. autocellgroup:: formal
+ :members:
+ :source:
+ :linenos:
+
+Formal support cells
+~~~~~~~~~~~~~~~~~~~~
+
+.. autocellgroup:: formal_tag
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_fsm.rst b/docs/source/cell/word_fsm.rst
new file mode 100644
index 00000000000..e6301bf3b9e
--- /dev/null
+++ b/docs/source/cell/word_fsm.rst
@@ -0,0 +1,9 @@
+Finite state machines
+---------------------
+
+.. todo:: Describe `$fsm` cell
+
+.. autocellgroup:: fsm
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_logic.rst b/docs/source/cell/word_logic.rst
new file mode 100644
index 00000000000..32945d560a0
--- /dev/null
+++ b/docs/source/cell/word_logic.rst
@@ -0,0 +1,46 @@
+Arbitrary logic functions
+-------------------------
+
+The `$lut` cell type implements a single-output LUT (lookup table). It
+implements an arbitrary logic function with its ``\LUT`` parameter to map input
+port ``\A`` to values of ``\Y`` output port values. In psuedocode: ``Y =
+\LUT[A]``. ``\A`` has width set by parameter ``\WIDTH`` and ``\Y`` has a width
+of 1. Every logic function with a single bit output has a unique `$lut`
+representation.
+
+The `$sop` cell type implements a sum-of-products expression, also known as
+disjunctive normal form (DNF). It implements an arbitrary logic function. Its
+structure mimics a programmable logic array (PLA). Output port ``\Y`` is the sum
+of products of the bits of the input port ``\A`` as defined by parameter
+``\TABLE``. ``\A`` is ``\WIDTH`` bits wide. The number of products in the sum is
+set by parameter ``\DEPTH``, and each product has two bits for each input bit -
+for the presence of the unnegated and negated version of said input bit in the
+product. Therefore the ``\TABLE`` parameter holds ``2 * \WIDTH * \DEPTH`` bits.
+
+For example:
+
+Let ``\WIDTH`` be 3. We would like to represent ``\Y =~\A[0] + \A[1]~\A[2]``.
+There are 2 products to be summed, so ``\DEPTH`` shall be 2.
+
+.. code-block::
+
+ ~A[2]-----+
+ A[2]----+|
+ ~A[1]---+||
+ A[1]--+|||
+ ~A[0]-+||||
+ A[0]+|||||
+ |||||| product formula
+ 010000 ~\A[0]
+ 001001 \A[1]~\A[2]
+
+So the value of ``\TABLE`` will become ``010000001001``.
+
+Any logic function with a single bit output can be represented with ``$sop`` but
+may have variously minimized or ordered summands represented in the ``\TABLE``
+values.
+
+.. autocellgroup:: logic
+ :members:
+ :source:
+ :linenos:
\ No newline at end of file
diff --git a/docs/source/cell/word_mem.rst b/docs/source/cell/word_mem.rst
new file mode 100644
index 00000000000..434ddea3ec5
--- /dev/null
+++ b/docs/source/cell/word_mem.rst
@@ -0,0 +1,281 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+.. _sec:memcells:
+
+Memories
+~~~~~~~~
+
+Memories are either represented using ``RTLIL::Memory`` objects, `$memrd_v2`,
+`$memwr_v2`, and `$meminit_v2` cells, or by `$mem_v2` cells alone.
+
+In the first alternative the ``RTLIL::Memory`` objects hold the general metadata
+for the memory (bit width, size in number of words, etc.) and for each port a
+`$memrd_v2` (read port) or `$memwr_v2` (write port) cell is created. Having
+individual cells for read and write ports has the advantage that they can be
+consolidated using resource sharing passes. In some cases this drastically
+reduces the number of required ports on the memory cell. In this alternative,
+memory initialization data is represented by `$meminit_v2` cells, which allow
+delaying constant folding for initialization addresses and data until after the
+frontend finishes.
+
+The `$memrd_v2` cells have a clock input ``CLK``, an enable input ``EN``, an
+address input ``ADDR``, a data output ``DATA``, an asynchronous reset input
+``ARST``, and a synchronous reset input ``SRST``. They also have the following
+parameters:
+
+``MEMID``
+ The name of the ``RTLIL::Memory`` object that is associated with this read
+ port.
+
+``ABITS``
+ The number of address bits (width of the ``ADDR`` input port).
+
+``WIDTH``
+ The number of data bits (width of the ``DATA`` output port). Note that this
+ may be a power-of-two multiple of the underlying memory's width -- such ports
+ are called wide ports and access an aligned group of cells at once. In this
+ case, the corresponding low bits of ``ADDR`` must be tied to 0.
+
+``CLK_ENABLE``
+ When this parameter is non-zero, the clock is used. Otherwise this read port
+ is asynchronous and the ``CLK`` input is not used.
+
+``CLK_POLARITY``
+ Clock is active on the positive edge if this parameter has the value ``1'b1``
+ and on the negative edge if this parameter is ``1'b0``.
+
+``TRANSPARENCY_MASK``
+ This parameter is a bitmask of write ports that this read port is transparent
+ with. The bits of this parameter are indexed by the write port's ``PORTID``
+ parameter. Transparency can only be enabled between synchronous ports sharing
+ a clock domain. When transparency is enabled for a given port pair, a read
+ and write to the same address in the same cycle will return the new value.
+ Otherwise the old value is returned.
+
+``COLLISION_X_MASK``
+ This parameter is a bitmask of write ports that have undefined collision
+ behavior with this port. The bits of this parameter are indexed by the write
+ port's ``PORTID`` parameter. This behavior can only be enabled between
+ synchronous ports sharing a clock domain. When undefined collision is enabled
+ for a given port pair, a read and write to the same address in the same cycle
+ will return the undefined (all-X) value.This option is exclusive (for a given
+ port pair) with the transparency option.
+
+``ARST_VALUE``
+ Whenever the ``ARST`` input is asserted, the data output will be reset to
+ this value. Only used for synchronous ports.
+
+``SRST_VALUE``
+ Whenever the ``SRST`` input is synchronously asserted, the data output will
+ be reset to this value. Only used for synchronous ports.
+
+``INIT_VALUE``
+ The initial value of the data output, for synchronous ports.
+
+``CE_OVER_SRST``
+ If this parameter is non-zero, the ``SRST`` input is only recognized when
+ ``EN`` is true. Otherwise, ``SRST`` is recognized regardless of ``EN``.
+
+The `$memwr_v2` cells have a clock input ``CLK``, an enable input ``EN`` (one
+enable bit for each data bit), an address input ``ADDR`` and a data input
+``DATA``. They also have the following parameters:
+
+``MEMID``
+ The name of the ``RTLIL::Memory`` object that is associated with this write
+ port.
+
+``ABITS``
+ The number of address bits (width of the ``ADDR`` input port).
+
+``WIDTH``
+ The number of data bits (width of the ``DATA`` output port). Like with
+ `$memrd_v2` cells, the width is allowed to be any power-of-two multiple of
+ memory width, with the corresponding restriction on address.
+
+``CLK_ENABLE``
+ When this parameter is non-zero, the clock is used. Otherwise this write port
+ is asynchronous and the ``CLK`` input is not used.
+
+``CLK_POLARITY``
+ Clock is active on positive edge if this parameter has the value ``1'b1`` and
+ on the negative edge if this parameter is ``1'b0``.
+
+``PORTID``
+ An identifier for this write port, used to index write port bit mask
+ parameters.
+
+``PRIORITY_MASK``
+ This parameter is a bitmask of write ports that this write port has priority
+ over in case of writing to the same address. The bits of this parameter are
+ indexed by the other write port's ``PORTID`` parameter. Write ports can only
+ have priority over write ports with lower port ID. When two ports write to
+ the same address and neither has priority over the other, the result is
+ undefined. Priority can only be set between two synchronous ports sharing
+ the same clock domain.
+
+The `$meminit_v2` cells have an address input ``ADDR``, a data input ``DATA``,
+with the width of the ``DATA`` port equal to ``WIDTH`` parameter times ``WORDS``
+parameter, and a bit enable mask input ``EN`` with width equal to ``WIDTH``
+parameter. All three of the inputs must resolve to a constant for synthesis to
+succeed.
+
+``MEMID``
+ The name of the ``RTLIL::Memory`` object that is associated with this
+ initialization cell.
+
+``ABITS``
+ The number of address bits (width of the ``ADDR`` input port).
+
+``WIDTH``
+ The number of data bits per memory location.
+
+``WORDS``
+ The number of consecutive memory locations initialized by this cell.
+
+``PRIORITY``
+ The cell with the higher integer value in this parameter wins an
+ initialization conflict.
+
+The HDL frontend models a memory using ``RTLIL::Memory`` objects and
+asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass (i.e. its
+various sub-passes) migrates `$dff` cells into the `$memrd_v2` and `$memwr_v2`
+cells making them synchronous, then converts them to a single `$mem_v2` cell and
+(optionally) maps this cell type to `$dff` cells for the individual words and
+multiplexer-based address decoders for the read and write interfaces. When the
+last step is disabled or not possible, a `$mem_v2` cell is left in the design.
+
+The `$mem_v2` cell provides the following parameters:
+
+``MEMID``
+ The name of the original ``RTLIL::Memory`` object that became this `$mem_v2`
+ cell.
+
+``SIZE``
+ The number of words in the memory.
+
+``ABITS``
+ The number of address bits.
+
+``WIDTH``
+ The number of data bits per word.
+
+``INIT``
+ The initial memory contents.
+
+``RD_PORTS``
+ The number of read ports on this memory cell.
+
+``RD_WIDE_CONTINUATION``
+ This parameter is ``RD_PORTS`` bits wide, containing a bitmask of "wide
+ continuation" read ports. Such ports are used to represent the extra data
+ bits of wide ports in the combined cell, and must have all control signals
+ identical with the preceding port, except for address, which must have the
+ proper sub-cell address encoded in the low bits.
+
+``RD_CLK_ENABLE``
+ This parameter is ``RD_PORTS`` bits wide, containing a clock enable bit for
+ each read port.
+
+``RD_CLK_POLARITY``
+ This parameter is ``RD_PORTS`` bits wide, containing a clock polarity bit for
+ each read port.
+
+``RD_TRANSPARENCY_MASK``
+ This parameter is ``RD_PORTS*WR_PORTS`` bits wide, containing a concatenation
+ of all ``TRANSPARENCY_MASK`` values of the original `$memrd_v2` cells.
+
+``RD_COLLISION_X_MASK``
+ This parameter is ``RD_PORTS*WR_PORTS`` bits wide, containing a concatenation
+ of all ``COLLISION_X_MASK`` values of the original `$memrd_v2` cells.
+
+``RD_CE_OVER_SRST``
+ This parameter is ``RD_PORTS`` bits wide, determining relative synchronous
+ reset and enable priority for each read port.
+
+``RD_INIT_VALUE``
+ This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the initial value
+ for each synchronous read port.
+
+``RD_ARST_VALUE``
+ This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the asynchronous
+ reset value for each synchronous read port.
+
+``RD_SRST_VALUE``
+ This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the synchronous
+ reset value for each synchronous read port.
+
+``WR_PORTS``
+ The number of write ports on this memory cell.
+
+``WR_WIDE_CONTINUATION``
+ This parameter is ``WR_PORTS`` bits wide, containing a bitmask of "wide
+ continuation" write ports.
+
+``WR_CLK_ENABLE``
+ This parameter is ``WR_PORTS`` bits wide, containing a clock enable bit for
+ each write port.
+
+``WR_CLK_POLARITY``
+ This parameter is ``WR_PORTS`` bits wide, containing a clock polarity bit for
+ each write port.
+
+``WR_PRIORITY_MASK``
+ This parameter is ``WR_PORTS*WR_PORTS`` bits wide, containing a concatenation
+ of all ``PRIORITY_MASK`` values of the original `$memwr_v2` cells.
+
+The `$mem_v2` cell has the following ports:
+
+``RD_CLK``
+ This input is ``RD_PORTS`` bits wide, containing all clock signals for the
+ read ports.
+
+``RD_EN``
+ This input is ``RD_PORTS`` bits wide, containing all enable signals for the
+ read ports.
+
+``RD_ADDR``
+ This input is ``RD_PORTS*ABITS`` bits wide, containing all address signals
+ for the read ports.
+
+``RD_DATA``
+ This output is ``RD_PORTS*WIDTH`` bits wide, containing all data signals for
+ the read ports.
+
+``RD_ARST``
+ This input is ``RD_PORTS`` bits wide, containing all asynchronous reset
+ signals for the read ports.
+
+``RD_SRST``
+ This input is ``RD_PORTS`` bits wide, containing all synchronous reset
+ signals for the read ports.
+
+``WR_CLK``
+ This input is ``WR_PORTS`` bits wide, containing all clock signals for the
+ write ports.
+
+``WR_EN``
+ This input is ``WR_PORTS*WIDTH`` bits wide, containing all enable signals for
+ the write ports.
+
+``WR_ADDR``
+ This input is ``WR_PORTS*ABITS`` bits wide, containing all address signals
+ for the write ports.
+
+``WR_DATA``
+ This input is ``WR_PORTS*WIDTH`` bits wide, containing all data signals for
+ the write ports.
+
+The `memory_collect` pass can be used to convert discrete `$memrd_v2`,
+`$memwr_v2`, and `$meminit_v2` cells belonging to the same memory to a single
+`$mem_v2` cell, whereas the `memory_unpack` pass performs the inverse operation.
+The `memory_dff` pass can combine asynchronous memory ports that are fed by or
+feeding registers into synchronous memory ports. The `memory_bram` pass can be
+used to recognize `$mem_v2` cells that can be implemented with a block RAM
+resource on an FPGA. The `memory_map` pass can be used to implement `$mem_v2`
+cells as basic logic: word-wide DFFs and address decoders.
+
+.. autocellgroup:: mem
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_mux.rst b/docs/source/cell/word_mux.rst
new file mode 100644
index 00000000000..3eca310f3f0
--- /dev/null
+++ b/docs/source/cell/word_mux.rst
@@ -0,0 +1,47 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Multiplexers
+------------
+
+Multiplexers are generated by the Verilog HDL frontend for ``?:``-expressions.
+Multiplexers are also generated by the proc pass to map the decision trees from
+RTLIL::Process objects to logic.
+
+The simplest multiplexer cell type is `$mux`. Cells of this type have a
+``WITDH`` parameter and data inputs ``A`` and ``B`` and a data output ``Y``, all
+of the specified width. This cell also has a single bit control input ``S``. If
+``S`` is 0 the value from the input ``A`` is sent to the output, if it is 1 the
+value from the ``B`` input is sent to the output. So the `$mux` cell implements
+the function :verilog:`Y = S ? B : A`.
+
+The `$pmux` cell is used to multiplex between many inputs using a one-hot select
+signal. Cells of this type have a ``WIDTH`` and a ``S_WIDTH`` parameter and
+inputs ``A``, ``B``, and ``S`` and an output ``Y``. The ``S`` input is
+``S_WIDTH`` bits wide. The ``A`` input and the output are both ``WIDTH`` bits
+wide and the ``B`` input is ``WIDTH*S_WIDTH`` bits wide. When all bits of ``S``
+are zero, the value from ``A`` input is sent to the output. If the :math:`n`\
+'th bit from ``S`` is set, the value :math:`n`\ 'th ``WIDTH`` bits wide slice of
+the ``B`` input is sent to the output. When more than one bit from ``S`` is set
+the output is undefined. Cells of this type are used to model "parallel cases"
+(defined by using the ``parallel_case`` attribute or detected by an
+optimization).
+
+The `$tribuf` cell is used to implement tristate logic. Cells of this type have
+a ``WIDTH`` parameter and inputs ``A`` and ``EN`` and an output ``Y``. The ``A``
+input and ``Y`` output are ``WIDTH`` bits wide, and the ``EN`` input is one bit
+wide. When ``EN`` is 0, the output is not driven. When ``EN`` is 1, the value
+from ``A`` input is sent to the ``Y`` output. Therefore, the `$tribuf` cell
+implements the function :verilog:`Y = EN ? A : 'bz`.
+
+Behavioural code with cascaded if-then-else- and case-statements usually results
+in trees of multiplexer cells. Many passes (from various optimizations to FSM
+extraction) heavily depend on these multiplexer trees to understand dependencies
+between signals. Therefore optimizations should not break these multiplexer
+trees (e.g. by replacing a multiplexer between a calculated signal and a
+constant zero with an `$and` gate).
+
+.. autocellgroup:: mux
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_reg.rst b/docs/source/cell/word_reg.rst
new file mode 100644
index 00000000000..25c82b8e63d
--- /dev/null
+++ b/docs/source/cell/word_reg.rst
@@ -0,0 +1,124 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Registers
+---------
+
+SR-type latches are represented by `$sr` cells. These cells have input ports
+``SET`` and ``CLR`` and an output port ``Q``. They have the following
+parameters:
+
+``WIDTH``
+ The width of inputs ``SET`` and ``CLR`` and output ``Q``.
+
+``SET_POLARITY``
+ The set input bits are active-high if this parameter has the value ``1'b1``
+ and active-low if this parameter is ``1'b0``.
+
+``CLR_POLARITY``
+ The reset input bits are active-high if this parameter has the value ``1'b1``
+ and active-low if this parameter is ``1'b0``.
+
+Both set and reset inputs have separate bits for every output bit. When both the
+set and reset inputs of an `$sr` cell are active for a given bit index, the
+reset input takes precedence.
+
+D-type flip-flops are represented by `$dff` cells. These cells have a clock port
+``CLK``, an input port ``D`` and an output port ``Q``. The following parameters
+are available for `$dff` cells:
+
+``WIDTH``
+ The width of input ``D`` and output ``Q``.
+
+``CLK_POLARITY``
+ Clock is active on the positive edge if this parameter has the value ``1'b1``
+ and on the negative edge if this parameter is ``1'b0``.
+
+D-type flip-flops with asynchronous reset are represented by `$adff` cells. As
+the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also
+have a single-bit ``ARST`` input port for the reset pin and the following
+additional two parameters:
+
+``ARST_POLARITY``
+ The asynchronous reset is active-high if this parameter has the value
+ ``1'b1`` and active-low if this parameter is ``1'b0``.
+
+``ARST_VALUE``
+ The state of ``Q`` will be set to this value when the reset is active.
+
+Usually these cells are generated by the `proc` pass using the information in
+the designs RTLIL::Process objects.
+
+D-type flip-flops with synchronous reset are represented by `$sdff` cells. As
+the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also
+have a single-bit ``SRST`` input port for the reset pin and the following
+additional two parameters:
+
+``SRST_POLARITY``
+ The synchronous reset is active-high if this parameter has the value ``1'b1``
+ and active-low if this parameter is ``1'b0``.
+
+``SRST_VALUE``
+ The state of ``Q`` will be set to this value when the reset is active.
+
+Note that the `$adff` and `$sdff` cells can only be used when the reset value is
+constant.
+
+D-type flip-flops with asynchronous load are represented by `$aldff` cells. As
+the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also
+have a single-bit ``ALOAD`` input port for the async load enable pin, a ``AD``
+input port with the same width as data for the async load data, and the
+following additional parameter:
+
+``ALOAD_POLARITY``
+ The asynchronous load is active-high if this parameter has the value ``1'b1``
+ and active-low if this parameter is ``1'b0``.
+
+D-type flip-flops with asynchronous set and reset are represented by `$dffsr`
+cells. As the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition
+they also have multi-bit ``SET`` and ``CLR`` input ports and the corresponding
+polarity parameters, like `$sr` cells.
+
+D-type flip-flops with enable are represented by `$dffe`, `$adffe`, `$aldffe`,
+`$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced variants of `$dff`,
+`$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset over enable) and `$sdff` (with
+enable over reset) cells, respectively. They have the same ports and parameters
+as their base cell. In addition they also have a single-bit ``EN`` input port
+for the enable pin and the following parameter:
+
+``EN_POLARITY``
+ The enable input is active-high if this parameter has the value ``1'b1`` and
+ active-low if this parameter is ``1'b0``.
+
+D-type latches are represented by `$dlatch` cells. These cells have an enable
+port ``EN``, an input port ``D``, and an output port ``Q``. The following
+parameters are available for `$dlatch` cells:
+
+``WIDTH``
+ The width of input ``D`` and output ``Q``.
+
+``EN_POLARITY``
+ The enable input is active-high if this parameter has the value ``1'b1`` and
+ active-low if this parameter is ``1'b0``.
+
+The latch is transparent when the ``EN`` input is active.
+
+D-type latches with reset are represented by `$adlatch` cells. In addition to
+`$dlatch` ports and parameters, they also have a single-bit ``ARST`` input port
+for the reset pin and the following additional parameters:
+
+``ARST_POLARITY``
+ The asynchronous reset is active-high if this parameter has the value
+ ``1'b1`` and active-low if this parameter is ``1'b0``.
+
+``ARST_VALUE``
+ The state of ``Q`` will be set to this value when the reset is active.
+
+D-type latches with set and reset are represented by `$dlatchsr` cells. In
+addition to `$dlatch` ports and parameters, they also have multi-bit ``SET`` and
+``CLR`` input ports and the corresponding polarity parameters, like `$sr` cells.
+
+.. autocellgroup:: reg
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_spec.rst b/docs/source/cell/word_spec.rst
new file mode 100644
index 00000000000..b5ce967d08a
--- /dev/null
+++ b/docs/source/cell/word_spec.rst
@@ -0,0 +1,9 @@
+Specify rules
+-------------
+
+.. todo:: `$specify2`, `$specify3`, and `$specrule` cells.
+
+.. autocellgroup:: spec
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_unary.rst b/docs/source/cell/word_unary.rst
new file mode 100644
index 00000000000..1243ef60cea
--- /dev/null
+++ b/docs/source/cell/word_unary.rst
@@ -0,0 +1,50 @@
+.. role:: verilog(code)
+ :language: Verilog
+
+Unary operators
+---------------
+
+All unary RTL cells have one input port ``A`` and one output port ``Y``. They
+also have the following parameters:
+
+``A_SIGNED``
+ Set to a non-zero value if the input ``A`` is signed and therefore should be
+ sign-extended when needed.
+
+``A_WIDTH``
+ The width of the input port ``A``.
+
+``Y_WIDTH``
+ The width of the output port ``Y``.
+
+.. table:: Cell types for unary operators with their corresponding Verilog expressions.
+
+ ================== ==============
+ Verilog Cell Type
+ ================== ==============
+ :verilog:`Y = ~A` `$not`
+ :verilog:`Y = +A` `$pos`
+ :verilog:`Y = -A` `$neg`
+ :verilog:`Y = &A` `$reduce_and`
+ :verilog:`Y = |A` `$reduce_or`
+ :verilog:`Y = ^A` `$reduce_xor`
+ :verilog:`Y = ~^A` `$reduce_xnor`
+ :verilog:`Y = |A` `$reduce_bool`
+ :verilog:`Y = !A` `$logic_not`
+ ================== ==============
+
+For the unary cells that output a logical value (`$reduce_and`, `$reduce_or`,
+`$reduce_xor`, `$reduce_xnor`, `$reduce_bool`, `$logic_not`), when the
+``Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only
+the least significant bit varies.
+
+Note that `$reduce_or` and `$reduce_bool` generally represent the same logic
+function. But the `read_verilog` frontend will generate them in different
+situations. A `$reduce_or` cell is generated when the prefix ``|`` operator is
+being used. A `$reduce_bool` cell is generated when a bit vector is used as a
+condition in an ``if``-statement or ``?:``-expression.
+
+.. autocellgroup:: unary
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell/word_wire.rst b/docs/source/cell/word_wire.rst
new file mode 100644
index 00000000000..0434cceaef4
--- /dev/null
+++ b/docs/source/cell/word_wire.rst
@@ -0,0 +1,9 @@
+Wire cells
+-------------------------
+
+.. todo:: Add information about `$slice` and `$concat` cells.
+
+.. autocellgroup:: wire
+ :members:
+ :source:
+ :linenos:
diff --git a/docs/source/cell_index.rst b/docs/source/cell_index.rst
new file mode 100644
index 00000000000..2d64db95e9e
--- /dev/null
+++ b/docs/source/cell_index.rst
@@ -0,0 +1,15 @@
+Internal cell library
+=====================
+
+The intermediate language used by Yosys (RTLIL) represents logic and memory with
+a series of cells. This section provides details for those cells, breaking them
+down into two major categories: coarse-grain word-level cells; and fine-grain
+gate-level cells. An additional section contains a list of properties which may
+be shared across multiple cells.
+
+.. toctree::
+ :maxdepth: 2
+
+ /cell/index_word
+ /cell/index_gate
+ /cell/properties
diff --git a/docs/source/code_examples/extensions/Makefile b/docs/source/code_examples/extensions/Makefile
index 2e621d70bcb..74b547a20aa 100644
--- a/docs/source/code_examples/extensions/Makefile
+++ b/docs/source/code_examples/extensions/Makefile
@@ -4,8 +4,8 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
.PHONY: all dots examples
all: dots examples
-dots: test1.dot
-examples: test0.log test1.log test2.log
+dots: test1.dot my_cmd.so
+examples: test0.log test1.log test2.log my_cmd.so
CXXFLAGS=$(shell $(YOSYS)-config --cxxflags)
DATDIR=$(shell $(YOSYS)-config --datdir)
diff --git a/docs/source/code_examples/fifo/.gitignore b/docs/source/code_examples/fifo/.gitignore
new file mode 100644
index 00000000000..b858bebc659
--- /dev/null
+++ b/docs/source/code_examples/fifo/.gitignore
@@ -0,0 +1,2 @@
+*.out
+*.stat
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 8e30fcc7c03..babbc9b5320 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,4 +1,5 @@
#!/usr/bin/env python3
+from pathlib import Path
import sys
import os
@@ -8,39 +9,18 @@
yosys_ver = "0.46"
# select HTML theme
-html_theme = 'furo'
-templates_path = ["_templates"]
-html_logo = '_static/logo.png'
-html_favicon = '_static/favico.png'
-html_css_files = ['yosyshq.css', 'custom.css']
-
-html_theme_options = {
- "sidebar_hide_name": True,
-
- "light_css_variables": {
- "color-brand-primary": "#d6368f",
- "color-brand-content": "#4b72b8",
- "color-api-name": "#8857a3",
- "color-api-pre-name": "#4b72b8",
- "color-link": "#8857a3",
- },
-
- "dark_css_variables": {
- "color-brand-primary": "#e488bb",
- "color-brand-content": "#98bdff",
- "color-api-name": "#8857a3",
- "color-api-pre-name": "#4b72b8",
- "color-link": "#be95d5",
- },
-}
+html_theme = 'furo-ys'
+html_css_files = ['custom.css']
# These folders are copied to the documentation's HTML output
html_static_path = ['_static', "_images"]
-# code blocks style
-pygments_style = 'colorful'
+# default to no highlight
highlight_language = 'none'
+# default single quotes to attempt auto reference, or fallback to code
+default_role = 'autoref'
+
extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex']
if os.getenv("READTHEDOCS"):
@@ -97,9 +77,15 @@
sys.path += [os.path.dirname(__file__) + "/../"]
extensions.append('util.cmdref')
-def setup(sphinx):
- from util.RtlilLexer import RtlilLexer
- sphinx.add_lexer("RTLIL", RtlilLexer)
+# use autodocs
+extensions.append('sphinx.ext.autodoc')
+extensions.append('util.cellref')
+cells_json = Path(__file__).parent / 'generated' / 'cells.json'
+
+from sphinx.application import Sphinx
+def setup(app: Sphinx) -> None:
+ from util.RtlilLexer import RtlilLexer
+ app.add_lexer("RTLIL", RtlilLexer)
- from util.YoscryptLexer import YoscryptLexer
- sphinx.add_lexer("yoscrypt", YoscryptLexer)
\ No newline at end of file
+ from furo_ys.lexers.YoscryptLexer import YoscryptLexer
+ app.add_lexer("yoscrypt", YoscryptLexer)
diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst
index ae0a9a36620..f8530b45bbf 100644
--- a/docs/source/getting_started/example_synth.rst
+++ b/docs/source/getting_started/example_synth.rst
@@ -2,13 +2,12 @@ Synthesis starter
-----------------
This page will be a guided walkthrough of the prepackaged iCE40 FPGA synthesis
-script - :cmd:ref:`synth_ice40`. We will take a simple design through each
-step, looking at the commands being called and what they do to the design. While
-:cmd:ref:`synth_ice40` is specific to the iCE40 platform, most of the operations
-we will be discussing are common across the majority of FPGA synthesis scripts.
-Thus, this document will provide a good foundational understanding of how
-synthesis in Yosys is performed, regardless of the actual architecture being
-used.
+script - `synth_ice40`. We will take a simple design through each step, looking
+at the commands being called and what they do to the design. While `synth_ice40`
+is specific to the iCE40 platform, most of the operations we will be discussing
+are common across the majority of FPGA synthesis scripts. Thus, this document
+will provide a good foundational understanding of how synthesis in Yosys is
+performed, regardless of the actual architecture being used.
.. seealso:: Advanced usage docs for
:doc:`/using_yosys/synthesis/synth`
@@ -59,8 +58,8 @@ can run each of the commands individually for a better sense of how each part
contributes to the flow. We will also start with just a single module;
``addr_gen``.
-At the bottom of the :cmd:ref:`help` output for
-:cmd:ref:`synth_ice40` is the complete list of commands called by this script.
+At the bottom of the `help` output for
+`synth_ice40` is the complete list of commands called by this script.
Let's start with the section labeled ``begin``:
.. literalinclude:: /cmd/synth_ice40.rst
@@ -105,10 +104,10 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy
.. note::
- :cmd:ref:`hierarchy` should always be the first command after the design has
- been read. By specifying the top module, :cmd:ref:`hierarchy` will also set
- the ``(* top *)`` attribute on it. This is used by other commands that need
- to know which module is the top.
+ `hierarchy` should always be the first command after the design has been
+ read. By specifying the top module, `hierarchy` will also set the ``(* top
+ *)`` attribute on it. This is used by other commands that need to know which
+ module is the top.
.. use doscon for a console-like display that supports the `yosys> [command]` format.
@@ -125,24 +124,24 @@ Our ``addr_gen`` circuit now looks like this:
:class: width-helper invert-helper
:name: addr_gen_hier
- ``addr_gen`` module after :cmd:ref:`hierarchy`
+ ``addr_gen`` module after `hierarchy`
Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted
from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted
-``$add`` and ``$eq`` cells we see. But control logic (like the ``if .. else``)
-and memory elements (like the ``addr <= 0``) are not so straightforward. These
-get put into "processes", shown in the schematic as ``PROC``. Note how the
-second line refers to the line numbers of the start/end of the corresponding
-``always @`` block. In the case of an ``initial`` block, we instead see the
-``PROC`` referring to line 0.
-
-To handle these, let us now introduce the next command: :doc:`/cmd/proc`.
-:cmd:ref:`proc` is a macro command like :cmd:ref:`synth_ice40`. Rather than
-modifying the design directly, it instead calls a series of other commands. In
-the case of :cmd:ref:`proc`, these sub-commands work to convert the behavioral
-logic of processes into multiplexers and registers. Let's see what happens when
-we run it. For now, we will call :yoscrypt:`proc -noopt` to prevent some
-automatic optimizations which would normally happen.
+`$add` and `$eq` cells we see. But control logic (like the ``if .. else``) and
+memory elements (like the ``addr <= 0``) are not so straightforward. These get
+put into "processes", shown in the schematic as ``PROC``. Note how the second
+line refers to the line numbers of the start/end of the corresponding ``always
+@`` block. In the case of an ``initial`` block, we instead see the ``PROC``
+referring to line 0.
+
+To handle these, let us now introduce the next command: :doc:`/cmd/proc`. `proc`
+is a macro command like `synth_ice40`. Rather than modifying the design
+directly, it instead calls a series of other commands. In the case of `proc`,
+these sub-commands work to convert the behavioral logic of processes into
+multiplexers and registers. Let's see what happens when we run it. For now, we
+will call :yoscrypt:`proc -noopt` to prevent some automatic optimizations which
+would normally happen.
.. figure:: /_images/code_examples/fifo/addr_gen_proc.*
:class: width-helper invert-helper
@@ -151,19 +150,18 @@ automatic optimizations which would normally happen.
``addr_gen`` module after :yoscrypt:`proc -noopt`
There are now a few new cells from our ``always @``, which have been
-highlighted. The ``if`` statements are now modeled with ``$mux`` cells, while
-the register uses an ``$adff`` cell. If we look at the terminal output we can
-also see all of the different ``proc_*`` commands being called. We will look at
-each of these in more detail in :doc:`/using_yosys/synthesis/proc`.
+highlighted. The ``if`` statements are now modeled with `$mux` cells, while the
+register uses an `$adff` cell. If we look at the terminal output we can also
+see all of the different ``proc_*`` commands being called. We will look at each
+of these in more detail in :doc:`/using_yosys/synthesis/proc`.
Notice how in the top left of :ref:`addr_gen_proc` we have a floating wire,
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 at
-the same time by separating them with a colon and space: :yoscrypt:`opt_expr;
-clean`.
+`clean`. We're also going to call `opt_expr` now, which would normally be
+called at the end of `proc`. We can call both commands at 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 invert-helper
@@ -171,24 +169,24 @@ clean`.
``addr_gen`` module after :yoscrypt:`opt_expr; clean`
-You may also notice that the highlighted ``$eq`` cell input of ``255`` has
-changed to ``8'11111111``. Constant values are presented in the format
+You may also notice that the highlighted `$eq` cell input of ``255`` has changed
+to ``8'11111111``. Constant values are presented in the format
``'``, with 32-bit values instead using the decimal number.
This indicates that the constant input has been reduced from 32-bit wide to
-8-bit wide. This is a side-effect of running :cmd:ref:`opt_expr`, which
-performs constant folding and simple expression rewriting. For more on why
-this happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section
-on opt_expr `.
+8-bit wide. This is a side-effect of running `opt_expr`, which performs
+constant folding and simple expression rewriting. For more on why this
+happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section on
+opt_expr `.
.. note::
: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`. You may notice some scripts will end each line
- with ``;;``. It is beneficial to run :cmd:ref:`clean` before inspecting
- intermediate products to remove disconnected parts of the circuit which have
- been left over, and in some cases can reduce the processing required in
- subsequent commands.
+ with ``;;``. It is beneficial to run `clean` before inspecting intermediate
+ products to remove disconnected parts of the circuit which have been left
+ over, and in some cases can reduce the processing required in subsequent
+ commands.
.. todo:: consider a brief glossary for terms like adff
@@ -202,8 +200,8 @@ 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 telling
-the :cmd:ref:`hierarchy` command that if the design includes any non-blackbox
-modules without an implementation it should return an error.
+the `hierarchy` command that if the design includes any non-blackbox 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
@@ -218,18 +216,17 @@ could restart our shell session, but instead let's use two new commands:
:end-before: yosys> proc
:caption: reloading :file:`fifo.v` and running :yoscrypt:`hierarchy -check -top fifo`
-Notice how this time we didn't see any of those `$abstract` modules? That's
+Notice how this time we didn't see any of those ``$abstract`` modules? That's
because when we ran ``yosys fifo.v``, the first command Yosys called was
:yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells
-:cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual
-compilation to a later :cmd:ref:`hierarchy` command. This is useful in cases
-where the default parameters of modules yield invalid code which is not
-synthesizable. This is why Yosys defers compilation automatically and is one of
-the reasons why hierarchy should always be the first command after loading the
-design. If we know that our design won't run into this issue, we can skip the
-``-defer``.
+`read_verilog` only read the abstract syntax tree and defer actual compilation
+to a later `hierarchy` command. This is useful in cases where the default
+parameters of modules yield invalid code which is not synthesizable. This is why
+Yosys defers compilation automatically and is one of the reasons why hierarchy
+should always be the first command after loading the design. If we know that
+our design won't run into this issue, we can skip the ``-defer``.
-.. todo:: :cmd:ref:`hierarchy` failure modes
+.. todo:: `hierarchy` failure modes
.. note::
@@ -243,19 +240,19 @@ design. If we know that our design won't run into this issue, we can skip the
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
-path for the ``rdata`` output. If you would like to see the entire design for
-yourself, you can do so with :doc:`/cmd/show`. Note that the :cmd:ref:`show`
-command only works with a single module, so you may need to call it with
-:yoscrypt:`show fifo`. :ref:`show_intro` section in
-:doc:`/getting_started/scripting_intro` has more on how to use :cmd:ref:`show`.
+We can also run `proc` now to finish off the full :ref:`synth_begin`. Because
+the design schematic is quite large, we will be showing just the data path for
+the ``rdata`` output. If you would like to see the entire design for yourself,
+you can do so with :doc:`/cmd/show`. Note that the `show` command only works
+with a single module, so you may need to call it with :yoscrypt:`show fifo`.
+:ref:`show_intro` section in :doc:`/getting_started/scripting_intro` has more on
+how to use `show`.
.. figure:: /_images/code_examples/fifo/rdata_proc.*
:class: width-helper invert-helper
:name: rdata_proc
- ``rdata`` output after :cmd:ref:`proc`
+ ``rdata`` output after `proc`
The highlighted ``fifo_reader`` block contains an instance of the
:ref:`addr_gen_proc` that we looked at earlier. Notice how the type is shown as
@@ -263,10 +260,10 @@ The highlighted ``fifo_reader`` block contains an instance of the
instance of the ``addr_gen`` module with the ``MAX_DATA`` parameter set to the
given value.
-The other highlighted block is a ``$memrd`` cell. At this stage of synthesis we
+The other highlighted block is a `$memrd` cell. At this stage of synthesis we
don't yet know what type of memory is going to be implemented, but we *do* know
that ``rdata <= data[raddr];`` could be implemented as a read from memory. Note
-that the ``$memrd`` cell here is asynchronous, with both the clock and enable
+that the `$memrd` cell here is asynchronous, with both the clock and enable
signal undefined; shown with the ``1'x`` inputs.
.. seealso:: Advanced usage docs for
@@ -276,7 +273,7 @@ Flattening
~~~~~~~~~~
At this stage of a synthesis flow there are a few other commands we could run.
-In :cmd:ref:`synth_ice40` we get these:
+In `synth_ice40` we get these:
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@@ -286,7 +283,7 @@ In :cmd:ref:`synth_ice40` we get these:
:name: synth_flatten
:caption: ``flatten`` section
-First off is :cmd:ref:`flatten`. Flattening the design like this can allow for
+First off is `flatten`. Flattening the design like this can allow for
optimizations between modules which would otherwise be missed. Let's run
:yoscrypt:`flatten;;` on our design.
@@ -309,23 +306,22 @@ optimizations between modules which would otherwise be missed. Let's run
The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from
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
+and merged with the ``raddr`` wire feeding into the `$memrd` cell. This wire
+merging happened during the call to `clean` which we can see in the
:ref:`flat_clean`.
.. note::
- :cmd:ref:`flatten` and :cmd:ref:`clean` would normally be combined into a
+ `flatten` and `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
+ a side effect of using `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
-:cmd:ref:`deminout`. These remove tristate and inout constructs respectively,
-replacing them with logic suitable for mapping to an FPGA. Since we do not have
-any such constructs in our example running these commands does not change our
-design.
+commands such as `tribuf` with the ``-logic`` option and `deminout`. These
+remove tristate and inout constructs respectively, replacing them with logic
+suitable for mapping to an FPGA. Since we do not have any such constructs in
+our example running these commands does not change our design.
The coarse-grain representation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -342,9 +338,9 @@ optimizations and other transformations done previously.
.. note::
- While the iCE40 flow had a :ref:`synth_flatten` and put :cmd:ref:`proc` in
- the :ref:`synth_begin`, some synthesis scripts will instead include these in
- this section.
+ While the iCE40 flow had a :ref:`synth_flatten` and put `proc` in the
+ :ref:`synth_begin`, some synthesis scripts will instead include these in this
+ section.
Part 1
^^^^^^
@@ -359,36 +355,35 @@ In the iCE40 flow, we start with the following commands:
:caption: ``coarse`` section (part 1)
:name: synth_coarse1
-We've already come across :cmd:ref:`opt_expr`, and :cmd:ref:`opt_clean` is the
-same as :cmd:ref:`clean` but with more verbose output. The :cmd:ref:`check`
-pass identifies a few obvious problems which will cause errors later. Calling
-it here lets us fail faster rather than wasting time on something we know is
-impossible.
+We've already come across `opt_expr`, and `opt_clean` is the same as `clean` but
+with more verbose output. The `check` pass identifies a few obvious problems
+which will cause errors later. Calling it here lets us fail faster rather than
+wasting time on something we know is impossible.
Next up is :yoscrypt:`opt -nodffe -nosdff` performing a set of simple
optimizations on the design. This command also ensures that only a specific
subset of FF types are included, in preparation for the next command:
-:doc:`/cmd/fsm`. Both :cmd:ref:`opt` and :cmd:ref:`fsm` are macro commands
-which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and
+:doc:`/cmd/fsm`. Both `opt` and `fsm` are macro commands which are explored in
+more detail in :doc:`/using_yosys/synthesis/opt` and
:doc:`/using_yosys/synthesis/fsm` respectively.
Up until now, the data path for ``rdata`` has remained the same since
-:ref:`rdata_flat`. However the next call to :cmd:ref:`opt` does cause a change.
-Specifically, the call to :cmd:ref:`opt_dff` without the ``-nodffe -nosdff``
-options is able to fold one of the ``$mux`` cells into the ``$adff`` to form an
-``$adffe`` cell; highlighted below:
+:ref:`rdata_flat`. However the next call to `opt` does cause a change.
+Specifically, the call to `opt_dff` without the ``-nodffe -nosdff`` options is
+able to fold one of the `$mux` cells into the `$adff` to form an `$adffe` cell;
+highlighted below:
.. literalinclude:: /code_examples/fifo/fifo.out
:language: doscon
:start-at: yosys> opt_dff
:end-before: yosys> select
- :caption: output of :cmd:ref:`opt_dff`
+ :caption: output of `opt_dff`
.. figure:: /_images/code_examples/fifo/rdata_adffe.*
:class: width-helper invert-helper
:name: rdata_adffe
- ``rdata`` output after :cmd:ref:`opt_dff`
+ ``rdata`` output after `opt_dff`
.. seealso:: Advanced usage docs for
@@ -414,27 +409,27 @@ First up is :doc:`/cmd/wreduce`. If we run this we get the following:
:language: doscon
:start-at: yosys> wreduce
:end-before: yosys> select
- :caption: output of :cmd:ref:`wreduce`
+ :caption: output of `wreduce`
Looking at the data path for ``rdata``, the most relevant of these width
reductions are the ones affecting ``fifo.$flatten\fifo_reader.$add$fifo.v``.
-That is the ``$add`` cell incrementing the fifo_reader address. We can look at
+That is the `$add` cell incrementing the fifo_reader address. We can look at
the schematic and see the output of that cell has now changed.
-.. todo:: pending bugfix in :cmd:ref:`wreduce` and/or :cmd:ref:`opt_clean`
+.. todo:: pending bugfix in `wreduce` and/or `opt_clean`
.. figure:: /_images/code_examples/fifo/rdata_wreduce.*
:class: width-helper invert-helper
:name: rdata_wreduce
- ``rdata`` output after :cmd:ref:`wreduce`
+ ``rdata`` output after `wreduce`
The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`.
Neither of these affect our design, and they're explored in more detail in
:doc:`/using_yosys/synthesis/opt`, so let's skip over them. :yoscrypt:`techmap
-map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain comparison operators by
-converting them to LUTs instead. The usage of :cmd:ref:`techmap` is explored
-more in :doc:`/using_yosys/synthesis/techmap_synth`.
+converting them to LUTs instead. The usage of `techmap` is explored more in
+:doc:`/using_yosys/synthesis/techmap_synth`.
Our next command to run is
:doc:`/cmd/memory_dff`.
@@ -443,17 +438,17 @@ Our next command to run is
:language: doscon
:start-at: yosys> memory_dff
:end-before: yosys> select
- :caption: output of :cmd:ref:`memory_dff`
+ :caption: output of `memory_dff`
.. figure:: /_images/code_examples/fifo/rdata_memrdv2.*
:class: width-helper invert-helper
:name: rdata_memrdv2
- ``rdata`` output after :cmd:ref:`memory_dff`
+ ``rdata`` output after `memory_dff`
-As the title suggests, :cmd:ref:`memory_dff` has merged the output ``$dff`` into
-the ``$memrd`` cell and converted it to a ``$memrd_v2`` (highlighted). This has
-also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous
+As the title suggests, `memory_dff` has merged the output `$dff` into the
+`$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has also
+connected the ``CLK`` port to the ``clk`` input as it is now a synchronous
memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and
``SRST=1'0``) inputs.
@@ -466,12 +461,11 @@ memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and
Part 3
^^^^^^
-The third part of the :cmd:ref:`synth_ice40` flow is a series of commands for
-mapping to DSPs. By default, the iCE40 flow will not map to the hardware DSP
-blocks and will only be performed if called with the ``-dsp`` flag:
-:yoscrypt:`synth_ice40 -dsp`. While our example has nothing that could be
-mapped to DSPs we can still take a quick look at the commands here and describe
-what they do.
+The third part of the `synth_ice40` flow is a series of commands for mapping to
+DSPs. By default, the iCE40 flow will not map to the hardware DSP blocks and
+will only be performed if called with the ``-dsp`` flag: :yoscrypt:`synth_ice40
+-dsp`. While our example has nothing that could be mapped to DSPs we can still
+take a quick look at the commands here and describe what they do.
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@@ -482,29 +476,27 @@ what they do.
:name: synth_coarse3
:yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting
-only cells of type ``$mul``. :yoscrypt:`techmap -map +/mul2dsp.v -map
-+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses :cmd:ref:`techmap` to map
-``$mul`` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40
-``SB_MAC16``. Any multipliers which aren't compatible with conversion to
-``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype`
-changes them back to ``$mul``.
+only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map
++/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses `techmap` to map `$mul`
+cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 ``SB_MAC16``.
+Any multipliers which aren't compatible with conversion to ``$__MUL16X16`` are
+relabelled to ``$__soft_mul`` before `chtype` changes them back to `$mul`.
During the mul2dsp conversion, some of the intermediate signals are marked with
the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict
the following commands to only operate on the cells and wires used for these
-signals. :cmd:ref:`setattr` removes the now unnecessary ``mul2dsp`` attribute.
-:cmd:ref:`opt_expr` we've already come across for const folding and simple
-expression rewriting, the ``-fine`` option just enables more fine-grain
-optimizations. Then we perform width reduction a final time and clear the
-selection.
+signals. `setattr` removes the now unnecessary ``mul2dsp`` attribute.
+`opt_expr` we've already come across for const folding and simple 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,
-but also pipeline registers and even a post-adder where applicable: turning a
-multiply + add into a single multiply-accumulate.
+Finally we have `ice40_dsp`: similar to the `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, but also pipeline
+registers and even a post-adder where applicable: turning a multiply + add into
+a single multiply-accumulate.
.. seealso:: Advanced usage docs for
:doc:`/using_yosys/synthesis/techmap_synth`
@@ -522,44 +514,43 @@ That brings us to the fourth and final part for the iCE40 synthesis flow:
:caption: ``coarse`` section (part 4)
: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 help
-identify opportunities for reusing logic. We do this by running
-:cmd:ref:`alumacc`, which we can see produce the following changes in our
-example design:
+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 help identify
+opportunities for reusing logic. We do this by running `alumacc`, which we can
+see produce the following changes in our example design:
.. literalinclude:: /code_examples/fifo/fifo.out
:language: doscon
:start-at: yosys> alumacc
:end-before: yosys> select
- :caption: output of :cmd:ref:`alumacc`
+ :caption: output of `alumacc`
.. figure:: /_images/code_examples/fifo/rdata_alumacc.*
:class: width-helper invert-helper
:name: rdata_alumacc
- ``rdata`` output after :cmd:ref:`alumacc`
+ ``rdata`` output after `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``.
+Once these cells have been inserted, the call to `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
+The other new command in this part is :doc:`/cmd/memory`. `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
-the step most relevant to our example: :cmd:ref:`memory_collect`. Up until this
-point, our memory reads and our memory writes have been totally disjoint cells;
-operating on the same memory only in the abstract. :cmd:ref:`memory_collect`
-combines all of the reads and writes for a memory block into a single cell.
+the step most relevant to our example: `memory_collect`. Up until this point,
+our memory reads and our memory writes have been totally disjoint cells;
+operating on the same memory only in the abstract. `memory_collect` combines all
+of the reads and writes for a memory block into a single cell.
.. figure:: /_images/code_examples/fifo/rdata_coarse.*
:class: width-helper invert-helper
:name: rdata_coarse
- ``rdata`` output after :cmd:ref:`memory_collect`
+ ``rdata`` output after `memory_collect`
-Looking at the schematic after running :cmd:ref:`memory_collect` we see that our
-``$memrd_v2`` cell has been replaced with a ``$mem_v2`` cell named ``data``, the
+Looking at the schematic after running `memory_collect` we see that our
+`$memrd_v2` cell has been replaced with a `$mem_v2` cell named ``data``, the
same name that we used in :ref:`fifo-v`. Where before we had a single set of
signals for address and enable, we now have one set for reading (``RD_*``) and
one for writing (``WR_*``), as well as both ``WR_DATA`` input and ``RD_DATA``
@@ -592,8 +583,8 @@ If you skipped calling :yoscrypt:`read_verilog -D ICE40_HX -lib -specify
Memory blocks
^^^^^^^^^^^^^
-Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and
-:cmd:ref:`techmap`.
+Mapping to hard memory blocks uses a combination of `memory_libmap` and
+`techmap`.
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@@ -609,28 +600,28 @@ Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and
``rdata`` output after :ref:`map_ram`
-The :ref:`map_ram` converts the generic ``$mem_v2`` into the iCE40
-``SB_RAM40_4K`` (highlighted). We can also see the memory address has been
-remapped, and the data bits have been reordered (or swizzled). There is also
-now a ``$mux`` cell controlling the value of ``rdata``. In :ref:`fifo-v` we
-wrote our memory as read-before-write, however the ``SB_RAM40_4K`` has undefined
-behaviour when reading from and writing to the same address in the same cycle.
-As a result, extra logic is added so that the generated circuit matches the
-behaviour of the verilog. :ref:`no_rw_check` describes how we could change our
-verilog to match our hardware instead.
+The :ref:`map_ram` converts the generic `$mem_v2` into the iCE40 ``SB_RAM40_4K``
+(highlighted). We can also see the memory address has been remapped, and the
+data bits have been reordered (or swizzled). There is also now a `$mux` cell
+controlling the value of ``rdata``. In :ref:`fifo-v` we wrote our memory as
+read-before-write, however the ``SB_RAM40_4K`` has undefined behaviour when
+reading from and writing to the same address in the same cycle. As a result,
+extra logic is added so that the generated circuit matches the behaviour of the
+verilog. :ref:`no_rw_check` describes how we could change our verilog to match
+our hardware instead.
-If we run :cmd:ref:`memory_libmap` under the :cmd:ref:`debug` command we can see
-candidates which were identified for mapping, along with the costs of each and
-what logic requires emulation.
+If we run `memory_libmap` under the `debug` command we can see candidates which
+were identified for mapping, along with the costs of each and what logic
+requires emulation.
.. literalinclude:: /code_examples/fifo/fifo.libmap
:language: doscon
:lines: 2, 6-
The ``$__ICE40_RAM4K_`` cell is defined in the file |techlibs/ice40/brams.txt|_,
-with the mapping to ``SB_RAM40_4K`` done by :cmd:ref:`techmap` using
+with the mapping to ``SB_RAM40_4K`` done by `techmap` using
|techlibs/ice40/brams_map.v|_. Any leftover memory cells are then converted
-into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
+into flip flops (the ``logic fallback``) with `memory_map`.
.. |techlibs/ice40/brams.txt| replace:: :file:`techlibs/ice40/brams.txt`
.. _techlibs/ice40/brams.txt: https://github.com/YosysHQ/yosys/tree/main/techlibs/ice40/brams.txt
@@ -654,8 +645,8 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
.. note::
The visual clutter on the ``RDATA`` output port (highlighted) is an
- unfortunate side effect of :cmd:ref:`opt_clean` on the swizzled data bits. In
- connecting the ``$mux`` input port directly to ``RDATA`` to reduce the number
+ unfortunate side effect of `opt_clean` on the swizzled data bits. In
+ connecting the `$mux` input port directly to ``RDATA`` to reduce the number
of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually
complex.
@@ -667,11 +658,10 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
Arithmetic
^^^^^^^^^^
-Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees
-somewhat of an explosion in cells as multi-bit ``$mux`` and ``$adffe`` are
-replaced with single-bit ``$_MUX_`` and ``$_DFFE_PP0P_`` cells, while the
-``$alu`` is replaced with primitive ``$_OR_`` and ``$_NOT_`` gates and a
-``$lut`` cell.
+Uses `techmap` to map basic arithmetic logic to hardware. This sees somewhat of
+an explosion in cells as multi-bit `$mux` and `$adffe` are replaced with
+single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the `$alu` is replaced with
+primitive `$_OR_` and `$_NOT_` gates and a `$lut` cell.
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@@ -693,14 +683,14 @@ replaced with single-bit ``$_MUX_`` and ``$_DFFE_PP0P_`` cells, while the
Flip-flops
^^^^^^^^^^
-Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and
-then use :cmd:ref:`techmap` to map them. In our example, this converts the
-``$_DFFE_PP0P_`` cells to ``SB_DFFER``.
+Convert FFs to the types supported in hardware with `dfflegalize`, and then use
+`techmap` to map them. In our example, this converts the `$_DFFE_PP0P_` cells
+to ``SB_DFFER``.
-We also run :cmd:ref:`simplemap` here to convert any remaining cells which could
-not be mapped to hardware into gate-level primitives. This includes optimizing
-``$_MUX_`` cells where one of the inputs is a constant ``1'0``, replacing it
-instead with an ``$_AND_`` cell.
+We also run `simplemap` here to convert any remaining cells which could not be
+mapped to hardware into gate-level primitives. This includes optimizing
+`$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it
+instead with an `$_AND_` cell.
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@@ -722,11 +712,10 @@ instead with an ``$_AND_`` cell.
LUTs
^^^^
-:cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive
-cell types to use ``$lut`` and ``SB_CARRY`` cells. Note that the iCE40 flow
-uses :cmd:ref:`abc9` rather than :cmd:ref:`abc`. For more on what these do, and
-what the difference between these two commands are, refer to
-:doc:`/using_yosys/synthesis/abc`.
+`abc` and `techmap` are used to map LUTs; converting primitive cell types to use
+`$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow uses `abc9` rather than
+`abc`. For more on what these do, and what the difference between these two
+commands are, refer to :doc:`/using_yosys/synthesis/abc`.
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@@ -742,8 +731,8 @@ what the difference between these two commands are, refer to
``rdata`` output after :ref:`map_luts`
-Finally we use :cmd:ref:`techmap` to map the generic ``$lut`` cells to iCE40
-``SB_LUT4`` cells.
+Finally we use `techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4``
+cells.
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@@ -769,12 +758,12 @@ Other cells
The following commands may also be used for mapping other cells:
-:cmd:ref:`hilomap`
+`hilomap`
Some architectures require special driver cells for driving a constant hi or
lo value. This command replaces simple constants with instances of such
driver cells.
-:cmd:ref:`iopadmap`
+`iopadmap`
Top-level input/outputs must usually be implemented using special I/O-pad
cells. This command inserts such cells to the design.
@@ -801,28 +790,27 @@ The new commands here are:
- :doc:`/cmd/stat`, and
- :doc:`/cmd/blackbox`.
-The output from :cmd:ref:`stat` is useful for checking resource utilization;
-providing a list of cells used in the design and the number of each, as well as
-the number of other resources used such as wires and processes. For this
-design, the final call to :cmd:ref:`stat` should look something like the
-following:
+The output from `stat` is useful for checking resource utilization; providing a
+list of cells used in the design and the number of each, as well as the number
+of other resources used such as wires and processes. For this design, the final
+call to `stat` should look something like the following:
.. literalinclude:: /code_examples/fifo/fifo.stat
:language: doscon
:start-at: yosys> stat -top fifo
-Note that the :yoscrypt:`-top fifo` here is optional. :cmd:ref:`stat` will
-automatically use the module with the ``top`` attribute set, which ``fifo`` was
-when we called :cmd:ref:`hierarchy`. If no module is marked ``top``, then stats
-will be shown for each module selected.
+Note that the :yoscrypt:`-top fifo` here is optional. `stat` will automatically
+use the module with the ``top`` attribute set, which ``fifo`` was when we called
+`hierarchy`. If no module is marked ``top``, then stats will be shown for each
+module selected.
-The :cmd:ref:`stat` output is also useful as a kind of sanity-check: Since we
-have already run :cmd:ref:`proc`, we wouldn't expect there to be any processes.
-We also expect ``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw
-a high number of flip-flops being used we might suspect something was wrong.
+The `stat` output is also useful as a kind of sanity-check: Since we have
+already run `proc`, we wouldn't expect there to be any processes. We also expect
+``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw a high number
+of flip-flops being used we might suspect something was wrong.
-If we instead called :cmd:ref:`stat` immediately after :yoscrypt:`read_verilog
-fifo.v` we would see something very different:
+If we instead called `stat` immediately after :yoscrypt:`read_verilog fifo.v` we
+would see something very different:
.. literalinclude:: /code_examples/fifo/fifo.stat
:language: doscon
@@ -845,10 +833,10 @@ The iCE40 synthesis flow has the following output modes available:
As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`,
our synthesized ``fifo`` design will be output as :file:`fifo.json`. We can
-then read the design back into Yosys with :cmd:ref:`read_json`, but make sure
-you use :yoscrypt:`design -reset` or open a new interactive terminal first. The
-JSON output we get can also be loaded into `nextpnr`_ to do place and route; but
-that is beyond the scope of this documentation.
+then read the design back into Yosys with `read_json`, but make sure you use
+:yoscrypt:`design -reset` or open a new interactive terminal first. The JSON
+output we get can also be loaded into `nextpnr`_ to do place and route; but that
+is beyond the scope of this documentation.
.. _nextpnr: https://github.com/YosysHQ/nextpnr
diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst
index 4d1a2f36a58..57ae5303639 100644
--- a/docs/source/getting_started/installation.rst
+++ b/docs/source/getting_started/installation.rst
@@ -88,7 +88,7 @@ A C++ compiler with C++17 support is required as well as some standard tools
such as GNU Flex, GNU Bison, Make and Python. Some additional tools: readline,
libffi, Tcl and zlib; are optional but enabled by default (see
:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the
-:cmd:ref:`show` command to display schematics.
+`show` command to display schematics.
Installing all prerequisites for Ubuntu 20.04:
@@ -109,7 +109,7 @@ Installing all prerequisites for macOS 11 (with Homebrew):
Running the build system
^^^^^^^^^^^^^^^^^^^^^^^^
-From the root `yosys` directory, call the following commands:
+From the root ``yosys`` directory, call the following commands:
.. code:: console
@@ -117,7 +117,7 @@ From the root `yosys` directory, call the following commands:
sudo make install
This will build and then install Yosys, making it available on the command line
-as `yosys`. Note that this also downloads, builds, and installs `ABC`_ (using
+as ``yosys``. Note that this also downloads, builds, and installs `ABC`_ (using
:program:`yosys-abc` as the executable name).
.. _ABC: https://github.com/berkeley-abc/abc
@@ -184,9 +184,8 @@ directories:
``passes/``
This directory contains a subdirectory for each pass or group of passes. For
- example as of this writing the directory :file:`passes/hierarchy/` contains the
- code for three passes: :cmd:ref:`hierarchy`, :cmd:ref:`submod`, and
- :cmd:ref:`uniquify`.
+ example as of this writing the directory :file:`passes/hierarchy/` contains
+ the code for three passes: `hierarchy`, `submod`, and `uniquify`.
``techlibs/``
This directory contains simulation models and standard implementations for
diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst
index a6b4cb6bb42..01954c6615c 100644
--- a/docs/source/getting_started/scripting_intro.rst
+++ b/docs/source/getting_started/scripting_intro.rst
@@ -7,8 +7,7 @@ file format and how you can make your own synthesis scripts.
Yosys script files typically use the :file:`.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`.
+were using on the previous page like `read_verilog` and `hierarchy`.
Script parsing
~~~~~~~~~~~~~~
@@ -39,9 +38,9 @@ Another special character that can be used in Yosys scripts is the bang ``!``.
Anything after the bang will be executed as a shell command. This can only be
terminated with a new line. Any semicolons, hashes, or other special characters
will be passed to the shell. If an error code is returned from the shell it
-will be raised by Yosys. :cmd:ref:`exec` provides a much more flexible way of
-executing commands, allowing the output to be logged and more control over when
-to generate errors.
+will be raised by Yosys. `exec` provides a much more flexible way of executing
+commands, allowing the output to be logged and more control over when to
+generate errors.
The synthesis starter script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,24 +61,23 @@ already, let's take a look at some of those script files now.
:caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example`
:name: fifo-ys
-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
+The first command there, :yoscrypt:`echo on`, uses `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.
-We briefly touched on :cmd:ref:`select` when it came up in
-:cmd:ref:`synth_ice40`, but let's look at it more now.
+We briefly touched on `select` when it came up in `synth_ice40`, but let's look
+at it more now.
.. _select_intro:
Selections intro
^^^^^^^^^^^^^^^^
-The :cmd:ref:`select` command is used to modify and view the list of selected
-objects:
+The `select` command is used to modify and view the list of selected objects:
.. literalinclude:: /code_examples/fifo/fifo.out
:language: doscon
@@ -99,7 +97,7 @@ 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
+gives us the `$add` and `$eq` cells, which we want to highlight for the
:ref:`addr_gen_hier` image.
.. _select_new_cells:
@@ -111,15 +109,16 @@ by referring to it as ``@new_cells``, which we will see later. 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 ` 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.
+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 ` 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.
+:yoscrypt:`clean addr_gen` to have `clean` operate on *just* the ``addr_gen``
+module.
Detailed documentation of the select framework can be found under
:doc:`/using_yosys/more_scripting/selections` or in the command reference at
@@ -130,23 +129,23 @@ Detailed documentation of the select framework can be found under
Displaying schematics
^^^^^^^^^^^^^^^^^^^^^
-While the :cmd:ref:`select` command is very useful, sometimes nothing beats
-being able to see a design for yourself. This is where :cmd:ref:`show` comes
-in. Note that this document is just an introduction to the :cmd:ref:`show`
-command, only covering the basics. For more information, including a guide on
-what the different symbols represent, see :ref:`interactive_show` and the
+While the `select` command is very useful, sometimes nothing beats being able to
+see a design for yourself. This is where `show` comes in. Note that this
+document is just an introduction to the `show` command, only covering the
+basics. For more information, including a guide on what the different symbols
+represent, see :ref:`interactive_show` and the
:doc:`/using_yosys/more_scripting/interactive_investigation` page.
.. figure:: /_images/code_examples/fifo/addr_gen_show.*
:class: width-helper invert-helper
:name: addr_gen_show
- Calling :yoscrypt:`show addr_gen` after :cmd:ref:`hierarchy`
+ Calling :yoscrypt:`show addr_gen` after `hierarchy`
.. note::
- The :cmd:ref:`show` command requires a working installation of `GraphViz`_
- and `xdot`_ for displaying the actual circuit diagrams.
+ The `show` command requires a working installation of `GraphViz`_ and `xdot`_
+ for displaying the actual circuit diagrams.
.. _GraphViz: http://www.graphviz.org/
.. _xdot: https://github.com/jrfonseca/xdot.py
@@ -160,8 +159,8 @@ we see the following:
:start-at: -prefix addr_gen_show
:end-before: yosys> show
-Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output
-a :file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix
+Calling `show` with :yoscrypt:`-format dot` tells it we want to output a
+:file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix
addr_gen_show` option indicates we want the file to be called
:file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we
need to store the image for displaying in the documentation you're reading. But
@@ -184,8 +183,8 @@ like when we called :yoscrypt:`select -module addr_gen` in :ref:`select_intro`.
That last parameter doesn't have to be a module name, it can be any valid
selection string. Remember when we :ref:`assigned a name to a
selection` and called it ``new_cells``? We saw in the
-:yoscrypt:`select -list` output that it contained two cells, an ``$add`` and an
-``$eq``. We can call :cmd:ref:`show` on that selection just as easily:
+:yoscrypt:`select -list` output that it contained two cells, an `$add` and an
+`$eq`. We can call `show` on that selection just as easily:
.. figure:: /_images/code_examples/fifo/new_cells_show.*
:class: width-helper invert-helper
@@ -207,21 +206,20 @@ the two ``PROC`` blocks. To achieve this highlight, we make use of the
Calling :yoscrypt:`show -color maroon3 @new_cells -color cornflowerblue p:* -notitle`
-As described in the the :cmd:ref:`help` output for :cmd:ref:`show` (or by
-clicking on the :cmd:ref:`show` link), colors are specified as :yoscrypt:`-color
-