Progress on AppNote 011

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}

manual/APPNOTE_011_Design_Investigation/.gitignore

@@ -5,3 +5,5 @@ example_03.dot
 cmos_00.dot
 cmos_01.dot
 splice.dot
+sumprod_00.dot
+sumprod_01.dot

manual/APPNOTE_011_Design_Investigation/foobaraddsub.v

@@ -0,0 +1,8 @@
+module foobaraddsub(a, b, c, d, fa, fs, ba, bs);
+  input [7:0] a, b, c, d;
+  output [7:0] fa, fs, ba, bs;
+  assign fa = a + (* foo *) b;
+  assign fs = a - (* foo *) b;
+  assign ba = c + (* bar *) d;
+  assign bs = c - (* bar *) d;
+endmodule

manual/APPNOTE_011_Design_Investigation/make.sh

@@ -3,7 +3,9 @@
 ../../yosys -p 'proc; opt; show -format dot -prefix splice' splice.v
 ../../yosys -p 'techmap; abc -liberty ../../techlibs/cmos/cmos_cells.lib;; show -format dot -prefix cmos_00' cmos.v
 ../../yosys -p 'techmap; splitnets -ports; abc -liberty ../../techlibs/cmos/cmos_cells.lib;; show -lib ../../techlibs/cmos/cmos_cells.v -format dot -prefix cmos_01' cmos.v
-sed -i '/^label=/ d;' example_*.dot splice.dot cmos_*.dot
+../../yosys -p 'opt; cd sumprod; select a:sumstuff; show -format dot -prefix sumprod_00' sumprod.v
+../../yosys -p 'opt; cd sumprod; select a:sumstuff %x; show -format dot -prefix sumprod_01' sumprod.v
+sed -i '/^label=/ d;' example_*.dot splice.dot cmos_*.dot sumprod_*.dot
 dot -Tpdf -o example_00.pdf example_00.dot
 dot -Tpdf -o example_01.pdf example_01.dot
 dot -Tpdf -o example_02.pdf example_02.dot
@@ -11,3 +13,5 @@ dot -Tpdf -o example_03.pdf example_03.dot
 dot -Tpdf -o splice.pdf splice.dot
 dot -Tpdf -o cmos_00.pdf cmos_00.dot
 dot -Tpdf -o cmos_01.pdf cmos_01.dot
+dot -Tpdf -o sumprod_00.pdf sumprod_00.dot
+dot -Tpdf -o sumprod_01.pdf sumprod_01.dot

manual/APPNOTE_011_Design_Investigation/sumprod.v

@@ -0,0 +1,12 @@
+module sumprod(a, b, c, sum, prod);
+
+  input [7:0] a, b, c;
+  output [7:0] sum, prod;
+
+  {* sumstuff *}
+  assign sum = a + b + c;
+  {* *}
+
+  assign prod = a * b * c;
+
+endmodule

passes/cmds/select.cc

@@ -1036,6 +1036,10 @@ struct LsPass : public Pass {
 		log("\n");
 		log("If a pattern is given, the objects matching the pattern are printed\n");
 		log("\n");
+		log("Note that this command does not use the selection mechanism and always operates\n");
+		log("on the whole design or whole active module. Use 'select -list' to show a list\n");
+		log("of currently selected objects.\n");
+		log("\n");
 	}
 	virtual void execute(std::vector<std::string> args, RTLIL::Design *design)
 	{