\chapter{Internal Cell Library} \label{chapter:celllib} Most of the passes in Yosys operate on netlists, i.e.~they only care about the RTLIL::Wire and RTLIL::Cell objects in an RTLIL::Module. This chapter discusses the cell types used by Yosys to represent a behavioural design internally. This chapter is split in two parts. In the first part the internal RTL cells are covered. These cells are used to represent the design on a coarse grain level. Like in the original HDL code on this level the cells operate on vectors of signals and complex cells like adders exist. In the second part the internal gate cells are covered. These cells are used to represent the design on a fine-grain gate-level. All cells from this category operate on single bit signals. \section{RTL Cells} Most of the RTL cells closely resemble the operators available in HDLs such as Verilog or VHDL. Therefore Verilog operators are used in the following sections to define the behaviour of the RTL cells. Note that all RTL cells have parameters indicating the size of inputs and outputs. When passes modify RTL cells they must always keep the values of these parameters in sync with the size of the signals connected to the inputs and outputs. Simulation models for the RTL cells can be found in the file {\tt techlibs/common/simlib.v} in the Yosys source tree. \subsection{Unary Operators} All unary RTL cells have one input port \B{A} and one output port \B{Y}. They also have the following parameters: \begin{itemize} \item \B{A\_SIGNED} \\ Set to a non-zero value if the input \B{A} is signed and therefore should be sign-extended when needed. \item \B{A\_WIDTH} \\ The width of the input port \B{A}. \item \B{Y\_WIDTH} \\ The width of the output port \B{Y}. \end{itemize} Table~\ref{tab:CellLib_unary} lists all cells for unary RTL operators. \begin{table}[t!] \hfil \begin{tabular}{ll} Verilog & Cell Type \\ \hline \lstinline[language=Verilog]; Y = ~A ; & {\tt \$not} \\ \lstinline[language=Verilog]; Y = +A ; & {\tt \$pos} \\ \lstinline[language=Verilog]; Y = -A ; & {\tt \$neg} \\ \hline \lstinline[language=Verilog]; Y = &A ; & {\tt \$reduce\_and} \\ \lstinline[language=Verilog]; Y = |A ; & {\tt \$reduce\_or} \\ \lstinline[language=Verilog]; Y = ^A ; & {\tt \$reduce\_xor} \\ \lstinline[language=Verilog]; Y = ~^A ; & {\tt \$reduce\_xnor} \\ \hline \lstinline[language=Verilog]; Y = |A ; & {\tt \$reduce\_bool} \\ \lstinline[language=Verilog]; Y = !A ; & {\tt \$logic\_not} \end{tabular} \caption{Cell types for unary operators with their corresponding Verilog expressions.} \label{tab:CellLib_unary} \end{table} Note that {\tt \$reduce\_or} and {\tt \$reduce\_bool} actually represent the same logic function. But the HDL frontends generate them in different situations. A {\tt \$reduce\_or} cell is generated when the prefix {\tt |} operator is being used. A {\tt \$reduce\_bool} cell is generated when a bit vector is used as a condition in an {\tt if}-statement or {\tt ?:}-expression. \subsection{Binary Operators} All binary RTL cells have two input ports \B{A} and \B{B} and one output port \B{Y}. They also have the following parameters: \begin{itemize} \item \B{A\_SIGNED} \\ Set to a non-zero value if the input \B{A} is signed and therefore should be sign-extended when needed. \item \B{A\_WIDTH} \\ The width of the input port \B{A}. \item \B{B\_SIGNED} \\ Set to a non-zero value if the input \B{B} is signed and therefore should be sign-extended when needed. \item \B{B\_WIDTH} \\ The width of the input port \B{B}. \item \B{Y\_WIDTH} \\ The width of the output port \B{Y}. \end{itemize} Table~\ref{tab:CellLib_binary} lists all cells for binary RTL operators. The additional cell type {\tt \$bu0} is similar to {\tt \$pos}, but always extends unsigned arguments with zeros. ({\tt \$pos} extends unsigned arguments with {\tt x}-bits if the most significant bit is {\tt x}.) This is used internally to correctly implement the {\tt ==} and {\tt !=} operators for constant arguments. \subsection{Multiplexers} Multiplexers are generated by the Verilog HDL frontend for {\tt ?:}-expressions. Multiplexers are also generated by the {\tt proc} pass to map the decision trees from RTLIL::Process objects to logic. The simplest multiplexer cell type is {\tt \$mux}. Cells of this type have a \B{WIDTH} parameter and data inputs \B{A} and \B{B} and a data ouput \B{Y}, all of the specified width. This cell also has a single bit control input \B{S}. If \B{S} is 0 the value from the \B{A} input is sent to the output, if it is 1 the value from the \B{B} input is sent to the output. So the {\tt \$mux} cell implements the function \lstinline[language=Verilog]; Y = S ? B : A;. The {\tt \$pmux} cell is used to multiplex between many inputs using a one-hot select signal. Cells of this type have a \B{WIDTH} and a \B{S\_WIDTH} parameter and inputs \B{A}, \B{B}, and \B{S} and an output \B{Y}. The \B{S} input is \B{S\_WIDTH} bits wide. The \B{A} input and the output are both \B{WIDTH} bits wide and the \B{B} input is \B{WIDTH}*\B{S\_WIDTH} bits wide. When all bits of \B{S} are zero, the value from \B{A} input is sent to the output. If the $n$'th bit from \B{S} is set, the value $n$'th \B{WIDTH} bits wide slice of the \B{B} input is sent to the output. When more than one bit from \B{S} is set the output is undefined. Cells of this type are used to model ``parallel cases'' (defined by using the {\tt parallel\_case} attribute or detected by an optimization). The {\tt \$safe\_pmux} behaves similarly to the {\tt \$pmux} cell type. But when more than one bit of \B{S} is set, it is guaranteed that this cell type will output the value of the \B{A} input instead of an undefined value. Behavioural code with cascaded {\tt if-then-else}- and {\tt case}-statements usually results in trees of multiplexer cells. Many passes (from various optimizations to FSM extraction) heavily depend on these multiplexer trees to understand dependencies between signals. Therefore optimizations should not break these multiplexer trees (e.g.~by replacing a multiplexer between a calculated signal and a constant zero with an {\tt \$and} gate). \begin{table}[t!] \hfil \begin{tabular}[t]{ll} Verilog & Cell Type \\ \hline \lstinline[language=Verilog]; Y = A & B; & {\tt \$and} \\ \lstinline[language=Verilog]; Y = A | B; & {\tt \$or} \\ \lstinline[language=Verilog]; Y = A ^ B; & {\tt \$xor} \\ \lstinline[language=Verilog]; Y = A ~^ B; & {\tt \$xnor} \\ \hline \lstinline[language=Verilog]; Y = A << B; & {\tt \$shl} \\ \lstinline[language=Verilog]; Y = A >> B; & {\tt \$shr} \\ \lstinline[language=Verilog]; Y = A <<< B; & {\tt \$sshl} \\ \lstinline[language=Verilog]; Y = A >>> B; & {\tt \$sshr} \\ \hline \lstinline[language=Verilog]; Y = A && B; & {\tt \$logic\_and} \\ \lstinline[language=Verilog]; Y = A || B; & {\tt \$logic\_or} \\ \hline \lstinline[language=Verilog]; Y = A === B; & {\tt \$eqx} \\ \lstinline[language=Verilog]; Y = A !== B; & {\tt \$nex} \\ \end{tabular} \hfil \begin{tabular}[t]{ll} Verilog & Cell Type \\ \hline \lstinline[language=Verilog]; Y = A < B; & {\tt \$lt} \\ \lstinline[language=Verilog]; Y = A <= B; & {\tt \$le} \\ \lstinline[language=Verilog]; Y = A == B; & {\tt \$eq} \\ \lstinline[language=Verilog]; Y = A != B; & {\tt \$ne} \\ \lstinline[language=Verilog]; Y = A >= B; & {\tt \$ge} \\ \lstinline[language=Verilog]; Y = A > B; & {\tt \$gt} \\ \hline \lstinline[language=Verilog]; Y = A + B; & {\tt \$add} \\ \lstinline[language=Verilog]; Y = A - B; & {\tt \$sub} \\ \lstinline[language=Verilog]; Y = A * B; & {\tt \$mul} \\ \lstinline[language=Verilog]; Y = A / B; & {\tt \$div} \\ \lstinline[language=Verilog]; Y = A % B; & {\tt \$mod} \\ \lstinline[language=Verilog]; Y = A ** B; & {\tt \$pow} \\ \end{tabular} \caption{Cell types for binary operators with their corresponding Verilog expressions.} \label{tab:CellLib_binary} \end{table} \subsection{Registers} D-Type Flip-Flops are represented by {\tt \$dff} cells. These cells have a clock port \B{CLK}, an input port \B{D} and an output port \B{Q}. The following parameters are available for \$dff cells: \begin{itemize} \item \B{WIDTH} \\ The width of input \B{D} and output \B{Q}. \item \B{CLK\_POLARITY} \\ Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative edge if this parameter is {\tt 1'b0}. \end{itemize} D-Type Flip-Flops with asynchronous resets are represented by {\tt \$adff} cells. As the {\tt \$dff} cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have a single-bit \B{ARST} input port for the reset pin and the following additional two parameters: \begin{itemize} \item \B{ARST\_POLARITY} \\ The asynchronous reset is high-active if this parameter has the value {\tt 1'b1} and low-active if this parameter is {\tt 1'b0}. \item \B{ARST\_VALUE} \\ The state of \B{Q} will be set to this value when the reset is active. \end{itemize} Note that the {\tt \$adff} cell can only be used when the reset value is constant. \begin{sloppypar} Usually these cells are generated by the {\tt proc} pass using the information in the designs RTLIL::Process objects. \end{sloppypar} \begin{fixme} Add information about {\tt \$sr} cells (set-reset flip-flops) and d-type latches. \end{fixme} \subsection{Memories} \label{sec:memcells} Memories are either represented using RTLIL::Memory objects and {\tt \$memrd} and {\tt \$memwr} cells or simply by using {\tt \$mem} cells. In the first alternative the RTLIL::Memory objects hold the general metadata for the memory (bit width, size in number of words, etc.) and for each port a {\tt \$memrd} (read port) or {\tt \$memwr} (write port) cell is created. Having individual cells for read and write ports has the advantage that they can be consolidated using resource sharing passes. In some cases this drastically reduces the number of required ports on the memory cell. The {\tt \$memrd} cells have a clock input \B{CLK}, an address input \B{ADDR} and a data output \B{DATA}. They also have the following parameters: \begin{itemize} \item \B{MEMID} \\ The name of the RTLIL::Memory object that is associated with this read port. \item \B{ABITS} \\ The number of address bits (width of the \B{ADDR} input port). \item \B{WIDTH} \\ The number of data bits (width of the \B{DATA} output port). \item \B{CLK\_ENABLE} \\ When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and the \B{CLK} input is not used. \item \B{CLK\_POLARITY} \\ Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative edge if this parameter is {\tt 1'b0}. \item \B{TRANSPARENT} \\ If this parameter is set to {\tt 1'b1}, a read and write to the same address in the same cycle will return the new value. Otherwise the old value is returned. \end{itemize} The {\tt \$memwr} cells have a clock input \B{CLK}, an enable input \B{EN} (one enable bit for each data bit), an address input \B{ADDR} and a data input \B{DATA}. They also have the following parameters: \begin{itemize} \item \B{MEMID} \\ The name of the RTLIL::Memory object that is associated with this read port. \item \B{ABITS} \\ The number of address bits (width of the \B{ADDR} input port). \item \B{WIDTH} \\ The number of data bits (width of the \B{DATA} output port). \item \B{CLK\_ENABLE} \\ When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and the \B{CLK} input is not used. \item \B{CLK\_POLARITY} \\ Clock is active on positive edge if this parameter has the value {\tt 1'b1} and on the negative edge if this parameter is {\tt 1'b0}. \item \B{PRIORITY} \\ The cell with the higher integer value in this parameter wins a write conflict. \end{itemize} The HDL frontend models a memory using RTLIL::Memory objects and asynchronous {\tt \$memrd} and {\tt \$memwr} cells. The {\tt memory} pass (i.e.~its various sub-passes) migrates {\tt \$dff} cells into the {\tt \$memrd} and {\tt \$memwr} cells making them synchronous, then converts them to a single {\tt \$mem} cell and (optionally) maps this cell type to {\tt \$dff} cells for the individual words and multiplexer-based address decoders for the read and write interfaces. When the last step is disabled or not possible, a {\tt \$mem} cell is left in the design. The {\tt \$mem} cell provides the following parameters: \begin{itemize} \item \B{MEMID} \\ The name of the original RTLIL::Memory object that became this {\tt \$mem} cell. \item \B{SIZE} \\ The number of words in the memory. \item \B{ABITS} \\ The number of address bits. \item \B{WIDTH} \\ The number of data bits per word. \item \B{RD\_PORTS} \\ The number of read ports on this memory cell. \item \B{RD\_CLK\_ENABLE} \\ This parameter is \B{RD\_PORTS} bits wide, containing a clock enable bit for each read port. \item \B{RD\_CLK\_POLARITY} \\ This parameter is \B{RD\_PORTS} bits wide, containing a clock polarity bit for each read port. \item \B{RD\_TRANSPARENT} \\ This parameter is \B{RD\_PORTS} bits wide, containing a transparent bit for each read port. \item \B{WR\_PORTS} \\ The number of write ports on this memory cell. \item \B{WR\_CLK\_ENABLE} \\ This parameter is \B{WR\_PORTS} bits wide, containing a clock enable bit for each write port. \item \B{WR\_CLK\_POLARITY} \\ This parameter is \B{WR\_PORTS} bits wide, containing a clock polarity bit for each write port. \end{itemize} The {\tt \$mem} cell has the following ports: \begin{itemize} \item \B{RD\_CLK} \\ This input is \B{RD\_PORTS} bits wide, containing all clock signals for the read ports. \item \B{RD\_ADDR} \\ This input is \B{RD\_PORTS}*\B{ABITS} bits wide, containing all address signals for the read ports. \item \B{RD\_DATA} \\ This input is \B{RD\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the read ports. \item \B{WR\_CLK} \\ This input is \B{WR\_PORTS} bits wide, containing all clock signals for the write ports. \item \B{WR\_EN} \\ This input is \B{WR\_PORTS}*\B{WIDTH} bits wide, containing all enable signals for the write ports. \item \B{WR\_ADDR} \\ This input is \B{WR\_PORTS}*\B{ABITS} bits wide, containing all address signals for the write ports. \item \B{WR\_DATA} \\ This input is \B{WR\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the write ports. \end{itemize} The {\tt techmap} pass can be used to manually map {\tt \$mem} cells to specialized memory cells on the target architecture, such as block ram resources on an FPGA. \subsection{Finite State Machines} \begin{fixme} Add a brief description of the {\tt \$fsm} cell type. \end{fixme} \section{Gates} \label{sec:celllib_gates} For gate level logic networks, fixed function single bit cells are used that do not provide any parameters. Simulation models for these cells can be found in the file {\tt techlibs/common/stdcells\_sim.v} in the Yosys source tree. \begin{table}[t] \hfil \begin{tabular}[t]{ll} Verilog & Cell Type \\ \hline \lstinline[language=Verilog]; Y = ~A; & {\tt \$\_INV\_} \\ \lstinline[language=Verilog]; Y = A & B; & {\tt \$\_AND\_} \\ \lstinline[language=Verilog]; Y = A | B; & {\tt \$\_OR\_} \\ \lstinline[language=Verilog]; Y = A ^ B; & {\tt \$\_XOR\_} \\ \lstinline[language=Verilog]; Y = S ? B : A; & {\tt \$\_MUX\_} \\ \hline \lstinline[language=Verilog]; always @(negedge C) Q <= D; & {\tt \$\_DFF\_N\_} \\ \lstinline[language=Verilog]; always @(posedge C) Q <= D; & {\tt \$\_DFF\_P\_} \\ \end{tabular} \hfil \begin{tabular}[t]{llll} $ClkEdge$ & $RstLvl$ & $RstVal$ & Cell Type \\ \hline \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_NN0\_} \\ \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_NN1\_} \\ \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_NP0\_} \\ \lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_NP1\_} \\ \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_PN0\_} \\ \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_PN1\_} \\ \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_PP0\_} \\ \lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_PP1\_} \\ \end{tabular} \caption{Cell types for gate level logic networks} \label{tab:CellLib_gates} \end{table} Table~\ref{tab:CellLib_gates} lists all cell types used for gate level logic. The cell types {\tt \$\_INV\_}, {\tt \$\_AND\_}, {\tt \$\_OR\_}, {\tt \$\_XOR\_} and {\tt \$\_MUX\_} are used to model combinatorial logic. The cell types {\tt \$\_DFF\_N\_} and {\tt \$\_DFF\_P\_} represent d-type flip-flops. The cell types {\tt \$\_DFF\_NN0\_}, {\tt \$\_DFF\_NN1\_}, {\tt \$\_DFF\_NP0\_}, {\tt \$\_DFF\_NP1\_}, {\tt \$\_DFF\_PN0\_}, {\tt \$\_DFF\_PN1\_}, {\tt \$\_DFF\_PP0\_} and {\tt \$\_DFF\_PP1\_} implement d-type flip-flops with asynchronous resets. The values in the table for these cell types relate to the following verilog code template, where \lstinline[mathescape,language=Verilog];$RstEdge$; is \lstinline[language=Verilog];posedge; if \lstinline[mathescape,language=Verilog];$RstLvl$; if \lstinline[language=Verilog];1;, and \lstinline[language=Verilog];negedge; otherwise. \begin{lstlisting}[mathescape,language=Verilog] always @($ClkEdge$ C, $RstEdge$ R) if (R == $RstLvl$) Q <= $RstVa$l; else Q <= D; \end{lstlisting} In most cases gate level logic networks are created from RTL networks using the {\tt techmap} pass. The flip-flop cells from the gate level logic network can be mapped to physical flip-flop cells from a Liberty file using the {\tt dfflibmap} pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC \citeweblink{ABC} using the {\tt abc} pass. \begin{fixme} Add information about {\tt \$assert} cells. \end{fixme} \begin{fixme} Add information about {\tt \$slice} and {\tt \$concat} cells. \end{fixme}