From e40134c856260d610b3ab2f242234e21f4f58ccd Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 6 Sep 2024 15:40:22 +1200 Subject: [PATCH] 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. --- docs/source/appendix/rtlil_text.rst | 4 ++-- .../{cell_gate.rst => cell/index_gate.rst} | 1 - .../{cell_word.rst => cell/index_word.rst} | 1 - docs/source/cell/properties.rst | 18 ++++++++++++++++++ docs/source/cell/word_binary.rst | 10 ---------- docs/source/cell_index.rst | 11 +++++++++++ docs/source/index.rst | 3 +-- .../interactive_investigation.rst | 2 +- docs/source/using_yosys/synthesis/opt.rst | 2 +- 9 files changed, 34 insertions(+), 18 deletions(-) rename docs/source/{cell_gate.rst => cell/index_gate.rst} (96%) rename docs/source/{cell_word.rst => cell/index_word.rst} (98%) create mode 100644 docs/source/cell/properties.rst create mode 100644 docs/source/cell_index.rst diff --git a/docs/source/appendix/rtlil_text.rst b/docs/source/appendix/rtlil_text.rst index 7febae2ed..2c7a82d19 100644 --- 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 b/docs/source/cell/index_gate.rst similarity index 96% rename from docs/source/cell_gate.rst rename to docs/source/cell/index_gate.rst index 4ff38ec5e..c9decc045 100644 --- a/docs/source/cell_gate.rst +++ b/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 b/docs/source/cell/index_word.rst similarity index 98% rename from docs/source/cell_word.rst rename to docs/source/cell/index_word.rst index d52c4c934..cb81c6991 100644 --- a/docs/source/cell_word.rst +++ b/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 new file mode 100644 index 000000000..72ea76112 --- /dev/null +++ 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 index 70b54004e..b0287f2d1 100644 --- 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 new file mode 100644 index 000000000..dcfd38a76 --- /dev/null +++ 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 index fbdd5ac6f..8b9cff869 100644 --- 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 index 68b538076..c6180306d 100644 --- 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 ``'`` 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 index d79a66a75..743b24997 100644 --- 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.