From fd84a3378eee639663005577c0b180b83cbbbd91 Mon Sep 17 00:00:00 2001
From: "Emil J. Tywoniak" <emil@tywoniak.eu>
Date: Thu, 9 May 2024 18:31:18 +0200
Subject: [PATCH] docs: Document $lut and $sop

---
 .../yosys_internals/formats/cell_library.rst  | 44 ++++++++++++++++++-
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst
index 2b8dc300154..69e82774c1f 100644
--- a/docs/source/yosys_internals/formats/cell_library.rst
+++ b/docs/source/yosys_internals/formats/cell_library.rst
@@ -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
 ~~~~~~~~~~~~~
 
@@ -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.