From a9ff81dd82d347b5ed867f142e61271aa40d85ee Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Thu, 20 Dec 2018 04:37:28 +0000
Subject: manual: document $meminit cell and memory_* passes.

---
 manual/CHAPTER_CellLib.tex | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

(limited to 'manual/CHAPTER_CellLib.tex')

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
index 277e89328..6589bb2e7 100644
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@ -211,14 +211,15 @@ Add information about {\tt \$sr} cells (set-reset flip-flops) and d-type latches
 \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.
+Memories are either represented using RTLIL::Memory objects, {\tt \$memrd}, {\tt \$memwr}, and {\tt \$meminit}
+cells, or by {\tt \$mem} cells alone.
 
 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.
+ports on the memory cell. In this alternative, memory initialization data is represented by {\tt \$meminit} cells,
+which allow delaying constant folding for initialization addresses and data until after the frontend finishes.
 
 The {\tt \$memrd} cells have a clock input \B{CLK}, an enable input \B{EN}, an
 address input \B{ADDR}, and a data output \B{DATA}. They also have the
@@ -273,6 +274,15 @@ edge if this parameter is {\tt 1'b0}.
 The cell with the higher integer value in this parameter wins a write conflict.
 \end{itemize}
 
+The {\tt \$meminit} cells have an address input \B{ADDR} and a data input \B{DATA}. Both of the inputs
+must resolve to a constant for synthesis to succeed. If two {\tt \$meminit} cells have the same
+\B{MEMID} parameter and \B{ADDR} input, the contents of that memory at that address is undefined.
+
+\begin{itemize}
+\item \B{MEMID} \\
+The name of the RTLIL::Memory object that is associated with this initialization cell.
+\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
@@ -295,6 +305,9 @@ The number of address bits.
 \item \B{WIDTH} \\
 The number of data bits per word.
 
+\item \B{INIT} \\
+The initial memory contents.
+
 \item \B{RD\_PORTS} \\
 The number of read ports on this memory cell.
 
@@ -345,9 +358,11 @@ This input is \B{WR\_PORTS}*\B{ABITS} bits wide, containing all address signals
 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.
+The {\tt memory\_collect} pass can be used to convert discrete {\tt \$memrd}, {\tt \$memwr}, and {\tt \$meminit} cells
+belonging to the same memory to a single {\tt \$mem} cell, whereas the {\tt memory\_unpack} pass performs the inverse operation.
+The {\tt memory\_dff} pass can combine asynchronous memory ports that are fed by or feeding registers into synchronous memory ports.
+The {\tt memory\_bram} pass can be used to recognize {\tt \$mem} cells that can be implemented with a block RAM resource on an FPGA.
+The {\tt memory\_map} pass can be used to implement {\tt \$mem} cells as basic logic: word-wide DFFs and address decoders.
 
 \subsection{Finite State Machines}
 
-- 
cgit v1.2.3


From c04908c99740e616cae454aa6a5d7a3dd13af2fa Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Thu, 20 Dec 2018 07:59:40 +0000
Subject: manual: fix typos.

---
 manual/CHAPTER_CellLib.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'manual/CHAPTER_CellLib.tex')

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
index 6589bb2e7..65a79020f 100644
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@ -254,7 +254,7 @@ enable bit for each data bit), an address input \B{ADDR} and a data input
 
 \begin{itemize}
 \item \B{MEMID} \\
-The name of the RTLIL::Memory object that is associated with this read port.
+The name of the RTLIL::Memory object that is associated with this write port.
 
 \item \B{ABITS} \\
 The number of address bits (width of the \B{ADDR} input port).
@@ -263,7 +263,7 @@ The number of address bits (width of the \B{ADDR} input port).
 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
+When this parameter is non-zero, the clock is used. Otherwise this write port is asynchronous and
 the \B{CLK} input is not used.
 
 \item \B{CLK\_POLARITY} \\
-- 
cgit v1.2.3


From 182d84ad54cff315e7afb07f5353a477e4c410f4 Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Fri, 21 Dec 2018 01:26:08 +0000
Subject: manual: make description of $meminit ports match reality.

---
 manual/CHAPTER_CellLib.tex | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

(limited to 'manual/CHAPTER_CellLib.tex')

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
index 65a79020f..d40a600ed 100644
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@ -274,13 +274,25 @@ edge if this parameter is {\tt 1'b0}.
 The cell with the higher integer value in this parameter wins a write conflict.
 \end{itemize}
 
-The {\tt \$meminit} cells have an address input \B{ADDR} and a data input \B{DATA}. Both of the inputs
-must resolve to a constant for synthesis to succeed. If two {\tt \$meminit} cells have the same
-\B{MEMID} parameter and \B{ADDR} input, the contents of that memory at that address is undefined.
+The {\tt \$meminit} cells have an address input \B{ADDR} and a data input \B{DATA}, with the width
+of the \B{DATA} port equal to \B{WIDTH} parameter times \B{WORDS} parameter. Both of the inputs
+must resolve to a constant for synthesis to succeed.
 
 \begin{itemize}
 \item \B{MEMID} \\
 The name of the RTLIL::Memory object that is associated with this initialization cell.
+
+\item \B{ABITS} \\
+The number of address bits (width of the \B{ADDR} input port).
+
+\item \B{WIDTH} \\
+The number of data bits per memory location.
+
+\item \B{WORDS} \\
+The number of consecutive memory locations initialized by this cell.
+
+\item \B{PRIORITY} \\
+The cell with the higher integer value in this parameter wins an initialization conflict.
 \end{itemize}
 
 The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
-- 
cgit v1.2.3


From f042559e9dbcc0738c6404903ac22da63cd27404 Mon Sep 17 00:00:00 2001
From: Clifford Wolf <clifford@clifford.at>
Date: Mon, 7 Jan 2019 10:07:28 +0100
Subject: Fix typo in manual

Signed-off-by: Clifford Wolf <clifford@clifford.at>
---
 manual/CHAPTER_CellLib.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'manual/CHAPTER_CellLib.tex')

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
index d40a600ed..e22664a82 100644
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@ -437,7 +437,7 @@ otherwise.
 \begin{lstlisting}[mathescape,language=Verilog]
 	always @($ClkEdge$ C, $RstEdge$ R)
 		if (R == $RstLvl$)
-			Q <= $RstVa$l;
+			Q <= $RstVal$;
 		else
 			Q <= D;
 \end{lstlisting}
-- 
cgit v1.2.3


From 7a45122168d06a416f1341e1adf0760cc4c462b8 Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Mon, 14 Jan 2019 16:08:58 +0000
Subject: manual: explain $tribuf cell.

---
 manual/CHAPTER_CellLib.tex | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'manual/CHAPTER_CellLib.tex')

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
index e22664a82..464f7d1a9 100644
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@ -119,6 +119,12 @@ than one bit from \B{S} is set the output is undefined. Cells of this type are u
 ``parallel cases'' (defined by using the {\tt parallel\_case} attribute or detected by
 an optimization).
 
+The {\tt \$tribuf} cell is used to implement tristate logic. Cells of this type have a \B{WIDTH}
+parameter and inputs \B{A} and \B{EN} and an output \B{Y}. The \B{A} input and \B{Y} output are
+\B{WIDTH} bits wide, and the \B{EN} input is one bit wide. When \B{EN} is 0, the output \B{Y}
+is not driven. When \B{EN} is 1, the value from \B{A} input is sent to the \B{Y} output. Therefore,
+the {\tt \$tribuf} cell implements the function \lstinline[language=Verilog]; Y = EN ? A : 'bz;.
+
 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
@@ -476,6 +482,10 @@ Add information about {\tt \$dffe}, {\tt \$dffsr}, {\tt \$dlatch}, and {\tt \$dl
 Add information about {\tt \$\_DFFE\_??\_}, {\tt \$\_DFFSR\_???\_}, {\tt \$\_DLATCH\_?\_}, and {\tt \$\_DLATCHSR\_???\_} cells.
 \end{fixme}
 
+\begin{fixme}
+Add information about {\tt \$\_TBUF\_} cells.
+\end{fixme}
+
 \begin{fixme}
 Add information about {\tt \$\_NAND\_}, {\tt \$\_NOR\_}, {\tt \$\_XNOR\_}, {\tt \$\_ANDNOT\_}, {\tt \$\_ORNOT\_},
 {\tt \$\_AOI3\_}, {\tt \$\_OAI3\_}, {\tt \$\_AOI4\_}, and {\tt \$\_OAI4\_} cells.
-- 
cgit v1.2.3


From fc2dd7ec8e433bf54fffdb85e9aa2556fe3e39a2 Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Mon, 14 Jan 2019 16:17:25 +0000
Subject: manual: document some gates.

---
 manual/CHAPTER_CellLib.tex | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

(limited to 'manual/CHAPTER_CellLib.tex')

diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex
index 464f7d1a9..e64919182 100644
--- a/manual/CHAPTER_CellLib.tex
+++ b/manual/CHAPTER_CellLib.tex
@@ -404,9 +404,15 @@ Verilog & Cell Type \\
 \hline
 \lstinline[language=Verilog]; Y = ~A;    & {\tt \$\_NOT\_} \\
 \lstinline[language=Verilog]; Y = A & B; & {\tt \$\_AND\_} \\
+\lstinline[language=Verilog]; Y = ~(A & B); & {\tt \$\_NAND\_} \\
+\lstinline[language=Verilog]; Y = A & ~B; & {\tt \$\_ANDNOT\_} \\
 \lstinline[language=Verilog]; Y = A | B; & {\tt \$\_OR\_} \\
+\lstinline[language=Verilog]; Y = ~(A | B); & {\tt \$\_NOR\_} \\
+\lstinline[language=Verilog]; Y = A | ~B; & {\tt \$\_ORNOT\_} \\
 \lstinline[language=Verilog]; Y = A ^ B; & {\tt \$\_XOR\_} \\
+\lstinline[language=Verilog]; Y = ~(A ^ B); & {\tt \$\_XNOR\_} \\
 \lstinline[language=Verilog]; Y = S ? B : A; & {\tt \$\_MUX\_} \\
+\lstinline[language=Verilog]; Y = EN ? A : 'bz; & {\tt \$\_TBUF\_} \\
 \hline
 \lstinline[language=Verilog]; always @(negedge C) Q <= D; & {\tt \$\_DFF\_N\_} \\
 \lstinline[language=Verilog]; always @(posedge C) Q <= D; & {\tt \$\_DFF\_P\_} \\
@@ -429,9 +435,10 @@ $ClkEdge$ & $RstLvl$ & $RstVal$ & Cell Type \\
 \end{table}
 
 Table~\ref{tab:CellLib_gates} lists all cell types used for gate level logic. The cell types
-{\tt \$\_NOT\_}, {\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.
+{\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 \$\_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
@@ -483,11 +490,6 @@ Add information about {\tt \$\_DFFE\_??\_}, {\tt \$\_DFFSR\_???\_}, {\tt \$\_DLA
 \end{fixme}
 
 \begin{fixme}
-Add information about {\tt \$\_TBUF\_} cells.
-\end{fixme}
-
-\begin{fixme}
-Add information about {\tt \$\_NAND\_}, {\tt \$\_NOR\_}, {\tt \$\_XNOR\_}, {\tt \$\_ANDNOT\_}, {\tt \$\_ORNOT\_},
-{\tt \$\_AOI3\_}, {\tt \$\_OAI3\_}, {\tt \$\_AOI4\_}, and {\tt \$\_OAI4\_} cells.
+Add information about {\tt \$\_AOI3\_}, {\tt \$\_OAI3\_}, {\tt \$\_AOI4\_}, and {\tt \$\_OAI4\_} cells.
 \end{fixme}
 
-- 
cgit v1.2.3

