Merge krys/help_docs and krys/better_rtds_action

Makefile

@@ -967,8 +967,20 @@ endif
 
 # also others, but so long as it doesn't fail this is enough to know we tried
 docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS)
-	mkdir -p docs/source/cmd
-	./$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual'
+	$(Q) mkdir -p docs/source/cmd
+	$(Q) mkdir -p temp/docs/source/cmd
+	$(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual'
+	$(Q) rsync -rc temp/docs/source/cmd docs/source
+	$(Q) rm -rf temp
+docs/source/cell/word_add.rst: $(TARGETS) $(EXTRA_TARGETS)
+	$(Q) mkdir -p docs/source/cell
+	$(Q) mkdir -p temp/docs/source/cell
+	$(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-cells-manual'
+	$(Q) rsync -rc temp/docs/source/cell docs/source
+	$(Q) rm -rf temp
+
+docs/source/generated/cells.json: docs/source/generated $(TARGETS) $(EXTRA_TARGETS)
+	$(Q) ./$(PROGRAM_PREFIX)yosys -p 'help -dump-cells-json $@'
 
 PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs
 docs/gen_examples:
@@ -1010,7 +1022,7 @@ docs/reqs:
 	$(Q) $(MAKE) -C docs reqs
 
 DOC_TARGET ?= html
-docs: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage
+docs: docs/source/cmd/abc.rst docs/source/generated/cells.json docs/gen_examples docs/gen_images docs/guidelines docs/usage
 	$(Q) $(MAKE) -C docs $(DOC_TARGET)
 
 clean:

docs/source/appendix/auxlibs.rst

@@ -29,30 +29,30 @@ 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
 ---
 
 ``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
 ----

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:`~`.
 

docs/source/yosys_internals/formats/rtlil_text.rst → 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_gate` and
+:doc:`/cell_word` for a detailed list of cell types.
 
 .. code:: BNF
 

docs/source/cell/gate_other.rst

@@ -0,0 +1,5 @@
+.. autocellgroup:: gate_other
+   :caption: Other gate-level cells
+   :members:
+   :source:
+   :linenos:

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:

docs/source/cell/word_binary.rst

@@ -0,0 +1,93 @@
+.. role:: verilog(code)
+   :language: Verilog
+
+Binary operators
+~~~~~~~~~~~~~~~~
+
+.. todo:: Add detail on ``$*x`` cells, `$eqx`, `$nex`, `$bweqx`, `$shiftx`
+
+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 is also known as "remainder" in several languages. 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: