Progress on AppNote 011

1 files changed, 79 insertions, 15 deletions

diff --git a/manual/APPNOTE_011_Design_Investigation.tex b/manual/APPNOTE_011_Design_Investigation.tex
index 46485809..3a677354 100644
--- a/manual/APPNOTE_011_Design_Investigation.tex
+++ b/manual/APPNOTE_011_Design_Investigation.tex
@@ -206,18 +206,7 @@ of the circuit.
 \end{figure}
 
 \begin{figure}[b!]
-\begin{lstlisting}
-module splice_demo(a, b, c, d, e, f, x, y);
-
-input [1:0] a, b, c, d, e, f;
-output [1:0] x = {a[0], a[1]};
-
-output [11:0] y;
-assign {y[11:4], y[1:0], y[3:2]} =
-		{a, b, -{c, d}, ~{e, f}};
-
-endmodule
-\end{lstlisting}
+\lstinputlisting{APPNOTE_011_Design_Investigation/splice.v}
 \caption{\tt splice.v}
 \label{splice_src}
 \end{figure}
@@ -441,11 +430,86 @@ this case this is also yields the diagram shown in Fig.~\ref{seladd}.
 The output of {\tt help select} contains a complete syntax reference for
 matching different properties.
 
-\subsection{Selecting logic cones}
+Many commands can operate on explicit selections. For example the command {\tt
+dump t:\$add} will print information on all {\tt \$add} cells in the active
+module. Whenever a command has {\tt [selection]} as last argument in its usage
+help, this means that it will use the engine behind the {\tt select} command
+to evaluate additional arguments and use the resulting selection instead of
+the selection performed by the last {\tt select} command.
+
+The command {\tt select -clear} can be used to reset the selection.
+
+\subsection{Operations on selections}
+
+\begin{figure}[b]
+\lstinputlisting{APPNOTE_011_Design_Investigation/foobaraddsub.v}
+\caption{Test module for operations on selections}
+\label{foobaraddsub}
+\end{figure}
+
+The {\tt select} command is actually much more powerful than it might seem on
+the first glimpse. When it is called with multiple arguments, each argument is
+evaluated and pushed separately on a stack. After all arguments have been
+processed it simply creates the union of all elements on the stack. So the
+following command will select all {\tt \$add} cells and all objects with
+the {\tt foo} attribute set:
+
+\begin{verbatim}
+select t:$add a:foo
+\end{verbatim}
+
+(Try this with the design shown in Fig.~\ref{foobaraddsub}. Use the {\tt
+select -list} command to list the current selection.)
+
+In many cases simply adding more and more stuff to the selection is an
+ineffective way of selecting the interesting part of the design. Special
+arguments can be used to differently combine the elements on the stack.
+For example the {\tt \%i} arguments intersects the last two elements on
+the stack. So the following command will select all {\$add} cells that
+have the {\tt foo} attribute set:
+
+\begin{verbatim}
+select t:$add a:foo %i
+\end{verbatim}
+
+\begin{figure}[t]
+\lstinputlisting{APPNOTE_011_Design_Investigation/sumprod.v}
+\caption{Another test module for operations on selections}
+\label{sumprod}
+\end{figure}
+
+The listing in Fig.~\ref{sumprod} used the Yosys non-standard {\tt \{* ... *\}}
+syntax to set the attribute {\tt sumstuff} on all cells generated by the first
+assign statement. (This works on arbitrary large blocks of Verilog code an
+can be used to mark portions of code for analysis.)
+
+\begin{figure}[b]
+\includegraphics[width=\linewidth]{APPNOTE_011_Design_Investigation/sumprod_00.pdf}
+\caption{Output of {\tt show a:sumstuff} on Fig.~\ref{sumprod}}
+\label{sumprod_00}
+\end{figure}
+
+Selecting {\tt a:sumstuff} in this module will yield the circuit diagram shown
+in Fig.~\ref{sumprod_00}. As only the cells themselves are selected, but not
+the temporary wire {\tt \$1\_Y}, the two adders are shown as two disjunct
+parts. This can be very useful for global signal like clock and reset signals: just
+unselect them using a command such as {\tt select -del clk rst} and each cell
+using them will get its own net label.
+
+In this case however we would like to see the cells connected properly. This
+can be achieved using the {\tt \%x} action, that broadens the selection, i.e.
+for each selected wire it selects all cells connected to the wire and vice
+versa. So {\tt show a:sumstuff \%x} yields the diagram schon in Fig.~\ref{sumprod_01}.
+
+\begin{figure}[t]
+\includegraphics[width=\linewidth]{APPNOTE_011_Design_Investigation/sumprod_01.pdf}
+\caption{Output of {\tt show a:sumstuff \%x} on Fig.~\ref{sumprod}}
+\label{sumprod_01}
+\end{figure}
 
 \FIXME{}
 
-\subsection{Boolean operations on selections}
+\subsection{Selecting logic cones}
 
 \FIXME{}
 
@@ -456,7 +520,7 @@ matching different properties.
 \section{Advanced investigation techniques}
 \label{poke}
 
-\FIXME{} --- eval, sat
+\FIXME{} --- submod, eval, sat
 
 \section{Conclusion}
 \label{conclusion}