2 \chapter{Internal Cell Library
}
3 \label{chapter:celllib
}
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
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.
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.
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.
25 Simulation models for the RTL cells can be found in the file
{\tt techlibs/common/simlib.v
} in the Yosys
28 \subsection{Unary Operators
}
30 All unary RTL cells have one input port
\B{A
} and one output port
\B{Y
}. They also
31 have the following parameters:
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
39 The width of the input port
\B{A
}.
42 The width of the output port
\B{Y
}.
45 Table~
\ref{tab:CellLib_unary
} lists all cells for unary RTL operators.
50 Verilog & Cell Type \\
52 \lstinline[language=Verilog
]; Y = ~A ; &
{\tt \$not
} \\
53 \lstinline[language=Verilog
]; Y = +A ; &
{\tt \$pos
} \\
54 \lstinline[language=Verilog
]; Y = -A ; &
{\tt \$neg
} \\
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} \\
61 \lstinline[language=Verilog
]; Y = |A ; &
{\tt \$reduce
\_bool} \\
62 \lstinline[language=Verilog
]; Y = !A ; &
{\tt \$logic
\_not}
64 \caption{Cell types for unary operators with their corresponding Verilog expressions.
}
65 \label{tab:CellLib_unary
}
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.
74 \subsection{Binary Operators
}
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:
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
85 The width of the input port
\B{A
}.
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
92 The width of the input port
\B{B
}.
95 The width of the output port
\B{Y
}.
98 Table~
\ref{tab:CellLib_binary
} lists all cells for binary RTL operators.
100 \subsection{Multiplexers
}
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.
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;.
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
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).
131 \begin{tabular
}[t
]{ll
}
132 Verilog & Cell Type \\
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
} \\
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
} \\
144 \lstinline[language=Verilog
]; Y = A && B; &
{\tt \$logic
\_and} \\
145 \lstinline[language=Verilog
]; Y = A || B; &
{\tt \$logic
\_or} \\
147 \lstinline[language=Verilog
]; Y = A === B; &
{\tt \$eqx
} \\
148 \lstinline[language=Verilog
]; Y = A !== B; &
{\tt \$nex
} \\
151 \begin{tabular
}[t
]{ll
}
152 Verilog & Cell Type \\
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
} \\
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
} \\
168 \caption{Cell types for binary operators with their corresponding Verilog expressions.
}
169 \label{tab:CellLib_binary
}
172 \subsection{Registers
}
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
180 The width of input
\B{D
} and output
\B{Q
}.
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
}.
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:
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
}.
196 \item \B{ARST
\_VALUE} \\
197 The state of
\B{Q
} will be set to this value when the reset is active.
200 Note that the
{\tt \$adff
} cell can only be used when the reset value is constant.
203 Usually these cells are generated by the
{\tt proc
} pass using the information
204 in the designs RTLIL::Process objects.
208 Add information about
{\tt \$sr
} cells (set-reset flip-flops) and d-type latches.
211 \subsection{Memories
}
214 Memories are either represented using RTLIL::Memory objects,
{\tt \$memrd
},
{\tt \$memwr
}, and
{\tt \$meminit
}
215 cells, or by
{\tt \$mem
} cells alone.
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. In this alternative, memory initialization data is represented by
{\tt \$meminit
} cells,
222 which allow delaying constant folding for initialization addresses and data until after the frontend finishes.
224 The
{\tt \$memrd
} cells have a clock input
\B{CLK
}, an enable input
\B{EN
}, an
225 address input
\B{ADDR
}, and a data output
\B{DATA
}. They also have the
226 following parameters:
230 The name of the RTLIL::Memory object that is associated with this read port.
233 The number of address bits (width of the
\B{ADDR
} input port).
236 The number of data bits (width of the
\B{DATA
} output port).
238 \item \B{CLK
\_ENABLE} \\
239 When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and
240 the
\B{CLK
} input is not used.
242 \item \B{CLK
\_POLARITY} \\
243 Clock is active on the positive edge if this parameter has the value
{\tt 1'b1
} and on the negative
244 edge if this parameter is
{\tt 1'b0
}.
246 \item \B{TRANSPARENT
} \\
247 If this parameter is set to
{\tt 1'b1
}, a read and write to the same address in the same cycle will
248 return the new value. Otherwise the old value is returned.
251 The
{\tt \$memwr
} cells have a clock input
\B{CLK
}, an enable input
\B{EN
} (one
252 enable bit for each data bit), an address input
\B{ADDR
} and a data input
253 \B{DATA
}. They also have the following parameters:
257 The name of the RTLIL::Memory object that is associated with this write port.
260 The number of address bits (width of the
\B{ADDR
} input port).
263 The number of data bits (width of the
\B{DATA
} output port).
265 \item \B{CLK
\_ENABLE} \\
266 When this parameter is non-zero, the clock is used. Otherwise this write port is asynchronous and
267 the
\B{CLK
} input is not used.
269 \item \B{CLK
\_POLARITY} \\
270 Clock is active on positive edge if this parameter has the value
{\tt 1'b1
} and on the negative
271 edge if this parameter is
{\tt 1'b0
}.
273 \item \B{PRIORITY
} \\
274 The cell with the higher integer value in this parameter wins a write conflict.
277 The
{\tt \$meminit
} cells have an address input
\B{ADDR
} and a data input
\B{DATA
}, with the width
278 of the
\B{DATA
} port equal to
\B{WIDTH
} parameter times
\B{WORDS
} parameter. Both of the inputs
279 must resolve to a constant for synthesis to succeed.
283 The name of the RTLIL::Memory object that is associated with this initialization cell.
286 The number of address bits (width of the
\B{ADDR
} input port).
289 The number of data bits per memory location.
292 The number of consecutive memory locations initialized by this cell.
294 \item \B{PRIORITY
} \\
295 The cell with the higher integer value in this parameter wins an initialization conflict.
298 The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
299 {\tt \$memrd
} and
{\tt \$memwr
} cells. The
{\tt memory
} pass (i.e.~its various sub-passes) migrates
300 {\tt \$dff
} cells into the
{\tt \$memrd
} and
{\tt \$memwr
} cells making them synchronous, then
301 converts them to a single
{\tt \$mem
} cell and (optionally) maps this cell type
302 to
{\tt \$dff
} cells for the individual words and multiplexer-based address decoders for the read and
303 write interfaces. When the last step is disabled or not possible, a
{\tt \$mem
} cell is left in the design.
305 The
{\tt \$mem
} cell provides the following parameters:
309 The name of the original RTLIL::Memory object that became this
{\tt \$mem
} cell.
312 The number of words in the memory.
315 The number of address bits.
318 The number of data bits per word.
321 The initial memory contents.
323 \item \B{RD
\_PORTS} \\
324 The number of read ports on this memory cell.
326 \item \B{RD
\_CLK\_ENABLE} \\
327 This parameter is
\B{RD
\_PORTS} bits wide, containing a clock enable bit for each read port.
329 \item \B{RD
\_CLK\_POLARITY} \\
330 This parameter is
\B{RD
\_PORTS} bits wide, containing a clock polarity bit for each read port.
332 \item \B{RD
\_TRANSPARENT} \\
333 This parameter is
\B{RD
\_PORTS} bits wide, containing a transparent bit for each read port.
335 \item \B{WR
\_PORTS} \\
336 The number of write ports on this memory cell.
338 \item \B{WR
\_CLK\_ENABLE} \\
339 This parameter is
\B{WR
\_PORTS} bits wide, containing a clock enable bit for each write port.
341 \item \B{WR
\_CLK\_POLARITY} \\
342 This parameter is
\B{WR
\_PORTS} bits wide, containing a clock polarity bit for each write port.
345 The
{\tt \$mem
} cell has the following ports:
349 This input is
\B{RD
\_PORTS} bits wide, containing all clock signals for the read ports.
352 This input is
\B{RD
\_PORTS} bits wide, containing all enable signals for the read ports.
354 \item \B{RD
\_ADDR} \\
355 This input is
\B{RD
\_PORTS}*
\B{ABITS
} bits wide, containing all address signals for the read ports.
357 \item \B{RD
\_DATA} \\
358 This input is
\B{RD
\_PORTS}*
\B{WIDTH
} bits wide, containing all data signals for the read ports.
361 This input is
\B{WR
\_PORTS} bits wide, containing all clock signals for the write ports.
364 This input is
\B{WR
\_PORTS}*
\B{WIDTH
} bits wide, containing all enable signals for the write ports.
366 \item \B{WR
\_ADDR} \\
367 This input is
\B{WR
\_PORTS}*
\B{ABITS
} bits wide, containing all address signals for the write ports.
369 \item \B{WR
\_DATA} \\
370 This input is
\B{WR
\_PORTS}*
\B{WIDTH
} bits wide, containing all data signals for the write ports.
373 The
{\tt memory
\_collect} pass can be used to convert discrete
{\tt \$memrd
},
{\tt \$memwr
}, and
{\tt \$meminit
} cells
374 belonging to the same memory to a single
{\tt \$mem
} cell, whereas the
{\tt memory
\_unpack} pass performs the inverse operation.
375 The
{\tt memory
\_dff} pass can combine asynchronous memory ports that are fed by or feeding registers into synchronous memory ports.
376 The
{\tt memory
\_bram} pass can be used to recognize
{\tt \$mem
} cells that can be implemented with a block RAM resource on an FPGA.
377 The
{\tt memory
\_map} pass can be used to implement
{\tt \$mem
} cells as basic logic: word-wide DFFs and address decoders.
379 \subsection{Finite State Machines
}
382 Add a brief description of the
{\tt \$fsm
} cell type.
386 \label{sec:celllib_gates
}
388 For gate level logic networks, fixed function single bit cells are used that do
389 not provide any parameters.
391 Simulation models for these cells can be found in the file
{\tt techlibs/common/simcells.v
} in the Yosys
396 \begin{tabular
}[t
]{ll
}
397 Verilog & Cell Type \\
399 \lstinline[language=Verilog
]; Y = ~A; &
{\tt \$
\_NOT\_} \\
400 \lstinline[language=Verilog
]; Y = A & B; &
{\tt \$
\_AND\_} \\
401 \lstinline[language=Verilog
]; Y = A | B; &
{\tt \$
\_OR\_} \\
402 \lstinline[language=Verilog
]; Y = A ^ B; &
{\tt \$
\_XOR\_} \\
403 \lstinline[language=Verilog
]; Y = S ? B : A; &
{\tt \$
\_MUX\_} \\
405 \lstinline[language=Verilog
]; always @(negedge C) Q <= D; &
{\tt \$
\_DFF\_N\_} \\
406 \lstinline[language=Verilog
]; always @(posedge C) Q <= D; &
{\tt \$
\_DFF\_P\_} \\
409 \begin{tabular
}[t
]{llll
}
410 $ClkEdge$ & $RstLvl$ & $RstVal$ & Cell Type \\
412 \lstinline[language=Verilog
];negedge; &
\lstinline[language=Verilog
];
0; &
\lstinline[language=Verilog
];
0; &
{\tt \$
\_DFF\_NN0\_} \\
413 \lstinline[language=Verilog
];negedge; &
\lstinline[language=Verilog
];
0; &
\lstinline[language=Verilog
];
1; &
{\tt \$
\_DFF\_NN1\_} \\
414 \lstinline[language=Verilog
];negedge; &
\lstinline[language=Verilog
];
1; &
\lstinline[language=Verilog
];
0; &
{\tt \$
\_DFF\_NP0\_} \\
415 \lstinline[language=Verilog
];negedge; &
\lstinline[language=Verilog
];
1; &
\lstinline[language=Verilog
];
1; &
{\tt \$
\_DFF\_NP1\_} \\
416 \lstinline[language=Verilog
];posedge; &
\lstinline[language=Verilog
];
0; &
\lstinline[language=Verilog
];
0; &
{\tt \$
\_DFF\_PN0\_} \\
417 \lstinline[language=Verilog
];posedge; &
\lstinline[language=Verilog
];
0; &
\lstinline[language=Verilog
];
1; &
{\tt \$
\_DFF\_PN1\_} \\
418 \lstinline[language=Verilog
];posedge; &
\lstinline[language=Verilog
];
1; &
\lstinline[language=Verilog
];
0; &
{\tt \$
\_DFF\_PP0\_} \\
419 \lstinline[language=Verilog
];posedge; &
\lstinline[language=Verilog
];
1; &
\lstinline[language=Verilog
];
1; &
{\tt \$
\_DFF\_PP1\_} \\
421 \caption{Cell types for gate level logic networks
}
422 \label{tab:CellLib_gates
}
425 Table~
\ref{tab:CellLib_gates
} lists all cell types used for gate level logic. The cell types
426 {\tt \$
\_NOT\_},
{\tt \$
\_AND\_},
{\tt \$
\_OR\_},
{\tt \$
\_XOR\_} and
{\tt \$
\_MUX\_}
427 are used to model combinatorial logic. The cell types
{\tt \$
\_DFF\_N\_} and
{\tt \$
\_DFF\_P\_}
428 represent d-type flip-flops.
430 The cell types
{\tt \$
\_DFF\_NN0\_},
{\tt \$
\_DFF\_NN1\_},
{\tt \$
\_DFF\_NP0\_},
{\tt \$
\_DFF\_NP1\_},
431 {\tt \$
\_DFF\_PN0\_},
{\tt \$
\_DFF\_PN1\_},
{\tt \$
\_DFF\_PP0\_} and
{\tt \$
\_DFF\_PP1\_} implement
432 d-type flip-flops with asynchronous resets. The values in the table for these cell types relate to the
433 following Verilog code template, where
\lstinline[mathescape,language=Verilog
];$RstEdge$; is
\lstinline[language=Verilog
];posedge;
434 if
\lstinline[mathescape,language=Verilog
];$RstLvl$; if
\lstinline[language=Verilog
];
1;, and
\lstinline[language=Verilog
];negedge;
437 \begin{lstlisting
}[mathescape,language=Verilog
]
438 always @($ClkEdge$ C, $RstEdge$ R)
445 In most cases gate level logic networks are created from RTL networks using the
{\tt techmap
} pass. The flip-flop cells
446 from the gate level logic network can be mapped to physical flip-flop cells from a Liberty file using the
{\tt dfflibmap
}
447 pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC
\citeweblink{ABC
}
448 using the
{\tt abc
} pass.
451 Add information about
{\tt \$assert
},
{\tt \$assume
},
{\tt \$live
},
{\tt \$fair
},
{\tt \$cover
},
{\tt \$equiv
},
452 {\tt \$initstate
},
{\tt \$anyconst
},
{\tt \$anyseq
},
{\tt \$allconst
},
{\tt \$allseq
} cells.
456 Add information about
{\tt \$slice
} and
{\tt \$concat
} cells.
460 Add information about
{\tt \$lut
} and
{\tt \$sop
} cells.
464 Add information about
{\tt \$alu
},
{\tt \$macc
},
{\tt \$fa
}, and
{\tt \$lcu
} cells.
468 Add information about
{\tt \$ff
} and
{\tt \$
\_FF\_} cells.
472 Add information about
{\tt \$dffe
},
{\tt \$dffsr
},
{\tt \$dlatch
}, and
{\tt \$dlatchsr
} cells.
476 Add information about
{\tt \$
\_DFFE\_??
\_},
{\tt \$
\_DFFSR\_???
\_},
{\tt \$
\_DLATCH\_?
\_}, and
{\tt \$
\_DLATCHSR\_???
\_} cells.
480 Add information about
{\tt \$
\_NAND\_},
{\tt \$
\_NOR\_},
{\tt \$
\_XNOR\_},
{\tt \$
\_ANDNOT\_},
{\tt \$
\_ORNOT\_},
481 {\tt \$
\_AOI3\_},
{\tt \$
\_OAI3\_},
{\tt \$
\_AOI4\_}, and
{\tt \$
\_OAI4\_} cells.