Added Yosys Manual

1 files changed, 408 insertions, 0 deletions

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
new file mode 100644
index 00000000..b4f98812
--- /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.
+