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