3 % http://ftp.univie.ac.at/packages/tex/macros/latex/contrib/IEEEtran/IEEEtran_HOWTO.pdf
4 \documentclass[9pt,technote,
a4paper]{IEEEtran
}
6 \usepackage[T1]{fontenc} % required for luximono!
7 \usepackage[scaled=
0.8]{luximono
} % typewriter font with bold face
9 % To install the luximono font files:
10 % getnonfreefonts-sys --all or
11 % getnonfreefonts-sys luximono
13 % when there are trouble you might need to:
14 % - Create /etc/texmf/updmap.d/99local-luximono.cfg
15 % containing the single line: Map ul9.map
16 % - Run update-updmap followed by mktexlsr and updmap-sys
18 % This commands must be executed as root with a root environment
19 % (i.e. run "sudo su" and then execute the commands in the root
20 % shell, don't just prefix the commands with "sudo").
22 \usepackage[unicode,bookmarks=false
]{hyperref
}
23 \usepackage[english
]{babel
}
24 \usepackage[utf8
]{inputenc}
33 \usepackage{algpseudocode
}
45 \usetikzlibrary{arrows
}
46 \usetikzlibrary{scopes
}
47 \usetikzlibrary{through
}
48 \usetikzlibrary{shapes.geometric
}
50 \def\FIXME{{\color{red
}\bf FIXME
}}
52 \lstset{basicstyle=
\ttfamily,frame=trBL,xleftmargin=
2em,xrightmargin=
1em,numbers=left
}
56 \title{Yosys Application Note
011: \\ Interactive Design Investigation
}
57 \author{Clifford Wolf \\ November
2013}
61 Yosys
\cite{yosys
} can be a great environment for building custom synthesis
62 flows
\cite{glaserwolf
}. It can also be an excellent tool for teaching and
63 learning Verilog based RTL synthesis. In both applications it is of great
64 importance to be able to analyze the designs it produces easily.
66 This Yosys application note covers the generation of circuit diagrams with the
67 Yosys
{\tt show
} command, the selection of interesting parts of the circuit
68 using the
{\tt select
} command, and briefly discusses advanced commands for
69 investigating the actual behavior of circuits.
72 \section{Installation and Prerequisites
}
74 This Application Note is based on GIT Rev.
{\tt \FIXME} from
\FIXME{} of
75 Yosys
\cite{yosys
}. The
{\tt README
} file covers how to install Yosys. The
76 {\tt show
} command requires a working installation of GraphViz
\cite{graphviz
}
77 for generating the actual circuit diagrams. Yosys must be build with Qt
78 support in order to activate the built-in SVG viewer. Alternatively an
79 external viewer can be used.
83 This application note is structured as follows:
85 Sec.~
\ref{intro_show
} introduces the
{\tt show
} command and explains the
86 symbols used in the circuit diagrams generated by it.
88 Sec.~
\ref{navigate
} introduces additional commands used to navigate in the
89 design and select portions of the design and print additional information on
90 the elements in the design that are not contained in the circuit diagrams.
92 Sec.~
\ref{poke
} introduces commands to evaluate the design and solve SAT
93 problems within the design.
95 Sec.~
\ref{conclusion
} concludes the
document and summarizes the key points.
97 \section{Introduction to the
{\tt show
} command
}
103 read_verilog example.v
111 module example(input clk, a, b, c,
113 always @(posedge clk)
115 y <= c ? a + b :
2'd0;
118 \caption{Yosys script with
{\tt show
} commands and example design
}
123 \includegraphics[width=
\linewidth]{APPNOTE_011_Design_Investigation/example_00.pdf
}
124 \includegraphics[width=
\linewidth]{APPNOTE_011_Design_Investigation/example_01.pdf
}
125 \includegraphics[width=
\linewidth]{APPNOTE_011_Design_Investigation/example_02.pdf
}
126 \caption{Output of the three
{\tt show
} commands from Fig.~
\ref{example_src
}}
130 The
{\tt show
} command generates a circuit diagram for the design in its
131 current state. Various options can be used to change the appearance of the
132 circuit diagram, set the name and format for the output file, and so forth.
133 When called without any special options, it saves the circuit diagram in
134 a temporary file and launches
{\tt yosys-svgviewer
} to display the diagram.
135 Subsequent calls to
{\tt show
} re-use the
{\tt yosys-svgviewer
} instance
138 \subsection{A simple circuit
}
140 Fig.~
\ref{example_src
} shows a simple synthesis script and Verilog file that
141 demonstrates the usage of
{\tt show
} in a simple setting. Note that
{\tt show
}
142 is called with the
{\tt -pause
} option, that halts execution of the Yosys
143 script until the user presses the Enter key. The
{\tt show -pause
} command
144 also allows the user to enter an interactive shell to further investigate the
145 circuit before continuing synthesis.
147 So this script, when executed, will show the design after each of the three
148 synthesis commands. The generated circuit diagrams are shown in Fig.~
\ref{example_out
}.
150 The first diagram (from top to bottom) shows the design directly after being
151 read by the Verilog front-end. Input and output ports are visualized using
152 octagonal shapes. Cells are visualized as rectangles with inputs on the left
153 and outputs on the right side. The cell labels are two lines long: The first line
154 contains a unique identifier for the cell and the second line contains the cell
155 type. Internal cell types are prefixed with a dollar sign. The Yosys manual
156 contains a chapter on the internal cell library used in Yosys.
158 Constants are shown as ellipses with the constant value as label. The syntax
159 {\tt <bit
\_width>'<bits>
} is used for for constants that are not
32-bit wide
160 and/or contain bits that are not
0 or
1 (but
{\tt x
} or
{\tt z
}). Ordinary
161 32-bit constants are written using decimal numbers.
163 Single-bit signals are shown as thin arrows pointing from the driver to the
164 load. Signals that are multiple bits wide are shown as think arrows.
166 Finally
{\it processes\/
} are shown in boxes with round corners. Processes
167 are Yosys' internal representation of the decision-trees and synchronization
168 events modelled in a Verilog
{\tt always
}-block. The label reads
{\tt PROC
}
169 followed by a unique identifier in the first line and contains the source code
170 location of the original
{\tt always
}-block in the
2nd line. Note how the
171 multiplexer from the
{\tt ?:
}-expression is represented as a
{\tt \$mux
} cell
172 but the multiplexer from the
{\tt if
}-statement is yet still hidden within the
177 The
{\tt proc
} command transforms the process from the first diagram into a
178 multiplexer and a d-type flip-flip, which brings us to the
2nd diagram.
180 The Rhombus shape to the right is a dangling wire. (Wire nodes are only shown
181 if they are dangling or have "`public"' names, for example names assigned from
182 the Verilog input.) Also note that the design now contains two instances of a
183 {\tt BUF
}-node. This are artefacts left behind by the
{\tt proc
}-command. It is
184 quite usual to see such artefacts after calling commands that perform changes
185 in the design, as most commands only care about doing the transformation in the
186 least complicated way, not about cleaning up after them. The next call to
{\tt
187 clean
} (or
{\tt opt
}, which includes
{\tt clean
} as one of its operations) will
188 clean up this artefacts. This operation is so common in Yosys scripts that it
189 can simply be abbreviated by using the
{\tt ;;
} token, which doubles as
190 separator for commands. Unless one wants to specifically analyze this artefacts
191 left behind some operations, it is therefore recommended to call
{\tt clean
}
192 before calling
{\tt show
}.
196 In this script we directly call
{\tt opt
} as next step, which finally leads us to
197 the
3rd diagram in Fig.~
\ref{example_out
}. Here we see that the
{\tt opt
} command
198 not only has removed the artifacts left behind by
{\tt proc
}, but also determined
199 correctly that it can remove the first
{\tt \$mux
} cell without changing the behavior
203 \includegraphics[width=
\linewidth,trim=
0 2cm
0 0]{APPNOTE_011_Design_Investigation/splice.pdf
}
204 \caption{Output of
{\tt yosys -p 'proc; opt; show' splice.v
}}
209 \lstinputlisting{APPNOTE_011_Design_Investigation/splice.v
}
210 \caption{\tt splice.v
}
215 \includegraphics[height=
\linewidth]{APPNOTE_011_Design_Investigation/cmos_00.pdf
}
216 \includegraphics[width=
\linewidth]{APPNOTE_011_Design_Investigation/cmos_01.pdf
}
217 \caption{Effects of
{\tt splitnets
} command and of providing a cell library. (The
218 circuit is a half-adder built from simple CMOS gates.)
}
219 \label{splitnets_libfile
}
222 \subsection{Break-out boxes for signal vectors
}
224 As has been indicated by the last example, Yosys is can manage signal vectors (aka.
225 multi-bit wires or buses) as native objects. This provides great advantages
226 when analyzing circuits that operate on wide integers. But it also introduces
227 some additional complexity when the individual bits of of a signal vector need
228 to be accessed. The example show in Fig.~
\ref{splice_dia
} and
\ref{splice_src
}
229 demonstrates how such circuits are visualized by the
{\tt show
} command.
231 The key elements in understanding this circuit diagram are of course the boxes
232 with round corners and rows labeled
{\tt <MSB
\_LEFT>:<LSB
\_LEFT> -- <MSB
\_RIGHT>:<LSB
\_RIGHT>
}.
233 Each of this boxes has one signal per row on one side and a common signal for all rows on the
234 other side. The
{\tt <MSB>:<LSB>
} tuples specify which bits are broken out from the signals
235 and are connected. So The top row of the box connecting the signals
{\tt a
} and
{\tt b
} indicates
236 that the bit
0 (i.e. the range
0:
0) from signal
{\tt a
} is connected to bit
1 (i.e. the range
237 1:
1) of signal
{\tt x
}.
239 Lines connecting such boxes together and lines connecting such boxes to cell
240 ports have slightly different look to emphasise that they are not actual signal
241 wires but a necessity of the graphical representation. This distinction seems
242 like a technicality, until one wants to debug a problem related to the way
243 Yosys internally represents signal vectors, for example when writing custom
246 \subsection{Gate level netlists
}
248 Finally Fig.~
\ref{splitnets_libfile
} shows two common pitfalls when working
249 with designs mapped to a cell library. The top figure has two problems: First
250 Yosys did not have access to the cell library when this diagram was generated,
251 resulting in all cell ports defaulting to being inputs. This is why all ports
252 are drawn on the left side the cells are awkwardly arranged in a large column.
253 Secondly the two-bit vector
{\tt y
} requires breakout-boxes for its individual
254 bits, resulting in an unnecessary complex diagram.
256 For the
2nd diagram Yosys has been given a description of the cell library as
257 Verilog file containing blackbox modules. There are two ways to load cell
258 descriptions into Yosys: First the Verilog file for the cell library can be
259 passed directly to the
{\tt show
} command using the
{\tt -lib <filename>
}
260 option. Secondly it is possible to load cell libraries into the design with
261 the
{\tt read
\_verilog -lib <filename>
} command. The later option has the great
262 advantage that the library only needs to be loaded once and can then be used
263 in all subsequent calls to the
{\tt show
} command.
265 In addition to that the
2nd diagram was generated after
{\tt splitnet -ports
}
266 was run on the design. This command splits all signal vectors into individual
267 signal bits, which is often desirable when looking at gate-level circuits. The
268 {\tt -ports
} option is required to also split module ports. Per default the
269 command only operates on interior signals.
271 \subsection{Miscellaneous notes
}
273 Per default the
{\tt show
} command outputs a temporary SVG file and launches
274 {\tt yosys-svgviewer
} to display it. The options
{\tt -format
},
{\tt -viewer
}
275 and
{\tt -prefix
} can be used to change format, viewer and filename prefix.
276 Note that the
{\tt pdf
} and
{\tt ps
} format are the only formats that support
277 plotting multiple modules in one run.
279 In
{\tt yosys-svgviewer
} the left mouse button is per default bound to move the
280 diagram (and the mouse wheel can be used for zooming in and out). However, in
281 some cases one wants to copy text from the diagram. In this cases the
282 View->Interactive checkbox must be activated. This switch the rendering back-end
283 to one that supports interaction with the SVG file, such as selecting text.
285 In densely connected circuits it is sometimes hard to keep track of the
286 individual signal wires. For this cases it can be useful to call
{\tt show
}
287 with the
{\tt -colors <integer>
} argument, which randomly assigns colors to the
288 nets. The integer (>
0) is used as seed value for the random number
289 generation. Sometimes it is necessary it try some values to find an assignment
290 of colors that works.
292 The command
{\tt help show
} prints a complete listing of all options supported
293 by the
{\tt show
} command.
295 \section{Navigating the design
}
298 Plotting circuit diagrams for entire modules in the design brings us only so
299 far. For complex modules the generated circuit diagrams are just stupidly big
300 and are no help at all. In such cases one first has to select the relevant
301 portions of the circuit.
303 In addition to
{\it what\/
} to display one only needs to carefully decide
304 {\it when\/
} to display it, with respect to the synthesis flow. In general
305 it is a good idea to troubleshoot a circuit in the earliest state where
306 a problem can be reproduces. So if for example internal state before calling
307 the
{\tt techmap
} command already fails to verify, it is better to troubleshoot
308 the coarse-grain version of the circuit before
{\tt techmap
} than the gate-level
309 circuit after
{\tt techmap
}.
313 Note: It is generally recommended to verify the internal state of a design by
314 writing it to a Verilog file using
{\tt write
\_verilog -noexpr
} and using the
315 simulation models from
{\tt simlib.v
} and
{\tt simcells.v
} from the Yosys data
316 directory (see
{\tt yosys-config -
{}-datdir
}).
318 \subsection{Interactive Navigation
}
345 \caption{Demonstration of
{\tt ls
} and
{\tt cd
} using
{\tt example.v
} from Fig.~
\ref{example_src
}}
351 attribute
\src "example.v:
5"
352 cell $add $add$example.v:
5$
2
353 parameter
\A_SIGNED 0
355 parameter
\B_SIGNED 0
360 connect
\Y $add$example.v:
5$
2_Y
363 \caption{Output of
{\tt dump \$
2} using the design from Fig.~
\ref{example_src
} and Fig.~
\ref{example_out
}}
367 Once the right state within the synthesis flow for debugging the circuit has
368 been identified, it is recommended to simply add the
{\tt shell
} command
369 to the matching place in the synthesis script. This command will stop the
370 synthesis at the specified moment and go to shell mode, where the user can
371 interactively enter commands.
373 For most cases, the shell will start with the whole design selected (i.e. when
374 the synthesis script does not already narrow the selection). The command
{\tt
375 ls
} can now be used to create a list of all modules. The command
{\tt cd
} can
376 be used to switch to one of the modules (type
{\tt cd ..
} to switch back). Now
377 the
{\tt ls
} command lists the objects within that module. Fig.~
\ref{lscd
}
378 demonstrates this using the design from Fig.~
\ref{example_src
}.
380 There is a thing to note in Fig.~
\ref{lscd
}: We can see that the cell names
381 from Fig.~
\ref{example_out
} are just abbreviations of the actual cell names,
382 namely the part after the last dollar-sign. Most auto-generated names (the ones
383 starting with a dollar sign) are rather long and contains some additional
384 information on the origin of the named object. But in most cases those names
385 can simply be abbreviated using the last part.
387 Usually all interactive work is done with one module selected using the
{\tt cd
}
388 command. But it is also possible to work from the design-context (
{\tt cd ..
}). In
389 this case all object names must be prefixed with
{\tt <module
\_name>/
}. For
390 example
{\tt a*/b*
} would refer to all objects whose names start with
{\tt b
} from
391 all modules whose names start with
{\tt a
}.
393 The
{\tt dump
} command can be used to print all information about an object.
394 For example
{\tt dump \$
2} will print Fig.~
\ref{dump2
}. This can for example
395 be useful to determine the names of nets connected to cells, as the net-names
396 are usually suppressed in the circuit diagram if they are auto-generated.
398 For the remainder of this
document we will assume that the commands are run from
399 module-context and not design-context.
401 \subsection{Working with selections
}
404 \includegraphics[width=
\linewidth]{APPNOTE_011_Design_Investigation/example_03.pdf
}
405 \caption{Output of
{\tt show
} after
{\tt select \$
2} or
{\tt select t:\$add
}
406 (see also Fig.~
\ref{example_out
})
}
410 When a module is selected using
{\tt cd
} command, all commands (with a few
411 exceptions, such as the
{\tt read
\_*
} and
{\tt write
\_*
} commands) operate
412 only on the selected module. So this can also be useful for synthesis scripts
413 where different synthesis strategies should be applied to different modules
416 But for most interactive work we want to further narrow the set of selected
417 objects. This can be done using the
{\tt select
} command.
419 For example, if the command
{\tt select \$
2} is executed, a subsequent
{\tt show
}
420 command will yield the diagram shown in Fig.~
\ref{seladd
}. Note that the nets are
421 now displayed in ellipses. This indicates that they are not selected, but only
422 shown because the diagram contains a cell that is connected to the net. This
423 of course makes no difference for the circuit that is shown, but it can be a useful
424 information when manipulating selections.
426 Objects can not only be selected by their name but also by other properties.
427 For example
{\tt select t:\$add
} will select all cells of type
{\tt \$add
}. In
428 this case this is also yields the diagram shown in Fig.~
\ref{seladd
}.
430 The output of
{\tt help select
} contains a complete syntax reference for
431 matching different properties.
433 Many commands can operate on explicit selections. For example the command
{\tt
434 dump t:\$add
} will print information on all
{\tt \$add
} cells in the active
435 module. Whenever a command has
{\tt [selection
]} as last argument in its usage
436 help, this means that it will use the engine behind the
{\tt select
} command
437 to evaluate additional arguments and use the resulting selection instead of
438 the selection performed by the last
{\tt select
} command.
440 The command
{\tt select -clear
} can be used to reset the selection.
442 \subsection{Operations on selections
}
445 \lstinputlisting{APPNOTE_011_Design_Investigation/foobaraddsub.v
}
446 \caption{Test module for operations on selections
}
450 The
{\tt select
} command is actually much more powerful than it might seem on
451 the first glimpse. When it is called with multiple arguments, each argument is
452 evaluated and pushed separately on a stack. After all arguments have been
453 processed it simply creates the union of all elements on the stack. So the
454 following command will select all
{\tt \$add
} cells and all objects with
455 the
{\tt foo
} attribute set:
461 (Try this with the design shown in Fig.~
\ref{foobaraddsub
}. Use the
{\tt
462 select -list
} command to list the current selection.)
464 In many cases simply adding more and more stuff to the selection is an
465 ineffective way of selecting the interesting part of the design. Special
466 arguments can be used to differently combine the elements on the stack.
467 For example the
{\tt \%i
} arguments intersects the last two elements on
468 the stack. So the following command will select all
{\$add
} cells that
469 have the
{\tt foo
} attribute set:
472 select t:$add a:foo
%i
476 \lstinputlisting{APPNOTE_011_Design_Investigation/sumprod.v
}
477 \caption{Another test module for operations on selections
}
481 The listing in Fig.~
\ref{sumprod
} used the Yosys non-standard
{\tt \
{* ... *\
}}
482 syntax to set the attribute
{\tt sumstuff
} on all cells generated by the first
483 assign statement. (This works on arbitrary large blocks of Verilog code an
484 can be used to mark portions of code for analysis.)
487 \includegraphics[width=
\linewidth]{APPNOTE_011_Design_Investigation/sumprod_00.pdf
}
488 \caption{Output of
{\tt show a:sumstuff
} on Fig.~
\ref{sumprod
}}
492 Selecting
{\tt a:sumstuff
} in this module will yield the circuit diagram shown
493 in Fig.~
\ref{sumprod_00
}. As only the cells themselves are selected, but not
494 the temporary wire
{\tt \$
1\_Y}, the two adders are shown as two disjunct
495 parts. This can be very useful for global signal like clock and reset signals: just
496 unselect them using a command such as
{\tt select -del clk rst
} and each cell
497 using them will get its own net label.
499 In this case however we would like to see the cells connected properly. This
500 can be achieved using the
{\tt \%x
} action, that broadens the selection, i.e.
501 for each selected wire it selects all cells connected to the wire and vice
502 versa. So
{\tt show a:sumstuff \%x
} yields the diagram schon in Fig.~
\ref{sumprod_01
}.
505 \includegraphics[width=
\linewidth]{APPNOTE_011_Design_Investigation/sumprod_01.pdf
}
506 \caption{Output of
{\tt show a:sumstuff \%x
} on Fig.~
\ref{sumprod
}}
512 \subsection{Selecting logic cones
}
516 \subsection{Storing and recalling selections
}
520 \section{Advanced investigation techniques
}
523 \FIXME{} --- submod, eval, sat
530 \begin{thebibliography
}{9}
533 Clifford Wolf. The Yosys Open SYnthesis Suite.
534 \url{http://www.clifford.at/yosys/
}
537 Johann Glaser. Clifford Wolf. Methodology and Example-Driven Interconnect
538 Synthesis for Designing Heterogeneous Coarse-Grain Reconfigurable
539 Architectures. In: Jan Haase (Editor).
{\it Models, Methods, and Tools for Complex Chip Design.
540 Lecture Notes in Electrical Engineering. Volume
265,
2014, pp
201-
221.\/
}
541 \href{http://dx.doi.org/
10.1007/
978-
3-
319-
01418-
0_12
}{DOI
10.1007/
978-
3-
319-
01418-
0\_12}
544 Graphviz - Graph Visualization Software.
545 \url{http://www.graphviz.org/
}
547 \end{thebibliography
}