manual/CHAPTER_CellLib.tex

   1
   2 \chapter{Internal Cell Library}
   3 \label{chapter:celllib}
   4
   5 Most of the passes in Yosys operate on netlists, i.e.~they only care about the RTLIL::Wire and RTLIL::Cell
   6 objects in an RTLIL::Module. This chapter discusses the cell types used by Yosys to represent a behavioural
   7 design internally.
   8
   9 This chapter is split in two parts. In the first part the internal RTL cells are covered. These cells
  10 are used to represent the design on a coarse grain level. Like in the original HDL code on this level the
  11 cells operate on vectors of signals and complex cells like adders exist. In the second part the internal
  12 gate cells are covered. These cells are used to represent the design on a fine-grain gate-level. All cells
  13 from this category operate on single bit signals.
  14
  15 \section{RTL Cells}
  16
  17 Most of the RTL cells closely resemble the operators available in HDLs such as
  18 Verilog or VHDL. Therefore Verilog operators are used in the following sections
  19 to define the behaviour of the RTL cells.
  20
  21 Note that all RTL cells have parameters indicating the size of inputs and outputs. When
  22 passes modify RTL cells they must always keep the values of these parameters in sync with
  23 the size of the signals connected to the inputs and outputs.
  24
  25 Simulation models for the RTL cells can be found in the file {\tt techlibs/common/simlib.v} in the Yosys
  26 source tree.
  27
  28 \subsection{Unary Operators}
  29
  30 All unary RTL cells have one input port \B{A} and one output port \B{Y}. They also
  31 have the following parameters:
  32
  33 \begin{itemize}
  34 \item \B{A\_SIGNED} \\
  35 Set to a non-zero value if the input \B{A} is signed and therefore should be sign-extended
  36 when needed.
  37
  38 \item \B{A\_WIDTH} \\
  39 The width of the input port \B{A}.
  40
  41 \item \B{Y\_WIDTH} \\
  42 The width of the output port \B{Y}.
  43 \end{itemize}
  44
  45 Table~\ref{tab:CellLib_unary} lists all cells for unary RTL operators.
  46
  47 \begin{table}[t!]
  48 \hfil
  49 \begin{tabular}{ll}
  50 Verilog & Cell Type \\
  51 \hline
  52 \lstinline[language=Verilog]; Y =  ~A ; & {\tt \$not} \\
  53 \lstinline[language=Verilog]; Y =  +A ; & {\tt \$pos} \\
  54 \lstinline[language=Verilog]; Y =  -A ; & {\tt \$neg} \\
  55 \hline
  56 \lstinline[language=Verilog]; Y =  &A ; & {\tt \$reduce\_and} \\
  57 \lstinline[language=Verilog]; Y =  |A ; & {\tt \$reduce\_or} \\
  58 \lstinline[language=Verilog]; Y =  ^A ; & {\tt \$reduce\_xor} \\
  59 \lstinline[language=Verilog]; Y = ~^A ; & {\tt \$reduce\_xnor} \\
  60 \hline
  61 \lstinline[language=Verilog]; Y =  |A ; & {\tt \$reduce\_bool} \\
  62 \lstinline[language=Verilog]; Y =  !A ; & {\tt \$logic\_not}
  63 \end{tabular}
  64 \caption{Cell types for unary operators with their corresponding Verilog expressions.}
  65 \label{tab:CellLib_unary}
  66 \end{table}
  67
  68 For the unary cells that output a logical value ({\tt \$reduce\_and}, {\tt \$reduce\_or},
  69 {\tt \$reduce\_xor}, {\tt \$reduce\_xnor}, {\tt \$reduce\_bool}, {\tt \$logic\_not}),
  70 when the \B{Y\_WIDTH} parameter is greater than 1, the output is zero-extended,
  71 and only the least significant bit varies.
  72
  73 Note that {\tt \$reduce\_or} and {\tt \$reduce\_bool} actually represent the same
  74 logic function. But the HDL frontends generate them in different situations. A
  75 {\tt \$reduce\_or} cell is generated when the prefix {\tt |} operator is being used. A
  76 {\tt \$reduce\_bool} cell is generated when a bit vector is used as a condition in
  77 an {\tt if}-statement or {\tt ?:}-expression.
  78
  79 \subsection{Binary Operators}
  80
  81 All binary RTL cells have two input ports \B{A} and \B{B} and one output port \B{Y}. They
  82 also have the following parameters:
  83
  84 \begin{itemize}
  85 \item \B{A\_SIGNED} \\
  86 Set to a non-zero value if the input \B{A} is signed and therefore should be sign-extended
  87 when needed.
  88
  89 \item \B{A\_WIDTH} \\
  90 The width of the input port \B{A}.
  91
  92 \item \B{B\_SIGNED} \\
  93 Set to a non-zero value if the input \B{B} is signed and therefore should be sign-extended
  94 when needed.
  95
  96 \item \B{B\_WIDTH} \\
  97 The width of the input port \B{B}.
  98
  99 \item \B{Y\_WIDTH} \\
 100 The width of the output port \B{Y}.
 101 \end{itemize}
 102
 103 Table~\ref{tab:CellLib_binary} lists all cells for binary RTL operators.
 104
 105 \begin{table}[t!]
 106 \hfil
 107 \begin{tabular}[t]{ll}
 108 Verilog & Cell Type \\
 109 \hline
 110 \lstinline[language=Verilog]; Y = A  & B; & {\tt \$and} \\
 111 \lstinline[language=Verilog]; Y = A  | B; & {\tt \$or} \\
 112 \lstinline[language=Verilog]; Y = A  ^ B; & {\tt \$xor} \\
 113 \lstinline[language=Verilog]; Y = A ~^ B; & {\tt \$xnor} \\
 114 \hline
 115 \lstinline[language=Verilog]; Y = A << B; & {\tt \$shl} \\
 116 \lstinline[language=Verilog]; Y = A >> B; & {\tt \$shr} \\
 117 \lstinline[language=Verilog]; Y = A <<< B; & {\tt \$sshl} \\
 118 \lstinline[language=Verilog]; Y = A >>> B; & {\tt \$sshr} \\
 119 \hline
 120 \lstinline[language=Verilog]; Y = A && B; & {\tt \$logic\_and} \\
 121 \lstinline[language=Verilog]; Y = A || B; & {\tt \$logic\_or} \\
 122 \hline
 123 \lstinline[language=Verilog]; Y = A === B; & {\tt \$eqx} \\
 124 \lstinline[language=Verilog]; Y = A !== B; & {\tt \$nex} \\
 125 \end{tabular}
 126 \hfil
 127 \begin{tabular}[t]{ll}
 128 Verilog & Cell Type \\
 129 \hline
 130 \lstinline[language=Verilog]; Y = A <  B; & {\tt \$lt} \\
 131 \lstinline[language=Verilog]; Y = A <= B; & {\tt \$le} \\
 132 \lstinline[language=Verilog]; Y = A == B; & {\tt \$eq} \\
 133 \lstinline[language=Verilog]; Y = A != B; & {\tt \$ne} \\
 134 \lstinline[language=Verilog]; Y = A >= B; & {\tt \$ge} \\
 135 \lstinline[language=Verilog]; Y = A >  B; & {\tt \$gt} \\
 136 \hline
 137 \lstinline[language=Verilog]; Y = A  + B; & {\tt \$add} \\
 138 \lstinline[language=Verilog]; Y = A  - B; & {\tt \$sub} \\
 139 \lstinline[language=Verilog]; Y = A  * B; & {\tt \$mul} \\
 140 \lstinline[language=Verilog]; Y = A  / B; & {\tt \$div} \\
 141 \lstinline[language=Verilog]; Y = A  % B; & {\tt \$mod} \\
 142 \multicolumn{1}{c}{\tt [N/A]} & {\tt \$divfloor} \\
 143 \multicolumn{1}{c}{\tt [N/A]} & {\tt \$modfoor} \\
 144 \lstinline[language=Verilog]; Y = A ** B; & {\tt \$pow} \\
 145 \end{tabular}
 146 \caption{Cell types for binary operators with their corresponding Verilog expressions.}
 147 \label{tab:CellLib_binary}
 148 \end{table}
 149
 150 The {\tt \$shl} and {\tt \$shr} cells implement logical shifts, whereas the {\tt \$sshl} and
 151 {\tt \$sshr} cells implement arithmetic shifts. The {\tt \$shl} and {\tt \$sshl} cells implement
 152 the same operation. All four of these cells interpret the second operand as unsigned, and require
 153 \B{B\_SIGNED} to be zero.
 154
 155 Two additional shift operator cells are available that do not directly correspond to any operator
 156 in Verilog, {\tt \$shift} and {\tt \$shiftx}. The {\tt \$shift} cell performs a right logical shift
 157 if the second operand is positive (or unsigned), and a left logical shift if it is negative.
 158 The {\tt \$shiftx} cell performs the same operation as the {\tt \$shift} cell, but the vacated bit
 159 positions are filled with undef (x) bits, and corresponds to the Verilog indexed part-select expression.
 160
 161 For the binary cells that output a logical value ({\tt \$logic\_and}, {\tt \$logic\_or},
 162 {\tt \$eqx}, {\tt \$nex}, {\tt \$lt}, {\tt \$le}, {\tt \$eq}, {\tt \$ne}, {\tt \$ge},
 163 {\tt \$gt}), when the \B{Y\_WIDTH} parameter is greater than 1, the output is zero-extended,
 164 and only the least significant bit varies.
 165
 166 Division and modulo cells are available in two rounding modes. The original {\tt \$div} and {\tt \$mod}
 167 cells are based on truncating division, and correspond to the semantics of the verilog {\tt /} and
 168 {\tt \%} operators. The {\tt \$divfloor} and {\tt \$modfloor} cells represent flooring division and
 169 flooring modulo, the latter of which is also known as ``remainder'' in several languages. See
 170 table~\ref{tab:CellLib_divmod} for a side-by-side comparison between the different semantics.
 171
 172 \begin{table}[h]
 173 \hfil
 174 \begin{tabular}{lr|rr|rr}
 175 \multirow{2}{*}{Division} & \multirow{2}{*}{Result} & \multicolumn{2}{c|}{Truncating} & \multicolumn{2}{c}{Flooring} \\
 176                &            & {\tt \$div} & {\tt \$mod} & {\tt \$divfloor} & {\tt \$modfloor} \\
 177 \hline
 178 {\tt -10 / 3}  & {\tt -3.3} & {\tt -3}    & {\tt -1}    & {\tt -4}         & {\tt 2} \\
 179 {\tt 10 / -3}  & {\tt -3.3} & {\tt -3}    & {\tt 1}     & {\tt -4}         & {\tt -2} \\
 180 {\tt -10 / -3} & {\tt 3.3}  & {\tt 3}     & {\tt -1}    & {\tt 3}          & {\tt -1} \\
 181 {\tt 10 / 3}   & {\tt 3.3}  & {\tt 3}     & {\tt 1}     & {\tt 3}          & {\tt 1} \\
 182 \end{tabular}
 183 \caption{Comparison between different rounding modes for division and modulo cells.}
 184 \label{tab:CellLib_divmod}
 185 \end{table}
 186
 187 \subsection{Multiplexers}
 188
 189 Multiplexers are generated by the Verilog HDL frontend for {\tt
 190 ?:}-expressions. Multiplexers are also generated by the {\tt proc} pass to map the decision trees
 191 from RTLIL::Process objects to logic.
 192
 193 The simplest multiplexer cell type is {\tt \$mux}. Cells of this type have a \B{WIDTH} parameter
 194 and data inputs \B{A} and \B{B} and a data output \B{Y}, all of the specified width. This cell also
 195 has a single bit control input \B{S}. If \B{S} is 0 the value from the \B{A} input is sent to
 196 the output, if it is 1 the value from the \B{B} input is sent to the output. So the {\tt \$mux}
 197 cell implements the function \lstinline[language=Verilog]; Y = S ? B : A;.
 198
 199 The {\tt \$pmux} cell is used to multiplex between many inputs using a one-hot select signal. Cells
 200 of this type have a \B{WIDTH} and a \B{S\_WIDTH} parameter and inputs \B{A}, \B{B}, and \B{S} and
 201 an output \B{Y}. The \B{S} input is \B{S\_WIDTH} bits wide. The \B{A} input and the output are both
 202 \B{WIDTH} bits wide and the \B{B} input is \B{WIDTH}*\B{S\_WIDTH} bits wide. When all bits of
 203 \B{S} are zero, the value from \B{A} input is sent to the output. If the $n$'th bit from \B{S} is
 204 set, the value $n$'th \B{WIDTH} bits wide slice of the \B{B} input is sent to the output. When more
 205 than one bit from \B{S} is set the output is undefined. Cells of this type are used to model
 206 ``parallel cases'' (defined by using the {\tt parallel\_case} attribute or detected by
 207 an optimization).
 208
 209 The {\tt \$tribuf} cell is used to implement tristate logic. Cells of this type have a \B{WIDTH}
 210 parameter and inputs \B{A} and \B{EN} and an output \B{Y}. The \B{A} input and \B{Y} output are
 211 \B{WIDTH} bits wide, and the \B{EN} input is one bit wide. When \B{EN} is 0, the output \B{Y}
 212 is not driven. When \B{EN} is 1, the value from \B{A} input is sent to the \B{Y} output. Therefore,
 213 the {\tt \$tribuf} cell implements the function \lstinline[language=Verilog]; Y = EN ? A : 'bz;.
 214
 215 Behavioural code with cascaded {\tt if-then-else}- and {\tt case}-statements
 216 usually results in trees of multiplexer cells. Many passes (from various
 217 optimizations to FSM extraction) heavily depend on these multiplexer trees to
 218 understand dependencies between signals. Therefore optimizations should not
 219 break these multiplexer trees (e.g.~by replacing a multiplexer between a
 220 calculated signal and a constant zero with an {\tt \$and} gate).
 221
 222 \subsection{Registers}
 223
 224 SR-type latches are represented by {\tt \$sr} cells.  These cells have input ports
 225 \B{SET} and \B{CLR} and an output port \B{Q}.  They have the following parameters:
 226
 227 \begin{itemize}
 228 \item \B{WIDTH} \\
 229 The width of inputs \B{SET} and \B{CLR} and output \B{Q}.
 230
 231 \item \B{SET\_POLARITY} \\
 232 The set input bits are active-high if this parameter has the value {\tt 1'b1} and active-low
 233 if this parameter is {\tt 1'b0}.
 234
 235 \item \B{CLR\_POLARITY} \\
 236 The reset input bits are active-high if this parameter has the value {\tt 1'b1} and active-low
 237 if this parameter is {\tt 1'b0}.
 238 \end{itemize}
 239
 240 Both set and reset inputs have separate bits for every output bit.
 241 When both the set and reset inputs of an {\tt \$sr} cell are active for a given bit
 242 index, the reset input takes precedence.
 243
 244 D-type flip-flops are represented by {\tt \$dff} cells. These cells have a clock port \B{CLK},
 245 an input port \B{D} and an output port \B{Q}. The following parameters are available for {\tt \$dff}
 246 cells:
 247
 248 \begin{itemize}
 249 \item \B{WIDTH} \\
 250 The width of input \B{D} and output \B{Q}.
 251
 252 \item \B{CLK\_POLARITY} \\
 253 Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative
 254 edge if this parameter is {\tt 1'b0}.
 255 \end{itemize}
 256
 257 D-type flip-flops with asynchronous reset are represented by {\tt \$adff} cells. As the {\tt \$dff}
 258 cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have a single-bit \B{ARST}
 259 input port for the reset pin and the following additional two parameters:
 260
 261 \begin{itemize}
 262 \item \B{ARST\_POLARITY} \\
 263 The asynchronous reset is active-high if this parameter has the value {\tt 1'b1} and active-low
 264 if this parameter is {\tt 1'b0}.
 265
 266 \item \B{ARST\_VALUE} \\
 267 The state of \B{Q} will be set to this value when the reset is active.
 268 \end{itemize}
 269
 270 \begin{sloppypar}
 271 Usually these cells are generated by the {\tt proc} pass using the information
 272 in the designs RTLIL::Process objects.
 273 \end{sloppypar}
 274
 275 D-type flip-flops with synchronous reset are represented by {\tt \$sdff} cells. As the {\tt \$dff}
 276 cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have a single-bit \B{SRST}
 277 input port for the reset pin and the following additional two parameters:
 278
 279 \begin{itemize}
 280 \item \B{SRST\_POLARITY} \\
 281 The synchronous reset is active-high if this parameter has the value {\tt 1'b1} and active-low
 282 if this parameter is {\tt 1'b0}.
 283
 284 \item \B{SRST\_VALUE} \\
 285 The state of \B{Q} will be set to this value when the reset is active.
 286 \end{itemize}
 287
 288 Note that the {\tt \$adff} and {\tt \$sdff} cells can only be used when the reset value is constant.
 289
 290 D-type flip-flops with asynchronous load are represented by {\tt \$aldff} cells. As the {\tt \$dff}
 291 cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have a single-bit \B{ALOAD}
 292 input port for the async load enable pin, a \B{AD} input port with the same width as data for
 293 the async load data, and the following additional parameter:
 294
 295 \begin{itemize}
 296 \item \B{ALOAD\_POLARITY} \\
 297 The asynchronous load is active-high if this parameter has the value {\tt 1'b1} and active-low
 298 if this parameter is {\tt 1'b0}.
 299 \end{itemize}
 300
 301 D-type flip-flops with asynchronous set and reset are represented by {\tt \$dffsr} cells.
 302 As the {\tt \$dff} cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have
 303 multi-bit \B{SET} and \B{CLR} input ports and the corresponding polarity parameters, like
 304 {\tt \$sr} cells.
 305
 306 D-type flip-flops with enable are represented by {\tt \$dffe}, {\tt \$adffe}, {\tt \$aldffe}, {\tt \$dffsre},
 307 {\tt \$sdffe}, and {\tt \$sdffce} cells, which are enhanced variants of {\tt \$dff}, {\tt \$adff}, {\tt \$aldff}, {\tt \$dffsr},
 308 {\tt \$sdff} (with reset over enable) and {\tt \$sdff} (with enable over reset)
 309 cells, respectively.  They have the same ports and parameters as their base cell.
 310 In addition they also have a single-bit \B{EN} input port for the enable pin and the following parameter:
 311
 312 \begin{itemize}
 313 \item \B{EN\_POLARITY} \\
 314 The enable input is active-high if this parameter has the value {\tt 1'b1} and active-low
 315 if this parameter is {\tt 1'b0}.
 316 \end{itemize}
 317
 318 D-type latches are represented by {\tt \$dlatch} cells.  These cells have an enable port \B{EN},
 319 an input port \B{D}, and an output port \B{Q}.  The following parameters are available for {\tt \$dlatch} cells:
 320
 321 \begin{itemize}
 322 \item \B{WIDTH} \\
 323 The width of input \B{D} and output \B{Q}.
 324
 325 \item \B{EN\_POLARITY} \\
 326 The enable input is active-high if this parameter has the value {\tt 1'b1} and active-low
 327 if this parameter is {\tt 1'b0}.
 328 \end{itemize}
 329
 330 The latch is transparent when the \B{EN} input is active.
 331
 332 D-type latches with reset are represented by {\tt \$adlatch} cells.  In addition to {\tt \$dlatch}
 333 ports and parameters, they also have a single-bit \B{ARST} input port for the reset pin and the following additional parameters:
 334
 335 \begin{itemize}
 336 \item \B{ARST\_POLARITY} \\
 337 The asynchronous reset is active-high if this parameter has the value {\tt 1'b1} and active-low
 338 if this parameter is {\tt 1'b0}.
 339
 340 \item \B{ARST\_VALUE} \\
 341 The state of \B{Q} will be set to this value when the reset is active.
 342 \end{itemize}
 343
 344 D-type latches with set and reset are represented by {\tt \$dlatchsr} cells.
 345 In addition to {\tt \$dlatch} ports and parameters, they also have multi-bit
 346 \B{SET} and \B{CLR} input ports and the corresponding polarity parameters, like
 347 {\tt \$sr} cells.
 348
 349 \subsection{Memories}
 350 \label{sec:memcells}
 351
 352 Memories are either represented using RTLIL::Memory objects, {\tt \$memrd\_v2}, {\tt \$memwr\_v2}, and {\tt \$meminit\_v2}
 353 cells, or by {\tt \$mem\_v2} cells alone.
 354
 355 In the first alternative the RTLIL::Memory objects hold the general metadata for the memory (bit width,
 356 size in number of words, etc.) and for each port a {\tt \$memrd\_v2} (read port) or {\tt \$memwr\_v2} (write port)
 357 cell is created. Having individual cells for read and write ports has the advantage that they can be
 358 consolidated using resource sharing passes. In some cases this drastically reduces the number of required
 359 ports on the memory cell. In this alternative, memory initialization data is represented by {\tt \$meminit\_v2} cells,
 360 which allow delaying constant folding for initialization addresses and data until after the frontend finishes.
 361
 362 The {\tt \$memrd\_v2} cells have a clock input \B{CLK}, an enable input \B{EN}, an
 363 address input \B{ADDR}, a data output \B{DATA}, an asynchronous reset input \B{ARST},
 364 and a synchronous reset input \B{SRST}. They also have the following parameters:
 365
 366 \begin{itemize}
 367 \item \B{MEMID} \\
 368 The name of the RTLIL::Memory object that is associated with this read port.
 369
 370 \item \B{ABITS} \\
 371 The number of address bits (width of the \B{ADDR} input port).
 372
 373 \item \B{WIDTH} \\
 374 The number of data bits (width of the \B{DATA} output port).  Note that this may be a power-of-two
 375 multiple of the underlying memory's width -- such ports are called wide ports and access an aligned
 376 group of cells at once.  In this case, the corresponding low bits of \B{ADDR} must be tied to 0.
 377
 378 \item \B{CLK\_ENABLE} \\
 379 When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and
 380 the \B{CLK} input is not used.
 381
 382 \item \B{CLK\_POLARITY} \\
 383 Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative
 384 edge if this parameter is {\tt 1'b0}.
 385
 386 \item \B{TRANSPARENCY\_MASK} \\
 387 This parameter is a bitmask of write ports that this read port is transparent with.  The bits
 388 of this parameter are indexed by the write port's \B{PORTID} parameter.  Transparency can only be
 389 enabled between synchronous ports sharing a clock domain.  When transparency is enabled for a given
 390 port pair, a read and write to the same address in the same cycle will return the new value.
 391 Otherwise the old value is returned.
 392
 393 \item \B{COLLISION\_X\_MASK} \\
 394 This parameter is a bitmask of write ports that have undefined collision behavior with this port.
 395 The bits of this parameter are indexed by the write port's \B{PORTID} parameter.  This behavior can only be
 396 enabled between synchronous ports sharing a clock domain.  When undefined collision is enabled for a given
 397 port pair, a read and write to the same address in the same cycle will return the undefined (all-X) value.
 398 This option is exclusive (for a given port pair) with the transparency option.
 399
 400 \item \B{ARST\_VALUE} \\
 401 Whenever the \B{ARST} input is asserted, the data output will be reset to this value.
 402 Only used for synchronous ports.
 403
 404 \item \B{SRST\_VALUE} \\
 405 Whenever the \B{SRST} input is synchronously asserted, the data output will be reset to this value.
 406 Only used for synchronous ports.
 407
 408 \item \B{INIT\_VALUE} \\
 409 The initial value of the data output, for synchronous ports.
 410
 411 \item \B{CE\_OVER\_SRST} \\
 412 If this parameter is non-zero, the \B{SRST} input is only recognized when \B{EN} is true.
 413 Otherwise, \B{SRST} is recognized regardless of \B{EN}.
 414 \end{itemize}
 415
 416 The {\tt \$memwr\_v2} cells have a clock input \B{CLK}, an enable input \B{EN} (one
 417 enable bit for each data bit), an address input \B{ADDR} and a data input
 418 \B{DATA}. They also have the following parameters:
 419
 420 \begin{itemize}
 421 \item \B{MEMID} \\
 422 The name of the RTLIL::Memory object that is associated with this write port.
 423
 424 \item \B{ABITS} \\
 425 The number of address bits (width of the \B{ADDR} input port).
 426
 427 \item \B{WIDTH} \\
 428 The number of data bits (width of the \B{DATA} output port). Like with {\tt \$memrd\_v2} cells,
 429 the width is allowed to be any power-of-two multiple of memory width, with the corresponding
 430 restriction on address.
 431
 432 \item \B{CLK\_ENABLE} \\
 433 When this parameter is non-zero, the clock is used. Otherwise this write port is asynchronous and
 434 the \B{CLK} input is not used.
 435
 436 \item \B{CLK\_POLARITY} \\
 437 Clock is active on positive edge if this parameter has the value {\tt 1'b1} and on the negative
 438 edge if this parameter is {\tt 1'b0}.
 439
 440 \item \B{PORTID} \\
 441 An identifier for this write port, used to index write port bit mask parameters.
 442
 443 \item \B{PRIORITY\_MASK} \\
 444 This parameter is a bitmask of write ports that this write port has priority over in case of writing
 445 to the same address.  The bits of this parameter are indexed by the other write port's \B{PORTID} parameter.
 446 Write ports can only have priority over write ports with lower port ID.  When two ports write to the same
 447 address and neither has priority over the other, the result is undefined.  Priority can only be set between
 448 two synchronous ports sharing the same clock domain.
 449 \end{itemize}
 450
 451 The {\tt \$meminit\_v2} cells have an address input \B{ADDR}, a data input \B{DATA}, with the width
 452 of the \B{DATA} port equal to \B{WIDTH} parameter times \B{WORDS} parameter, and a bit enable mask input
 453 \B{EN} with width equal to \B{WIDTH} parameter. All three of the inputs
 454 must resolve to a constant for synthesis to succeed.
 455
 456 \begin{itemize}
 457 \item \B{MEMID} \\
 458 The name of the RTLIL::Memory object that is associated with this initialization cell.
 459
 460 \item \B{ABITS} \\
 461 The number of address bits (width of the \B{ADDR} input port).
 462
 463 \item \B{WIDTH} \\
 464 The number of data bits per memory location.
 465
 466 \item \B{WORDS} \\
 467 The number of consecutive memory locations initialized by this cell.
 468
 469 \item \B{PRIORITY} \\
 470 The cell with the higher integer value in this parameter wins an initialization conflict.
 471 \end{itemize}
 472
 473 The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
 474 {\tt \$memrd\_v2} and {\tt \$memwr\_v2} cells. The {\tt memory} pass (i.e.~its various sub-passes) migrates
 475 {\tt \$dff} cells into the {\tt \$memrd\_v2} and {\tt \$memwr\_v2} cells making them synchronous, then
 476 converts them to a single {\tt \$mem\_v2} cell and (optionally) maps this cell type
 477 to {\tt \$dff} cells for the individual words and multiplexer-based address decoders for the read and
 478 write interfaces. When the last step is disabled or not possible, a {\tt \$mem\_v2} cell is left in the design.
 479
 480 The {\tt \$mem\_v2} cell provides the following parameters:
 481
 482 \begin{itemize}
 483 \item \B{MEMID} \\
 484 The name of the original RTLIL::Memory object that became this {\tt \$mem\_v2} cell.
 485
 486 \item \B{SIZE} \\
 487 The number of words in the memory.
 488
 489 \item \B{ABITS} \\
 490 The number of address bits.
 491
 492 \item \B{WIDTH} \\
 493 The number of data bits per word.
 494
 495 \item \B{INIT} \\
 496 The initial memory contents.
 497
 498 \item \B{RD\_PORTS} \\
 499 The number of read ports on this memory cell.
 500
 501 \item \B{RD\_WIDE\_CONTINUATION} \\
 502 This parameter is \B{RD\_PORTS} bits wide, containing a bitmask of ``wide continuation'' read ports.
 503 Such ports are used to represent the extra data bits of wide ports in the combined cell, and must
 504 have all control signals identical with the preceding port, except for address, which must have
 505 the proper sub-cell address encoded in the low bits.
 506
 507 \item \B{RD\_CLK\_ENABLE} \\
 508 This parameter is \B{RD\_PORTS} bits wide, containing a clock enable bit for each read port.
 509
 510 \item \B{RD\_CLK\_POLARITY} \\
 511 This parameter is \B{RD\_PORTS} bits wide, containing a clock polarity bit for each read port.
 512
 513 \item \B{RD\_TRANSPARENCY\_MASK} \\
 514 This parameter is \B{RD\_PORTS*WR\_PORTS} bits wide, containing a concatenation of all
 515 \B{TRANSPARENCY\_MASK} values of the original {\tt \$memrd\_v2} cells.
 516
 517 \item \B{RD\_COLLISION\_X\_MASK} \\
 518 This parameter is \B{RD\_PORTS*WR\_PORTS} bits wide, containing a concatenation of all
 519 \B{COLLISION\_X\_MASK} values of the original {\tt \$memrd\_v2} cells.
 520
 521 \item \B{RD\_CE\_OVER\_SRST} \\
 522 This parameter is \B{RD\_PORTS} bits wide, determining relative synchronous reset and enable priority for each read port.
 523
 524 \item \B{RD\_INIT\_VALUE} \\
 525 This parameter is \B{RD\_PORTS*WIDTH} bits wide, containing the initial value for each synchronous read port.
 526
 527 \item \B{RD\_ARST\_VALUE} \\
 528 This parameter is \B{RD\_PORTS*WIDTH} bits wide, containing the asynchronous reset value for each synchronous read port.
 529
 530 \item \B{RD\_SRST\_VALUE} \\
 531 This parameter is \B{RD\_PORTS*WIDTH} bits wide, containing the synchronous reset value for each synchronous read port.
 532
 533 \item \B{WR\_PORTS} \\
 534 The number of write ports on this memory cell.
 535
 536 \item \B{WR\_WIDE\_CONTINUATION} \\
 537 This parameter is \B{WR\_PORTS} bits wide, containing a bitmask of ``wide continuation'' write ports.
 538
 539 \item \B{WR\_CLK\_ENABLE} \\
 540 This parameter is \B{WR\_PORTS} bits wide, containing a clock enable bit for each write port.
 541
 542 \item \B{WR\_CLK\_POLARITY} \\
 543 This parameter is \B{WR\_PORTS} bits wide, containing a clock polarity bit for each write port.
 544
 545 \item \B{WR\_PRIORITY\_MASK} \\
 546 This parameter is \B{WR\_PORTS*WR\_PORTS} bits wide, containing a concatenation of all
 547 \B{PRIORITY\_MASK} values of the original {\tt \$memwr\_v2} cells.
 548 \end{itemize}
 549
 550 The {\tt \$mem\_v2} cell has the following ports:
 551
 552 \begin{itemize}
 553 \item \B{RD\_CLK} \\
 554 This input is \B{RD\_PORTS} bits wide, containing all clock signals for the read ports.
 555
 556 \item \B{RD\_EN} \\
 557 This input is \B{RD\_PORTS} bits wide, containing all enable signals for the read ports.
 558
 559 \item \B{RD\_ADDR} \\
 560 This input is \B{RD\_PORTS}*\B{ABITS} bits wide, containing all address signals for the read ports.
 561
 562 \item \B{RD\_DATA} \\
 563 This input is \B{RD\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the read ports.
 564
 565 \item \B{RD\_ARST} \\
 566 This input is \B{RD\_PORTS} bits wide, containing all asynchronous reset signals for the read ports.
 567
 568 \item \B{RD\_SRST} \\
 569 This input is \B{RD\_PORTS} bits wide, containing all synchronous reset signals for the read ports.
 570
 571 \item \B{WR\_CLK} \\
 572 This input is \B{WR\_PORTS} bits wide, containing all clock signals for the write ports.
 573
 574 \item \B{WR\_EN} \\
 575 This input is \B{WR\_PORTS}*\B{WIDTH} bits wide, containing all enable signals for the write ports.
 576
 577 \item \B{WR\_ADDR} \\
 578 This input is \B{WR\_PORTS}*\B{ABITS} bits wide, containing all address signals for the write ports.
 579
 580 \item \B{WR\_DATA} \\
 581 This input is \B{WR\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the write ports.
 582 \end{itemize}
 583
 584 The {\tt memory\_collect} pass can be used to convert discrete {\tt \$memrd\_v2}, {\tt \$memwr\_v2}, and {\tt \$meminit\_v2} cells
 585 belonging to the same memory to a single {\tt \$mem\_v2} cell, whereas the {\tt memory\_unpack} pass performs the inverse operation.
 586 The {\tt memory\_dff} pass can combine asynchronous memory ports that are fed by or feeding registers into synchronous memory ports.
 587 The {\tt memory\_bram} pass can be used to recognize {\tt \$mem\_v2} cells that can be implemented with a block RAM resource on an FPGA.
 588 The {\tt memory\_map} pass can be used to implement {\tt \$mem\_v2} cells as basic logic: word-wide DFFs and address decoders.
 589
 590 \subsection{Finite State Machines}
 591
 592 \begin{fixme}
 593 Add a brief description of the {\tt \$fsm} cell type.
 594 \end{fixme}
 595
 596 \subsection{Specify rules}
 597
 598 \begin{fixme}
 599 Add information about {\tt \$specify2}, {\tt \$specify3}, and {\tt \$specrule} cells.
 600 \end{fixme}
 601
 602 \subsection{Formal verification cells}
 603
 604 \begin{fixme}
 605 Add information about {\tt \$assert}, {\tt \$assume}, {\tt \$live}, {\tt \$fair}, {\tt \$cover}, {\tt \$equiv},
 606 {\tt \$initstate}, {\tt \$anyconst}, {\tt \$anyseq}, {\tt \$allconst}, {\tt \$allseq} cells.
 607 \end{fixme}
 608
 609 \begin{fixme}
 610 Add information about {\tt \$ff} and {\tt \$\_FF\_} cells.
 611 \end{fixme}
 612
 613 \section{Gates}
 614 \label{sec:celllib_gates}
 615
 616 For gate level logic networks, fixed function single bit cells are used that do
 617 not provide any parameters.
 618
 619 Simulation models for these cells can be found in the file {\tt techlibs/common/simcells.v} in the Yosys
 620 source tree.
 621
 622 \begin{table}[t]
 623 \hfil
 624 \begin{tabular}[t]{ll}
 625 Verilog & Cell Type \\
 626 \hline
 627 \lstinline[language=Verilog]; Y = A;     & {\tt \$\_BUF\_} \\
 628 \lstinline[language=Verilog]; Y = ~A;    & {\tt \$\_NOT\_} \\
 629 \lstinline[language=Verilog]; Y = A & B; & {\tt \$\_AND\_} \\
 630 \lstinline[language=Verilog]; Y = ~(A & B); & {\tt \$\_NAND\_} \\
 631 \lstinline[language=Verilog]; Y = A & ~B; & {\tt \$\_ANDNOT\_} \\
 632 \lstinline[language=Verilog]; Y = A | B; & {\tt \$\_OR\_} \\
 633 \lstinline[language=Verilog]; Y = ~(A | B); & {\tt \$\_NOR\_} \\
 634 \lstinline[language=Verilog]; Y = A | ~B; & {\tt \$\_ORNOT\_} \\
 635 \lstinline[language=Verilog]; Y = A ^ B; & {\tt \$\_XOR\_} \\
 636 \lstinline[language=Verilog]; Y = ~(A ^ B); & {\tt \$\_XNOR\_} \\
 637 \lstinline[language=Verilog]; Y = ~((A & B) | C); & {\tt \$\_AOI3\_} \\
 638 \lstinline[language=Verilog]; Y = ~((A | B) & C); & {\tt \$\_OAI3\_} \\
 639 \lstinline[language=Verilog]; Y = ~((A & B) | (C & D)); & {\tt \$\_AOI4\_} \\
 640 \lstinline[language=Verilog]; Y = ~((A | B) & (C | D)); & {\tt \$\_OAI4\_} \\
 641 \lstinline[language=Verilog]; Y = S ? B : A; & {\tt \$\_MUX\_} \\
 642 \lstinline[language=Verilog]; Y = ~(S ? B : A); & {\tt \$\_NMUX\_} \\
 643 (see below) & {\tt \$\_MUX4\_} \\
 644 (see below) & {\tt \$\_MUX8\_} \\
 645 (see below) & {\tt \$\_MUX16\_} \\
 646 \lstinline[language=Verilog]; Y = EN ? A : 1'bz; & {\tt \$\_TBUF\_} \\
 647 \hline
 648 \lstinline[language=Verilog]; always @(negedge C) Q <= D; & {\tt \$\_DFF\_N\_} \\
 649 \lstinline[language=Verilog]; always @(posedge C) Q <= D; & {\tt \$\_DFF\_P\_} \\
 650 \lstinline[language=Verilog]; always @* if (!E) Q <= D; & {\tt \$\_DLATCH\_N\_} \\
 651 \lstinline[language=Verilog]; always @* if (E)  Q <= D; & {\tt \$\_DLATCH\_P\_} \\
 652 \end{tabular}
 653 \caption{Cell types for gate level logic networks (main list)}
 654 \label{tab:CellLib_gates}
 655 \end{table}
 656
 657 \begin{table}[t]
 658 \hfil
 659 \begin{tabular}[t]{llll}
 660 $ClkEdge$ & $RstLvl$ & $RstVal$ & Cell Type \\
 661 \hline
 662 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_NN0\_}, {\tt \$\_SDFF\_NN0\_} \\
 663 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_NN1\_}, {\tt \$\_SDFF\_NN1\_} \\
 664 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_NP0\_}, {\tt \$\_SDFF\_NP0\_} \\
 665 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_NP1\_}, {\tt \$\_SDFF\_NP1\_} \\
 666 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_PN0\_}, {\tt \$\_SDFF\_PN0\_} \\
 667 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_PN1\_}, {\tt \$\_SDFF\_PN1\_} \\
 668 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_PP0\_}, {\tt \$\_SDFF\_PP0\_} \\
 669 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_PP1\_}, {\tt \$\_SDFF\_PP1\_} \\
 670 \end{tabular}
 671 \caption{Cell types for gate level logic networks (FFs with reset)}
 672 \label{tab:CellLib_gates_adff}
 673 \end{table}
 674
 675 \begin{table}[t]
 676 \hfil
 677 \begin{tabular}[t]{lll}
 678 $ClkEdge$ & $EnLvl$ & Cell Type \\
 679 \hline
 680 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_NN\_} \\
 681 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_NP\_} \\
 682 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_PN\_} \\
 683 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_PP\_} \\
 684 \end{tabular}
 685 \caption{Cell types for gate level logic networks (FFs with enable)}
 686 \label{tab:CellLib_gates_dffe}
 687 \end{table}
 688
 689 \begin{table}[t]
 690 \begin{tabular}[t]{lllll}
 691 $ClkEdge$ & $RstLvl$ & $RstVal$ & $EnLvl$ & Cell Type \\
 692 \hline
 693 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_NN0N\_}, {\tt \$\_SDFFE\_NN0N\_}, {\tt \$\_SDFFCE\_NN0N\_} \\
 694 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_NN0P\_}, {\tt \$\_SDFFE\_NN0P\_}, {\tt \$\_SDFFCE\_NN0P\_} \\
 695 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_NN1N\_}, {\tt \$\_SDFFE\_NN1N\_}, {\tt \$\_SDFFCE\_NN1N\_} \\
 696 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_NN1P\_}, {\tt \$\_SDFFE\_NN1P\_}, {\tt \$\_SDFFCE\_NN1P\_} \\
 697 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_NP0N\_}, {\tt \$\_SDFFE\_NP0N\_}, {\tt \$\_SDFFCE\_NP0N\_} \\
 698 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_NP0P\_}, {\tt \$\_SDFFE\_NP0P\_}, {\tt \$\_SDFFCE\_NP0P\_} \\
 699 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_NP1N\_}, {\tt \$\_SDFFE\_NP1N\_}, {\tt \$\_SDFFCE\_NP1N\_} \\
 700 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_NP1P\_}, {\tt \$\_SDFFE\_NP1P\_}, {\tt \$\_SDFFCE\_NP1P\_} \\
 701 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_PN0N\_}, {\tt \$\_SDFFE\_PN0N\_}, {\tt \$\_SDFFCE\_PN0N\_} \\
 702 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_PN0P\_}, {\tt \$\_SDFFE\_PN0P\_}, {\tt \$\_SDFFCE\_PN0P\_} \\
 703 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_PN1N\_}, {\tt \$\_SDFFE\_PN1N\_}, {\tt \$\_SDFFCE\_PN1N\_} \\
 704 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_PN1P\_}, {\tt \$\_SDFFE\_PN1P\_}, {\tt \$\_SDFFCE\_PN1P\_} \\
 705 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_PP0N\_}, {\tt \$\_SDFFE\_PP0N\_}, {\tt \$\_SDFFCE\_PP0N\_} \\
 706 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_PP0P\_}, {\tt \$\_SDFFE\_PP0P\_}, {\tt \$\_SDFFCE\_PP0P\_} \\
 707 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_PP1N\_}, {\tt \$\_SDFFE\_PP1N\_}, {\tt \$\_SDFFCE\_PP1N\_} \\
 708 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_PP1P\_}, {\tt \$\_SDFFE\_PP1P\_}, {\tt \$\_SDFFCE\_PP1P\_} \\
 709 \end{tabular}
 710 \caption{Cell types for gate level logic networks (FFs with reset and enable)}
 711 \label{tab:CellLib_gates_adffe}
 712 \end{table}
 713
 714 \begin{table}[t]
 715 \hfil
 716 \begin{tabular}[t]{llll}
 717 $ClkEdge$ & $SetLvl$ & $RstLvl$ & Cell Type \\
 718 \hline
 719 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSR\_NNN\_} \\
 720 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSR\_NNP\_} \\
 721 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSR\_NPN\_} \\
 722 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSR\_NPP\_} \\
 723 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSR\_PNN\_} \\
 724 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSR\_PNP\_} \\
 725 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSR\_PPN\_} \\
 726 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSR\_PPP\_} \\
 727 \end{tabular}
 728 \caption{Cell types for gate level logic networks (FFs with set and reset)}
 729 \label{tab:CellLib_gates_dffsr}
 730 \end{table}
 731
 732 \begin{table}[t]
 733 \hfil
 734 \begin{tabular}[t]{lllll}
 735 $ClkEdge$ & $SetLvl$ & $RstLvl$ & $EnLvl$ & Cell Type \\
 736 \hline
 737 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSRE\_NNNN\_} \\
 738 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSRE\_NNNP\_} \\
 739 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSRE\_NNPN\_} \\
 740 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSRE\_NNPP\_} \\
 741 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSRE\_NPNN\_} \\
 742 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSRE\_NPNP\_} \\
 743 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSRE\_NPPN\_} \\
 744 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSRE\_NPPP\_} \\
 745 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSRE\_PNNN\_} \\
 746 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSRE\_PNNP\_} \\
 747 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSRE\_PNPN\_} \\
 748 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSRE\_PNPP\_} \\
 749 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSRE\_PPNN\_} \\
 750 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSRE\_PPNP\_} \\
 751 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSRE\_PPPN\_} \\
 752 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSRE\_PPPP\_} \\
 753 \end{tabular}
 754 \caption{Cell types for gate level logic networks (FFs with set and reset and enable)}
 755 \label{tab:CellLib_gates_dffsre}
 756 \end{table}
 757
 758 \begin{table}[t]
 759 \hfil
 760 \begin{tabular}[t]{llll}
 761 $EnLvl$ & $RstLvl$ & $RstVal$ & Cell Type \\
 762 \hline
 763 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCH\_NN0\_} \\
 764 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCH\_NN1\_} \\
 765 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCH\_NP0\_} \\
 766 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCH\_NP1\_} \\
 767 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCH\_PN0\_} \\
 768 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCH\_PN1\_} \\
 769 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCH\_PP0\_} \\
 770 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCH\_PP1\_} \\
 771 \end{tabular}
 772 \caption{Cell types for gate level logic networks (latches with reset)}
 773 \label{tab:CellLib_gates_adlatch}
 774 \end{table}
 775
 776 \begin{table}[t]
 777 \hfil
 778 \begin{tabular}[t]{llll}
 779 $EnLvl$ & $SetLvl$ & $RstLvl$ & Cell Type \\
 780 \hline
 781 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCHSR\_NNN\_} \\
 782 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCHSR\_NNP\_} \\
 783 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCHSR\_NPN\_} \\
 784 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCHSR\_NPP\_} \\
 785 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCHSR\_PNN\_} \\
 786 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCHSR\_PNP\_} \\
 787 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DLATCHSR\_PPN\_} \\
 788 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DLATCHSR\_PPP\_} \\
 789 \end{tabular}
 790 \caption{Cell types for gate level logic networks (latches with set and reset)}
 791 \label{tab:CellLib_gates_dlatchsr}
 792 \end{table}
 793
 794 \begin{table}[t]
 795 \hfil
 796 \begin{tabular}[t]{llll}
 797 $SetLvl$ & $RstLvl$ & Cell Type \\
 798 \hline
 799 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_SR\_NN\_} \\
 800 \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_SR\_NP\_} \\
 801 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_SR\_PN\_} \\
 802 \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_SR\_PP\_} \\
 803 \end{tabular}
 804 \caption{Cell types for gate level logic networks (SR latches)}
 805 \label{tab:CellLib_gates_sr}
 806 \end{table}
 807
 808 Tables~\ref{tab:CellLib_gates}, \ref{tab:CellLib_gates_dffe}, \ref{tab:CellLib_gates_adff}, \ref{tab:CellLib_gates_adffe}, \ref{tab:CellLib_gates_dffsr}, \ref{tab:CellLib_gates_dffsre}, \ref{tab:CellLib_gates_adlatch}, \ref{tab:CellLib_gates_dlatchsr} and \ref{tab:CellLib_gates_sr} list all cell types used for gate level logic. The cell types
 809 {\tt \$\_BUF\_}, {\tt \$\_NOT\_}, {\tt \$\_AND\_}, {\tt \$\_NAND\_}, {\tt \$\_ANDNOT\_},
 810 {\tt \$\_OR\_}, {\tt \$\_NOR\_}, {\tt \$\_ORNOT\_}, {\tt \$\_XOR\_}, {\tt \$\_XNOR\_},
 811 {\tt \$\_AOI3\_}, {\tt \$\_OAI3\_}, {\tt \$\_AOI4\_}, {\tt \$\_OAI4\_},
 812 {\tt \$\_MUX\_}, {\tt \$\_MUX4\_}, {\tt \$\_MUX8\_}, {\tt \$\_MUX16\_} and {\tt \$\_NMUX\_} are used to model combinatorial logic.
 813 The cell type {\tt \$\_TBUF\_} is used to model tristate logic.
 814
 815 The {\tt \$\_MUX4\_}, {\tt \$\_MUX8\_} and {\tt \$\_MUX16\_} cells are used to model wide muxes, and correspond to the following Verilog code:
 816
 817 \begin{lstlisting}[language=Verilog]
 818 // $_MUX4_
 819 assign Y = T ? (S ? D : C) :
 820                (S ? B : A);
 821 // $_MUX8_
 822 assign Y = U ? T ? (S ? H : G) :
 823                    (S ? F : E) :
 824                T ? (S ? D : C) :
 825                    (S ? B : A);
 826 // $_MUX16_
 827 assign Y = V ? U ? T ? (S ? P : O) :
 828                        (S ? N : M) :
 829                    T ? (S ? L : K) :
 830                        (S ? J : I) :
 831                U ? T ? (S ? H : G) :
 832                        (S ? F : E) :
 833                    T ? (S ? D : C) :
 834                        (S ? B : A);
 835 \end{lstlisting}
 836
 837 The cell types {\tt \$\_DFF\_N\_} and {\tt \$\_DFF\_P\_} represent d-type flip-flops.
 838
 839 The cell types {\tt \$\_DFFE\_[NP][NP]\_}
 840 implement d-type flip-flops with enable. The values in the table for these cell types relate to the
 841 following Verilog code template.
 842
 843 \begin{lstlisting}[mathescape,language=Verilog]
 844         always @($ClkEdge$ C)
 845                 if (EN == $EnLvl$)
 846                         Q <= D;
 847 \end{lstlisting}
 848
 849 The cell types {\tt \$\_DFF\_[NP][NP][01]\_} implement
 850 d-type flip-flops with asynchronous reset. The values in the table for these cell types relate to the
 851 following Verilog code template, where \lstinline[mathescape,language=Verilog];$RstEdge$; is \lstinline[language=Verilog];posedge;
 852 if \lstinline[mathescape,language=Verilog];$RstLvl$; if \lstinline[language=Verilog];1;, and \lstinline[language=Verilog];negedge;
 853 otherwise.
 854
 855 \begin{lstlisting}[mathescape,language=Verilog]
 856         always @($ClkEdge$ C, $RstEdge$ R)
 857                 if (R == $RstLvl$)
 858                         Q <= $RstVal$;
 859                 else
 860                         Q <= D;
 861 \end{lstlisting}
 862
 863 The cell types {\tt \$\_SDFF\_[NP][NP][01]\_} implement
 864 d-type flip-flops with synchronous reset. The values in the table for these cell types relate to the
 865 following Verilog code template:
 866
 867 \begin{lstlisting}[mathescape,language=Verilog]
 868         always @($ClkEdge$ C)
 869                 if (R == $RstLvl$)
 870                         Q <= $RstVal$;
 871                 else
 872                         Q <= D;
 873 \end{lstlisting}
 874
 875 The cell types {\tt \$\_DFFE\_[NP][NP][01][NP]\_} implement
 876 d-type flip-flops with asynchronous reset and enable.  The values in the table for these cell types relate to the
 877 following Verilog code template, where \lstinline[mathescape,language=Verilog];$RstEdge$; is \lstinline[language=Verilog];posedge;
 878 if \lstinline[mathescape,language=Verilog];$RstLvl$; if \lstinline[language=Verilog];1;, and \lstinline[language=Verilog];negedge;
 879 otherwise.
 880
 881 \begin{lstlisting}[mathescape,language=Verilog]
 882         always @($ClkEdge$ C, $RstEdge$ R)
 883                 if (R == $RstLvl$)
 884                         Q <= $RstVal$;
 885                 else if (EN == $EnLvl$)
 886                         Q <= D;
 887 \end{lstlisting}
 888
 889 The cell types {\tt \$\_SDFFE\_[NP][NP][01][NP]\_} implement d-type flip-flops
 890 with synchronous reset and enable, with reset having priority over enable.
 891 The values in the table for these cell types relate to the
 892 following Verilog code template:
 893
 894 \begin{lstlisting}[mathescape,language=Verilog]
 895         always @($ClkEdge$ C)
 896                 if (R == $RstLvl$)
 897                         Q <= $RstVal$;
 898                 else if (EN == $EnLvl$)
 899                         Q <= D;
 900 \end{lstlisting}
 901
 902 The cell types {\tt \$\_SDFFCE\_[NP][NP][01][NP]\_} implement d-type flip-flops
 903 with synchronous reset and enable, with enable having priority over reset.
 904 The values in the table for these cell types relate to the
 905 following Verilog code template:
 906
 907 \begin{lstlisting}[mathescape,language=Verilog]
 908         always @($ClkEdge$ C)
 909                 if (EN == $EnLvl$)
 910                         if (R == $RstLvl$)
 911                                 Q <= $RstVal$;
 912                         else
 913                                 Q <= D;
 914 \end{lstlisting}
 915
 916 The cell types {\tt \$\_DFFSR\_[NP][NP][NP]\_} implement
 917 d-type flip-flops with asynchronous set and reset. The values in the table for these cell types relate to the
 918 following Verilog code template, where \lstinline[mathescape,language=Verilog];$RstEdge$; is \lstinline[language=Verilog];posedge;
 919 if \lstinline[mathescape,language=Verilog];$RstLvl$; if \lstinline[language=Verilog];1;, \lstinline[language=Verilog];negedge;
 920 otherwise, and \lstinline[mathescape,language=Verilog];$SetEdge$; is \lstinline[language=Verilog];posedge;
 921 if \lstinline[mathescape,language=Verilog];$SetLvl$; if \lstinline[language=Verilog];1;, \lstinline[language=Verilog];negedge;
 922 otherwise.
 923
 924 \begin{lstlisting}[mathescape,language=Verilog]
 925         always @($ClkEdge$ C, $RstEdge$ R, $SetEdge$ S)
 926                 if (R == $RstLvl$)
 927                         Q <= 0;
 928                 else if (S == $SetLvl$)
 929                         Q <= 1;
 930                 else
 931                         Q <= D;
 932 \end{lstlisting}
 933
 934 The cell types {\tt \$\_DFFSRE\_[NP][NP][NP][NP]\_} implement
 935 d-type flip-flops with asynchronous set and reset and enable. The values in the table for these cell types relate to the
 936 following Verilog code template, where \lstinline[mathescape,language=Verilog];$RstEdge$; is \lstinline[language=Verilog];posedge;
 937 if \lstinline[mathescape,language=Verilog];$RstLvl$; if \lstinline[language=Verilog];1;, \lstinline[language=Verilog];negedge;
 938 otherwise, and \lstinline[mathescape,language=Verilog];$SetEdge$; is \lstinline[language=Verilog];posedge;
 939 if \lstinline[mathescape,language=Verilog];$SetLvl$; if \lstinline[language=Verilog];1;, \lstinline[language=Verilog];negedge;
 940 otherwise.
 941
 942 \begin{lstlisting}[mathescape,language=Verilog]
 943         always @($ClkEdge$ C, $RstEdge$ R, $SetEdge$ S)
 944                 if (R == $RstLvl$)
 945                         Q <= 0;
 946                 else if (S == $SetLvl$)
 947                         Q <= 1;
 948                 else if (E == $EnLvl$)
 949                         Q <= D;
 950 \end{lstlisting}
 951
 952 The cell types {\tt \$\_DLATCH\_N\_} and {\tt \$\_DLATCH\_P\_} represent d-type latches.
 953
 954 The cell types {\tt \$\_DLATCH\_[NP][NP][01]\_} implement
 955 d-type latches with reset. The values in the table for these cell types relate to the
 956 following Verilog code template:
 957
 958 \begin{lstlisting}[mathescape,language=Verilog]
 959         always @*
 960                 if (R == $RstLvl$)
 961                         Q <= $RstVal$;
 962                 else if (E == $EnLvl$)
 963                         Q <= D;
 964 \end{lstlisting}
 965
 966 The cell types {\tt \$\_DLATCHSR\_[NP][NP][NP]\_} implement
 967 d-type latches with set and reset. The values in the table for these cell types relate to the
 968 following Verilog code template:
 969
 970 \begin{lstlisting}[mathescape,language=Verilog]
 971         always @*
 972                 if (R == $RstLvl$)
 973                         Q <= 0;
 974                 else if (S == $SetLvl$)
 975                         Q <= 1;
 976                 else if (E == $EnLvl$)
 977                         Q <= D;
 978 \end{lstlisting}
 979
 980 The cell types {\tt \$\_SR\_[NP][NP]\_} implement
 981 sr-type latches. The values in the table for these cell types relate to the
 982 following Verilog code template:
 983
 984 \begin{lstlisting}[mathescape,language=Verilog]
 985         always @*
 986                 if (R == $RstLvl$)
 987                         Q <= 0;
 988                 else if (S == $SetLvl$)
 989                         Q <= 1;
 990 \end{lstlisting}
 991
 992 In most cases gate level logic networks are created from RTL networks using the {\tt techmap} pass. The flip-flop cells
 993 from the gate level logic network can be mapped to physical flip-flop cells from a Liberty file using the {\tt dfflibmap}
 994 pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC \citeweblink{ABC}
 995 using the {\tt abc} pass.
 996
 997 \begin{fixme}
 998 Add information about {\tt \$slice} and {\tt \$concat} cells.
 999 \end{fixme}
1000
1001 \begin{fixme}
1002 Add information about {\tt \$lut} and {\tt \$sop} cells.
1003 \end{fixme}
1004
1005 \begin{fixme}
1006 Add information about {\tt \$alu}, {\tt \$macc}, {\tt \$fa}, and {\tt \$lcu} cells.
1007 \end{fixme}