diff options
Diffstat (limited to 'manual/CHAPTER_CellLib.tex')
-rw-r--r-- | manual/CHAPTER_CellLib.tex | 408 |
1 files changed, 408 insertions, 0 deletions
diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex new file mode 100644 index 000000000..b4f988129 --- /dev/null +++ b/manual/CHAPTER_CellLib.tex @@ -0,0 +1,408 @@ + +\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/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. + +\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} \\ +\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}. +\end{itemize} + +The {\tt \$memwr} cells have a clock input \B{CLK}, an enable input \B{EN}, 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}. +\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{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} 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/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. + |