Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Document $lut and $sop #4387

Merged
merged 1 commit into from
May 13, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 42 additions & 2 deletions docs/source/yosys_internals/formats/cell_library.rst
Original file line number Diff line number Diff line change
Expand Up @@ -661,6 +661,48 @@ The CONFIG parameter carries the following information:
B is an array of concatenated 1-bit-wide unsigned integers to also be summed up.

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.

Specify rules
~~~~~~~~~~~~~

Expand Down Expand Up @@ -1192,6 +1234,4 @@ file via ABC using the abc pass.

.. todo:: Add information about ``$slice`` and ``$concat`` cells.

.. todo:: Add information about ``$lut`` and ``$sop`` cells.

.. todo:: Add information about ``$alu``, ``$fa``, and ``$lcu`` cells.