Progress on AppNote 011

manual/APPNOTE_011_Design_Investigation.tex

@@ -427,6 +427,12 @@ Objects can not only be selected by their name but also by other properties.
 For example {\tt select t:\$add} will select all cells of type {\tt \$add}. In
 this case this is also yields the diagram shown in Fig.~\ref{seladd}.
 
+\begin{figure}[b]
+\lstinputlisting{APPNOTE_011_Design_Investigation/foobaraddsub.v}
+\caption{Test module for operations on selections}
+\label{foobaraddsub}
+\end{figure}
+
 The output of {\tt help select} contains a complete syntax reference for
 matching different properties.
 
@@ -437,14 +443,25 @@ 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.
+Normally the {\tt select} command overwrites a previous selection. The
+commands {\tt select -add} and {\tt select -del} can be used to add
+or remove objects from the current selection.
+
+The command {\tt select -clear} can be used to reset the selection to the
+default, which is a complete selection of everything in the current module.
 
 \subsection{Operations on selections}
 
+\begin{figure}[t]
+\lstinputlisting{APPNOTE_011_Design_Investigation/sumprod.v}
+\caption{Another test module for operations on selections}
+\label{sumprod}
+\end{figure}
+
 \begin{figure}[b]
-\lstinputlisting{APPNOTE_011_Design_Investigation/foobaraddsub.v}
-\caption{Test module for operations on selections}
-\label{foobaraddsub}
+\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}
 
 The {\tt select} command is actually much more powerful than it might seem on
@@ -464,31 +481,20 @@ 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:
+For example the {\tt \%i} arguments pops the last two elements from
+the stack, intersects them, and pushed the result back 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 \{* ... *\}}
+The listing in Fig.~\ref{sumprod} uses 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
@@ -507,11 +513,144 @@ versa. So {\tt show a:sumstuff \%x} yields the diagram schon in Fig.~\ref{sumpro
 \label{sumprod_01}
 \end{figure}
 
-\FIXME{}
-
 \subsection{Selecting logic cones}
 
-\FIXME{}
+Fig.~\ref{sumprod_01} shows what is called the {\it input cone\/} of {\tt sum}, i.e.
+all cells and signals that are used to generate the signal {\tt sum}. The {\tt \%ci}
+action can be used to select the input cones of all object in the top selection
+in the stack maintained by the {\tt select} command.
+
+As the {\tt \%x} action, this commands broadens the selection by one "`step"'. But
+this time to operation inly works against the direction of data flow. That means,
+wires only select cells via output ports and cells only select wires via input ports.
+
+Fig.~\ref{select_prod} show the sequence of diagrams generated by the following
+commands:
+
+\begin{verbatim}
+show prod
+show prod %ci
+show prod %ci %ci
+show prod %ci %ci %ci
+\end{verbatim}
+
+When selecting many levels of logic, repeating {\tt \%ci} over and over again
+can be a bit dull. So there is a shortcut for that: the number of iterations
+can be appended to the action. So for example the action {\tt \%ci3} is
+identical to performing the {\tt \%ci} action three times.
+
+The action {\tt \%ci*} performs the {\tt \%ci} action over and over again until
+it has no effect anymore.
+
+\begin{figure}[t]
+\hfill \includegraphics[width=4cm,trim=0 1cm 0 1cm]{APPNOTE_011_Design_Investigation/sumprod_02.pdf} \\
+\includegraphics[width=\linewidth,trim=0 0cm 0 1cm]{APPNOTE_011_Design_Investigation/sumprod_03.pdf} \\
+\includegraphics[width=\linewidth,trim=0 0cm 0 1cm]{APPNOTE_011_Design_Investigation/sumprod_04.pdf} \\
+\includegraphics[width=\linewidth,trim=0 2cm 0 1cm]{APPNOTE_011_Design_Investigation/sumprod_05.pdf} \\
+\caption{Objects selected by {\tt select prod \%ci...}}
+\label{select_prod}
+\end{figure}
+
+\medskip
+
+In most cases there are certain cell types and/or ports that should not be considered for the {\tt \%ci}
+action, or we only want to follow certain cell types and/or ports. This can be achieved using additional
+patterns that can be appended to the {\tt \%ci} action.
+
+Lets consider the design from Fig.~\ref{memdemo_src}. It serves no purpose other than being a non-trivial
+circuit for demonstrating the usage of {\tt \%ci} pattern. We synthesize the circuit using {\tt proc;
+opt; memory; opt} and change to the {\tt memdemo} module with {\tt cd memdemo}. If we type {\tt show}
+now we see the diagram shown in Fig.~\ref{memdemo_00}.
+
+\begin{figure}[b!]
+\lstinputlisting{APPNOTE_011_Design_Investigation/memdemo.v}
+\caption{Demo circuit for demonstrating cell/port pattern in {\tt \%ci} actions}
+\label{memdemo_src}
+\end{figure}
+
+\begin{figure*}[t]
+\includegraphics[width=\linewidth,trim=0 0cm 0 0cm]{APPNOTE_011_Design_Investigation/memdemo_00.pdf} \\
+\caption{Complete circuit diagram for the design shown in Fig.~\ref{memdemo_src}}
+\label{memdemo_00}
+\end{figure*}
+
+But maybe we are only interested in the tree of multiplexers that select the
+output value. In order to get there, we would start by just showing the output signal
+and its immediate predecessors:
+
+\begin{verbatim}
+show y %ci2
+\end{verbatim}
+
+From this we would learn that {\tt y} is driven by a {\tt \$dff cell}, that
+{\tt y} is connected to the output port {\tt Q}, that the {\tt clk} signal goes
+into the {\tt CLK} input port of the cell, and that the data comes from a
+auto-generated wire into the input {\tt D} of the flip-flop cell.
+
+As we are not interested in the clock signal we add an additional pattern to the {\tt \%ci}
+action, that tells it to only follow ports {\tt Q} and {\tt D} of {\tt \$dff} cells:
+
+\begin{verbatim}
+show y %ci2:+$dff[Q,D]
+\end{verbatim}
+
+To add a pattern we add a colon followed by the pattern to the {\tt \%ci}
+action. The pattern it self starts with {\tt -} or {\tt +}, indicating if it is
+an include or exclude pattern, followed by an optional comma separated list
+of cell types, followed by an optional comma separated list of port names in
+square brackets.
+
+Since we know that the only cell considered in this case we could as well only
+specify the port names:
+
+\begin{verbatim}
+show y %ci2:+[Q,D]
+\end{verbatim}
+
+Or we could decide to tell the {\tt \%ci} action to not follow the {\tt CLK} input:
+
+\begin{verbatim}
+show y %ci2:-[CLK]
+\end{verbatim}
+
+\begin{figure}[b]
+\includegraphics[width=\linewidth,trim=0 0cm 0 0cm]{APPNOTE_011_Design_Investigation/memdemo_01.pdf} \\
+\caption{Output of {\tt show y \%ci2:+\$dff[Q,D] \%ci*:-\$mux[S]:-\$dff}}
+\label{memdemo_01}
+\end{figure}
+
+Next we would investigate the next logic level by adding another {\tt \%ci2} to
+the command:
+
+\begin{verbatim}
+show y %ci2:-[CLK] %ci2
+\end{verbatim}
+
+From this we would learn that the next cell is a {\tt \$mux} cell and we would add additional
+pattern to narrow the selection on the path we are interested. In the end we would end up
+with a commands such as
+
+\begin{verbatim}
+show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff
+\end{verbatim}
+
+in which the first {\tt \%ci} jumps over the initial d-type flip-flop and the
+2nd action selects the entire input cone without going multiplexer select
+inputs and flip-flop cells. The diagram produces by this command is shown in
+Fig.~\ref{memdemo_01}.
+
+\medskip
+
+Similar to {\tt \%ci} exists an action {\tt \%co} to select output cones that
+accepts the same syntax for pattern and repetition. The {\tt \%x} action mentioned
+previously also accepts this advanced syntax.
+
+This actions for traversing the circuit graph, combined with the actions for
+boolean operations such as intersection ({\tt \%i}) and difference ({\tt \%d})
+are a powerful tool for extracting the relevant portions of the circuit under
+investigation.
+
+See {\tt help select} for a complete list of actions available in selections.
 
 \subsection{Storing and recalling selections}
 

manual/APPNOTE_011_Design_Investigation/.gitignore

@@ -7,3 +7,9 @@ cmos_01.dot
 splice.dot
 sumprod_00.dot
 sumprod_01.dot
+sumprod_02.dot
+sumprod_03.dot
+sumprod_04.dot
+sumprod_05.dot
+memdemo_00.dot
+memdemo_01.dot

manual/APPNOTE_011_Design_Investigation/make.sh

@@ -5,7 +5,13 @@
 ../../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
 ../../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
+../../yosys -p 'opt; cd sumprod; select prod; show -format dot -prefix sumprod_02' sumprod.v
+../../yosys -p 'opt; cd sumprod; select prod %ci; show -format dot -prefix sumprod_03' sumprod.v
+../../yosys -p 'opt; cd sumprod; select prod %ci2; show -format dot -prefix sumprod_04' sumprod.v
+../../yosys -p 'opt; cd sumprod; select prod %ci3; show -format dot -prefix sumprod_05' sumprod.v
+../../yosys -p 'proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_00' memdemo.v
+../../yosys -p 'proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_01 y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff' memdemo.v
+sed -i '/^label=/ d;' example_*.dot splice.dot cmos_*.dot sumprod_*.dot memdemo_*.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
@@ -15,3 +21,9 @@ 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
+dot -Tpdf -o sumprod_02.pdf sumprod_02.dot
+dot -Tpdf -o sumprod_03.pdf sumprod_03.dot
+dot -Tpdf -o sumprod_04.pdf sumprod_04.dot
+dot -Tpdf -o sumprod_05.pdf sumprod_05.dot
+dot -Tpdf -o memdemo_00.pdf memdemo_00.dot
+dot -Tpdf -o memdemo_01.pdf memdemo_01.dot

manual/APPNOTE_011_Design_Investigation/memdemo.v

@@ -0,0 +1,19 @@
+module memdemo(clk, d, y);
+
+input clk;
+input [3:0] d;
+output reg [3:0] y;
+
+integer i;
+reg [1:0] s1, s2;
+reg [3:0] mem [0:3];
+
+always @(posedge clk) begin
+    for (i = 0; i < 4; i = i+1)
+        mem[i] <= mem[(i+1) % 4] + mem[(i+2) % 4];
+    { s2, s1 } = d ? { s1, s2 } ^ d : 0;
+    mem[s1] <= d;
+    y <= mem[s2];
+end
+
+endmodule