path: root/manual
diff options
Diffstat (limited to 'manual')
4 files changed, 122 insertions, 5 deletions
diff --git a/manual/APPNOTE_011_Design_Investigation.tex b/manual/APPNOTE_011_Design_Investigation.tex
index 1dc9459f..9791ef79 100644
--- a/manual/APPNOTE_011_Design_Investigation.tex
+++ b/manual/APPNOTE_011_Design_Investigation.tex
@@ -79,7 +79,20 @@ external viewer can be used.
\section{Introduction to the {\tt show} command}
+The {\tt show} command generates a circuit diagram for the design in its
+current state. Various options can be used to change the appearance of the
+circuit diagram, set the name and format for the output file, and so forth.
+When called without any special options, it saves the circuit diagram in
+a temporary file and launches {\tt yosys-svgviewer} to display the diagram.
+Subsequent calls to {\tt show} re-use the {\tt yosys-svgviewer} instance
+(if still running).
+Fig.~\ref{example_src} shows a simple synthesis script and Verilog file that
+demonstrates the usage of {\tt show} in a simple setting. Note that {\tt show}
+is called with the {\tt -pause} option, that halts execution of the Yosys
+script until the user presses the Enter key. The {\tt show -pause} command
+also allows the user to enter an interactive shell to further investigate the
+circuit before continuing synthesis.
@@ -99,18 +112,110 @@ module example(input clk, a, b, c,
y <= c ? a + b : 2'd0;
-\caption{Synthesis script with added show commands and example code}
+\caption{Yosys script with {\tt show} commands and example design}
+So this script, when executed, will show the design after each of the three
+synthesis commands. The generated circuit diagrams are shown in Fig.~\ref{example_out}.
+The first diagram (from top to bottom) shows the design directly after being
+read by the Verilog front-end. Input and output ports are visualized using
+octagonal shapes. Cells are visualized as rectangles with inputs on the left
+and outputs on the right side. The cell labels are two lines long: The first line
+contains the cell name (or a {\tt \_<number\_} placeholder for cells without
+a name from the original Verilog, such as cells created from Verilog
+expressions) and the second line contains the cell type. Internal cell types
+are prefixed with a dollar sign. The Yosys manual contains a chapter on the
+internal cell library used in Yosys.
+Constants are shown as ellipses with the constant value as label. The syntax
+{\tt <bit\_width>'<bits>} is used for for constants that are not 32-bit wide
+and/or contain bits that are not 0 or 1 (but {\tt x} or {\tt z}). Ordinary
+32-bit constants are written using decimal numbers.
+Single-bit signals are shown as thin arrows pointing from the driver to the
+load. Signals that are multiple bits wide are shown as think arrows.
+Finally {\it processes\/} are shown in boxes with round corners. Processes
+are Yosys' internal representation of the decision-trees and synchronization
+events modelled in a Verilog {\tt always}-block. The label reads {\tt PROC} in the
+first line and contains the source code location of the original {\tt
+always}-block in the 2nd line. Not how the multiplexer from the {\tt ?:}-expression
+is represented as a {\tt \$mux} cell but the multiplexer from the {\tt if}-statement
+is yet still hidden within the process.
+The {\tt proc} command transforms the process from the first diagram into a
+multiplexer and a d-type flip-flip, which brings us to the 2nd diagram.
+Note that the auto-generated numbers for the cells have changed since the first
+diagram, because they are just placeholders . We will cover how to avoid this
+later in this document.
-\caption{\tt Output of the three show commands from Fig.~\ref{example_src}}
+\caption{Output of the three {\tt show} commands from Fig.~\ref{example_src}}
+Also note that the design now contains two instances of a {\tt BUF}-node. The
+Rhombus shape to the right is a dangling wire. (Wire nodes are only shown if
+they are dangling or have names assigned from the Verilog input.) This are
+artefacts left behind by the {\tt proc}-command. It is quite usual to see such
+artefacts after calling commands that perform changes in the design, as most
+commands only care about doing the transformation in a foolproof way, not about
+cleaning up after them. The next call to {\tt clean} (or {\tt opt}, which
+includes {\tt clean} as one of its operations) will clean up this artefacts.
+This operation is so common in Yosys scripts that it can simply be abbreviated
+by using the {\tt ;;} token, which doubles as separator for commands. Unless
+one wants to specifically analyze this artefacts left behind some operations,
+it is therefore recommended to call {\tt clean} before calling {\tt show}.
+In this script we directly call {\tt opt} as next step, which finally leads us to
+the 3rd diagram in Fig.~\ref{example_out}. Here we see that the {\tt opt} command
+not only has removed the artifacts left behind by {\tt proc}, but also determined
+correctly that it can remove the first {\tt \$mux} cell without changing the behavior
+of the circuit.
+\includegraphics[width=\linewidth,trim=0 2cm 0 0]{APPNOTE_011_Design_Investigation/splice.pdf}
+\caption{Output of {\tt yosys -p 'proc; opt; show' splice.v}}
+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}};
+\caption{\tt splice.v}
+\FIXME{} --- Splicing, Cell libraries
+\section{Navigating the design}
+\FIXME{} --- cd and ls, multi-page diagrams, select, cones and boolean operations
+\section{Advanced investigation techniques}
+\FIXME{} --- dump, eval, sat
diff --git a/manual/APPNOTE_011_Design_Investigation/.gitignore b/manual/APPNOTE_011_Design_Investigation/.gitignore
index 6d396bb3..b6fb3068 100644
--- a/manual/APPNOTE_011_Design_Investigation/.gitignore
+++ b/manual/APPNOTE_011_Design_Investigation/.gitignore
@@ -1,3 +1,4 @@
diff --git a/manual/APPNOTE_011_Design_Investigation/ b/manual/APPNOTE_011_Design_Investigation/
index 31820695..60c6c6be 100644
--- a/manual/APPNOTE_011_Design_Investigation/
+++ b/manual/APPNOTE_011_Design_Investigation/
@@ -1,6 +1,8 @@
../../yosys example.ys
-sed -i '/^label=/ d;' example_*.dot
+../../yosys -p 'proc; opt; show -format dot -prefix splice' splice.v
+sed -i '/^label=/ d;' example_*.dot
dot -Tpdf -o example_00.pdf
dot -Tpdf -o example_01.pdf
dot -Tpdf -o example_02.pdf
+dot -Tpdf -o splice.pdf
diff --git a/manual/APPNOTE_011_Design_Investigation/splice.v b/manual/APPNOTE_011_Design_Investigation/splice.v
new file mode 100644
index 00000000..b6796c51
--- /dev/null
+++ b/manual/APPNOTE_011_Design_Investigation/splice.v
@@ -0,0 +1,9 @@
+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}};