Docs: Update for properties

Add properties page, move cell_gate and cell_word under a singular cell_index along with properties. Fix links accordingly. Also drop x-aware and x-output todos since they are resolved.
YosysHQ · Sep 6, 2024 · 4803af0 · 4803af0
1 parent 831e108
commit 4803af0
Show file tree

Hide file tree

Showing 9 changed files with 34 additions and 18 deletions.
diff --git a/docs/source/appendix/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:`/cell_gate` and
-:doc:`/cell_word` 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.rst → docs/source/cell/index_gate.rst b/docs/source/cell_gate.rst → docs/source/cell/index_gate.rst
@@ -16,7 +16,6 @@ The combinatorial logic cells can be mapped to physical cells from a Liberty
 file via ABC using the abc pass.
 
 .. toctree::
-   :caption: Gate-level cells
    :maxdepth: 2
 
    /cell/gate_comb_simple

diff --git a/docs/source/cell_word.rst → docs/source/cell/index_word.rst b/docs/source/cell_word.rst → docs/source/cell/index_word.rst
@@ -15,7 +15,6 @@ Simulation models for the RTL cells can be found in the file
 
 .. toctree::
    :maxdepth: 2
-   :glob:
 
    /cell/word_unary
    /cell/word_binary

diff --git a/docs/source/cell/properties.rst b/docs/source/cell/properties.rst
@@ -0,0 +1,18 @@
+Cell properties
+---------------
+
+.. TODO:: Fill :cell:ref:`is_evaluable`
+
+.. cell:defprop:: is_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 ``B=0`` has undefined output.
+
+Refer to the :ref:`propindex` for the list of cells with a given property.
diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst
@@ -6,16 +6,6 @@ Binary operators
 
 .. TODO:: display cell titles
 
-.. todo:: 'x' aware warning
-
-   some passes will treat cell as the non 'x' aware cell, i.e. synthesis; `$eqx`
-   `$nex` `$bweqx`
-
-.. todo:: 'x' output
-
-   shiftx, div, mod, pmux (less-so) can produce 'x' output even if all inputs
-   are defined
-
 All binary RTL cells have two input ports ``A`` and ``B`` and one output port
 ``Y``. They also have the following parameters:
 

diff --git a/docs/source/cell_index.rst b/docs/source/cell_index.rst
@@ -0,0 +1,11 @@
+Internal cell library
+=====================
+
+.. todo:: brief overview of internal cell library
+
+.. toctree::
+   :maxdepth: 2
+
+   /cell/index_word
+   /cell/index_gate
+   /cell/properties
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -50,6 +50,5 @@ available, go to :ref:`commandindex`.
 
    bib
 
-   cell_word
-   cell_gate
+   cell_index
    cmd_ref
diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst
@@ -65,7 +65,7 @@ displayed as rectangles with inputs on the left and outputs on the right side.
 The cell labels are two lines long: The first line contains a unique identifier
 for the cell and the second line contains the cell type. Internal cell types are
 prefixed with a dollar sign. For more details on the internal cell library, see
-:doc:`/cell_gate` and :doc:`/cell_word`.
+:doc:`/cell_index`.
 
 Constants are shown as ellipses with the constant value as label. The syntax
 ``<bit_width>'<bits>`` is used for constants that are not 32-bit wide and/or

diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst
@@ -27,7 +27,7 @@ Constant folding and simple expression rewriting - `opt_expr`
 .. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index`
 
 This pass performs constant folding on the internal combinational cell types
-described in :doc:`/cell_gate` and :doc:`/cell_word`. This means a cell with all
+described in :doc:`/cell_index`. This means a cell with all
 constant inputs is replaced with the constant value this cell drives. In some
 cases this pass can also optimize cells with some constant inputs.