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 Note that {\tt \$reduce\_or} and {\tt \$reduce\_bool} actually represent the same
  69 logic function. But the HDL frontends generate them in different situations. A
  70 {\tt \$reduce\_or} cell is generated when the prefix {\tt |} operator is being used. A
  71 {\tt \$reduce\_bool} cell is generated when a bit vector is used as a condition in
  72 an {\tt if}-statement or {\tt ?:}-expression.
  73
  74 \subsection{Binary Operators}
  75
  76 All binary RTL cells have two input ports \B{A} and \B{B} and one output port \B{Y}. They
  77 also have the following parameters:
  78
  79 \begin{itemize}
  80 \item \B{A\_SIGNED} \\
  81 Set to a non-zero value if the input \B{A} is signed and therefore should be sign-extended
  82 when needed.
  83
  84 \item \B{A\_WIDTH} \\
  85 The width of the input port \B{A}.
  86
  87 \item \B{B\_SIGNED} \\
  88 Set to a non-zero value if the input \B{B} is signed and therefore should be sign-extended
  89 when needed.
  90
  91 \item \B{B\_WIDTH} \\
  92 The width of the input port \B{B}.
  93
  94 \item \B{Y\_WIDTH} \\
  95 The width of the output port \B{Y}.
  96 \end{itemize}
  97
  98 Table~\ref{tab:CellLib_binary} lists all cells for binary RTL operators.
  99
 100 \subsection{Multiplexers}
 101
 102 Multiplexers are generated by the Verilog HDL frontend for {\tt
 103 ?:}-expressions. Multiplexers are also generated by the {\tt proc} pass to map the decision trees
 104 from RTLIL::Process objects to logic.
 105
 106 The simplest multiplexer cell type is {\tt \$mux}. Cells of this type have a \B{WIDTH} parameter
 107 and data inputs \B{A} and \B{B} and a data output \B{Y}, all of the specified width. This cell also
 108 has a single bit control input \B{S}. If \B{S} is 0 the value from the \B{A} input is sent to
 109 the output, if it is 1 the value from the \B{B} input is sent to the output. So the {\tt \$mux}
 110 cell implements the function \lstinline[language=Verilog]; Y = S ? B : A;.
 111
 112 The {\tt \$pmux} cell is used to multiplex between many inputs using a one-hot select signal. Cells
 113 of this type have a \B{WIDTH} and a \B{S\_WIDTH} parameter and inputs \B{A}, \B{B}, and \B{S} and
 114 an output \B{Y}. The \B{S} input is \B{S\_WIDTH} bits wide. The \B{A} input and the output are both
 115 \B{WIDTH} bits wide and the \B{B} input is \B{WIDTH}*\B{S\_WIDTH} bits wide. When all bits of
 116 \B{S} are zero, the value from \B{A} input is sent to the output. If the $n$'th bit from \B{S} is
 117 set, the value $n$'th \B{WIDTH} bits wide slice of the \B{B} input is sent to the output. When more
 118 than one bit from \B{S} is set the output is undefined. Cells of this type are used to model
 119 ``parallel cases'' (defined by using the {\tt parallel\_case} attribute or detected by
 120 an optimization).
 121
 122 Behavioural code with cascaded {\tt if-then-else}- and {\tt case}-statements
 123 usually results in trees of multiplexer cells. Many passes (from various
 124 optimizations to FSM extraction) heavily depend on these multiplexer trees to
 125 understand dependencies between signals. Therefore optimizations should not
 126 break these multiplexer trees (e.g.~by replacing a multiplexer between a
 127 calculated signal and a constant zero with an {\tt \$and} gate).
 128
 129 \begin{table}[t!]
 130 \hfil
 131 \begin{tabular}[t]{ll}
 132 Verilog & Cell Type \\
 133 \hline
 134 \lstinline[language=Verilog]; Y = A  & B; & {\tt \$and} \\
 135 \lstinline[language=Verilog]; Y = A  | B; & {\tt \$or} \\
 136 \lstinline[language=Verilog]; Y = A  ^ B; & {\tt \$xor} \\
 137 \lstinline[language=Verilog]; Y = A ~^ B; & {\tt \$xnor} \\
 138 \hline
 139 \lstinline[language=Verilog]; Y = A << B; & {\tt \$shl} \\
 140 \lstinline[language=Verilog]; Y = A >> B; & {\tt \$shr} \\
 141 \lstinline[language=Verilog]; Y = A <<< B; & {\tt \$sshl} \\
 142 \lstinline[language=Verilog]; Y = A >>> B; & {\tt \$sshr} \\
 143 \hline
 144 \lstinline[language=Verilog]; Y = A && B; & {\tt \$logic\_and} \\
 145 \lstinline[language=Verilog]; Y = A || B; & {\tt \$logic\_or} \\
 146 \hline
 147 \lstinline[language=Verilog]; Y = A === B; & {\tt \$eqx} \\
 148 \lstinline[language=Verilog]; Y = A !== B; & {\tt \$nex} \\
 149 \end{tabular}
 150 \hfil
 151 \begin{tabular}[t]{ll}
 152 Verilog & Cell Type \\
 153 \hline
 154 \lstinline[language=Verilog]; Y = A <  B; & {\tt \$lt} \\
 155 \lstinline[language=Verilog]; Y = A <= B; & {\tt \$le} \\
 156 \lstinline[language=Verilog]; Y = A == B; & {\tt \$eq} \\
 157 \lstinline[language=Verilog]; Y = A != B; & {\tt \$ne} \\
 158 \lstinline[language=Verilog]; Y = A >= B; & {\tt \$ge} \\
 159 \lstinline[language=Verilog]; Y = A >  B; & {\tt \$gt} \\
 160 \hline
 161 \lstinline[language=Verilog]; Y = A  + B; & {\tt \$add} \\
 162 \lstinline[language=Verilog]; Y = A  - B; & {\tt \$sub} \\
 163 \lstinline[language=Verilog]; Y = A  * B; & {\tt \$mul} \\
 164 \lstinline[language=Verilog]; Y = A  / B; & {\tt \$div} \\
 165 \lstinline[language=Verilog]; Y = A  % B; & {\tt \$mod} \\
 166 \lstinline[language=Verilog]; Y = A ** B; & {\tt \$pow} \\
 167 \end{tabular}
 168 \caption{Cell types for binary operators with their corresponding Verilog expressions.}
 169 \label{tab:CellLib_binary}
 170 \end{table}
 171
 172 \subsection{Registers}
 173
 174 D-Type Flip-Flops are represented by {\tt \$dff} cells. These cells have a clock port \B{CLK},
 175 an input port \B{D} and an output port \B{Q}. The following parameters are available for \$dff
 176 cells:
 177
 178 \begin{itemize}
 179 \item \B{WIDTH} \\
 180 The width of input \B{D} and output \B{Q}.
 181
 182 \item \B{CLK\_POLARITY} \\
 183 Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative
 184 edge if this parameter is {\tt 1'b0}.
 185 \end{itemize}
 186
 187 D-Type Flip-Flops with asynchronous resets are represented by {\tt \$adff} cells. As the {\tt \$dff}
 188 cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have a single-bit \B{ARST}
 189 input port for the reset pin and the following additional two parameters:
 190
 191 \begin{itemize}
 192 \item \B{ARST\_POLARITY} \\
 193 The asynchronous reset is high-active if this parameter has the value {\tt 1'b1} and low-active
 194 if this parameter is {\tt 1'b0}.
 195
 196 \item \B{ARST\_VALUE} \\
 197 The state of \B{Q} will be set to this value when the reset is active.
 198 \end{itemize}
 199
 200 Note that the {\tt \$adff} cell can only be used when the reset value is constant.
 201
 202 \begin{sloppypar}
 203 Usually these cells are generated by the {\tt proc} pass using the information
 204 in the designs RTLIL::Process objects.
 205 \end{sloppypar}
 206
 207 \begin{fixme}
 208 Add information about {\tt \$sr} cells (set-reset flip-flops) and d-type latches.
 209 \end{fixme}
 210
 211 \subsection{Memories}
 212 \label{sec:memcells}
 213
 214 Memories are either represented using RTLIL::Memory objects and {\tt \$memrd} and {\tt \$memwr} cells
 215 or simply by using {\tt \$mem} cells.
 216
 217 In the first alternative the RTLIL::Memory objects hold the general metadata for the memory (bit width,
 218 size in number of words, etc.) and for each port a {\tt \$memrd} (read port) or {\tt \$memwr} (write port)
 219 cell is created. Having individual cells for read and write ports has the advantage that they can be
 220 consolidated using resource sharing passes. In some cases this drastically reduces the number of required
 221 ports on the memory cell.
 222
 223 The {\tt \$memrd} cells have a clock input \B{CLK}, an enable input \B{EN}, an
 224 address input \B{ADDR}, and a data output \B{DATA}. They also have the
 225 following parameters:
 226
 227 \begin{itemize}
 228 \item \B{MEMID} \\
 229 The name of the RTLIL::Memory object that is associated with this read port.
 230
 231 \item \B{ABITS} \\
 232 The number of address bits (width of the \B{ADDR} input port).
 233
 234 \item \B{WIDTH} \\
 235 The number of data bits (width of the \B{DATA} output port).
 236
 237 \item \B{CLK\_ENABLE} \\
 238 When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and
 239 the \B{CLK} input is not used.
 240
 241 \item \B{CLK\_POLARITY} \\
 242 Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative
 243 edge if this parameter is {\tt 1'b0}.
 244
 245 \item \B{TRANSPARENT} \\
 246 If this parameter is set to {\tt 1'b1}, a read and write to the same address in the same cycle will
 247 return the new value. Otherwise the old value is returned.
 248 \end{itemize}
 249
 250 The {\tt \$memwr} cells have a clock input \B{CLK}, an enable input \B{EN} (one
 251 enable bit for each data bit), an address input \B{ADDR} and a data input
 252 \B{DATA}. They also have the following parameters:
 253
 254 \begin{itemize}
 255 \item \B{MEMID} \\
 256 The name of the RTLIL::Memory object that is associated with this read port.
 257
 258 \item \B{ABITS} \\
 259 The number of address bits (width of the \B{ADDR} input port).
 260
 261 \item \B{WIDTH} \\
 262 The number of data bits (width of the \B{DATA} output port).
 263
 264 \item \B{CLK\_ENABLE} \\
 265 When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and
 266 the \B{CLK} input is not used.
 267
 268 \item \B{CLK\_POLARITY} \\
 269 Clock is active on positive edge if this parameter has the value {\tt 1'b1} and on the negative
 270 edge if this parameter is {\tt 1'b0}.
 271
 272 \item \B{PRIORITY} \\
 273 The cell with the higher integer value in this parameter wins a write conflict.
 274 \end{itemize}
 275
 276 The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
 277 {\tt \$memrd} and {\tt \$memwr} cells. The {\tt memory} pass (i.e.~its various sub-passes) migrates
 278 {\tt \$dff} cells into the {\tt \$memrd} and {\tt \$memwr} cells making them synchronous, then
 279 converts them to a single {\tt \$mem} cell and (optionally) maps this cell type
 280 to {\tt \$dff} cells for the individual words and multiplexer-based address decoders for the read and
 281 write interfaces. When the last step is disabled or not possible, a {\tt \$mem} cell is left in the design.
 282
 283 The {\tt \$mem} cell provides the following parameters:
 284
 285 \begin{itemize}
 286 \item \B{MEMID} \\
 287 The name of the original RTLIL::Memory object that became this {\tt \$mem} cell.
 288
 289 \item \B{SIZE} \\
 290 The number of words in the memory.
 291
 292 \item \B{ABITS} \\
 293 The number of address bits.
 294
 295 \item \B{WIDTH} \\
 296 The number of data bits per word.
 297
 298 \item \B{RD\_PORTS} \\
 299 The number of read ports on this memory cell.
 300
 301 \item \B{RD\_CLK\_ENABLE} \\
 302 This parameter is \B{RD\_PORTS} bits wide, containing a clock enable bit for each read port.
 303
 304 \item \B{RD\_CLK\_POLARITY} \\
 305 This parameter is \B{RD\_PORTS} bits wide, containing a clock polarity bit for each read port.
 306
 307 \item \B{RD\_TRANSPARENT} \\
 308 This parameter is \B{RD\_PORTS} bits wide, containing a transparent bit for each read port.
 309
 310 \item \B{WR\_PORTS} \\
 311 The number of write ports on this memory cell.
 312
 313 \item \B{WR\_CLK\_ENABLE} \\
 314 This parameter is \B{WR\_PORTS} bits wide, containing a clock enable bit for each write port.
 315
 316 \item \B{WR\_CLK\_POLARITY} \\
 317 This parameter is \B{WR\_PORTS} bits wide, containing a clock polarity bit for each write port.
 318 \end{itemize}
 319
 320 The {\tt \$mem} cell has the following ports:
 321
 322 \begin{itemize}
 323 \item \B{RD\_CLK} \\
 324 This input is \B{RD\_PORTS} bits wide, containing all clock signals for the read ports.
 325
 326 \item \B{RD\_EN} \\
 327 This input is \B{RD\_PORTS} bits wide, containing all enable signals for the read ports.
 328
 329 \item \B{RD\_ADDR} \\
 330 This input is \B{RD\_PORTS}*\B{ABITS} bits wide, containing all address signals for the read ports.
 331
 332 \item \B{RD\_DATA} \\
 333 This input is \B{RD\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the read ports.
 334
 335 \item \B{WR\_CLK} \\
 336 This input is \B{WR\_PORTS} bits wide, containing all clock signals for the write ports.
 337
 338 \item \B{WR\_EN} \\
 339 This input is \B{WR\_PORTS}*\B{WIDTH} bits wide, containing all enable signals for the write ports.
 340
 341 \item \B{WR\_ADDR} \\
 342 This input is \B{WR\_PORTS}*\B{ABITS} bits wide, containing all address signals for the write ports.
 343
 344 \item \B{WR\_DATA} \\
 345 This input is \B{WR\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the write ports.
 346 \end{itemize}
 347
 348 The {\tt techmap} pass can be used to manually map {\tt \$mem} cells to
 349 specialized memory cells on the target architecture, such as block ram resources
 350 on an FPGA.
 351
 352 \subsection{Finite State Machines}
 353
 354 \begin{fixme}
 355 Add a brief description of the {\tt \$fsm} cell type.
 356 \end{fixme}
 357
 358 \section{Gates}
 359 \label{sec:celllib_gates}
 360
 361 For gate level logic networks, fixed function single bit cells are used that do
 362 not provide any parameters.
 363
 364 Simulation models for these cells can be found in the file {\tt techlibs/common/simcells.v} in the Yosys
 365 source tree.
 366
 367 \begin{table}[t]
 368 \hfil
 369 \begin{tabular}[t]{ll}
 370 Verilog & Cell Type \\
 371 \hline
 372 \lstinline[language=Verilog]; Y = ~A;    & {\tt \$\_NOT\_} \\
 373 \lstinline[language=Verilog]; Y = A & B; & {\tt \$\_AND\_} \\
 374 \lstinline[language=Verilog]; Y = A | B; & {\tt \$\_OR\_} \\
 375 \lstinline[language=Verilog]; Y = A ^ B; & {\tt \$\_XOR\_} \\
 376 \lstinline[language=Verilog]; Y = S ? B : A; & {\tt \$\_MUX\_} \\
 377 \hline
 378 \lstinline[language=Verilog]; always @(negedge C) Q <= D; & {\tt \$\_DFF\_N\_} \\
 379 \lstinline[language=Verilog]; always @(posedge C) Q <= D; & {\tt \$\_DFF\_P\_} \\
 380 \end{tabular}
 381 \hfil
 382 \begin{tabular}[t]{llll}
 383 $ClkEdge$ & $RstLvl$ & $RstVal$ & Cell Type \\
 384 \hline
 385 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_NN0\_} \\
 386 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_NN1\_} \\
 387 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_NP0\_} \\
 388 \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_NP1\_} \\
 389 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_PN0\_} \\
 390 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_PN1\_} \\
 391 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_PP0\_} \\
 392 \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_PP1\_} \\
 393 \end{tabular}
 394 \caption{Cell types for gate level logic networks}
 395 \label{tab:CellLib_gates}
 396 \end{table}
 397
 398 Table~\ref{tab:CellLib_gates} lists all cell types used for gate level logic. The cell types
 399 {\tt \$\_NOT\_}, {\tt \$\_AND\_}, {\tt \$\_OR\_}, {\tt \$\_XOR\_} and {\tt \$\_MUX\_}
 400 are used to model combinatorial logic. The cell types {\tt \$\_DFF\_N\_} and {\tt \$\_DFF\_P\_}
 401 represent d-type flip-flops.
 402
 403 The cell types {\tt \$\_DFF\_NN0\_}, {\tt \$\_DFF\_NN1\_}, {\tt \$\_DFF\_NP0\_}, {\tt \$\_DFF\_NP1\_},
 404 {\tt \$\_DFF\_PN0\_}, {\tt \$\_DFF\_PN1\_}, {\tt \$\_DFF\_PP0\_} and {\tt \$\_DFF\_PP1\_} implement
 405 d-type flip-flops with asynchronous resets. The values in the table for these cell types relate to the
 406 following Verilog code template, where \lstinline[mathescape,language=Verilog];$RstEdge$; is \lstinline[language=Verilog];posedge;
 407 if \lstinline[mathescape,language=Verilog];$RstLvl$; if \lstinline[language=Verilog];1;, and \lstinline[language=Verilog];negedge;
 408 otherwise.
 409
 410 \begin{lstlisting}[mathescape,language=Verilog]
 411         always @($ClkEdge$ C, $RstEdge$ R)
 412                 if (R == $RstLvl$)
 413                         Q <= $RstVa$l;
 414                 else
 415                         Q <= D;
 416 \end{lstlisting}
 417
 418 In most cases gate level logic networks are created from RTL networks using the {\tt techmap} pass. The flip-flop cells
 419 from the gate level logic network can be mapped to physical flip-flop cells from a Liberty file using the {\tt dfflibmap}
 420 pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC \citeweblink{ABC}
 421 using the {\tt abc} pass.
 422
 423 \begin{fixme}
 424 Add information about {\tt \$assert}, {\tt \$assume}, {\tt \$equiv}, {\tt \$initstate}, {\tt \$aconst}, and {\tt \$anyconst} cells.
 425 \end{fixme}
 426
 427 \begin{fixme}
 428 Add information about {\tt \$slice} and {\tt \$concat} cells.
 429 \end{fixme}
 430
 431 \begin{fixme}
 432 Add information about {\tt \$lut} and {\tt \$sop} cells.
 433 \end{fixme}
 434
 435 \begin{fixme}
 436 Add information about {\tt \$alu}, {\tt \$macc}, {\tt \$fa}, and {\tt \$lcu} cells.
 437 \end{fixme}
 438
 439 \begin{fixme}
 440 Add information about {\tt \$dffe}, {\tt \$dffsr}, {\tt \$dlatch}, and {\tt \$dlatchsr} cells.
 441 \end{fixme}
 442
 443 \begin{fixme}
 444 Add information about {\tt \$\_DFFE\_??\_}, {\tt \$\_DFFSR\_???\_}, {\tt \$\_DLATCH\_?\_}, and {\tt \$\_DLATCHSR\_???\_} cells.
 445 \end{fixme}
 446
 447 \begin{fixme}
 448 Add information about {\tt \$\_NAND\_}, {\tt \$\_NOR\_}, {\tt \$\_XNOR\_}, {\tt \$\_AOI3\_}, {\tt \$\_OAI3\_}, {\tt \$\_AOI4\_}, and {\tt \$\_OAI4\_} cells.
 449 \end{fixme}
 450