diff --git a/docs/source/cell/word_arith.rst b/docs/source/cell/word_arith.rst new file mode 100644 index 000000000..38111a7d5 --- /dev/null +++ b/docs/source/cell/word_arith.rst @@ -0,0 +1,93 @@ +Coarse arithmetics +------------------ + +Multiply-accumulate +~~~~~~~~~~~~~~~~~~~ + +The `$macc` cell type represents a generalized multiply and accumulate +operation. The cell is purely combinational. It outputs the result of summing up +a sequence of products and other injected summands. + +.. code-block:: + + Y = 0 +- a0factor1 * a0factor2 +- a1factor1 * a1factor2 +- ... + + B[0] + B[1] + ... + +The A port consists of concatenated pairs of multiplier inputs ("factors"). A +zero length factor2 acts as a constant 1, turning factor1 into a simple summand. + +In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long. + +.. code-block:: + + struct A { + u(CONFIG.mul_info[0].factor1_len) a0factor1; + u(CONFIG.mul_info[0].factor2_len) a0factor2; + u(CONFIG.mul_info[1].factor1_len) a1factor1; + u(CONFIG.mul_info[1].factor2_len) a1factor2; + ... + }; + +The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. The +CONFIG parameter carries the following information: + +.. code-block:: + + struct CONFIG { + u4 num_bits; + struct mul_info { + bool is_signed; + bool is_subtract; + u(num_bits) factor1_len; + u(num_bits) factor2_len; + }[num_ports]; + }; + +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. + +.. autocellgroup:: arith + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_debug.rst b/docs/source/cell/word_debug.rst new file mode 100644 index 000000000..92c753dbe --- /dev/null +++ b/docs/source/cell/word_debug.rst @@ -0,0 +1,138 @@ +.. role:: verilog(code) + :language: Verilog + +Debugging cells +--------------- + +The `$print` cell is used to log the values of signals, akin to (and +translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It +has the following parameters: + +``FORMAT`` + The internal format string. The syntax is described below. + +``ARGS_WIDTH`` + The width (in bits) of the signal on the ``ARGS`` port. + +``TRG_ENABLE`` + True if triggered on specific signals defined in ``TRG``; false if triggered + whenever ``ARGS`` or ``EN`` change and ``EN`` is 1. + +If ``TRG_ENABLE`` is true, the following parameters also apply: + +``TRG_WIDTH`` + The number of bits in the ``TRG`` port. + +``TRG_POLARITY`` + For each bit in ``TRG``, 1 if that signal is positive-edge triggered, 0 if + negative-edge triggered. + +``PRIORITY`` + When multiple `$print` or `$check` cells fire on the same trigger, they + execute in descending priority order. + +Ports: + +``TRG`` + The signals that control when this `$print` cell is triggered. + + If the width of this port is zero and ``TRG_ENABLE`` is true, the cell is + triggered during initial evaluation (time zero) only. + +``EN`` + Enable signal for the whole cell. + +``ARGS`` + The values to be displayed, in format string order. + +.. autocellgroup:: debug + :members: + :source: + :linenos: + +Format string syntax +~~~~~~~~~~~~~~~~~~~~ + +The format string syntax resembles Python f-strings. Regular text is passed +through unchanged until a format specifier is reached, starting with a ``{``. + +Format specifiers have the following syntax. Unless noted, all items are +required: + +``{`` + Denotes the start of the format specifier. + +size + Signal size in bits; this many bits are consumed from the ``ARGS`` port by + this specifier. + +``:`` + Separates the size from the remaining items. + +justify + ``>`` for right-justified, ``<`` for left-justified. + +padding + ``0`` for zero-padding, or a space for space-padding. + +width\ *?* + (optional) The number of characters wide to pad to. + +base + * ``b`` for base-2 integers (binary) + * ``o`` for base-8 integers (octal) + * ``d`` for base-10 integers (decimal) + * ``h`` for base-16 integers (hexadecimal) + * ``c`` for ASCII characters/strings + * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and + :verilog:`$realtime`) + +For integers, this item may follow: + +``+``\ *?* + (optional, decimals only) Include a leading plus for non-negative numbers. + This can assist with symmetry with negatives in tabulated output. + +signedness + ``u`` for unsigned, ``s`` for signed. This distinction is only respected + when rendering decimals. + +ASCII characters/strings have no special options, but the signal size must be +divisible by 8. + +For simulation time, the signal size must be zero. + +Finally: + +``}`` + Denotes the end of the format specifier. + +Some example format specifiers: + ++ ``{8:>02hu}`` - 8-bit unsigned integer rendered as hexadecimal, + right-justified, zero-padded to 2 characters wide. ++ ``{32:< 15d+s}`` - 32-bit signed integer rendered as decimal, left-justified, + space-padded to 15 characters wide, positive values prefixed with ``+``. ++ ``{16:< 10hu}`` - 16-bit unsigned integer rendered as hexadecimal, + left-justified, space-padded to 10 characters wide. ++ ``{0:>010t}`` - simulation time, right-justified, zero-padded to 10 characters + wide. + +To include literal ``{`` and ``}`` characters in your format string, use ``{{`` +and ``}}`` respectively. + +It is an error for a format string to consume more or less bits from ``ARGS`` +than the port width. + +Values are never truncated, regardless of the specified width. + +Note that further restrictions on allowable combinations of options may apply +depending on the backend used. + +For example, Verilog does not have a format specifier that allows zero-padding a +string (i.e. more than 1 ASCII character), though zero-padding a single +character is permitted. + +Thus, while the RTLIL format specifier ``{8:>02c}`` translates to ``%02c``, +``{16:>02c}`` cannot be represented in Verilog and will fail to emit. In this +case, ``{16:> 02c}`` must be used, which translates to ``%2s``. diff --git a/docs/source/cell/word_formal.rst b/docs/source/cell/word_formal.rst new file mode 100644 index 000000000..81bab8988 --- /dev/null +++ b/docs/source/cell/word_formal.rst @@ -0,0 +1,14 @@ +Formal verification cells +------------------------- + +.. TODO:: Describe formal cells + + `$check`, `$assert`, `$assume`, `$live`, `$fair`, `$cover`, `$equiv`, + `$initstate`, `$anyconst`, `$anyseq`, `$anyinit`, `$allconst`, and `$allseq`. + + Also `$ff` and `$_FF_` cells. + +.. autocellgroup:: formal + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_fsm.rst b/docs/source/cell/word_fsm.rst new file mode 100644 index 000000000..943904b2b --- /dev/null +++ b/docs/source/cell/word_fsm.rst @@ -0,0 +1,9 @@ +Finite state machines +--------------------- + +.. TODO:: Describe `$fsm` cell + +.. autocellgroup:: fsm + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_mem.rst b/docs/source/cell/word_mem.rst new file mode 100644 index 000000000..434ddea3e --- /dev/null +++ b/docs/source/cell/word_mem.rst @@ -0,0 +1,281 @@ +.. role:: verilog(code) + :language: Verilog + +.. _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 output 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. + +.. autocellgroup:: mem + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_mux.rst b/docs/source/cell/word_mux.rst new file mode 100644 index 000000000..3eca310f3 --- /dev/null +++ b/docs/source/cell/word_mux.rst @@ -0,0 +1,47 @@ +.. role:: verilog(code) + :language: Verilog + +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 ``WIDTH`` 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). + +.. autocellgroup:: mux + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_other.rst b/docs/source/cell/word_other.rst deleted file mode 100644 index 9e5ac2a37..000000000 --- a/docs/source/cell/word_other.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. autocellgroup:: word_other - :caption: Other word-level cells - :members: - :source: - :linenos: diff --git a/docs/source/cell/word_reg.rst b/docs/source/cell/word_reg.rst new file mode 100644 index 000000000..25c82b8e6 --- /dev/null +++ b/docs/source/cell/word_reg.rst @@ -0,0 +1,124 @@ +.. role:: verilog(code) + :language: Verilog + +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. + +.. autocellgroup:: reg + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_spec.rst b/docs/source/cell/word_spec.rst new file mode 100644 index 000000000..33ef40774 --- /dev/null +++ b/docs/source/cell/word_spec.rst @@ -0,0 +1,9 @@ +Specify rules +------------- + +.. TODO:: `$specify2`, `$specify3`, and `$specrule` cells. + +.. autocellgroup:: spec + :members: + :source: + :linenos: diff --git a/docs/source/cell_gate.rst b/docs/source/cell_gate.rst index 0e977c587..4262fe210 100644 --- a/docs/source/cell_gate.rst +++ b/docs/source/cell_gate.rst @@ -1,6 +1,395 @@ +.. role:: verilog(code) + :language: Verilog + +.. _sec:celllib_gates: + Gate-level cells ---------------- +.. todo:: Split gate-level cells into subpages + + Consider also checking wording to be less academic and consistent. + +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 `, :numref:`%s `, +:numref:`%s `, :numref:`%s `, +:numref:`%s `, :numref:`%s `, +:numref:`%s `, :numref:`%s +` and :numref:`%s ` 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. + .. toctree:: :caption: Gate-level cells :maxdepth: 2 diff --git a/docs/source/cell_word.rst b/docs/source/cell_word.rst index c23a4e1b1..a736801fa 100644 --- a/docs/source/cell_word.rst +++ b/docs/source/cell_word.rst @@ -19,4 +19,21 @@ Simulation models for the RTL cells can be found in the file /cell/word_unary /cell/word_binary - /cell/word_other + /cell/word_mux + /cell/word_reg + /cell/word_mem + /cell/word_fsm + /cell/word_arith + /cell/word_spec + /cell/word_formal + /cell/word_debug + +.. todo:: Add information about `$slice` and `$concat` cells. + +.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. + +.. autocellgroup:: word_other + :caption: Other word-level cells + :members: + :source: + :linenos: diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index f078ed59e..68b538076 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:`/yosys_internals/formats/cell_library`. +:doc:`/cell_gate` and :doc:`/cell_word`. 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 7af2231c9..87763dbbe 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -27,9 +27,9 @@ 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:`/yosys_internals/formats/cell_library`. 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. +described in :doc:`/cell_gate` and :doc:`/cell_word`. 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. .. table:: Const folding rules for `$_AND_` cells as used in `opt_expr`. :name: tab:opt_expr_and @@ -182,6 +182,8 @@ away by `opt_expr`. Performing DFF optimizations - `opt_dff` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. todo:: ``$_DFF_`` isn't a valid cell + This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and `$adff` cells) with a constant data input and replaces them with a constant driver. It can also merge clock enables and synchronous reset multiplexers, removing unused diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst deleted file mode 100644 index 73dbc4e69..000000000 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ /dev/null @@ -1,1086 +0,0 @@ -.. role:: verilog(code) - :language: Verilog - -.. _chapter:celllib: - -Internal cell library -===================== - -.. todo:: less academic, also check formatting consistency - -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. - -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 ``\WIDTH`` 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 output 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. - -Coarse arithmetics -~~~~~~~~~~~~~~~~~~~~~ - -The `$macc` cell type represents a generalized multiply and accumulate -operation. The cell is purely combinational. It outputs the result of summing up -a sequence of products and other injected summands. - -.. code-block:: - - Y = 0 +- a0factor1 * a0factor2 +- a1factor1 * a1factor2 +- ... - + B[0] + B[1] + ... - -The A port consists of concatenated pairs of multiplier inputs ("factors"). A -zero length factor2 acts as a constant 1, turning factor1 into a simple summand. - -In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long. - -.. code-block:: - - struct A { - u(CONFIG.mul_info[0].factor1_len) a0factor1; - u(CONFIG.mul_info[0].factor2_len) a0factor2; - u(CONFIG.mul_info[1].factor1_len) a1factor1; - u(CONFIG.mul_info[1].factor2_len) a1factor2; - ... - }; - -The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. The -CONFIG parameter carries the following information: - -.. code-block:: - - struct CONFIG { - u4 num_bits; - struct mul_info { - bool is_signed; - bool is_subtract; - u(num_bits) factor1_len; - u(num_bits) factor2_len; - }[num_ports]; - }; - -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 -~~~~~~~~~~~~~ - -Add information about `$specify2`, `$specify3`, and `$specrule` cells. - -Formal verification cells -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add information about `$check`, `$assert`, `$assume`, `$live`, `$fair`, -`$cover`, `$equiv`, `$initstate`, `$anyconst`, `$anyseq`, `$anyinit`, -`$allconst`, `$allseq` cells. - -Add information about `$ff` and `$_FF_` cells. - -Debugging cells -~~~~~~~~~~~~~~~ - -The `$print` cell is used to log the values of signals, akin to (and -translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It -has the following parameters: - -``\FORMAT`` - The internal format string. The syntax is described below. - -``\ARGS_WIDTH`` - The width (in bits) of the signal on the ``\ARGS`` port. - -``\TRG_ENABLE`` - True if triggered on specific signals defined in ``\TRG``; false if triggered - whenever ``\ARGS`` or ``\EN`` change and ``\EN`` is 1. - -If ``\TRG_ENABLE`` is true, the following parameters also apply: - -``\TRG_WIDTH`` - The number of bits in the ``\TRG`` port. - -``\TRG_POLARITY`` - For each bit in ``\TRG``, 1 if that signal is positive-edge triggered, 0 if - negative-edge triggered. - -``\PRIORITY`` - When multiple `$print` or `$check` cells fire on the same trigger, they - execute in descending priority order. - -Ports: - -``\TRG`` - The signals that control when this `$print` cell is triggered. - - If the width of this port is zero and ``\TRG_ENABLE`` is true, the cell is - triggered during initial evaluation (time zero) only. - -``\EN`` - Enable signal for the whole cell. - -``\ARGS`` - The values to be displayed, in format string order. - -Format string syntax -^^^^^^^^^^^^^^^^^^^^ - -The format string syntax resembles Python f-strings. Regular text is passed -through unchanged until a format specifier is reached, starting with a ``{``. - -Format specifiers have the following syntax. Unless noted, all items are -required: - -``{`` - Denotes the start of the format specifier. - -size - Signal size in bits; this many bits are consumed from the ``\ARGS`` port by - this specifier. - -``:`` - Separates the size from the remaining items. - -justify - ``>`` for right-justified, ``<`` for left-justified. - -padding - ``0`` for zero-padding, or a space for space-padding. - -width\ *?* - (optional) The number of characters wide to pad to. - -base - * ``b`` for base-2 integers (binary) - * ``o`` for base-8 integers (octal) - * ``d`` for base-10 integers (decimal) - * ``h`` for base-16 integers (hexadecimal) - * ``c`` for ASCII characters/strings - * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and - :verilog:`$realtime`) - -For integers, this item may follow: - -``+``\ *?* - (optional, decimals only) Include a leading plus for non-negative numbers. - This can assist with symmetry with negatives in tabulated output. - -signedness - ``u`` for unsigned, ``s`` for signed. This distinction is only respected - when rendering decimals. - -ASCII characters/strings have no special options, but the signal size must be -divisible by 8. - -For simulation time, the signal size must be zero. - -Finally: - -``}`` - Denotes the end of the format specifier. - -Some example format specifiers: - -+ ``{8:>02hu}`` - 8-bit unsigned integer rendered as hexadecimal, - right-justified, zero-padded to 2 characters wide. -+ ``{32:< 15d+s}`` - 32-bit signed integer rendered as decimal, left-justified, - space-padded to 15 characters wide, positive values prefixed with ``+``. -+ ``{16:< 10hu}`` - 16-bit unsigned integer rendered as hexadecimal, - left-justified, space-padded to 10 characters wide. -+ ``{0:>010t}`` - simulation time, right-justified, zero-padded to 10 characters - wide. - -To include literal ``{`` and ``}`` characters in your format string, use ``{{`` -and ``}}`` respectively. - -It is an error for a format string to consume more or less bits from ``\ARGS`` -than the port width. - -Values are never truncated, regardless of the specified width. - -Note that further restrictions on allowable combinations of options may apply -depending on the backend used. - -For example, Verilog does not have a format specifier that allows zero-padding a -string (i.e. more than 1 ASCII character), though zero-padding a single -character is permitted. - -Thus, while the RTLIL format specifier ``{8:>02c}`` translates to ``%02c``, -``{16:>02c}`` cannot be represented in Verilog and will fail to emit. In this -case, ``{16:> 02c}`` must be used, which translates to ``%2s``. - -.. _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 `, :numref:`%s `, -:numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s -` and :numref:`%s ` 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. - -.. todo:: Add information about `$slice` and `$concat` cells. - -.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. - -.. todo:: Add information about ``$demux`` cell. \ No newline at end of file diff --git a/techlibs/common/simlib.v b/techlibs/common/simlib.v index fb294b53b..d567b7b0b 100644 --- a/techlibs/common/simlib.v +++ b/techlibs/common/simlib.v @@ -601,6 +601,7 @@ assign Y = t1 ^ C, X = (t2 | t3) ^ (Y ^ Y); endmodule // -------------------------------------------------------- +//* group arith // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- @@ -639,6 +640,7 @@ endmodule //* ver 2 //* title Arithmetic logic unit +//* group arith //- A building block supporting both binary addition/subtraction operations, and //- indirectly, comparison operations. //- Typically created by the `alumacc` pass, which transforms: @@ -1055,6 +1057,7 @@ endmodule // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- //- $macc (A, B, Y) +//* group arith //- //- Multiply and accumulate. //- A building block for summing any number of negated and unnegated signals @@ -1510,6 +1513,7 @@ assign Y = {B, A}; endmodule // -------------------------------------------------------- +//* group mux // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- @@ -1530,6 +1534,7 @@ assign Y = S ? B : A; endmodule // -------------------------------------------------------- +//* group mux module \$bmux (A, S, Y); @@ -1557,6 +1562,7 @@ endgenerate endmodule // -------------------------------------------------------- +//* group mux module \$pmux (A, B, S, Y); @@ -1591,6 +1597,7 @@ end endmodule // -------------------------------------------------------- +//* group mux // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- @@ -1662,6 +1669,7 @@ end endmodule // -------------------------------------------------------- +//* group mux // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| //- @@ -1684,6 +1692,7 @@ assign Y = EN ? A : 'bz; endmodule // -------------------------------------------------------- +//* group spec module \$specify2 (EN, SRC, DST); @@ -1722,6 +1731,7 @@ endspecify endmodule // -------------------------------------------------------- +//* group spec module \$specify3 (EN, SRC, DST, DAT); @@ -1830,6 +1840,7 @@ endspecify endmodule // -------------------------------------------------------- +//* group spec module \$specrule (EN_SRC, EN_DST, SRC, DST); @@ -1896,6 +1907,7 @@ endgenerate endmodule // -------------------------------------------------------- +//* group formal module \$assert (A, EN); @@ -1913,6 +1925,7 @@ end endmodule // -------------------------------------------------------- +//* group formal module \$assume (A, EN); @@ -1930,6 +1943,7 @@ end endmodule // -------------------------------------------------------- +//* group formal module \$live (A, EN); @@ -1938,6 +1952,7 @@ input A, EN; endmodule // -------------------------------------------------------- +//* group formal module \$fair (A, EN); @@ -1946,6 +1961,7 @@ input A, EN; endmodule // -------------------------------------------------------- +//* group formal module \$cover (A, EN); @@ -1954,6 +1970,7 @@ input A, EN; endmodule // -------------------------------------------------------- +//* group formal module \$initstate (Y); @@ -1971,6 +1988,7 @@ end endmodule // -------------------------------------------------------- +//* group formal module \$anyconst (Y); @@ -1983,6 +2001,7 @@ assign Y = 'bx; endmodule // -------------------------------------------------------- +//* group formal module \$anyseq (Y); @@ -1999,6 +2018,7 @@ endmodule `ifndef SIMLIB_GLOBAL_CLOCK `define SIMLIB_GLOBAL_CLOCK $global_clk `endif +//* group formal module \$anyinit (D, Q); parameter WIDTH = 0; @@ -2015,6 +2035,7 @@ end endmodule `endif // -------------------------------------------------------- +//* group formal module \$allconst (Y); @@ -2027,6 +2048,7 @@ assign Y = 'bx; endmodule // -------------------------------------------------------- +//* group formal module \$allseq (Y); @@ -2039,6 +2061,7 @@ assign Y = 'bx; endmodule // -------------------------------------------------------- +//* group formal module \$equiv (A, B, Y); @@ -2059,6 +2082,7 @@ end endmodule // -------------------------------------------------------- +//* group debug module \$print (EN, TRG, ARGS); @@ -2078,6 +2102,7 @@ input [ARGS_WIDTH-1:0] ARGS; endmodule // -------------------------------------------------------- +//* group debug module \$check (A, EN, TRG, ARGS); @@ -2100,6 +2125,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOSR +//* group reg module \$sr (SET, CLR, Q); @@ -2132,6 +2158,7 @@ endmodule `ifndef SIMLIB_GLOBAL_CLOCK `define SIMLIB_GLOBAL_CLOCK $global_clk `endif +//* group formal module \$ff (D, Q); @@ -2148,6 +2175,7 @@ endmodule `endif // -------------------------------------------------------- +//* group reg module \$dff (CLK, D, Q); @@ -2166,6 +2194,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$dffe (CLK, EN, D, Q); @@ -2186,6 +2215,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOSR +//* group reg module \$dffsr (CLK, SET, CLR, D, Q); @@ -2218,6 +2248,7 @@ endgenerate endmodule // -------------------------------------------------------- +//* group reg module \$dffsre (CLK, SET, CLR, EN, D, Q); @@ -2252,6 +2283,7 @@ endmodule `endif // -------------------------------------------------------- +//* group reg module \$adff (CLK, ARST, D, Q); @@ -2276,6 +2308,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$aldff (CLK, ALOAD, AD, D, Q); @@ -2300,6 +2333,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$sdff (CLK, SRST, D, Q); @@ -2324,6 +2358,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$adffe (CLK, ARST, EN, D, Q); @@ -2349,6 +2384,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$aldffe (CLK, ALOAD, AD, EN, D, Q); @@ -2374,6 +2410,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$sdffe (CLK, SRST, EN, D, Q); @@ -2399,6 +2436,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$sdffce (CLK, SRST, EN, D, Q); @@ -2426,6 +2464,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$dlatch (EN, D, Q); @@ -2444,6 +2483,7 @@ end endmodule // -------------------------------------------------------- +//* group reg module \$adlatch (EN, ARST, D, Q); @@ -2467,6 +2507,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOSR +//* group reg module \$dlatchsr (EN, SET, CLR, D, Q); @@ -2500,6 +2541,7 @@ endmodule `endif // -------------------------------------------------------- +//* group fsm module \$fsm (CLK, ARST, CTRL_IN, CTRL_OUT); @@ -2594,6 +2636,7 @@ endmodule // -------------------------------------------------------- `ifndef SIMLIB_NOMEM +//* group mem module \$memrd (CLK, EN, ADDR, DATA); @@ -2618,6 +2661,8 @@ end endmodule +//* group mem + module \$memrd_v2 (CLK, EN, ARST, SRST, ADDR, DATA); parameter MEMID = ""; @@ -2647,6 +2692,7 @@ end endmodule // -------------------------------------------------------- +//* group mem module \$memwr (CLK, EN, ADDR, DATA); @@ -2672,6 +2718,7 @@ end endmodule +//* group mem module \$memwr_v2 (CLK, EN, ADDR, DATA); parameter MEMID = ""; @@ -2698,6 +2745,7 @@ end endmodule // -------------------------------------------------------- +//* group mem module \$meminit (ADDR, DATA); @@ -2721,6 +2769,7 @@ end endmodule // -------------------------------------------------------- +//* group mem module \$meminit_v2 (ADDR, DATA, EN); @@ -2745,6 +2794,7 @@ end endmodule // -------------------------------------------------------- +//* group mem module \$mem (RD_CLK, RD_EN, RD_ADDR, RD_DATA, WR_CLK, WR_EN, WR_ADDR, WR_DATA); @@ -2833,6 +2883,8 @@ end endmodule +//* group mem + module \$mem_v2 (RD_CLK, RD_EN, RD_ARST, RD_SRST, RD_ADDR, RD_DATA, WR_CLK, WR_EN, WR_ADDR, WR_DATA); parameter MEMID = "";