From: whitequark <whitequark@whitequark.org>
Date: Thu, 5 Dec 2019 09:39:34 +0000 (+0000)
Subject: manual: document $dffe, $dffsr, $_DFFE_*, $_DFFSR_* cells.
X-Git-Tag: working-ls180~848^2
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=72a5674c03e6749263e61751616b05b3be80e7cc;p=yosys.git

manual: document $dffe, $dffsr, $_DFFE_*, $_DFFSR_* cells.
---

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
index 0106059b6..6367a4b37 100644
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@ -177,8 +177,8 @@ Verilog & Cell Type \\
 
 \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}
@@ -190,13 +190,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} \\
@@ -210,8 +220,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}
@@ -430,6 +459,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}
@@ -438,11 +491,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.
@@ -455,6 +519,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}
@@ -486,11 +569,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}