Merge pull request #1553 from whitequark/manual-dffx

Document $dffe, $dffsr, $_DFFE_*, $_DFFSR_* cells

1 files changed, 90 insertions, 11 deletions

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
index 00a88cc82..55abd9b96 100644
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@ -198,8 +198,8 @@ calculated signal and a constant zero with an {\tt \$and} gate).
 
 \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
+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 {\tt \$dff}
 cells:
 
 \begin{itemize}
@@ -211,13 +211,23 @@ Clock is active on the positive edge if this parameter has the value {\tt 1'b1}
 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}
+D-type flip-flops with enable are represented by {\tt \$dffe} 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{EN}
+input port for the enable pin and the following parameter:
+
+\begin{itemize}
+\item \B{EN\_POLARITY} \\
+The enable input is active-high if this parameter has the value {\tt 1'b1} and active-low
+if this parameter is {\tt 1'b0}.
+\end{itemize}
+
+D-type flip-flops with asynchronous reset 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
+The asynchronous reset is active-high if this parameter has the value {\tt 1'b1} and active-low
 if this parameter is {\tt 1'b0}.
 
 \item \B{ARST\_VALUE} \\
@@ -231,8 +241,27 @@ Usually these cells are generated by the {\tt proc} pass using the information
 in the designs RTLIL::Process objects.
 \end{sloppypar}
 
+D-type flip-flops with asynchronous set and reset are represented by {\tt \$dffsr} 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{SET} input port for the set pin, a single-bit \B{CLR} input port for the reset pin,
+and the following two parameters:
+
+\begin{itemize}
+\item \B{SET\_POLARITY} \\
+The set input is active-high if this parameter has the value {\tt 1'b1} and active-low
+if this parameter is {\tt 1'b0}.
+
+\item \B{CLR\_POLARITY} \\
+The reset input is active-high if this parameter has the value {\tt 1'b1} and active-low
+if this parameter is {\tt 1'b0}.
+\end{itemize}
+
+When both the set and reset inputs of a {\tt \$dffsr} cell are active, the reset input takes
+precedence.
+
 \begin{fixme}
-Add information about {\tt \$sr} cells (set-reset flip-flops) and d-type latches.
+Add information about {\tt \$sr} cells (set-reset flip-flops), {\tt \$dlatch} cells (d-type latches),
+and {\tt \$dlatchsr} cells (d-type latches with set/reset).
 \end{fixme}
 
 \subsection{Memories}
@@ -451,6 +480,30 @@ $ClkEdge$ & $RstLvl$ & $RstVal$ & Cell Type \\
 \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}
+% FIXME: the layout of this is broken and I have no idea how to fix it
+\hfil
+\begin{tabular}[t]{lll}
+$ClkEdge$ & $EnLvl$ & Cell Type \\
+\hline
+\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_NN\_} \\
+\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_NP\_} \\
+\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & {\tt \$\_DFFE\_PN\_} \\
+\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & {\tt \$\_DFFE\_PP\_} \\
+\end{tabular}
+% FIXME: the layout of this is broken too
+\hfil
+\begin{tabular}[t]{llll}
+$ClkEdge$ & $SetLvl$ & $RstLvl$ & Cell Type \\
+\hline
+\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSR\_NNN\_} \\
+\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSR\_NNP\_} \\
+\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSR\_NPN\_} \\
+\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSR\_NPP\_} \\
+\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSR\_PNN\_} \\
+\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSR\_PNP\_} \\
+\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFFSR\_PPN\_} \\
+\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFFSR\_PPP\_} \\
+\end{tabular}
 \caption{Cell types for gate level logic networks}
 \label{tab:CellLib_gates}
 \end{table}
@@ -459,11 +512,22 @@ Table~\ref{tab:CellLib_gates} lists all cell types used for gate level logic. Th
 {\tt \$\_NOT\_}, {\tt \$\_AND\_}, {\tt \$\_NAND\_}, {\tt \$\_ANDNOT\_}, {\tt \$\_OR\_}, {\tt \$\_NOR\_},
 {\tt \$\_ORNOT\_}, {\tt \$\_XOR\_}, {\tt \$\_XNOR\_} and {\tt \$\_MUX\_} are used to model combinatorial logic.
 The cell type {\tt \$\_TBUF\_} is used to model tristate logic.
+
 The cell types {\tt \$\_DFF\_N\_} and {\tt \$\_DFF\_P\_} represent d-type flip-flops.
 
+The cell types {\tt \$\_DFFE\_NN\_}, {\tt \$\_DFFE\_NP\_}, {\tt \$\_DFFE\_PN\_} and {\tt \$\_DFFE\_PP\_}
+implement d-type flip-flops with enable. The values in the table for these cell types relate to the
+following Verilog code template.
+
+\begin{lstlisting}[mathescape,language=Verilog]
+	always @($ClkEdge$ C)
+		if (EN == $EnLvl$)
+			Q <= D;
+\end{lstlisting}
+
 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
+d-type flip-flops with asynchronous reset. 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.
@@ -476,6 +540,25 @@ otherwise.
 			Q <= D;
 \end{lstlisting}
 
+The cell types {\tt \$\_DFFSR\_NNN\_}, {\tt \$\_DFFSR\_NNP\_}, {\tt \$\_DFFSR\_NPN\_}, {\tt \$\_DFFSR\_NPP\_},
+{\tt \$\_DFFSR\_PNN\_}, {\tt \$\_DFFSR\_PNP\_}, {\tt \$\_DFFSR\_PPN\_} and {\tt \$\_DFFSR\_PPP\_} implement
+d-type flip-flops with asynchronous set and reset. 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;, \lstinline[language=Verilog];negedge;
+otherwise, and \lstinline[mathescape,language=Verilog];$SetEdge$; is \lstinline[language=Verilog];posedge;
+if \lstinline[mathescape,language=Verilog];$SetLvl$; if \lstinline[language=Verilog];1;, \lstinline[language=Verilog];negedge;
+otherwise.
+
+\begin{lstlisting}[mathescape,language=Verilog]
+	always @($ClkEdge$ C, $RstEdge$ R, $SetEdge$ S)
+		if (R == $RstLvl$)
+			Q <= 0;
+		else if (S == $SetLvl$)
+			Q <= 1;
+		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}
@@ -507,11 +590,7 @@ Add information about {\tt \$ff} and {\tt \$\_FF\_} cells.
 \end{fixme}
 
 \begin{fixme}
-Add information about {\tt \$dffe}, {\tt \$dffsr}, {\tt \$dlatch}, and {\tt \$dlatchsr} cells.
-\end{fixme}
-
-\begin{fixme}
-Add information about {\tt \$\_DFFE\_??\_}, {\tt \$\_DFFSR\_???\_}, {\tt \$\_DLATCH\_?\_}, and {\tt \$\_DLATCHSR\_???\_} cells.
+Add information about {\tt \$\_DLATCH\_?\_}, and {\tt \$\_DLATCHSR\_???\_} cells.
 \end{fixme}
 
 \begin{fixme}