Rst docs conversion (#3496)

Rst docs conversion

1 files changed, 1020 insertions, 0 deletions

diff --git a/docs/source/CHAPTER_CellLib.rst b/docs/source/CHAPTER_CellLib.rst
new file mode 100644
index 000000000..c5db434a6
--- /dev/null
+++ b/docs/source/CHAPTER_CellLib.rst
@@ -0,0 +1,1020 @@
+.. role:: verilog(code)
+	:language: Verilog
+
+.. _chapter:celllib:
+
+Internal cell library
+=====================
+
+Most of the passes in Yosys operate on netlists, i.e. they only care about the
+RTLIL::Wire and RTLIL::Cell objects in an RTLIL::Module. This chapter discusses
+the cell types used by Yosys to represent a behavioural design internally.
+
+This chapter is split in two parts. In the first part the internal RTL cells are
+covered. These cells are used to represent the design on a coarse grain level.
+Like in the original HDL code on this level the cells operate on vectors of
+signals and complex cells like adders exist. In the second part the internal
+gate cells are covered. These cells are used to represent the design on a
+fine-grain gate-level. All cells from this category operate on single bit
+signals.
+
+RTL cells
+---------
+
+Most of the RTL cells closely resemble the operators available in HDLs such as
+Verilog or VHDL. Therefore Verilog operators are used in the following sections
+to define the behaviour of the RTL cells.
+
+Note that all RTL cells have parameters indicating the size of inputs and
+outputs. When passes modify RTL cells they must always keep the values of these
+parameters in sync with the size of the signals connected to the inputs and
+outputs.
+
+Simulation models for the RTL cells can be found in the file
+``techlibs/common/simlib.v`` in the Yosys source tree.
+
+Unary operators
+~~~~~~~~~~~~~~~
+
+All unary RTL cells have one input port ``\A`` 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``.
+
+``\Y_WIDTH``
+	The width of the output port ``\Y``.
+
+:numref:`tab:CellLib_unary` lists all cells for unary RTL operators.
+
+.. table:: Cell types for unary operators with their corresponding Verilog expressions.
+	:name: tab:CellLib_unary
+
+	================== ============
+	Verilog            Cell Type
+	================== ============
+	:verilog:`Y =  ~A` $not
+	:verilog:`Y =  +A` $pos
+	:verilog:`Y =  -A` $neg
+	:verilog:`Y =  &A` $reduce_and
+	:verilog:`Y =  |A` $reduce_or
+	:verilog:`Y =  ^A` $reduce_xor
+	:verilog:`Y = ~^A` $reduce_xnor
+	:verilog:`Y =  |A` $reduce_bool
+	:verilog:`Y =  !A` $logic_not
+	================== ============
+
+For the unary cells that output a logical value (``$reduce_and``,
+``$reduce_or``, ``$reduce_xor``, ``$reduce_xnor``, ``$reduce_bool``,
+``$logic_not``), when the ``\Y_WIDTH`` parameter is greater than 1, the output
+is zero-extended, and only the least significant bit varies.
+
+Note that ``$reduce_or`` and ``$reduce_bool`` actually represent the same logic
+function. But the HDL frontends generate them in different situations. A
+``$reduce_or`` cell is generated when the prefix ``|`` operator is being used. A
+``$reduce_bool`` cell is generated when a bit vector is used as a condition in
+an ``if``-statement or ``?:``-expression.
+
+Binary operators
+~~~~~~~~~~~~~~~~
+
+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``.
+
+:numref:`tab:CellLib_binary` lists all cells for binary RTL operators.
+
+.. table:: Cell types for binary operators with their corresponding Verilog expressions.
+	:name: tab:CellLib_binary
+
+	======================= ============= ======================= =========
+	Verilog 	        Cell Type     Verilog                 Cell Type
+	======================= ============= ======================= =========
+	:verilog:`Y = A  & B`   $and          :verilog:`Y = A <  B`   $lt
+	:verilog:`Y = A  | B`   $or           :verilog:`Y = A <= B`   $le
+	:verilog:`Y = A  ^ B`   $xor          :verilog:`Y = A == B`   $eq
+	:verilog:`Y = A ~^ B`   $xnor         :verilog:`Y = A != B`   $ne
+	:verilog:`Y = A << B`   $shl          :verilog:`Y = A >= B`   $ge
+	:verilog:`Y = A >> B`   $shr          :verilog:`Y = A >  B`   $gt
+	:verilog:`Y = A <<< B`  $sshl         :verilog:`Y = A  + B`   $add
+	:verilog:`Y = A >>> B`  $sshr         :verilog:`Y = A  - B`   $sub
+	:verilog:`Y = A && B`   $logic_and    :verilog:`Y = A  * B`   $mul
+	:verilog:`Y = A || B`   $logic_or     :verilog:`Y = A  / B`   $div
+	:verilog:`Y = A === B`  $eqx          :verilog:`Y = A  % B`   $mod 
+	:verilog:`Y = A !== B`  $nex          ``N/A``                 $divfloor
+	:verilog:`Y = A ** B`   $pow          ``N/A``                 $modfoor
+	======================= ============= ======================= =========
+
+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
+:numref:`tab:CellLib_divmod` for a side-by-side comparison between the different
+semantics.
+
+.. table:: Comparison between different rounding modes for division and modulo cells.
+	:name: tab:CellLib_divmod
+
+	+-----------+--------+-----------+-----------+-----------+-----------+
+	| 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        |
+	+-----------+--------+-----------+-----------+-----------+-----------+
+
+Multiplexers
+~~~~~~~~~~~~
+
+Multiplexers are generated by the Verilog HDL frontend for ``?:``-expressions.
+Multiplexers are also generated by the proc pass to map the decision trees from
+RTLIL::Process objects to logic.
+
+The simplest multiplexer cell type is ``$mux``. Cells of this type have a
+``\WITDH`` parameter and data inputs ``\A`` and ``\B`` and a data output ``\Y``,
+all of the specified width. This cell also has a single bit control input
+``\S``. If ``\S`` is 0 the value from the input ``\A`` is sent to the output, if
+it is 1 the value from the ``\B`` input is sent to the output. So the ``$mux``
+cell implements the function :verilog:`Y = S ? B : A`.
+
+The ``$pmux`` cell is used to multiplex between many inputs using a one-hot
+select signal. Cells of this type have a ``\WIDTH`` and a ``\S_WIDTH`` parameter
+and inputs ``\A``, ``\B``, and ``\S`` and an output ``\Y``. The ``\S`` input is
+``\S_WIDTH`` bits wide. The ``\A`` input and the output are both ``\WIDTH`` bits
+wide and the ``\B`` input is ``\WIDTH*\S_WIDTH`` bits wide. When all bits of
+``\S`` are zero, the value from ``\A`` input is sent to the output. If the
+:math:`n`\ 'th bit from ``\S`` is set, the value :math:`n`\ 'th ``\WIDTH`` bits
+wide slice of the ``\B`` input is sent to the output. When more than one bit
+from ``\S`` is set the output is undefined. Cells of this type are used to model
+"parallel cases" (defined by using the ``parallel_case`` attribute or detected
+by an optimization).
+
+The ``$tribuf`` cell is used to implement tristate logic. Cells of this type
+have a ``\B`` parameter and inputs ``\A`` and ``\EN`` and an output ``\Y``. The
+``\A`` input and ``\Y`` output are ``\WIDTH`` bits wide, and the ``\EN`` input
+is one bit wide. When ``\EN`` is 0, the output is not driven. When ``\EN`` is 1,
+the value from ``\A`` input is sent to the ``\Y`` output. Therefore, the
+``$tribuf`` cell implements the function :verilog:`Y = EN ? A : 'bz`.
+
+Behavioural code with cascaded if-then-else- and case-statements usually results
+in trees of multiplexer cells. Many passes (from various optimizations to FSM
+extraction) heavily depend on these multiplexer trees to understand dependencies
+between signals. Therefore optimizations should not break these multiplexer
+trees (e.g. by replacing a multiplexer between a calculated signal and a
+constant zero with an ``$and`` gate).
+
+Registers
+~~~~~~~~~
+
+SR-type latches are represented by ``$sr`` cells. These cells have input ports
+``\SET`` and ``\CLR`` and an output port ``\Q``. They have the following
+parameters:
+
+``\WIDTH``
+	The width of inputs ``\SET`` and ``\CLR`` and output ``\Q``.
+
+``\SET_POLARITY``
+	The set input bits are active-high if this parameter has the value
+	``1'b1`` and active-low if this parameter is ``1'b0``.
+
+``\CLR_POLARITY``
+	The reset input bits are active-high if this parameter has the value
+	``1'b1`` and active-low if this parameter is ``1'b0``.
+
+Both set and reset inputs have separate bits for every output bit. When both the
+set and reset inputs of an ``$sr`` cell are active for a given bit index, the
+reset input takes precedence.
+
+D-type flip-flops are represented by ``$dff`` cells. These cells have a clock
+port ``\CLK``, an input port ``\D`` and an output port ``\Q``. The following
+parameters are available for ``$dff`` cells:
+
+``\WIDTH``
+	The width of input ``\D`` and output ``\Q``.
+
+``\CLK_POLARITY``
+	Clock is active on the positive edge if this parameter has the value
+	``1'b1`` and on the negative edge if this parameter is ``1'b0``.
+
+D-type flip-flops with asynchronous reset are represented by ``$adff`` cells. As
+the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they
+also have a single-bit ``\ARST`` input port for the reset pin and the following
+additional two parameters:
+
+``\ARST_POLARITY``
+	The asynchronous reset is active-high if this parameter has the value
+	``1'b1`` and active-low if this parameter is ``1'b0``.
+
+``\ARST_VALUE``
+   	The state of ``\Q`` will be set to this value when the reset is active.
+
+Usually these cells are generated by the ``proc`` pass using the information in
+the designs RTLIL::Process objects.
+
+D-type flip-flops with synchronous reset are represented by ``$sdff`` cells. As
+the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they
+also have a single-bit ``\SRST`` input port for the reset pin and the following
+additional two parameters:
+
+``\SRST_POLARITY``
+	The synchronous reset is active-high if this parameter has the value
+	``1'b1`` and active-low if this parameter is ``1'b0``.
+
+``\SRST_VALUE``
+	The state of ``\Q`` will be set to this value when the reset is active.
+
+Note that the ``$adff`` and ``$sdff`` cells can only be used when the reset value is
+constant.
+
+D-type flip-flops with asynchronous load are represented by ``$aldff`` cells. As
+the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they
+also have a single-bit ``\ALOAD`` input port for the async load enable pin, a
+``\AD`` input port with the same width as data for the async load data, and the
+following additional parameter:
+
+``\ALOAD_POLARITY``
+	The asynchronous load is active-high if this parameter has the value
+	``1'b1`` and active-low if this parameter is ``1'b0``.
+
+D-type flip-flops with asynchronous set and reset are represented by ``$dffsr``
+cells. As the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In
+addition they also have multi-bit ``\SET`` and ``\CLR`` input ports and the
+corresponding polarity parameters, like ``$sr`` cells.
+
+D-type flip-flops with enable are represented by ``$dffe``, ``$adffe``,
+``$aldffe``, ``$dffsre``, ``$sdffe``, and ``$sdffce`` cells, which are enhanced
+variants of ``$dff``, ``$adff``, ``$aldff``, ``$dffsr``, ``$sdff`` (with reset
+over enable) and ``$sdff`` (with enable over reset) cells, respectively.  They
+have the same ports and parameters as their base cell. In addition they also
+have a single-bit ``\EN`` input port for the enable pin and the following
+parameter:
+
+``\EN_POLARITY``
+	The enable input is active-high if this parameter has the value ``1'b1``
+	and active-low if this parameter is ``1'b0``.
+
+D-type latches are represented by ``$dlatch`` cells.  These cells have an enable
+port ``\EN``, an input port ``\D``, and an output port ``\Q``.  The following
+parameters are available for ``$dlatch`` cells:
+
+``\WIDTH``
+	The width of input ``\D`` and output ``\Q``.
+
+``\EN_POLARITY``
+	The enable input is active-high if this parameter has the value ``1'b1``
+	and active-low if this parameter is ``1'b0``.
+
+The latch is transparent when the ``\EN`` input is active.
+
+D-type latches with reset are represented by ``$adlatch`` cells.  In addition to
+``$dlatch`` ports and parameters, they also have a single-bit ``\ARST`` input
+port for the reset pin and the following additional parameters:
+
+``\ARST_POLARITY``
+	The asynchronous reset is active-high if this parameter has the value
+	``1'b1`` and active-low if this parameter is ``1'b0``.
+
+``\ARST_VALUE``
+	The state of ``\Q`` will be set to this value when the reset is active.
+
+D-type latches with set and reset are represented by ``$dlatchsr`` cells. In
+addition to ``$dlatch`` ports and parameters, they also have multi-bit ``\SET``
+and ``\CLR`` input ports and the corresponding polarity parameters, like ``$sr``
+cells.
+
+.. _sec:memcells:
+
+Memories
+~~~~~~~~
+
+Memories are either represented using RTLIL::Memory objects, ``$memrd_v2``,
+``$memwr_v2``, and ``$meminit_v2`` cells, or by ``$mem_v2`` cells alone.
+
+In the first alternative the RTLIL::Memory objects hold the general metadata for
+the memory (bit width, size in number of words, etc.) and for each port a
+``$memrd_v2`` (read port) or ``$memwr_v2`` (write port) cell is created. Having
+individual cells for read and write ports has the advantage that they can be
+consolidated using resource sharing passes. In some cases this drastically
+reduces the number of required ports on the memory cell. In this alternative,
+memory initialization data is represented by ``$meminit_v2`` cells, which allow
+delaying constant folding for initialization addresses and data until after the
+frontend finishes.
+
+The ``$memrd_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``, an
+address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input
+``\ARST``, and a synchronous reset input ``\SRST``. They also have the following
+parameters:
+
+``\MEMID``
+	The name of the RTLIL::Memory object that is associated with this read
+	port.
+
+``\ABITS``
+	The number of address bits (width of the ``\ADDR`` input port).
+
+``\WIDTH``
+	The number of data bits (width of the ``\DATA`` output port).  Note that
+	this may be a power-of-two multiple of the underlying memory's width --
+	such ports are called wide ports and access an aligned group of cells at
+	once.  In this case, the corresponding low bits of ``\ADDR`` must be
+	tied to 0.
+
+``\CLK_ENABLE``
+	When this parameter is non-zero, the clock is used. Otherwise this read
+	port is asynchronous and the ``\CLK`` input is not used.
+
+``\CLK_POLARITY``
+	Clock is active on the positive edge if this parameter has the value
+	``1'b1`` and on the negative edge if this parameter is ``1'b0``.
+
+``\TRANSPARENCY_MASK``
+	This parameter is a bitmask of write ports that this read port is
+	transparent with. The bits of this parameter are indexed by the write
+	port's ``\PORTID`` parameter. Transparency can only be enabled between
+	synchronous ports sharing a clock domain. When transparency is enabled
+	for a given port pair, a read and write to the same address in the same
+	cycle will return the new value. Otherwise the old value is returned.
+
+``\COLLISION_X_MASK``
+	This parameter is a bitmask of write ports that have undefined collision
+	behavior with this port. The bits of this parameter are indexed by the
+	write port's ``\PORTID`` parameter. This behavior can only be enabled
+	between synchronous ports sharing a clock domain. When undefined
+	collision is enabled for a given port pair, a read and write to the same
+	address in the same cycle will return the undefined (all-X) value.This
+	option is exclusive (for a given port pair) with the transparency
+	option.
+
+``\ARST_VALUE``
+	Whenever the ``\ARST`` input is asserted, the data output will be reset
+	to this value. Only used for synchronous ports.
+
+``\SRST_VALUE``
+	Whenever the ``\SRST`` input is synchronously asserted, the data output
+	will be reset to this value. Only used for synchronous ports.
+
+``\INIT_VALUE``
+	The initial value of the data output, for synchronous ports.
+
+``\CE_OVER_SRST``
+	If this parameter is non-zero, the ``\SRST`` input is only recognized
+	when ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of
+	``\EN``.
+
+The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``
+(one enable bit for each data bit), an address input ``\ADDR`` and a data input
+``\DATA``. They also have the following parameters:
+
+``\MEMID``
+	The name of the RTLIL::Memory object that is associated with this write
+	port.
+
+``\ABITS``
+	The number of address bits (width of the ``\ADDR`` input port).
+
+``\WIDTH``
+	The number of data bits (width of the ``\DATA`` output port). Like with
+	``$memrd_v2`` cells, the width is allowed to be any power-of-two
+	multiple of memory width, with the corresponding restriction on address.
+
+``\CLK_ENABLE``
+	When this parameter is non-zero, the clock is used. Otherwise this write
+	port is asynchronous and the ``\CLK`` input is not used.
+
+``\CLK_POLARITY``
+	Clock is active on positive edge if this parameter has the value
+	``1'b1`` and on the negative edge if this parameter is ``1'b0``.
+
+``\PORTID``
+	An identifier for this write port, used to index write port bit mask parameters.
+
+``\PRIORITY_MASK``
+	This parameter is a bitmask of write ports that this write port has
+	priority over in case of writing to the same address.  The bits of this
+	parameter are indexed by the other write port's ``\PORTID`` parameter.
+	Write ports can only have priority over write ports with lower port ID.
+	When two ports write to the same address and neither has priority over
+	the other, the result is undefined.  Priority can only be set between
+	two synchronous ports sharing the same clock domain.
+
+The ``$meminit_v2`` cells have an address input ``\ADDR``, a data input
+``\DATA``, with the width of the ``\DATA`` port equal to ``\WIDTH`` parameter
+times ``\WORDS`` parameter, and a bit enable mask input ``\EN`` with width equal
+to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for
+synthesis to succeed.
+
+``\MEMID``
+	The name of the RTLIL::Memory object that is associated with this
+	initialization cell.
+
+``\ABITS``
+	The number of address bits (width of the ``\ADDR`` input port).
+
+``\WIDTH``
+	The number of data bits per memory location.
+
+``\WORDS``
+	The number of consecutive memory locations initialized by this cell.
+
+``\PRIORITY``
+	The cell with the higher integer value in this parameter wins an
+	initialization conflict.
+
+The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
+``$memrd_v2`` and ``$memwr_v2`` cells. The ``memory`` pass (i.e.~its various
+sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and ``$memwr_v2``
+cells making them synchronous, then converts them to a single ``$mem_v2`` cell
+and (optionally) maps this cell type to ``$dff`` cells for the individual words
+and multiplexer-based address decoders for the read and write interfaces. When
+the last step is disabled or not possible, a ``$mem_v2`` cell is left in the
+design.
+
+The ``$mem_v2`` cell provides the following parameters:
+
+``\MEMID``
+	The name of the original RTLIL::Memory object that became this
+	``$mem_v2`` cell.
+
+``\SIZE``
+	The number of words in the memory.
+
+``\ABITS``
+	The number of address bits.
+
+``\WIDTH``
+	The number of data bits per word.
+
+``\INIT``
+	The initial memory contents.
+
+``\RD_PORTS``
+	The number of read ports on this memory cell.
+
+``\RD_WIDE_CONTINUATION``
+	This parameter is ``\RD_PORTS`` bits wide, containing a bitmask of
+	"wide continuation" read ports. Such ports are used to represent the
+	extra data bits of wide ports in the combined cell, and must have all
+	control signals identical with the preceding port, except for address,
+	which must have the proper sub-cell address encoded in the low bits.
+
+``\RD_CLK_ENABLE``
+	This parameter is ``\RD_PORTS`` bits wide, containing a clock enable bit
+	for each read port.
+
+``\RD_CLK_POLARITY``
+	This parameter is ``\RD_PORTS`` bits wide, containing a clock polarity
+	bit for each read port.
+
+``\RD_TRANSPARENCY_MASK``
+	This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a
+	concatenation of all ``\TRANSPARENCY_MASK`` values of the original
+	``$memrd_v2`` cells.
+
+``\RD_COLLISION_X_MASK``
+	This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a
+	concatenation of all ``\COLLISION_X_MASK`` values of the original
+	``$memrd_v2`` cells.
+
+``\RD_CE_OVER_SRST``
+	This parameter is ``\RD_PORTS`` bits wide, determining relative
+	synchronous reset and enable priority for each read port.
+
+``\RD_INIT_VALUE``
+	This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the initial
+	value for each synchronous read port.
+
+``\RD_ARST_VALUE``
+	This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the
+	asynchronous reset value for each synchronous read port.
+
+``\RD_SRST_VALUE``
+	This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the
+	synchronous reset value for each synchronous read port.
+
+``\WR_PORTS``
+	The number of write ports on this memory cell.
+
+``\WR_WIDE_CONTINUATION``
+	This parameter is ``\WR_PORTS`` bits wide, containing a bitmask of
+	"wide continuation" write ports.
+
+``\WR_CLK_ENABLE``
+	This parameter is ``\WR_PORTS`` bits wide, containing a clock enable bit
+	for each write port.
+
+``\WR_CLK_POLARITY``
+	This parameter is ``\WR_PORTS`` bits wide, containing a clock polarity
+	bit for each write port.
+
+``\WR_PRIORITY_MASK``
+	This parameter is ``\WR_PORTS*\WR_PORTS`` bits wide, containing a
+	concatenation of all ``\PRIORITY_MASK`` values of the original
+	``$memwr_v2`` cells.
+
+The ``$mem_v2`` cell has the following ports:
+
+``\RD_CLK``
+	This input is ``\RD_PORTS`` bits wide, containing all clock signals for
+	the read ports.
+
+``\RD_EN``
+	This input is ``\RD_PORTS`` bits wide, containing all enable signals for
+	the read ports.
+
+``\RD_ADDR``
+	This input is ``\RD_PORTS*\ABITS`` bits wide, containing all address
+	signals for the read ports.
+
+``\RD_DATA``
+	This input is ``\RD_PORTS*\WIDTH`` bits wide, containing all data
+	signals for the read ports.
+
+``\RD_ARST``
+	This input is ``\RD_PORTS`` bits wide, containing all asynchronous reset
+	signals for the read ports.
+
+``\RD_SRST``
+	This input is ``\RD_PORTS`` bits wide, containing all synchronous reset
+	signals for the read ports.
+
+``\WR_CLK``
+	This input is ``\WR_PORTS`` bits wide, containing all clock signals for
+	the write ports.
+
+``\WR_EN``
+	This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all enable
+	signals for the write ports.
+
+``\WR_ADDR``
+	This input is ``\WR_PORTS*\ABITS`` bits wide, containing all address
+	signals for the write ports.
+
+``\WR_DATA``
+	This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data
+	signals for the write ports.
+
+The ``memory_collect`` pass can be used to convert discrete ``$memrd_v2``,
+``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same memory to a
+single ``$mem_v2`` cell, whereas the ``memory_unpack`` pass performs the inverse
+operation. The ``memory_dff`` pass can combine asynchronous memory ports that
+are fed by or feeding registers into synchronous memory ports. The
+``memory_bram`` pass can be used to recognize ``$mem_v2`` cells that can be
+implemented with a block RAM resource on an FPGA. The ``memory_map`` pass can be
+used to implement ``$mem_v2`` cells as basic logic: word-wide DFFs and address
+decoders.
+
+Finite state machines
+~~~~~~~~~~~~~~~~~~~~~
+
+Add a brief description of the ``$fsm`` cell type.
+
+Specify rules
+~~~~~~~~~~~~~
+
+Add information about ``$specify2``, ``$specify3``, and ``$specrule`` cells.
+
+Formal verification cells
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add information about ``$assert``, ``$assume``, ``$live``, ``$fair``,
+``$cover``, ``$equiv``, ``$initstate``, ``$anyconst``, ``$anyseq``,
+``$anyinit``, ``$allconst``, ``$allseq`` cells.
+
+Add information about ``$ff`` and ``$_FF_`` cells.
+
+.. _sec:celllib_gates:
+
+Gates
+-----
+
+For gate level logic networks, fixed function single bit cells are used that do
+not provide any parameters.
+
+Simulation models for these cells can be found in the file
+techlibs/common/simcells.v in the Yosys source tree.
+
+.. table:: Cell types for gate level logic networks (main list)
+	:name: tab:CellLib_gates
+
+	======================================= ============
+	Verilog                                 Cell Type
+	======================================= ============
+	:verilog:`Y = A`                        $_BUF_
+	:verilog:`Y = ~A`                       $_NOT_
+	:verilog:`Y = A & B`                    $_AND_
+	:verilog:`Y = ~(A & B)`                 $_NAND_
+	:verilog:`Y = A & ~B`                   $_ANDNOT_
+	:verilog:`Y = A | B`                    $_OR_
+	:verilog:`Y = ~(A | B)`                 $_NOR_
+	:verilog:`Y = A | ~B`                   $_ORNOT_
+	:verilog:`Y = A ^ B`                    $_XOR_
+	:verilog:`Y = ~(A ^ B)`                 $_XNOR_
+	:verilog:`Y = ~((A & B) | C)`           $_AOI3_
+	:verilog:`Y = ~((A | B) & C)`           $_OAI3_
+	:verilog:`Y = ~((A & B) | (C & D))`     $_AOI4_
+	:verilog:`Y = ~((A | B) & (C | D))`     $_OAI4_
+	:verilog:`Y = S ? B : A`                $_MUX_
+	:verilog:`Y = ~(S ? B : A)`             $_NMUX_
+	(see below)                             $_MUX4_
+	(see below)                             $_MUX8_
+	(see below)                             $_MUX16_
+	:verilog:`Y = EN ? A : 1'bz`            $_TBUF_
+	:verilog:`always @(negedge C) Q <= D`   $_DFF_N_
+	:verilog:`always @(posedge C) Q <= D`   $_DFF_P_
+	:verilog:`always @* if (!E) Q <= D`     $_DLATCH_N_
+	:verilog:`always @* if (E)  Q <= D`     $_DLATCH_P_
+	======================================= ============
+
+.. table:: Cell types for gate level logic networks (FFs with reset)
+	:name: tab:CellLib_gates_adff
+
+	================== ============== ============== =======================
+	:math:`ClkEdge`    :math:`RstLvl` :math:`RstVal` Cell Type
+	================== ============== ============== =======================
+	:verilog:`negedge` ``0``          ``0``          $_DFF_NN0_, $_SDFF_NN0_
+	:verilog:`negedge` ``0``          ``1``          $_DFF_NN1_, $_SDFF_NN1_
+	:verilog:`negedge` ``1``          ``0``          $_DFF_NP0_, $_SDFF_NP0_
+	:verilog:`negedge` ``1``          ``1``          $_DFF_NP1_, $_SDFF_NP1_
+	:verilog:`posedge` ``0``          ``0``          $_DFF_PN0_, $_SDFF_PN0_
+	:verilog:`posedge` ``0``          ``1``          $_DFF_PN1_, $_SDFF_PN1_
+	:verilog:`posedge` ``1``          ``0``          $_DFF_PP0_, $_SDFF_PP0_
+	:verilog:`posedge` ``1``          ``1``          $_DFF_PP1_, $_SDFF_PP1_
+	================== ============== ============== =======================
+
+
+.. table:: Cell types for gate level logic networks (FFs with enable)
+	:name: tab:CellLib_gates_dffe
+
+	================== ============= ===========
+	:math:`ClkEdge`    :math:`EnLvl` Cell Type
+	================== ============= ===========
+	:verilog:`negedge` ``0``         $_DFFE_NN_
+	:verilog:`negedge` ``1``         $_DFFE_NP_
+	:verilog:`posedge` ``0``         $_DFFE_PN_
+	:verilog:`posedge` ``1``         $_DFFE_PP_
+	================== ============= ===========
+
+
+.. table:: Cell types for gate level logic networks (FFs with reset and enable)
+	:name: tab:CellLib_gates_adffe
+
+	================== ============== ============== ============= ===========================================
+	:math:`ClkEdge`    :math:`RstLvl` :math:`RstVal` :math:`EnLvl` Cell Type
+	================== ============== ============== ============= ===========================================
+	:verilog:`negedge` ``0``          ``0``          ``0``         $_DFFE_NN0N_, $_SDFFE_NN0N_, $_SDFFCE_NN0N_
+	:verilog:`negedge` ``0``          ``0``          ``1``         $_DFFE_NN0P_, $_SDFFE_NN0P_, $_SDFFCE_NN0P_
+	:verilog:`negedge` ``0``          ``1``          ``0``         $_DFFE_NN1N_, $_SDFFE_NN1N_, $_SDFFCE_NN1N_
+	:verilog:`negedge` ``0``          ``1``          ``1``         $_DFFE_NN1P_, $_SDFFE_NN1P_, $_SDFFCE_NN1P_
+	:verilog:`negedge` ``1``          ``0``          ``0``         $_DFFE_NP0N_, $_SDFFE_NP0N_, $_SDFFCE_NP0N_
+	:verilog:`negedge` ``1``          ``0``          ``1``         $_DFFE_NP0P_, $_SDFFE_NP0P_, $_SDFFCE_NP0P_
+	:verilog:`negedge` ``1``          ``1``          ``0``         $_DFFE_NP1N_, $_SDFFE_NP1N_, $_SDFFCE_NP1N_
+	:verilog:`negedge` ``1``          ``1``          ``1``         $_DFFE_NP1P_, $_SDFFE_NP1P_, $_SDFFCE_NP1P_
+	:verilog:`posedge` ``0``          ``0``          ``0``         $_DFFE_PN0N_, $_SDFFE_PN0N_, $_SDFFCE_PN0N_
+	:verilog:`posedge` ``0``          ``0``          ``1``         $_DFFE_PN0P_, $_SDFFE_PN0P_, $_SDFFCE_PN0P_
+	:verilog:`posedge` ``0``          ``1``          ``0``         $_DFFE_PN1N_, $_SDFFE_PN1N_, $_SDFFCE_PN1N_
+	:verilog:`posedge` ``0``          ``1``          ``1``         $_DFFE_PN1P_, $_SDFFE_PN1P_, $_SDFFCE_PN1P_
+	:verilog:`posedge` ``1``          ``0``          ``0``         $_DFFE_PP0N_, $_SDFFE_PP0N_, $_SDFFCE_PP0N_
+	:verilog:`posedge` ``1``          ``0``          ``1``         $_DFFE_PP0P_, $_SDFFE_PP0P_, $_SDFFCE_PP0P_
+	:verilog:`posedge` ``1``          ``1``          ``0``         $_DFFE_PP1N_, $_SDFFE_PP1N_, $_SDFFCE_PP1N_
+	:verilog:`posedge` ``1``          ``1``          ``1``         $_DFFE_PP1P_, $_SDFFE_PP1P_, $_SDFFCE_PP1P_
+	================== ============== ============== ============= ===========================================
+
+.. table:: Cell types for gate level logic networks (FFs with set and reset)
+	:name: tab:CellLib_gates_dffsr
+
+	================== ============== ============== ============
+	:math:`ClkEdge`    :math:`SetLvl` :math:`RstLvl` Cell Type
+	================== ============== ============== ============
+	:verilog:`negedge` ``0``          ``0``          $_DFFSR_NNN_
+	:verilog:`negedge` ``0``          ``1``          $_DFFSR_NNP_
+	:verilog:`negedge` ``1``          ``0``          $_DFFSR_NPN_
+	:verilog:`negedge` ``1``          ``1``          $_DFFSR_NPP_
+	:verilog:`posedge` ``0``          ``0``          $_DFFSR_PNN_
+	:verilog:`posedge` ``0``          ``1``          $_DFFSR_PNP_
+	:verilog:`posedge` ``1``          ``0``          $_DFFSR_PPN_
+	:verilog:`posedge` ``1``          ``1``          $_DFFSR_PPP_
+	================== ============== ============== ============
+
+
+.. table:: Cell types for gate level logic networks (FFs with set and reset and enable)
+	:name: tab:CellLib_gates_dffsre
+
+	================== ============== ============== ============= ==============
+	:math:`ClkEdge`    :math:`SetLvl` :math:`RstLvl` :math:`EnLvl` Cell Type
+	================== ============== ============== ============= ==============
+	:verilog:`negedge` ``0``          ``0``          ``0``         $_DFFSRE_NNNN_
+	:verilog:`negedge` ``0``          ``0``          ``1``         $_DFFSRE_NNNP_
+	:verilog:`negedge` ``0``          ``1``          ``0``         $_DFFSRE_NNPN_
+	:verilog:`negedge` ``0``          ``1``          ``1``         $_DFFSRE_NNPP_
+	:verilog:`negedge` ``1``          ``0``          ``0``         $_DFFSRE_NPNN_
+	:verilog:`negedge` ``1``          ``0``          ``1``         $_DFFSRE_NPNP_
+	:verilog:`negedge` ``1``          ``1``          ``0``         $_DFFSRE_NPPN_
+	:verilog:`negedge` ``1``          ``1``          ``1``         $_DFFSRE_NPPP_
+	:verilog:`posedge` ``0``          ``0``          ``0``         $_DFFSRE_PNNN_
+	:verilog:`posedge` ``0``          ``0``          ``1``         $_DFFSRE_PNNP_
+	:verilog:`posedge` ``0``          ``1``          ``0``         $_DFFSRE_PNPN_
+	:verilog:`posedge` ``0``          ``1``          ``1``         $_DFFSRE_PNPP_
+	:verilog:`posedge` ``1``          ``0``          ``0``         $_DFFSRE_PPNN_
+	:verilog:`posedge` ``1``          ``0``          ``1``         $_DFFSRE_PPNP_
+	:verilog:`posedge` ``1``          ``1``          ``0``         $_DFFSRE_PPPN_
+	:verilog:`posedge` ``1``          ``1``          ``1``         $_DFFSRE_PPPP_
+	================== ============== ============== ============= ==============
+
+
+.. table:: Cell types for gate level logic networks (latches with reset)
+	:name: tab:CellLib_gates_adlatch
+
+	============= ============== ============== =============
+	:math:`EnLvl` :math:`RstLvl` :math:`RstVal` Cell Type
+	============= ============== ============== =============
+	``0``         ``0``          ``0``          $_DLATCH_NN0_
+	``0``         ``0``          ``1``          $_DLATCH_NN1_
+	``0``         ``1``          ``0``          $_DLATCH_NP0_
+	``0``         ``1``          ``1``          $_DLATCH_NP1_
+	``1``         ``0``          ``0``          $_DLATCH_PN0_
+	``1``         ``0``          ``1``          $_DLATCH_PN1_
+	``1``         ``1``          ``0``          $_DLATCH_PP0_
+	``1``         ``1``          ``1``          $_DLATCH_PP1_
+	============= ============== ============== =============
+
+
+.. table:: Cell types for gate level logic networks (latches with set and reset)
+	:name: tab:CellLib_gates_dlatchsr
+
+	============= ============== ============== ===============
+	:math:`EnLvl` :math:`SetLvl` :math:`RstLvl` Cell Type
+	============= ============== ============== ===============
+	``0``         ``0``          ``0``          $_DLATCHSR_NNN_
+	``0``         ``0``          ``1``          $_DLATCHSR_NNP_
+	``0``         ``1``          ``0``          $_DLATCHSR_NPN_
+	``0``         ``1``          ``1``          $_DLATCHSR_NPP_
+	``1``         ``0``          ``0``          $_DLATCHSR_PNN_
+	``1``         ``0``          ``1``          $_DLATCHSR_PNP_
+	``1``         ``1``          ``0``          $_DLATCHSR_PPN_
+	``1``         ``1``          ``1``          $_DLATCHSR_PPP_
+	============= ============== ============== ===============
+
+
+
+.. table:: Cell types for gate level logic networks (SR latches)
+	:name: tab:CellLib_gates_sr
+
+	============== ============== =========
+	:math:`SetLvl` :math:`RstLvl` Cell Type
+	============== ============== =========
+	``0``          ``0``          $_SR_NN_
+	``0``          ``1``          $_SR_NP_
+	``1``          ``0``          $_SR_PN_
+	``1``          ``1``          $_SR_PP_
+	============== ============== =========
+
+
+Tables \ :numref:`%s <tab:CellLib_gates>`, :numref:`%s
+<tab:CellLib_gates_dffe>`, :numref:`%s <tab:CellLib_gates_adff>`, :numref:`%s
+<tab:CellLib_gates_adffe>`, :numref:`%s <tab:CellLib_gates_dffsr>`, :numref:`%s
+<tab:CellLib_gates_dffsre>`, :numref:`%s <tab:CellLib_gates_adlatch>`,
+:numref:`%s <tab:CellLib_gates_dlatchsr>` and :numref:`%s
+<tab:CellLib_gates_sr>` list all cell types used for gate level logic. The cell
+types ``$_BUF_``, ``$_NOT_``, ``$_AND_``, ``$_NAND_``, ``$_ANDNOT_``, ``$_OR_``,
+``$_NOR_``, ``$_ORNOT_``, ``$_XOR_``, ``$_XNOR_``, ``$_AOI3_``, ``$_OAI3_``,
+``$_AOI4_``, ``$_OAI4_``, ``$_MUX_``, ``$_MUX4_``, ``$_MUX8_``, ``$_MUX16_`` and
+``$_NMUX_`` are used to model combinatorial logic. The cell type ``$_TBUF_`` is
+used to model tristate logic.
+
+The ``$_MUX4_``, ``$_MUX8_`` and ``$_MUX16_`` cells are used to model wide
+muxes, and correspond to the following Verilog code:
+
+.. code-block:: verilog
+	:force:
+
+	// $_MUX4_
+	assign Y = T ? (S ? D : C) :
+	               (S ? B : A);
+	// $_MUX8_
+	assign Y = U ? T ? (S ? H : G) :
+	                   (S ? F : E) :
+	               T ? (S ? D : C) :
+	                   (S ? B : A);
+	// $_MUX16_
+	assign Y = V ? U ? T ? (S ? P : O) :
+	                       (S ? N : M) :
+	                   T ? (S ? L : K) :
+	                       (S ? J : I) :
+	               U ? T ? (S ? H : G) :
+	                       (S ? F : E) :
+	                   T ? (S ? D : C) :
+	                       (S ? B : A);
+
+The cell types ``$_DFF_N_`` and ``$_DFF_P_`` represent d-type flip-flops.
+
+The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The
+values in the table for these cell types relate to the following Verilog code
+template.
+
+.. code-block:: verilog
+	:force:
+
+	always @(CLK_EDGE C)
+		if (EN == EN_LVL)
+			Q <= D;
+
+The cell types ``$_DFF_[NP][NP][01]_`` implement d-type flip-flops with
+asynchronous reset. The values in the table for these cell types relate to the
+following Verilog code template, where ``RST_EDGE`` is ``posedge`` if
+``RST_LVL`` if ``1``, and ``negedge`` otherwise.
+
+.. code-block:: verilog
+	:force:
+
+	always @(CLK_EDGE C, RST_EDGE R)
+		if (R == RST_LVL)
+			Q <= RST_VAL;
+		else
+			Q <= D;
+
+The cell types ``$_SDFF_[NP][NP][01]_`` implement d-type flip-flops with
+synchronous reset. The values in the table for these cell types relate to the
+following Verilog code template:
+
+.. code-block:: verilog
+	:force:
+
+	always @(CLK_EDGE C)
+		if (R == RST_LVL)
+			Q <= RST_VAL;
+		else
+			Q <= D;
+
+The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with
+asynchronous reset and enable. The values in the table for these cell types
+relate to the following Verilog code template, where ``RST_EDGE`` is
+``posedge`` if ``RST_LVL`` if ``1``, and ``negedge`` otherwise.
+
+.. code-block:: verilog
+	:force:
+
+	always @(CLK_EDGE C, RST_EDGE R)
+		if (R == RST_LVL)
+			Q <= RST_VAL;
+		else if (EN == EN_LVL)
+			Q <= D;
+
+The cell types ``$_SDFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with
+synchronous reset and enable, with reset having priority over enable. The values
+in the table for these cell types relate to the following Verilog code template:
+
+.. code-block:: verilog
+	:force:
+
+	always @(CLK_EDGE C)
+		if (R == RST_LVL)
+			Q <= RST_VAL;
+		else if (EN == EN_LVL)
+			Q <= D;
+
+The cell types ``$_SDFFCE_[NP][NP][01][NP]_`` implement d-type flip-flops with
+synchronous reset and enable, with enable having priority over reset. The values
+in the table for these cell types relate to the following Verilog code template:
+
+.. code-block:: verilog
+	:force:
+
+	always @(CLK_EDGE C)
+		if (EN == EN_LVL)
+			if (R == RST_LVL)
+				Q <= RST_VAL;
+			else
+				Q <= D;
+
+The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with
+asynchronous set and reset. The values in the table for these cell types relate
+to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if
+``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge``
+if ``SET_LVL`` if ``1``, ``negedge`` otherwise.
+
+.. code-block:: verilog
+	:force:
+
+	always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S)
+		if (R == RST_LVL)
+			Q <= 0;
+		else if (S == SET_LVL)
+			Q <= 1;
+		else
+			Q <= D;
+
+The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with
+asynchronous set and reset and enable. The values in the table for these cell
+types relate to the following Verilog code template, where ``RST_EDGE`` is
+``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE``
+is ``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise.
+
+.. code-block:: verilog
+	:force:
+
+	always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S)
+		if (R == RST_LVL)
+			Q <= 0;
+		else if (S == SET_LVL)
+			Q <= 1;
+		else if (E == EN_LVL)
+			Q <= D;
+
+The cell types ``$_DLATCH_N_`` and ``$_DLATCH_P_`` represent d-type latches.
+
+The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset.
+The values in the table for these cell types relate to the following Verilog
+code template:
+
+.. code-block:: verilog
+	:force:
+
+	always @*
+		if (R == RST_LVL)
+			Q <= RST_VAL;
+		else if (E == EN_LVL)
+			Q <= D;
+
+The cell types ``$_DLATCHSR_[NP][NP][NP]_`` implement d-type latches with set
+and reset. The values in the table for these cell types relate to the following
+Verilog code template:
+
+.. code-block:: verilog
+	:force:
+
+	always @*
+		if (R == RST_LVL)
+			Q <= 0;
+		else if (S == SET_LVL)
+			Q <= 1;
+		else if (E == EN_LVL)
+			Q <= D;
+
+The cell types ``$_SR_[NP][NP]_`` implement sr-type latches. The values in the
+table for these cell types relate to the following Verilog code template:
+
+.. code-block:: verilog
+	:force:
+
+	always @*
+		if (R == RST_LVL)
+			Q <= 0;
+		else if (S == SET_LVL)
+			Q <= 1;
+
+In most cases gate level logic networks are created from RTL networks using the
+techmap pass. The flip-flop cells from the gate level logic network can be
+mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass.
+The combinatorial logic cells can be mapped to physical cells from a Liberty
+file via ABC using the abc pass.
+
+Add information about ``$slice`` and ``$concat`` cells.
+
+Add information about ``$lut`` and ``$sop`` cells.
+
+Add information about ``$alu``, ``$macc``, ``$fa``, and ``$lcu`` cells.