riscv
/
yosys
mirror of https://github.com/YosysHQ/yosys.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Added Yosys Manual

This commit is contained in:
Clifford Wolf 2013-07-20 15:19:12 +02:00
parent 3650fd7fbe
commit 61ed6b32d1
48 changed files with 7949 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Makefile
View File

@ -100,9 +100,13 @@ install: $(TARGETS)
install-abc:
install yosys-abc /usr/local/bin/
manual:
cd manual && bash make.sh
clean:
rm -f $(OBJS) $(GENFILES) $(TARGETS)
rm -f libs/*/*.d frontends/*/*.d passes/*/*.d backends/*/*.d kernel/*.d
cd manual && rm *.aux *.bbl *.blg *.idx *.log *.out *.pdf *.toc
test ! -f libs/svgviewer/Makefile || make -C libs/svgviewer distclean
mrproper: clean
@ -137,6 +141,6 @@ config-gprof: clean
-include backends/*/*.d
-include kernel/*.d
.PHONY: all top-all abc test install install-abc clean mrproper qtcreator
.PHONY: all top-all abc test install install-abc manual clean mrproper qtcreator
.PHONY: config-clean config-clang-debug config-gcc-debug config-release

8
manual/.gitignore vendored Normal file
View File

@ -0,0 +1,8 @@
*.aux
*.bbl
*.blg
*.idx
*.log
*.out
*.pdf
*.toc

12
manual/CHAPTER_Appnotes.tex Normal file
View File

@ -0,0 +1,12 @@
\chapter{Application Notes}
\label{chapter:appnotes}
\begin{fixme}
This appendix will cover some typical use-cases of Yosys in the form of application notes.
\end{fixme}
\section{Synthesizing using a Cell Library in Liberty Format}
\section{Reverse Engeneering the MOS6502 from an NMOS Transistor Netlist}
\section{Reconfigurable Coarse-Grain Synthesis using Intersynth}

145
manual/CHAPTER_Approach.tex Normal file
View File

@ -0,0 +1,145 @@
\chapter{Approach}
\label{chapter:approach}
Yosys is a tool for synthesising (behavioural) Verilog HDL code to target architecture netlists. Yosys aims at a wide
range of application domains and thus must be flexible and easy to adapt to new tasks. This chapter covers the general
approach followed in the effort to implement this tool.
\section{Data- and Control-Flow}
The data- and control-flow of a typical synthesis-tool is very similar to the data- and control-flow of a typical
compiler: different subsystems are called in a predetermined order, each consuming the data generated by the
last subsystem and generating the data for the next subsystem (see Fig.~\ref{fig:approach_flow}).
\begin{figure}[b]
\hfil
\begin{tikzpicture}
\path (-1.5,3) coordinate (cursor);
\draw[-latex] ($ (cursor) + (0,-1.5) $) -- ++(1,0);
\draw[fill=orange!10] ($ (cursor) + (1,-3) $) rectangle node[rotate=90] {Frontend} ++(1,3) coordinate (cursor);
\draw[-latex] ($ (cursor) + (0,-1.5) $) -- ++(1,0);
\draw[fill=green!10] ($ (cursor) + (1,-3) $) rectangle node[rotate=90] {Pass} ++(1,3) coordinate (cursor);
\draw[-latex] ($ (cursor) + (0,-1.5) $) -- ++(1,0);
\draw[fill=green!10] ($ (cursor) + (1,-3) $) rectangle node[rotate=90] {Pass} ++(1,3) coordinate (cursor);
\draw[-latex] ($ (cursor) + (0,-1.5) $) -- ++(1,0);
\draw[fill=green!10] ($ (cursor) + (1,-3) $) rectangle node[rotate=90] {Pass} ++(1,3) coordinate (cursor);
\draw[-latex] ($ (cursor) + (0,-1.5) $) -- ++(1,0);
\draw[fill=orange!10] ($ (cursor) + (1,-3) $) rectangle node[rotate=90] {Backend} ++(1,3) coordinate (cursor);
\draw[-latex] ($ (cursor) + (0,-1.5) $) -- ++(1,0);
\path (-3,-0.5) coordinate (cursor);
\draw (cursor) -- node[below] {HDL} ++(3,0) coordinate (cursor);
\draw[|-|] (cursor) -- node[below] {Internal Format(s)} ++(8,0) coordinate (cursor);
\draw (cursor) -- node[below] {Netlist} ++(3,0);
\path (-3,3.5) coordinate (cursor);
\draw[-] (cursor) -- node[above] {High-Level} ++(3,0) coordinate (cursor);
\draw[-] (cursor) -- ++(8,0) coordinate (cursor);
\draw[->] (cursor) -- node[above] {Low-Level} ++(3,0);
\end{tikzpicture}
\caption{General data- and control-flow of a synthesis tool}
\label{fig:approach_flow}
\end{figure}
The first subsystem to be called is usually called a {\it frontend}. It does not process the data generated by
another subsystem but instead reads the user input; in the case of a HDL synthesis tool the behavioural
HDL code.
The subsystems that consume data from previous subsystems and produces data for the next subsystems (usually in the
same or a similar format) are called {\it passes}.
The last subsystem that is executed transforms the data generated by the last pass into a suitable output
format and writes it to a disk file. This subsystem is usually called the {\it backend}.
In Yosys all frontends, passes and backends are directly available as commands in the synthesis script. Thus
the user can easily create a custom synthesis flow just by calling passes in the right order in a synthesis
script.
\section{Internal Formats in Yosys}
Yosys uses two different internal formats. The first is used to store an abstract syntax tree (AST) of a verilog
input file. This format is simply called {\it AST} and is generated by the Verilog Frontend. This data structure
is then consumed by a subsystem called {\it AST Frontend}\footnote{In Yosys the term {\it pass} is only used to
refer to commands that operate on the RTLIL data structure.}. This AST Frontend then generates a design in Yosys'
main internal format, the Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does that
by first performing a number of simplifications within the AST representation and then generating RTLIL from
the simplified AST data structure.
The RTLIL representation is used by all passes as input and outputs. This has the following advantages over
using different representational formats between different passes:
\begin{itemize}
\item The passes can be re-arranged in a different order and passes can be removed or inserted.
\item Passes can simply pass-thru the parts of the design they don't change without the need
to convert between formats. In fact Yosys passes output the same data structure they received
as input and perform all changes in place.
\item All passes use the same interface, thus reducing the effort required to understand a pass
when reading the Yosys source code, e.g.~when adding additional features.
\end{itemize}
The RTLIL representation is basically a netlist representation with the following additional features:
\begin{itemize}
\item An internal cell library with fixed-function cells to represent RTL datapath and register cells as well
as logical gate-level cells (single-bit gates and registers).
\item Support for multi-bit values that can use individual bits from wires as well as constant bits to
represent coarse-grain netlists.
\item Support for basic behavioural constructs (if-then-else structures and multi-case switches with
a sensitivity list for updating the outputs).
\item Support for multi-port memories.
\end{itemize}
The use of RTLIL also has the disadvantage of having a very powerful format
between all passes, even when doing gate-level synthesis where the more
advanced features are not needed. In order to reduce complexity for passes that
operate on a low-level representation, these passes check the features used in
the input RTLIL and fail to run when non-supported high-level constructs are
used. In such cases a pass that transforms the higher-level constructs to
lower-level constructs must be called from the synthesis script first.
\section{Typical Use Case}
\label{sec:typusecase}
The following example script may be used in a synthesis flow to convert the behavioural Verilog code
from the input file {\tt design.v} to a gate-level netlist {\tt synth.v} using the cell library
described by the Liberty file \citeweblink{LibertyFormat} {\tt cells.lib}:
\begin{lstlisting}[language=sh,numbers=left,frame=single]
# read input file tpo internal representation
read_verilog design.v
# convert high-level behavioral parts ("processes") to d-type flip-flops and muxes
proc
# perform some simple optimizations
opt
# convert high-level memory constructs to d-type flip-flops and multiplexers
memory
# perform some simple optimizations
opt
# convert design to (logical) gate-level netlists
techmap
# perform some simple optimizations
opt
# map internal register types to the ones from the cell library
dfflibmap -liberty cells.lib
# use ABC to map remaining logic to cells from the cell library
abc -liberty cells.lib
# cleanup
opt
# write results to output file
write_verilog synth.v
\end{lstlisting}
A detailed description of the commands available in Yosys can be found in App.~\ref{commandref}.

35
manual/CHAPTER_Auxlibs.tex Normal file
View File

@ -0,0 +1,35 @@
\chapter{Auxilary Libraries}
The Yosys source distribution contains some auxilary libraries that are bundled
with Yosys.
\section{SHA1}
The files in {\tt libs/sha1/} provide a SHA1 implementation written by Micael
Hildenborg \citeweblink{smallsha1}. It is used for generating unique names when
specializing parameterized modules.
\section{BigInt}
The files in {\tt libs/bigint/} provide a library for performing arithmetic with
arbitrary length integers. It is written by Matt McCutchen \citeweblink{bigint}.
The BigInt library is used for evaluating constant expressions, e.g.~using the {\tt
ConstEval} class provided in {\tt kernel/consteval.h}.
\section{SubCircuit}
\label{sec:SubCircuit}
The files in {\tt libs/subcircuit} provide a library for solving the subcircuit
isomorphism problem. It is written by Clifford Wolf and based on the Ullmann
Subgraph Isomorphism Algorithm \cite{UllmannSubgraphIsomorphism}. It is used by
the {\tt extract} pass (see {\tt help extract} or Sec.~\ref{cmd:extract}).
\section{ezSAT}
The files in {\tt libs/ezsat} provide a library for simplifying generating CNF
formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT
library is written by Clifford Wolf. It is used by the {\tt sat} pass (see
{\tt help sat} or Sec.~\ref{cmd:sat}).

26
manual/CHAPTER_Auxprogs.tex Normal file
View File

@ -0,0 +1,26 @@
\chapter{Auxilary Programs}
Besides the main {\tt yosys} executable, the Yosys distribution contains a set
of additional helper programs.
\section{yosys-config}
The {\tt yosys-config} tool (an auto-generated shell-script) can be used to
query compiler options and other information needed for building loadable
modules for Yosys. FIXME: See Sec.~\ref{chapter:prog} for details.
\section{yosys-filterlib}
\label{sec:filterlib}
The {\tt yosys-filterlib} tool is a small utility that can be used to strip
or extract information from a Liberty file. See Sec.~\ref{sec:techmap_extern}
for details.
\section{yosys-svgviewer}
The {\tt yosys-svgviewer} tool is a small Qt program that can be used to view
SVG files. This tool is automatically launched by the {\tt show} command when
no {\tt -format} and no {\tt -viewer} option is passed to the command. See
{\tt help show} or Sec.~\ref{cmd:show} for details.

839
manual/CHAPTER_Basics.tex Normal file
View File

@ -0,0 +1,839 @@
\chapter{Basic Principles}
\label{chapter:basics}
This chapter contains a short introduction to the basic principles of digital
circuit synthesis.
\section{Levels of Abstraction}
Digital circuits can be represented at different levels of abstraction.
During the design process a circuit is usually first specified using a higher
level abstraction. Implementation can then be understood as finding a
functionally equivalent representation at a lower abstraction level. When
this is done automatically using software, the term {\it synthesis} is used.
So synthesis is the automatic conversion of a high-level representation of a
circuit to a functionally equivalent low-level representation of a circuit.
Figure~\ref{fig:Basics_abstractions} lists the different levels of abstraction
and how they relate to different kinds of synthesis.
\begin{figure}[b!]
\hfil
\begin{tikzpicture}
\tikzstyle{lvl} = [draw, fill=green!10, rectangle, minimum height=2em, minimum width=15em]
\node[lvl] (sys) {System Level};
\node[lvl] (hl) [below of=sys] {High Level};
\node[lvl] (beh) [below of=hl] {Behavioral Level};
\node[lvl] (rtl) [below of=beh] {Register-Transfer Level (RTL)};
\node[lvl] (lg) [below of=rtl] {Logical Gate Level};
\node[lvl] (pg) [below of=lg] {Physical Gate Level};
\node[lvl] (sw) [below of=pg] {Switch Level};
\draw[dotted] (sys.east) -- ++(1,0) coordinate (sysx);
\draw[dotted] (hl.east) -- ++(1,0) coordinate (hlx);
\draw[dotted] (beh.east) -- ++(1,0) coordinate (behx);
\draw[dotted] (rtl.east) -- ++(1,0) coordinate (rtlx);
\draw[dotted] (lg.east) -- ++(1,0) coordinate (lgx);
\draw[dotted] (pg.east) -- ++(1,0) coordinate (pgx);
\draw[dotted] (sw.east) -- ++(1,0) coordinate (swx);
\draw[gray,|->] (sysx) -- node[right] {System Design} (hlx);
\draw[|->|] (hlx) -- node[right] {High Level Synthesis (HLS)} (behx);
\draw[->|] (behx) -- node[right] {Behavioral Synthesis} (rtlx);
\draw[->|] (rtlx) -- node[right] {RTL Synthesis} (lgx);
\draw[->|] (lgx) -- node[right] {Logic Synthesis} (pgx);
\draw[gray,->|] (pgx) -- node[right] {Cell Library} (swx);
\draw[dotted] (behx) -- ++(5,0) coordinate (a);
\draw[dotted] (pgx) -- ++(5,0) coordinate (b);
\draw[|->|] (a) -- node[right] {Yosys} (b);
\end{tikzpicture}
\caption{Different levels of abstraction and synthesis.}
\label{fig:Basics_abstractions}
\end{figure}
Regardless of the way a lower level representation of a circuit is
obtained (synthesis or manual design), the lower level representation is usually
verified by comparing simulation results of the lower level and the higher level
representation \footnote{In the last years formal equivalence
checking also became an important verification method for validating RTL and
lower abstraction representation of the design.}.
Therefore even if no synthesis is used, there must still be a simulatable
representation of the circuit in all levels to allow for verification of the
design.
Note: The exact meaning of terminology such as ``High-Level'' is of course not
fixed over time. For example the HDL ``ABEL'' was first introduced in 1985 as ``A High-Level
Design Language for Programmable Logic Devices'' \cite{ABEL}, but would not
be considered a ``High-Level Language'' today.
\subsection{System Level}
The System Level abstraction of a system only looks at its biggest building
blocks like CPUs and computing cores. On this level the circuit is usually described
using traditional programming languages like C/C++ or Matlab. Sometimes special
software libraries are used that are aimed at simulation circuits on the system
level, such as SystemC.
Usually no synthesis tools are used to automatically transform a system level
representation of a circuit to a lower-level representation. But system level
design tools exist that can be used to connect system level building blocks.
The IEEE 1685-2009 standard defines the IP-XACT file format that can be used to
represent designs on the system level and building blocks that can be used in
such system level designs. \cite{IP-XACT}
\subsection{High Level}
The high-level abstraction of a system (sometimes referred to as {\it
algorithmic} level) is also often represented using traditional programming
languages, but with a reduced feature set. For example when representing a
design at the high level abstraction in C, pointers can only be used to mimic
concepts that can be found in hardware, such as memory interfaces. Full
featured dynamic memory management is not allowed as it has no corresponding
concept in digital circuits.
Tools exist to synthesize high level code (usually in the form of C/C++/SystemC
code with additional metadata) to behavioural HDL code (usually in the form of
Verilog or VHDL code). Aside from the many commercial tools for high level synthesis
there are also a number of FOSS tools for high level synthesis
\citeweblink{C_to_Verilog} \citeweblink{LegUp}.
\subsection{Behavioural Level}
At the behavioural abstraction level a language aimed at hardware description such
as Verilog or VHDL is used to describe the circuit, but so-called {\it behavioural
modelling} is used in at least part of the circuit description. In behavioural
modelling there must be a language feature that allows for imperative programming to be used to
describe data paths and registers. This is the {\tt always}-block in Verilog and
the {\tt process}-block in VHDL.
In behavioural modelling, code fragments are provided together with a {\it
sensitivity list}; a list of signals and conditions. In simulation, the code
fragment is executed whenever a signal in the sensitivity list changes its
value or a condition in the sensitivity list is triggered. A synthesis tool
must be able to transfer this representation into an appropriate datapath followed
by the appropriate types of register.
For example consider the following verilog code fragment:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
always @(posedge clk)
y <= a + b;
\end{lstlisting}
In simulation the statement \lstinline[language=Verilog]{y <= a + b} is executed whenever
a positive edge on the signal \lstinline[language=Verilog]{clk} is detected. The synthesis
result however will contain an adder that calculates the sum \lstinline[language=Verilog]{a + b}
all the time, followed by a d-type flip-flop with the adder output on its D-input and the
signal \lstinline[language=Verilog]{y} on its Q-output.
Usually the imperative code fragments used in behavioural modelling can contain
statements for conditional execution (\lstinline[language=Verilog]{if}- and
\lstinline[language=Verilog]{case}-statements in Verilog) as well as loops,
as long as those loops can be completely unrolled.
Interestingly there seems to be no other FOSS Tool that is capable of
performing Verilog or VHDL behavioural syntheses besides Yosys (see
App.~\ref{chapter:sota}).
\subsection{Register-Transfer Level (RTL)}
On the Register-Transfer Level the design is represented by combinatorial data
paths and registers (usually d-type flip flops). The following verilog code fragment
is equivalent to the previous verilog example, but is in RTL representation:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
assign tmp = a + b; // combinatorial data path
always @(posedge clk) // register
y <= tmp;
\end{lstlisting}
A design in RTL representation is usually stored using HDLs like Verilog and VHDL. But only
a very limited subset of features is used, namely minimalistic {\tt always}-blocks (Verilog)
or {\tt process}-blocks (VHDL) that model the register type used and unconditional assignments
for the datapath logic. The use of HDLs on this level simplifies simulation as no additional
tools are required to simulate a design in RTL representation.
Many optimizations and analyses can be performed best at the RTL level. Examples include FSM
detection and optimization, identification of memories or other larger building blocks
and identification of shareable resources.
Note that RTL is the first abstraction level in which the circuit is represented as a
graph of circuit elements (registers and combinatorical cells) and signals. Such a graph,
when encoded as list of cells and connections, is called a netlist.
RTL synthesis is easy as each circuit node element in the netlist can simply be replaced
with an equivalent gate-level circuit. However, usually the term {\it RTL synthesis} does
not only refer to synthesizing an RTL netlist to a gate level netlist but also to performing
a number of highly sophisticated optimizations within the RTL representation, such as
the examples listed above.
A number of FOSS tools exist that can perform isolated tasks within the domain of RTL
synthesis steps. But there seems to be no FOSS tool that covers a wide range of RTL
synthesis operations.
\subsection{Logical Gate Level}
On the logical gate level the design is represented by a netlist that uses only
cells from a small number of single-bit cells, such as basic logic gates (AND,
OR, NOT, XOR, etc.) and Registers (usually D-Type Flip-flops).
A number of netlist formats exists that can be used on this level, e.g.~the Electronic Design
Interchange Format (EDIF), but for ease of simulation often a HDL netlist is used. The latter
is a HDL file (Verilog or VHDL) that only uses the most basic language constructs for instantiation
and connecting of cells.
There are two challenges in logic synthesis: First finding opportunities for optimizations
within the gate level netlist and second the optimal (or at least good) mapping of the logic
gate netlist to an equivalent netlist of physically available gate types.
The simplest approach to logic synthesis is {\it two-level logic synthesis}, where a logic function
is converted into a sum-of-products representation, e.g.~using a karnaugh map.
This is a simple approach, but has exponential worst-case effort and can not make efficient use of
physical gates other than AND/NAND-, OR/NOR- and NOT-Gates.
Therefore modern logic synthesis tools utilize much more complicated {\it multi-level logic
synthesis} algorithms \cite{MultiLevelLogicSynth}. Most of these algorithms convert the
logic function to a Binary-Decision-Diagram (BDD) or And-Inverter-Graph (AIG) and work from that
representation. The former has the advantage that it has a unique normalized form. The latter has
much better worst case performance and is therefore better suited for the synthesis of large
logic functions.
Good FOSS tools exists for multi-level logic synthesis \citeweblink{ABC}
\citeweblink{AIGER} \citeweblink{MVSIS}.
Yosys contains basic logic synthesis functionality but can also use ABC
\citeweblink{ABC} for the logic synthesis step. Using ABC is recommended.
\subsection{Physical Gate Level}
On the physical gate level only gates are used that are physically available on
the target architecture. In some cases this may only be NAND, NOR and NOT gates as well as
D-Type registers. In other cases this might include cells that are more complex than the cells
used at the logical gate level (e.g.~complete half-adders). In the case of an FPGA-based
design the physical gate level representation is a netlist of LUTs with optional output
registers, as these are the basic building blocks of FPGA logic cells.
For the synthesis tool chain this abstraction is usually the lowest level. In
case of an ASIC-based design the cell library might contain further information on
how the physical cells map to individual switches (transistors).
\subsection{Switch Level}
A switch level representation of a circuit is a netlist utilizing single transistors as cells.
Switch level modelling is possible in Verilog and VHDL, but is seldom used in modern designs,
as in modern digital ASIC or FPGA flows the physical gates are considered the atomic build blocks
of the logic circuit.
\subsection{Yosys}
Yosys is a Verilog HDL synthesis tool. This means that it takes a behavioural
design description as input and generates an RTL, logical gate or physical gate
level description of the design as output. Yosys' main strengths are behavioural
and RTL synthesis. A wide range of commands (synthesis passes) exist
within Yosys that can be used to perform a wide range of synthesis tasks within
the domain of behavioural, rtl and logic synthesis. Yosys is designed to be
extensible and therefore is a good basis for implementing custom synthesis
tools for specialised tasks.
\section{Features of Synthesizable Verilog}
The subset of Verilog \cite{Verilog2005} that is synthesizable is specified in
a separate IEEE standards document, the IEEE standard 1364.1-2002 \cite{VerilogSynth}.
This standard also describes how certain language constructs are to be interpreted in
the scope of synthesis.
This section provides a quick overview of the most important features of
synthesizable Verilog, structured in order of increasing complexity.
\subsection{Structural Verilog}
{\it Structural Verilog} (also known as {\it Verilog Netlists}) is a Netlist in
Verilog syntax. Only the following language constructs are used in this case:
\begin{itemize}
\item Constant values
\item Wire and port declarations
\item Static assignments of signals to other signals
\item Cell instantiations
\end{itemize}
Many tools (especially at the back end of the synthesis chain) only support
structural verilog as input. ABC is an example of such a tool. Unfortunately
there is no standard specifying what {\it Structural Verilog} actually is,
leading to some confusion about what syntax constructs are supported in
structural verilog when it comes to features such as attributes or multi-bit
signals.
\subsection{Expressions in Verilog}
In all situations where Verilog accepts a constant value or signal name,
expressions using arithmetic operations such as
\lstinline[language=Verilog]{+}, \lstinline[language=Verilog]{-} and \lstinline[language=Verilog]{*},
boolean operations such as
\lstinline[language=Verilog]{&} (AND), \lstinline[language=Verilog]{|} (OR) and \lstinline[language=Verilog]{^} (XOR)
and many others (comparison operations, unary operator, etc.) can also be used.
During synthesis these operators are replaced by cells that implement the respective function.
Many FOSS tools that claim to be able to process Verilog in fact only support
basic structural verilog and simple expressions. Yosys can be used to convert
full featured synthesizable verilog to this simpler subset, thus enabling such
applications to be used with a richer set of Verilog features.
\subsection{Behavioural Modelling}
Code that utilizes the Verilog {\tt always} statement is using {\it Behavioural
Modelling}. In behavioural, modelling a circuit is described by means of imperative
program code that is executed on certain events, namely any change, a rising
edge, or a falling edge of a signal. This is a very flexible construct during
simulation but is only synthesizable when one of the following is modelled:
\begin{itemize}
\item {\bf Asynchronous or latched logic} \\
In this case the sensitivity list must contain all expressions that are used within
the {\tt always} block. The syntax \lstinline[language=Verilog]{@*} can be used
for these cases. Examples of this kind include:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
// asynchronous
always @* begin
if (add_mode)
y <= a + b;
else
y <= a - b;
end
// latched
always @* begin
if (!hold)
y <= a + b;
end
\end{lstlisting}
Note that latched logic is often considered bad style and in many cases just
the result of sloppy HDL design. Therefore many synthesis tools generate warnings
whenever latched logic is generated.
\item {\bf Synchronous logic (with optional synchronous reset)} \\
This is logic with d-type flip-flops on the output. In this case the sensitivity
list must only contain the respective clock edge. Example:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
// counter with synchronous reset
always @(posedge clk) begin
if (reset)
y <= 0;
else
y <= y + 1;
end
\end{lstlisting}
\item {\bf Synchronous logic with asynchronous reset} \\
This is logic with d-type flip-flops with asynchronous resets on the output. In
this case the sensitivity list must only contain the respective clock and reset edges.
The values assigned in the reset branch must be constant. Example:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
// counter with asynchronous reset
always @(posedge clk, posedge reset) begin
if (reset)
y <= 0;
else
y <= y + 1;
end
\end{lstlisting}
\end{itemize}
Many synthesis tools support a wider subset of flip-flops that can be modelled
using {\tt always}-statements (including Yosys). But only the ones listed above
are covered by the Verilog synthesis standard and when writing new designs one
should limit herself or himself to these cases.
In behavioural modelling, blocking assignments (=) and non-blocking assignments
(<=) can be used. The concept of blocking vs.~non-blocking assignment is one
of the most misunderstood constructs in Verilog \cite{Cummings00}.
The blocking assignment behaves exactly like an assignment in any imperative
programming language, while with the non-blocking assignment the right hand side
of the assignment is evaluated immediately but the actual update of the left
hand side register is delayed until the end of the time-step. For example the Verilog
code \lstinline[language=Verilog]{a <= b; b <= a;} exchanges the values of
the two registers. See Sec.~\ref{sec:blocking_nonblocking} for a more
detailed description of this behaviour.
\subsection{Functions and Tasks}
Verilog supports {\it Functions} and {\it Tasks} to bundle statements that are
used in multiple places (similar to {\it Procedures} in imperative programming).
Both constructs can be implemented easily by substituting the function/task-call
with the body of the function or task.
\subsection{Conditionals, Loops and Generate-Statements}
Verilog supports \lstinline[language=Verilog]{if-else}-statements and
\lstinline[language=Verilog]{for}-loops inside \lstinline[language=Verilog]{always}-statements.
It also supports both features in \lstinline[language=Verilog]{generate}-statements
on the module level. This can be used to selectively enable or disable parts of the
module based on the module parameters (\lstinline[language=Verilog]{if-else})
or to generate a set of similar subcircuits (\lstinline[language=Verilog]{for}).
While the \lstinline[language=Verilog]{if-else}-statement
inside an always-block is part of behavioural modelling, the three other cases
are (at least for a synthesis tool) part of a built-in macro processor. Therefore it must
be possible for the synthesis tool to completely unroll all loops and evaluate the
condition in all \lstinline[language=Verilog]{if-else}-statement in
\lstinline[language=Verilog]{generate}-statements using const-folding.
Examples for this can be found in Fig.~\ref{fig:StateOfTheArt_for} and
Fig.~\ref{fig:StateOfTheArt_gen} in App.~\ref{chapter:sota}.
\subsection{Arrays and Memories}
Verilog supports arrays. This is in general a synthesizable language feature.
In most cases arrays can be synthesized by generating addressable memories.
However, when complex or asynchronous access patterns are used, it is not
possible to model an array as memory. In these cases the array must
be modelled using individual signals for each word and all accesses to the array
must be implemented using large multiplexers.
In some cases it would be possible to model an array using memories, but it
is not desired. Consider the following delay circuit:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
module (clk, in_data, out_data);
parameter BITS = 8;
parameter STAGES = 4;
input clk;
input [BITS-1:0] in_data;
output [BITS-1:0] out_data;
reg [BITS-1:0] ffs [STAGES-1:0];
integer i;
always @(posedge clk) begin
ffs[0] <= in_data;
for (i = 1; i < STAGES; i = i+1)
ffs[i] <= ffs[i-1];
end
assign out_data = ffs[STAGES-1];
endmodule
\end{lstlisting}
This could be implemented using an addressable memory with {\tt STAGES} input
and output ports. A better implementation would be to use a simple chain of flip-flops
(a so-called shift register).
This better implementation can either be obtained by first creating a memory-based
implementation and then optimizing it based on the static address signals for all ports
or directly identifying such situations in the language front end and converting
all memory accesses to direct accesses to the correct signals.
\section{Challenges in Digital Circuit Synthesis}
This section summarizes the most important challenges in digital circuit
synthesis. Tools can be characterized by how well they address these topics.
\subsection{Standards Compliance}
The most important challenge is compliance with the HDL standards in question (in case
of Verilog the IEEE Standards 1364.1-2002 and 1364-2005). This can be broken down in two
items:
\begin{itemize}
\item Completeness of implementation of the standard
\item Correctness of implementation of the standard
\end{itemize}
Completeness is mostly important to guarantee compatibility
with existing HDL code. Once a design has been verified and tested, HDL designers
are very reluctant regarding changes to the design, even if it is only about
a few minor changes to work around a missing feature in a new synthesis tool.
Correctness is crucial. In some areas this is obvious (such as
correct synthesis of basic behavioural models). But it is also crucial for the
areas that concern minor details of the standard, such as the exact rules
for handling signed expressions, even when the HDL code does not target
different synthesis tools. This is because (different to software source code that
is only processed by compilers), in most design flows HDL code is not only
processed by the synthesis tool but also by one or more simulators and sometimes
even a formal verification tool. It is key for this verification process
that all these tools use the same interpretation for the HDL code.
\subsection{Optimizations}
Generally it is hard to give a one-dimensional description of how well a synthesis tool
optimizes the design. First of all because not all optimizations are applicable to all
designs and all synthesis tasks. Some optimizations work (best) on a coarse grain level
(with complex cells such as adders or multipliers) and others work (best) on a fine
grain level (single bit gates). Some optimizations target area and others target speed.
Some work well on large designs while others don't scale well and can only be applied
to small designs.
A good tool is capable of applying a wide range of optimizations at different
levels of abstraction and gives the designer control over which optimizations
are performed (or skipped) and what the optimization goals are.
\subsection{Technology Mapping}
Technology mapping is the process of converting the design into a netlist of
cells that are available in the target architecture. In an ASIC flow this might
be the process-specific cell library provided by the fab. In an FPGA flow this
might be LUT cells as well as special function units such as dedicated multipliers.
In a coarse-grain flow this might even be more complex special function units.
An open and vendor independent tool is especially of interest if it supports
a wide range of different types of target architectures.
\section{Script-Based Synthesis Flows}
A digital design is usually started by implementing a high-level or
system-level simulation of the desired function. This description is then
manually transformed (or re-implemented) into a synthesizable lower-level
description (usually at the behavioural level) and the equivalence of the
two representations is verified by simulating both and comparing the simulation
results.
Then the synthesizable description is transformed to lower-level
representations using a series of tools and the results are again verified
using simulation. This process is illustrated in Fig.~\ref{fig:Basics_flow}.
\begin{figure}[t!]
\hfil
\begin{tikzpicture}
\tikzstyle{manual} = [draw, fill=green!10, rectangle, minimum height=2em, minimum width=8em, node distance=10em]
\tikzstyle{auto} = [draw, fill=orange!10, rectangle, minimum height=2em, minimum width=8em, node distance=10em]
\node[manual] (sys) {\begin{minipage}{8em}
\center
System Level \\
Model
\end{minipage}};
\node[manual] (beh) [right of=sys] {\begin{minipage}{8em}
\center
Behavioral \\
Model
\end{minipage}};
\node[auto] (rtl) [right of=beh] {\begin{minipage}{8em}
\center
RTL \\
Model
\end{minipage}};
\node[auto] (gates) [right of=rtl] {\begin{minipage}{8em}
\center
Gate-Level \\
Model
\end{minipage}};
\draw[-latex] (beh) edge[double, bend left] node[above] {synthesis} (rtl);
\draw[-latex] (rtl) edge[double, bend left] node[above] {synthesis} (gates);
\draw[latex-latex] (sys) edge[bend right] node[below] {verify} (beh);
\draw[latex-latex] (beh) edge[bend right] node[below] {verify} (rtl);
\draw[latex-latex] (rtl) edge[bend right] node[below] {verify} (gates);
\end{tikzpicture}
\caption{Typical design flow. Green boxes represent manually created models. Orange boxes represent
models generated by synthesis tools.}
\label{fig:Basics_flow}
\end{figure}
In this example the System Level Model and the Behavioural Model are both
manually written design files. After the equivalence of system level model
and behavioural model has been verified, the lower level representations of the
design can be generated using synthesis tools. Finally the RTL Model and
the Gate-Level Model are verified and the design process is finished.
However, in any real-world design effort there will be multiple iterations for
this design process. The reason for this can be the late change of a design
requirement or the fact that the analysis of a low-abstraction model (e.g.~gate-level
timing analysis) revealed that a design change is required in order to meet
the design requirements (e.g.~maximum possible clock speed).
Whenever the behavioural model or the system level model is
changed their equivalence must be re-verified by re-running the simulations
and comparing the results. Whenever the behavioural model is changed the
synthesis must be re-run and the synthesis results must be re-verified.
In order to guarantee reproducibility it is important to be able to re-run all
automatic steps in a design project with a fixed set of settings easily.
Because of this, usually all programs used in a synthesis flow can be
controlled using scripts. This means that all functions are available via
text commands. When such a tool provides a gui, this is complementary to,
and not instead of, a command line interface.
Usually a synthesis flow in an UNIX/Linux environment would be controlled by a
shell script that calls all required tools (synthesis and simulation/verification
in this example) in the correct order. Each of these tools would be called with
a script file containing commands for the respective tool. All settings required
for the tool would be provided by these script files so that no manual interaction
would be necessary. These script files are considered design sources and should
be kept under version control just like the source code of the system level and the
behavioural model.
\section{Methods from Compiler Design}
Some parts of synthesis tools involve problem domains that are traditionally known from
compiler design. This section addresses some of these domains.
\subsection{Lexing and Parsing}
The best known concepts from compiler design are probably {\it lexing} and {\it parsing}.
These are two methods that together can be used to process complex computer languages
easily. \cite{Dragonbook}
A {\it lexer} consumes single characters from the input and generates a stream of {\it lexical
tokens} that consist of a {\it type} and a {\it value}. For example the Verilog input
``\lstinline[language=Verilog]{assign foo = bar + 42;}'' might be translated by the lexer
to the list of lexical tokens given in Tab.~\ref{tab:Basics_tokens}.
\begin{table}[t]
\hfil
\begin{tabular}{ll}
Token-Type & Token-Value \\
\hline
\tt TOK\_ASSIGN & - \\
\tt TOK\_IDENTIFIER & ``{\tt foo}'' \\
\tt TOK\_EQ & - \\
\tt TOK\_IDENTIFIER & ``{\tt bar}'' \\
\tt TOK\_PLUS & - \\
\tt TOK\_NUMBER & 42 \\
\tt TOK\_SEMICOLON & - \\
\end{tabular}
\caption{Exemplary token list for the statement ``\lstinline[language=Verilog]{assign foo = bar + 42;}''.}
\label{tab:Basics_tokens}
\end{table}
The lexer is usually generated by a lexer generator (e.g.~{\tt flex} \citeweblink{flex}) from a
description file that is using regular expressions to specify the text pattern that should match
the individual tokens.
The lexer is also responsible for skipping ignored characters (such as white spaces outside string
constants and comments in the case of Verilog) and converting the original text snippet to a token
value.
Note that individual keywords use different token types (instead of a keyword type with different
token values). This is because the parser usually can only use the Token-Type to make a decision on
the grammatical role of a token.
The parser then transforms the list of tokens into a parse tree that closely resembles the productions
from the computer languages grammar. As the lexer, the parser is also typically generated by a code
generator (e.g.~{\tt bison} \citeweblink{bison}) from a grammar description in Backus-Naur Form (BNF).
Let's consider the following BNF (in Bison syntax):
\begin{lstlisting}[numbers=left,frame=single]
assign_stmt: TOK_ASSIGN TOK_IDENTIFIER TOK_EQ expr TOK_SEMICOLON;
expr: TOK_IDENTIFIER | TOK_NUMBER | expr TOK_PLUS expr;
\end{lstlisting}
\begin{figure}[b!]
\hfil
\begin{tikzpicture}
\tikzstyle{node} = [draw, fill=green!10, ellipse, minimum height=2em, minimum width=8em, node distance=10em]
\draw (+0,+1) node[node] (n1) {\tt assign\_stmt};
\draw (-6,-1) node[node] (n11) {\tt TOK\_ASSIGN};
\draw (-3,-2) node[node] (n12) {\tt TOK\_IDENTIFIER};
\draw (+0,-1) node[node] (n13) {\tt TOK\_EQ};
\draw (+3,-2) node[node] (n14) {\tt expr};
\draw (+6,-1) node[node] (n15) {\tt TOK\_SEMICOLON};
\draw (-1,-4) node[node] (n141) {\tt expr};
\draw (+3,-4) node[node] (n142) {\tt TOK\_PLUS};
\draw (+7,-4) node[node] (n143) {\tt expr};
\draw (-1,-5.5) node[node] (n1411) {\tt TOK\_IDENTIFIER};
\draw (+7,-5.5) node[node] (n1431) {\tt TOK\_NUMBER};
\draw[-latex] (n1) -- (n11);
\draw[-latex] (n1) -- (n12);
\draw[-latex] (n1) -- (n13);
\draw[-latex] (n1) -- (n14);
\draw[-latex] (n1) -- (n15);
\draw[-latex] (n14) -- (n141);
\draw[-latex] (n14) -- (n142);
\draw[-latex] (n14) -- (n143);
\draw[-latex] (n141) -- (n1411);
\draw[-latex] (n143) -- (n1431);
\end{tikzpicture}
\caption{Example parse tree for the Verilog expression ``\lstinline[language=Verilog]{assign foo = bar + 42;}''.}
\label{fig:Basics_parsetree}
\end{figure}
The parser converts the token list to the parse tree in Fig.~\ref{fig:Basics_parsetree}. Note that the parse
tree never actually exists as a whole as data structure in memory. Instead the parser calls user-specified
code snippets (so-called {\it reduce-functions}) for all inner nodes of the parse tree in depth-first order.
In some very simple applications (e.g.~code generation for stack machines) it is possible to perform the
task at hand directly in the reduce functions. But usually the reduce functions are only used to build an in-memory
data structure with the relevant information from the parse tree. This data structure is called an {\it abstract
syntax tree} (AST).
The exact format for the abstract syntax tree is application specific (while the format of the parse tree and token
list are mostly dictated by the grammar of the language at hand). Figure~\ref{fig:Basics_ast} illustrates what an
AST for the parse tree in Fig.~\ref{fig:Basics_parsetree} could look like.
Usually the AST is then converted into yet another representation that is more suitable for further processing.
In compilers this is often an assembler-like three-address-code intermediate representation. \cite{Dragonbook}
\begin{figure}[t]
\hfil
\begin{tikzpicture}
\tikzstyle{node} = [draw, fill=green!10, ellipse, minimum height=2em, minimum width=8em, node distance=10em]
\draw (+0,+0) node[node] (n1) {\tt ASSIGN};
\draw (-2,-2) node[node] (n11) {\tt ID: foo};
\draw (+2,-2) node[node] (n12) {\tt PLUS};
\draw (+0,-4) node[node] (n121) {\tt ID: bar};
\draw (+4,-4) node[node] (n122) {\tt CONST: 42};
\draw[-latex] (n1) -- (n11);
\draw[-latex] (n1) -- (n12);
\draw[-latex] (n12) -- (n121);
\draw[-latex] (n12) -- (n122);
\end{tikzpicture}
\caption{Example abstract syntax tree for the Verilog expression ``\lstinline[language=Verilog]{assign foo = bar + 42;}''.}
\label{fig:Basics_ast}
\end{figure}
\subsection{Multi-Pass Compilation}
Complex problems are often best solved when split up into smaller problems. This is certainly true
for compilers as well as for synthesis tools. The components responsible for solving the smaller problems can
be connected in two different ways: through {\it Single-Pass Pipelining} and by using {\it Multiple Passes}.
Traditionally a parser and lexer are connected using the pipelined approach: The lexer provides a function that
is called by the parser. This function reads data from the input until a complete lexical token has been read. Then
this token is returned to the parser. So the lexer does not first generate a complete list of lexical tokens
and then passes it to the parser. Instead they are running concurrently and the parser can consume tokens as
the lexer produces them.
The single-pass pipelining approach has the advantage of lower memory footprint (at no time the complete design
must be kept in memory) but has the disadvantage of tighter coupling between the interacting components.
Therefore single-pass pipelining should only be used when the lower memory footprint is required or the
components are also conceptually tightly coupled. The latter certainly is the case for a parser and its lexer.
But when data is passed between two conceptually loosely coupled components it is often
beneficial to use a multi-pass approach.
In the multi-pass approach the first component processes all the data and the result is stored in a in-memory
data structure. Then the second component is called with this data. This reduces complexity, as only one
component is running at a time. It also improves flexibility as components can be exchanged easier.
Most modern compilers are multi-pass compilers.
\iffalse
\subsection{Static Single Assignment Form}
In imperative programming (and behavioural HDL design) it is possible to assign the same variable multiple times.
This can either mean that the variable is independently used in two different contexts or that the final value
of the variable depends on a condition.
The following examples show C code in which one variable is used independently in two different contexts:
\begin{minipage}{7.7cm}
\begin{lstlisting}[numbers=left,frame=single,language=C++]
void demo1()
{
int a = 1;
printf("%d\n", a);
a = 2;
printf("%d\n", a);
}
\end{lstlisting}
\end{minipage}
\hfil
\begin{minipage}{7.7cm}
\begin{lstlisting}[frame=single,language=C++]
void demo1()
{
int a = 1;
printf("%d\n", a);
int b = 2;
printf("%d\n", b);
}
\end{lstlisting}
\end{minipage}
\begin{minipage}{7.7cm}
\begin{lstlisting}[numbers=left,frame=single,language=C++]
void demo2(bool foo)
{
int a;
if (foo) {
a = 23;
printf("%d\n", a);
} else {
a = 42;
printf("%d\n", a);
}
}
\end{lstlisting}
\end{minipage}
\hfil
\begin{minipage}{7.7cm}
\begin{lstlisting}[frame=single,language=C++]
void demo2(bool foo)
{
int a, b;
if (foo) {
a = 23;
printf("%d\n", a);
} else {
b = 42;
printf("%d\n", b);
}
}
\end{lstlisting}
\end{minipage}
In both examples the left version (only variable \lstinline[language=C++]{a}) and the right version (variables
\lstinline[language=Verilog]{a} and \lstinline[language=Verilog]{b}) are equivalent. Therefore it is
desired for further processing to bring the code in an equivalent form for both cases.
In the following example the variable is assigned twice but it cannot be easily replaced by two variables:
\begin{lstlisting}[frame=single,language=C++]
void demo3(bool foo)
{
int a = 23
if (foo)
a = 42;
printf("%d\n", a);
}
\end{lstlisting}
Static single assignment (SSA) form is a representation of imperative code that uses identical representations
for the left and right version of demos 1 and 2, but can still represent demo 3. In SSA form each assignment
assigns a new variable (usually written with an index). But it also introduces a special $\Phi$-function to
merge the different instances of a variable when needed. In C-pseudo-code the demo 3 would be written as follows
using SSA from:
\begin{lstlisting}[frame=single,language=C++]
void demo3(bool foo)
{
int a_1, a_2, a_3;
a_1 = 23
if (foo)
a_2 = 42;
a_3 = phi(a_1, a_2);
printf("%d\n", a_3);
}
\end{lstlisting}
The $\Phi$-function is usually interpreted as ``these variables must be stored
in the same memory location'' during code generation. Most modern compilers for imperative languages
such as C/C++ use SSA form for at least some of its passes as it is very easy to manipulate and analyse.
\fi

408
manual/CHAPTER_CellLib.tex Normal file
View File

@ -0,0 +1,408 @@
\chapter{Internal Cell Library}
\label{chapter:celllib}
Most of the passes in Yosys operate on netlists, i.e.~they only care about the RTLIL::Wire and RTLIL::Cell
objects in an RTLIL::Module. This chapter discusses the cell types used by Yosys to represent a behavioural
design internally.
This chapter is split in two parts. In the first part the internal RTL cells are covered. These cells
are used to represent the design on a coarse grain level. Like in the original HDL code on this level the
cells operate on vectors of signals and complex cells like adders exist. In the second part the internal
gate cells are covered. These cells are used to represent the design on a fine-grain gate-level. All cells
from this category operate on single bit signals.
\section{RTL Cells}
Most of the RTL cells closely resemble the operators available in HDLs such as
Verilog or VHDL. Therefore Verilog operators are used in the following sections
to define the behaviour of the RTL cells.
Note that all RTL cells have parameters indicating the size of inputs and outputs. When
passes modify RTL cells they must always keep the values of these parameters in sync with
the size of the signals connected to the inputs and outputs.
Simulation models for the RTL cells can be found in the file {\tt techlibs/simlib.v} in the Yosys
source tree.
\subsection{Unary Operators}
All unary RTL cells have one input port \B{A} and one output port \B{Y}. They also
have the following parameters:
\begin{itemize}
\item \B{A\_SIGNED} \\
Set to a non-zero value if the input \B{A} is signed and therefore should be sign-extended
when needed.
\item \B{A\_WIDTH} \\
The width of the input port \B{A}.
\item \B{Y\_WIDTH} \\
The width of the output port \B{Y}.
\end{itemize}
Table~\ref{tab:CellLib_unary} lists all cells for unary RTL operators.
\begin{table}[t!]
\hfil
\begin{tabular}{ll}
Verilog & Cell Type \\
\hline
\lstinline[language=Verilog]; Y = ~A ; & {\tt \$not} \\
\lstinline[language=Verilog]; Y = +A ; & {\tt \$pos} \\
\lstinline[language=Verilog]; Y = -A ; & {\tt \$neg} \\
\hline
\lstinline[language=Verilog]; Y = &A ; & {\tt \$reduce\_and} \\
\lstinline[language=Verilog]; Y = |A ; & {\tt \$reduce\_or} \\
\lstinline[language=Verilog]; Y = ^A ; & {\tt \$reduce\_xor} \\
\lstinline[language=Verilog]; Y = ~^A ; & {\tt \$reduce\_xnor} \\
\hline
\lstinline[language=Verilog]; Y = |A ; & {\tt \$reduce\_bool} \\
\lstinline[language=Verilog]; Y = !A ; & {\tt \$logic\_not}
\end{tabular}
\caption{Cell types for unary operators with their corresponding Verilog expressions.}
\label{tab:CellLib_unary}
\end{table}
Note that {\tt \$reduce\_or} and {\tt \$reduce\_bool} actually represent the same
logic function. But the HDL frontends generate them in different situations. A
{\tt \$reduce\_or} cell is generated when the prefix {\tt |} operator is being used. A
{\tt \$reduce\_bool} cell is generated when a bit vector is used as a condition in
an {\tt if}-statement or {\tt ?:}-expression.
\subsection{Binary Operators}
All binary RTL cells have two input ports \B{A} and \B{B} and one output port \B{Y}. They
also have the following parameters:
\begin{itemize}
\item \B{A\_SIGNED} \\
Set to a non-zero value if the input \B{A} is signed and therefore should be sign-extended
when needed.
\item \B{A\_WIDTH} \\
The width of the input port \B{A}.
\item \B{B\_SIGNED} \\
Set to a non-zero value if the input \B{B} is signed and therefore should be sign-extended
when needed.
\item \B{B\_WIDTH} \\
The width of the input port \B{B}.
\item \B{Y\_WIDTH} \\
The width of the output port \B{Y}.
\end{itemize}
Table~\ref{tab:CellLib_binary} lists all cells for binary RTL operators.
\subsection{Multiplexers}
Multiplexers are generated by the Verilog HDL frontend for {\tt
?:}-expressions. Multiplexers are also generated by the {\tt proc} pass to map the decision trees
from RTLIL::Process objects to logic.
The simplest multiplexer cell type is {\tt \$mux}. Cells of this type have a \B{WIDTH} parameter
and data inputs \B{A} and \B{B} and a data ouput \B{Y}, all of the specified width. This cell also
has a single bit control input \B{S}. If \B{S} is 0 the value from the \B{A} input is sent to
the output, if it is 1 the value from the \B{B} input is sent to the output. So the {\tt \$mux}
cell implements the function \lstinline[language=Verilog]; Y = S ? B : A;.
The {\tt \$pmux} cell is used to multiplex between many inputs using a one-hot select signal. Cells
of this type have a \B{WIDTH} and a \B{S\_WIDTH} parameter and inputs \B{A}, \B{B}, and \B{S} and
an output \B{Y}. The \B{S} input is \B{S\_WIDTH} bits wide. The \B{A} input and the output are both
\B{WIDTH} bits wide and the \B{B} input is \B{WIDTH}*\B{S\_WIDTH} bits wide. When all bits of
\B{S} are zero, the value from \B{A} input is sent to the output. If the $n$'th bit from \B{S} is
set, the value $n$'th \B{WIDTH} bits wide slice of the \B{B} input is sent to the output. When more
than one bit from \B{S} is set the output is undefined. Cells of this type are used to model
``parallel cases'' (defined by using the {\tt parallel\_case} attribute or detected by
an optimization).
The {\tt \$safe\_pmux} behaves similarly to the {\tt \$pmux} cell type. But when more than one bit
of \B{S} is set, it is guaranteed that this cell type will output the value of the \B{A} input instead of
an undefined value.
Behavioural code with cascaded {\tt if-then-else}- and {\tt case}-statements
usually results in trees of multiplexer cells. Many passes (from various
optimizations to FSM extraction) heavily depend on these multiplexer trees to
understand dependencies between signals. Therefore optimizations should not
break these multiplexer trees (e.g.~by replacing a multiplexer between a
calculated signal and a constant zero with an {\tt \$and} gate).
\begin{table}[t!]
\hfil
\begin{tabular}[t]{ll}
Verilog & Cell Type \\
\hline
\lstinline[language=Verilog]; Y = A & B; & {\tt \$and} \\
\lstinline[language=Verilog]; Y = A | B; & {\tt \$or} \\
\lstinline[language=Verilog]; Y = A ^ B; & {\tt \$xor} \\
\lstinline[language=Verilog]; Y = A ~^ B; & {\tt \$xnor} \\
\hline
\lstinline[language=Verilog]; Y = A << B; & {\tt \$shl} \\
\lstinline[language=Verilog]; Y = A >> B; & {\tt \$shr} \\
\lstinline[language=Verilog]; Y = A <<< B; & {\tt \$sshl} \\
\lstinline[language=Verilog]; Y = A >>> B; & {\tt \$sshr} \\
\hline
\lstinline[language=Verilog]; Y = A && B; & {\tt \$logic\_and} \\
\lstinline[language=Verilog]; Y = A || B; & {\tt \$logic\_or} \\
\end{tabular}
\hfil
\begin{tabular}[t]{ll}
Verilog & Cell Type \\
\hline
\lstinline[language=Verilog]; Y = A < B; & {\tt \$lt} \\
\lstinline[language=Verilog]; Y = A <= B; & {\tt \$le} \\
\lstinline[language=Verilog]; Y = A == B; & {\tt \$eq} \\
\lstinline[language=Verilog]; Y = A != B; & {\tt \$ne} \\
\lstinline[language=Verilog]; Y = A >= B; & {\tt \$ge} \\
\lstinline[language=Verilog]; Y = A > B; & {\tt \$gt} \\
\hline
\lstinline[language=Verilog]; Y = A + B; & {\tt \$add} \\
\lstinline[language=Verilog]; Y = A - B; & {\tt \$sub} \\
\lstinline[language=Verilog]; Y = A * B; & {\tt \$mul} \\
\lstinline[language=Verilog]; Y = A / B; & {\tt \$div} \\
\lstinline[language=Verilog]; Y = A % B; & {\tt \$mod} \\
\lstinline[language=Verilog]; Y = A ** B; & {\tt \$pow} \\
\end{tabular}
\caption{Cell types for binary operators with their corresponding Verilog expressions.}
\label{tab:CellLib_binary}
\end{table}
\subsection{Registers}
D-Type Flip-Flops are represented by {\tt \$dff} cells. These cells have a clock port \B{CLK},
an input port \B{D} and an output port \B{Q}. The following parameters are available for \$dff
cells:
\begin{itemize}
\item \B{WIDTH} \\
The width of input \B{D} and output \B{Q}.
\item \B{CLK\_POLARITY} \\
Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative
edge if this parameter is {\tt 1'b0}.
\end{itemize}
D-Type Flip-Flops with asynchronous resets are represented by {\tt \$adff} cells. As the {\tt \$dff}
cells they have \B{CLK}, \B{D} and \B{Q} ports. In addition they also have a single-bit \B{ARST}
input port for the reset pin and the following additional two parameters:
\begin{itemize}
\item \B{ARST\_POLARITY} \\
The asynchronous reset is high-active if this parameter has the value {\tt 1'b1} and low-active
if this parameter is {\tt 1'b0}.
\item \B{ARST\_VALUE} \\
The state of \B{Q} will be set to this value when the reset is active.
\end{itemize}
Note that the {\tt \$adff} cell can only be used when the reset value is constant.
\begin{sloppypar}
Usually these cells are generated by the {\tt proc} pass using the information
in the designs RTLIL::Process objects.
\end{sloppypar}
\begin{fixme}
Add information about {\tt \$sr} cells (set-reset flip-flops) and d-type latches.
\end{fixme}
\subsection{Memories}
\label{sec:memcells}
Memories are either represented using RTLIL::Memory objects and {\tt \$memrd} and {\tt \$memwr} cells
or simply by using {\tt \$mem} cells.
In the first alternative the RTLIL::Memory objects hold the general metadata for the memory (bit width,
size in number of words, etc.) and for each port a {\tt \$memrd} (read port) or {\tt \$memwr} (write port)
cell is created. Having individual cells for read and write ports has the advantage that they can be
consolidated using resource sharing passes. In some cases this drastically reduces the number of required
ports on the memory cell.
The {\tt \$memrd} cells have a clock input \B{CLK}, an address input \B{ADDR} and a data output
\B{DATA}. They also have the following parameters:
\begin{itemize}
\item \B{MEMID} \\
The name of the RTLIL::Memory object that is associated with this read port.
\item \B{ABITS} \\
The number of address bits (width of the \B{ADDR} input port).
\item \B{WIDTH} \\
The number of data bits (width of the \B{DATA} output port).
\item \B{CLK\_ENABLE} \\
When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and
the \B{CLK} input is not used.
\item \B{CLK\_POLARITY} \\
Clock is active on the positive edge if this parameter has the value {\tt 1'b1} and on the negative
edge if this parameter is {\tt 1'b0}.
\end{itemize}
The {\tt \$memwr} cells have a clock input \B{CLK}, an enable input \B{EN}, an address input \B{ADDR}
and a data input \B{DATA}. They also have the following parameters:
\begin{itemize}
\item \B{MEMID} \\
The name of the RTLIL::Memory object that is associated with this read port.
\item \B{ABITS} \\
The number of address bits (width of the \B{ADDR} input port).
\item \B{WIDTH} \\
The number of data bits (width of the \B{DATA} output port).
\item \B{CLK\_ENABLE} \\
When this parameter is non-zero, the clock is used. Otherwise this read port is asynchronous and
the \B{CLK} input is not used.
\item \B{CLK\_POLARITY} \\
Clock is active on positive edge if this parameter has the value {\tt 1'b1} and on the negative
edge if this parameter is {\tt 1'b0}.
\end{itemize}
The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
{\tt \$memrd} and {\tt \$memwr} cells. The {\tt memory} pass (i.e.~its various sub-passes) migrates
{\tt \$dff} cells into the {\tt \$memrd} and {\tt \$memwr} cells making them synchronous, then
converts them to a single {\tt \$mem} cell and (optionally) maps this cell type
to {\tt \$dff} cells for the individual words and multiplexer-based address decoders for the read and
write interfaces. When the last step is disabled or not possible, a {\tt \$mem} cell is left in the design.
The {\tt \$mem} cell provides the following parameters:
\begin{itemize}
\item \B{MEMID} \\
The name of the original RTLIL::Memory object that became this {\tt \$mem} cell.
\item \B{SIZE} \\
The number of words in the memory.
\item \B{ABITS} \\
The number of address bits.
\item \B{WIDTH} \\
The number of data bits per word.
\item \B{RD\_PORTS} \\
The number of read ports on this memory cell.
\item \B{RD\_CLK\_ENABLE} \\
This parameter is \B{RD\_PORTS} bits wide, containing a clock enable bit for each read port.
\item \B{RD\_CLK\_POLARITY} \\
This parameter is \B{RD\_PORTS} bits wide, containing a clock polarity bit for each read port.
\item \B{WR\_PORTS} \\
The number of write ports on this memory cell.
\item \B{WR\_CLK\_ENABLE} \\
This parameter is \B{WR\_PORTS} bits wide, containing a clock enable bit for each write port.
\item \B{WR\_CLK\_POLARITY} \\
This parameter is \B{WR\_PORTS} bits wide, containing a clock polarity bit for each write port.
\end{itemize}
The {\tt \$mem} cell has the following ports:
\begin{itemize}
\item \B{RD\_CLK} \\
This input is \B{RD\_PORTS} bits wide, containing all clock signals for the read ports.
\item \B{RD\_ADDR} \\
This input is \B{RD\_PORTS}*\B{ABITS} bits wide, containing all address signals for the read ports.
\item \B{RD\_DATA} \\
This input is \B{RD\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the read ports.
\item \B{WR\_CLK} \\
This input is \B{WR\_PORTS} bits wide, containing all clock signals for the write ports.
\item \B{WR\_EN} \\
This input is \B{WR\_PORTS} bits wide, containing all enable signals for the write ports.
\item \B{WR\_ADDR} \\
This input is \B{WR\_PORTS}*\B{ABITS} bits wide, containing all address signals for the write ports.
\item \B{WR\_DATA} \\
This input is \B{WR\_PORTS}*\B{WIDTH} bits wide, containing all data signals for the write ports.
\end{itemize}
The {\tt techmap} pass can be used to manually map {\tt \$mem} cells to
specialized memory cells on the target architecture, such as block ram resources
on an FPGA.
\subsection{Finite State Machines}
\begin{fixme}
Add a brief description of the {\tt \$fsm} cell type.
\end{fixme}
\section{Gates}
\label{sec:celllib_gates}
For gate level logic networks, fixed function single bit cells are used that do
not provide any parameters.
Simulation models for these cells can be found in the file {\tt techlibs/stdcells\_sim.v} in the Yosys
source tree.
\begin{table}[t]
\hfil
\begin{tabular}[t]{ll}
Verilog & Cell Type \\
\hline
\lstinline[language=Verilog]; Y = ~A; & {\tt \$\_INV\_} \\
\lstinline[language=Verilog]; Y = A & B; & {\tt \$\_AND\_} \\
\lstinline[language=Verilog]; Y = A | B; & {\tt \$\_OR\_} \\
\lstinline[language=Verilog]; Y = A ^ B; & {\tt \$\_XOR\_} \\
\lstinline[language=Verilog]; Y = S ? B : A; & {\tt \$\_MUX\_} \\
\hline
\lstinline[language=Verilog]; always @(negedge C) Q <= D; & {\tt \$\_DFF\_N\_} \\
\lstinline[language=Verilog]; always @(posedge C) Q <= D; & {\tt \$\_DFF\_P\_} \\
\end{tabular}
\hfil
\begin{tabular}[t]{llll}
$ClkEdge$ & $RstLvl$ & $RstVal$ & Cell Type \\
\hline
\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_NN0\_} \\
\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_NN1\_} \\
\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_NP0\_} \\
\lstinline[language=Verilog];negedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_NP1\_} \\
\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_PN0\_} \\
\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];0; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_PN1\_} \\
\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];0; & {\tt \$\_DFF\_PP0\_} \\
\lstinline[language=Verilog];posedge; & \lstinline[language=Verilog];1; & \lstinline[language=Verilog];1; & {\tt \$\_DFF\_PP1\_} \\
\end{tabular}
\caption{Cell types for gate level logic networks}
\label{tab:CellLib_gates}
\end{table}
Table~\ref{tab:CellLib_gates} lists all cell types used for gate level logic. The cell types
{\tt \$\_INV\_}, {\tt \$\_AND\_}, {\tt \$\_OR\_}, {\tt \$\_XOR\_} and {\tt \$\_MUX\_}
are used to model combinatorial logic. The cell types {\tt \$\_DFF\_N\_} and {\tt \$\_DFF\_P\_}
represent d-type flip-flops.
The cell types {\tt \$\_DFF\_NN0\_}, {\tt \$\_DFF\_NN1\_}, {\tt \$\_DFF\_NP0\_}, {\tt \$\_DFF\_NP1\_},
{\tt \$\_DFF\_PN0\_}, {\tt \$\_DFF\_PN1\_}, {\tt \$\_DFF\_PP0\_} and {\tt \$\_DFF\_PP1\_} implement
d-type flip-flops with asynchronous resets. The values in the table for these cell types relate to the
following verilog code template, where \lstinline[mathescape,language=Verilog];$RstEdge$; is \lstinline[language=Verilog];posedge;
if \lstinline[mathescape,language=Verilog];$RstLvl$; if \lstinline[language=Verilog];1;, and \lstinline[language=Verilog];negedge;
otherwise.
\begin{lstlisting}[mathescape,language=Verilog]
always @($ClkEdge$ C, $RstEdge$ R)
if (R == $RstLvl$)
Q <= $RstVa$l;
else
Q <= D;
\end{lstlisting}
In most cases gate level logic networks are created from RTL networks using the {\tt techmap} pass. The flip-flop cells
from the gate level logic network can be mapped to physical flip-flop cells from a Liberty file using the {\tt dfflibmap}
pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC \citeweblink{ABC}
using the {\tt abc} pass.

209
manual/CHAPTER_Eval.tex Normal file
View File

@ -0,0 +1,209 @@
\chapter{Evaluation, Conclusion, Future Work}
\label{chapter:eval}
The Yosys source tree contains over 200 test cases\footnote{Most of this test
cases are copied from HANA \citeweblink{HANA} or the ASIC-WORLD website
\citeweblink{ASIC-WORLD}.} which are used in the {\tt make test} make-target.
Besides these there is an external Yosys benchmark and test case package that
contains a few larger designs \citeweblink{YosysTestsGit}. This package
contains the designs listed in Tab.~\ref{tab:yosys-test-designs}.
\begin{table}
\hfil
\begin{tabular}{lrrp{8.5cm}}
Test-Design & Source & Gates\footnotemark & Description / Comments \\
\hline
{\tt aes\_core} & IWLS2005 & $ 41{,}837 $ & \footnotesize AES Cipher written by Rudolf Usselmann \\
{\tt i2c} & IWLS2005 & $ 1{,}072 $ & \footnotesize WISHBONE compliant I2C Master by Richard Herveille \\
{\tt openmsp430} & OpenCores & $ 7{,}173 $ & \footnotesize MSP430 compatible CPU by Olivier Girard \\
{\tt or1200} & OpenCores & $ 42{,}675 $ & \footnotesize The OpenRISC 1200 CPU by Damjan Lampret \\
{\tt sasc} & IWLS2005 & $ 456 $ & \footnotesize Simple Async. Serial Comm. Device by Rudolf Usselmann \\
{\tt simple\_spi} & IWLS2005 & $ 690 $ & \footnotesize MC68HC11E based SPI interface by Richard Herveille \\
{\tt spi} & IWLS2005 & $ 2{,}478 $ & \footnotesize SPI IP core by Simon Srot \\
{\tt ss\_pcm} & IWLS2005 & $ 279 $ & \footnotesize PCM IO Slave by Rudolf Usselmann \\
{\tt systemcaes} & IWLS2005 & $ 6{,}893 $ & \footnotesize AES core (using SystemC to Verilog) by Javier Castillo \\
{\tt usb\_phy} & IWLS2005 & $ 515 $ & \footnotesize USB 1.1 PHY by Rudolf Usselmann \\
\end{tabular}
\caption{Tests included in the yosys-tests package.}
\label{tab:yosys-test-designs}
\end{table}
\footnotetext{
Number of gates determined using the Yosys synthesis script ``{\tt hierarchy -top \$top; proc; opt; memory; opt; techmap; opt; abc; opt; flatten \$top; hierarchy -top \$top; abc; opt; select -count */c:*}''.
}
\section{Correctness of Synthesis Results}
The following measures were taken to increase the confidence in the correctness of the Yosys synthesis results:
\begin{itemize}
\item Yosys comes with a large selection\footnote{At the time of this writing
269 test cases.} of small test cases that are evaluated when the command {\tt
make test} is executed. During development of Yosys it was shown that this
collection of test cases is sufficient to catch most bugs. The following more
sophisticated test procedures only caught a few additional bugs. Whenever this
happend, an appropiate test case was added to the collection of small test
cases for {\tt make test} to ensure better testability of the feature in
question in the future.
\item The designs listed in Tab.~\ref{tab:yosys-test-designs} where validated
using the formal verification tool Synopsys Formality\citeweblink{Formality}.
The Yosys synthesis scripts used to synthesize the individual designs for this
test are slightly different per design in order to broaden the coverage of
Yosys features. The large majority of all errors encountered using these tests
are false-negatives, mostly related to FSM encoding or signal naming in large
array logic (such as in memory blocks). Therefore the {\tt fsm\_recode} pass
was extended so it can be used to generate TCL commands for Synopsys Formality
that describe the relationship between old and new state encodings. Also the
method used to generate signal and cell names in the Verilog backend was
slightly modified in order to improve the automatic matching of net names in
Synopsys Formality. With these changes in place all designs in Tab.~\ref{tab:yosys-test-designs}
validate successfully using Formality.
\item VlogHammer \citeweblink{VlogHammer} is a set of scripts that
auto-generate a large collection of test cases\footnote{At the time of this
writing over 6600 test cases.} and synthesize them using Yosys and the
following freely available propritary synthesis tools.
\begin{itemize}
\item Xilinx Vivado WebPack (2013.2) \citeweblink{XilinxWebPACK}
\item Xilinx ISE (XST) WebPack (14.5) \citeweblink{XilinxWebPACK}
\item Altera Quartus II Web Edition (13.0) \citeweblink{QuartusWeb}
\end{itemize}
The built-in SAT solver of Yosys is used to formally
verify the Yosys RTL- and Gate-Level netlists against the netlists generated by
this other tools.\footnote{A SAT solver is a program that can solve the boolean
satisfiability problem. The built-in SAT solver in Yosys can be used for formal
equivalence checking, amongst other things. See Sec.~\ref{cmd:sat} for details.}
When differences are found, the input pattern that result in
different outputs are used for simulating the original Verilog code as well as
the synthesis results using the following Verilog simulators.
\begin{itemize}
\item Xilinx ISIM (from Xilinx ISE 14.5 \citeweblink{XilinxWebPACK})
\item Modelsim 10.1d (from Quartus II 13.0 \citeweblink{QuartusWeb})
\item Icarus Verilog (no specific version)
\end{itemize}
The set of tests performed by VlogHammer systematically verify the correct
behaviour of
\begin{itemize}
\item Yosys Verilog Frontend and RTL generation
\item Yosys Gate-Level Technology Mapping
\item Yosys SAT Models for RTL- and Gate-Level cells
\item Yosys Constant Evaluator Models for RTL- and Gate-Level cells
\end{itemize}
against the reference provided by the other tools. A few bugs related to sign
extensions and bit-width extensions where found (and have been fixed meanwhile)
using this approach. This test also revealed a small number of bugs in the
other tools (i.e.~Vivado, XST, Quartus, ISIM and Icarus Verilog; no bugs where
found in Modelsim using vlogHammer so far).
\end{itemize}
Although complex software can never be expected to be fully bug-free
\cite{MURPHY}, it has been shown that Yosys is mature and feature-complete
enough to handle most real-world cases correctly.
\section{Quality of synthesis results}
In this section an attempt to evaluate the quality of Yosys synthesis results is made. To this end the
synthesis results of a commercial FPGA synthesis tool when presented with the original HDL code vs.~when
presented with the Yosys synthesis result are compared.
The OpenMSP430 and the OpenRISC 1200 test cases were synthesized using the following Yosys synthesis script:
\begin{lstlisting}[numbers=left,frame=single,mathescape]
hierarchy -check
proc; opt; fsm; opt; memory; opt
techmap; opt; abc; opt
\end{lstlisting}
The original RTL and the Yosys output where both passed to the Xilinx XST 14.5
FPGA synthesis tool. The following setting where used for XST:
\begin{lstlisting}[numbers=left,frame=single,mathescape]
-p artix7
-use_dsp48 NO
-iobuf NO
-ram_extract NO
-rom_extract NO
-fsm_extract YES
-fsm_encoding Auto
\end{lstlisting}
The results of this comparison is summarized in Tab.~\ref{tab:synth-test}. The
used FPGA resources (registers and LUTs) and performance (maximum frequency as
reported by XST) are given per module (indentation indicates module hierarchy,
the numbers are including all contained modules).
For most modules the results are very similar between XST and Yosys. XST is
used in both cases for the final mapping of logic to LUTs. So this comparison
only compares the high-level synthesis functions (such as FSM extraction and
encoding) of Yosys and XST.
\begin{table}
\def\nomhz{--- \phantom{MHz}}
\def\P#1 {(#1\hbox to 0px{)\hss}}
\hfil
\begin{tabular}{l|rrr|rrr}
& \multicolumn{3}{c|}{Without Yosys} & \multicolumn{3}{c}{With Yosys} \\
Module & Regs & LUTs & Max. Freq. & Regs & LUTs & Max. Freq. \\
\hline
{\tt openMSP430} & 689 & 2210 & 71 MHz & 719 & 2779 & 53 MHz \\
{\tt \hskip1em omsp\_clock\_module} & 21 & 30 & 645 MHz & 21 & 30 & 644 MHz \\
{\tt \hskip1em \hskip1em omsp\_sync\_cell} & 2 & --- & 1542 MHz & 2 & --- & 1542 MHz \\
{\tt \hskip1em \hskip1em omsp\_sync\_reset} & 2 & --- & 1542 MHz & 2 & --- & 1542 MHz \\
{\tt \hskip1em omsp\_dbg} & 143 & 344 & 292 MHz & 149 & 430 & 353 MHz \\
{\tt \hskip1em \hskip1em omsp\_dbg\_uart} & 76 & 135 & 377 MHz & 79 & 139 & 389 MHz \\
{\tt \hskip1em omsp\_execution\_unit} & 266 & 911 & 80 MHz & 266 & 1034 & 137 MHz \\
{\tt \hskip1em \hskip1em omsp\_alu} & --- & 202 & \nomhz & --- & 263 & \nomhz \\
{\tt \hskip1em \hskip1em omsp\_register\_file} & 231 & 478 & 285 MHz & 231 & 506 & 293 MHz \\
{\tt \hskip1em omsp\_frontend} & 115 & 340 & 178 MHz & 118 & 527 & 206 MHz \\
{\tt \hskip1em omsp\_mem\_backbone} & 38 & 141 & 1087 MHz & 38 & 144 & 1087 MHz \\
{\tt \hskip1em omsp\_multiplier} & 73 & 397 & 129 MHz & 102 & 1053 & 55 MHz \\
{\tt \hskip1em omsp\_sfr} & 6 & 18 & 1023 MHz & 6 & 20 & 1023 MHz \\
{\tt \hskip1em omsp\_watchdog} & 24 & 53 & 362 MHz & 24 & 70 & 360 MHz \\
\hline
{\tt or1200\_top} & 7148 & 9969 & 135 MHz & 7173 & 10238 & 108 MHz \\
{\tt \hskip1em or1200\_alu} & --- & 681 & \nomhz & --- & 641 & \nomhz \\
{\tt \hskip1em or1200\_cfgr} & --- & 11 & \nomhz & --- & 11 & \nomhz \\
{\tt \hskip1em or1200\_ctrl} & 175 & 186 & 464 MHz & 174 & 279 & 377 MHz \\
{\tt \hskip1em or1200\_except} & 241 & 451 & 313 MHz & 241 & 353 & 301 MHz \\
{\tt \hskip1em or1200\_freeze} & 6 & 18 & 507 MHz & 6 & 16 & 515 MHz \\
{\tt \hskip1em or1200\_if} & 68 & 143 & 806 MHz & 68 & 139 & 790 MHz \\
{\tt \hskip1em or1200\_lsu} & 8 & 138 & \nomhz & 12 & 205 & 1306 MHz \\
{\tt \hskip1em \hskip1em or1200\_mem2reg} & --- & 60 & \nomhz & --- & 66 & \nomhz \\
{\tt \hskip1em \hskip1em or1200\_reg2mem} & --- & 29 & \nomhz & --- & 29 & \nomhz \\
{\tt \hskip1em or1200\_mult\_mac} & 394 & 2209 & 240 MHz & 394 & 2230 & 241 MHz \\
{\tt \hskip1em \hskip1em or1200\_amultp2\_32x32} & 256 & 1783 & 240 MHz & 256 & 1770 & 241 MHz \\
{\tt \hskip1em or1200\_operandmuxes} & 65 & 129 & 1145 MHz & 65 & 129 & 1145 MHz \\
{\tt \hskip1em or1200\_rf} & 1041 & 1722 & 822 MHz & 1042 & 1722 & 581 MHz \\
{\tt \hskip1em or1200\_sprs} & 18 & 432 & 724 MHz & 18 & 469 & 722 MHz \\
{\tt \hskip1em or1200\_wbmux} & 33 & 93 & \nomhz & 33 & 78 & \nomhz \\
{\tt \hskip1em or1200\_dc\_top} & --- & 5 & \nomhz & --- & 5 & \nomhz \\
{\tt \hskip1em or1200\_dmmu\_top} & 2445 & 1004 & \nomhz & 2445 & 1043 & \nomhz \\
{\tt \hskip1em \hskip1em or1200\_dmmu\_tlb} & 2444 & 975 & \nomhz & 2444 & 1013 & \nomhz \\
{\tt \hskip1em or1200\_du} & 67 & 56 & 859 MHz & 67 & 56 & 859 MHz \\
{\tt \hskip1em or1200\_ic\_top} & 39 & 100 & 527 MHz & 41 & 136 & 514 MHz \\
{\tt \hskip1em \hskip1em or1200\_ic\_fsm} & 40 & 42 & 408 MHz & 40 & 75 & 484 MHz \\
{\tt \hskip1em or1200\_pic} & 38 & 50 & 1169 MHz & 38 & 50 & 1177 MHz \\
{\tt \hskip1em or1200\_tt} & 64 & 112 & 370 MHz & 64 & 186 & 437 MHz \\
\end{tabular}
\caption{Synthesis results (as reported by XST) for OpenMSP430 and OpenRISC 1200}
\label{tab:synth-test}
\end{table}
\section{Conclusion and Future Work}
Yosys is capable of correctly synthesizing real-world Verilog designs. The
generated netlists are of a decent quality. However, in cases where dedicated
hardware resources should be used for certain functions it is of course
necessary to implement proper technology mapping for these functions in
Yosys. This can be as easy as calling the {\tt techmap} pass with an
architecture-specific mapping file in the synthesis script. As no such thing
has been done in the above tests, it is only natural that the resulting designs
cannot benefit from these dedicated hardware resources.
Therefore future work includes the implementation of architecture-specific
technology mappings besides additional frontends (VHDL), backends (EDIF),
and above all else, application specific passes. After all, this was
the main motivation for the development of Yosys in the first place.

98
manual/CHAPTER_Intro.tex Normal file
View File

@ -0,0 +1,98 @@
\chapter{Introduction}
\label{chapter:intro}
This document presents the Free and Open Source (FOSS) Verilog HDL synthesis tool ``Yosys''.
Its design and implementation as well as its performance on real-world designs
is discussed in this document.
\section{History of Yosys}
A Hardware Description Language (HDL) is a computer language used to describe
circuits. A HDL synthesis tool is a computer program that takes a formal
description of a circuit written in an HDL as input and generates a netlist
that implements the given circuit as output.
Currently the most widely used and supported HDLs for digital circuits are
Verilog \cite{Verilog2005}\cite{VerilogSynth} and
VHDL\footnote{VHDL is an acronym for ``VHSIC hardware description language''
and VHSIC is an acronym for ``Very-High-Speed Integrated
Circuits''.} \cite{VHDL}\cite{VHDLSynth}.
Both HDLs are used for test and verification purposes as well as logic
synthesis, resulting in a set of synthesizable and a set of non-synthesizable
language features. In this document we only look at the synthesizable subset
of the language features.
In recent work on heterogeneous coarse-grain reconfigurable
logic \cite{intersynth} the need for a custom application-specific HDL synthesis
tool emerged. It was soon realised that a synthesis tool that understood Verilog
or VHDL would be preferred over a synthesis tool for a custom HDL. Given an
existing Verilog or VHDL front end, the work for writing the necessary
additional features and integrating them in an existing tool can be estimated to be
about the same as writing a new tool with support for a minimalistic custom HDL.
The proposed custom HDL synthesis tool should be licensed under a Free
and Open Source Software (FOSS) licence. So an existing FOSS Verilog or VHDL
synthesis tool would have been needed as basis to build upon. The main advantages
of choosing Verilog or VHDL is the ability to synthesize existing HDL code and
to mitigate the requirement for circuit-designers to learn a new language. In order to take full advantage of any existing FOSS Verilog or VHDL tool,
such a tool would have to provide a feature-complete implementation of the
synthesizable HDL subset.
Basic RTL synthesis is a well understood field \cite{LogicSynthesis}. Lexing,
parsing and processing of computer languages \cite{Dragonbook} is a thoroughly
researched field. All the information required to write such tools has been openly
available for a long time, and it is therefore likely that a FOSS HDL synthesis tool
with a feature-complete Verilog or VHDL front end must exist which can be used as a basis for a custom RTL synthesis tool.
Due to the authors preference for Verilog over VHDL it has been decided early
on to go for Verilog instead of VHDL\footnote{A quick investigation into FOSS
VHDL tools yielded similar grim results for FOSS VHDL synthesis tools.}.
So the existing FOSS Verilog synthesis tools were evaluated (see
App.~\ref{chapter:sota}). The results of this evaluation are utterly
devastating. Therefore a completely new Verilog synthesis tool was implemented
and is recommended as basis for custom synthesis tools. This is the tool that
is discussed in this document.
\section{Structure of this Document}
The structure of this document is a follows:
Chapter~\ref{chapter:intro} is this introduction.
Chapter~\ref{chapter:basics} covers a short introduction to the world of HDL
synthesis. Basic principles and the terminology is outlined in this chapter.
Chapter~\ref{chapter:approach} gives the quickest possible outline to how the
problem of implementing a HDL synthesis tool is approached in the case of
Yosys.
Chapter~\ref{chapter:overview} contains a more detailed overview of the
implementation of Yosys. This chapter covers the data structures used in
Yosys to represent a design in detail and is therefore recommended reading
for everyone who is interested in understanding the Yosys internals.
Chapter~\ref{chapter:celllib} covers the internal cell library used by Yosys.
This is especially important knowledge for anyone who wants to understand the
intermediate netlists used internally by Yosys.
Chapter~ \ref{chapter:prog} gives a tour to the internal APIs of Yosys. This
is recommended reading for everyone who actually wants to read or write
Yosys source code. The chapter concludes with an example loadable module
for Yosys.
Chapters~\ref{chapter:verilog}, \ref{chapter:opt}, and \ref{chapter:techmap}
cover three improtant pieces of the synthesis pileline: The Verilog frontend,
the optimization passes and the technology mapping to the target architecture,
respectively.
Chapter~\ref{chapter:eval} covers the evaluation of the performance
(correctness and quality) of Yosys on real-world input data.
The chapter concludes the main part of this document with conclusions and
outlook to future work.
Various appendices, including a command reference manual
(App.~\ref{commandref}) and an evaluation of pre-existing FOSS Verilog
synthesis tools (App.~\ref{chapter:sota}) complete this document.

320
manual/CHAPTER_Optimize.tex Normal file
View File

@ -0,0 +1,320 @@
\chapter{Optimizations}
\label{chapter:opt}
Yosys employs a number of optimizations to generate better and cleaner results.
This chapter outlines these optimizations.
\section{Simple Optimizations}
The Yosys pass {\tt opt} runs a number of simple optimizations. This includes removing unused
signals and cells and const folding. It is recommended to run this pass after each major step
in the synthesis script. At the time of this writing the {\tt opt} pass executes the following
passes that each perform a simple optimization:
\begin{itemize}
\item Once at the beginning of {\tt opt}:
\begin{itemize}
\item {\tt opt\_const}
\item {\tt opt\_share -nomux}
\end{itemize}
\item Repeat until result is stable:
\begin{itemize}
\item {\tt opt\_muxtree}
\item {\tt opt\_reduce}
\item {\tt opt\_share}
\item {\tt opt\_rmdff}
\item {\tt opt\_clean}
\item {\tt opt\_const}
\end{itemize}
\end{itemize}
The following section describes each of the {\tt opt\_*} passes.
\subsection{The opt\_const pass}
This pass performs const folding on the internal combinational cell types
described in Chap.~\ref{chapter:celllib}. This means a cell with all constant
inputs is replaced with the constant value this cell drives. In some cases
this pass can also optimize cells with some constant inputs.
\begin{table}
\hfil
\begin{tabular}{cc|c}
A-Input & B-Input & Replacement \\
\hline
any & 0 & 0 \\
0 & any & 0 \\
1 & 1 & 1 \\
\hline
X/Z & X/Z & X \\
1 & X/Z & X \\
X/Z & 1 & X \\
\hline
any & X/Z & 0 \\
X/Z & any & 0 \\
\hline
$a$ & 1 & $a$ \\
1 & $b$ & $b$ \\
\end{tabular}
\caption{Const folding rules for {\tt\$\_AND\_} cells as used in {\tt opt\_const}.}
\label{tab:opt_const_and}
\end{table}
Table~\ref{tab:opt_const_and} shows the replacement rules used for optimizing
an {\tt\$\_AND\_} gate. The first three rules implement the obvious const folding
rules. Note that `any' might include dynamic values calculated by other parts
of the circuit. The following three lines propagate undef (X) states.
These are the only three cases in which it is allowed to propagate an undef
according to Sec.~5.1.10 of IEEE Std. 1364-2005 \cite{Verilog2005}.
The next two lines assume the value 0 for undef states. These two rules are only
used if no other subsitutions are possible in the current module. If other substitutions
are possible they are performed first, in the hope that the `any' will change to
an undef value or a 1 and therefore the output can be set to undef.
The last two lines simply replace an {\tt\$\_AND\_} gate with one constant-1
input with a buffer.
Besides this basic const folding the {\tt opt\_const} pass can replace 1-bit wide
{\tt \$eq} and {\tt \$ne} cells with buffers or not-gates if one input is constant.
The {\tt opt\_const} pass is very conservative regarding optimizing {\tt \$mux} cells,
as these cells are often used to model decision-trees and breaking these trees can
interfere with other optimizations.
\subsection{The opt\_muxtree pass}
This pass optimizes trees of multiplexer cells by analyzing the select inputs.
Consider the following simple example:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
module uut(a, y);
input a;
output [1:0] y = a ? (a ? 1 : 2) : 3;
endmodule
\end{lstlisting}
The output can never be 2, as this would require \lstinline[language=Verilog];a;
to be 1 for the outer multiplexer and 0 for the inner multiplexer. The {\tt
opt\_muxtree} pass detects this contradiction and replaces the inner multiplexer
with a constant 1, yielding the logic for \lstinline[language=Verilog];y = a ? 1 : 3;.
\subsection{The opt\_reduce pass}
\begin{sloppypar}
This is a simple optimization pass that identifies and consolidates identical input
bits to {\tt \$reduce\_and} and {\tt \$reduce\_or} cells. It also sorts the input
bits to ease identification of shareable {\tt \$reduce\_and} and {\tt \$reduce\_or} cells
in other passes.
\end{sloppypar}
This pass also identifies and consolidates identical inputs to multiplexer cells. In this
case the new shared select bit is driven using a {\tt \$reduce\_or} cell that combines
the original select bits.
Lastly this pass consolidates trees of {\tt \$reduce\_and} cells and trees of
{\tt \$reduce\_or} cells to single large {\tt \$reduce\_and} or {\tt \$reduce\_or} cells.
These three simple optimizations are performed in a loop until a stable result is
produced.
\subsection{The opt\_rmdff pass}
This pass identifies single-bit d-type flip-flops ({\tt \$\_DFF\_*}, {\tt \$dff}, and {\tt
\$adff} cells) with a constant data input and replaces them with a constant driver.
\subsection{The opt\_clean pass}
This pass identifies unused signals and cells and removes them from the design. It also
creates an \B{unused\_bits} attribute on wires with unused bits. This attribute can be
used for debugging or by other optimization passes.
\subsection{The opt\_share pass}
This pass performs trivial resource sharing. This means that this pass identifies cells
with identical inputs and replaces them with a single instance of the cell.
The option {\tt -nomux} can be used to disable resource sharing for multiplexer
cells ({\tt \$mux}, {\tt \$pmux}, and {\tt \$safe\_pmux}). This can be useful as
it prevents multiplexer trees to be merged, which might prevent {\tt opt\_muxtree}
to identify possible optimizations.
\section{FSM Extraction and Encoding}
The {\tt fsm} pass performs finite-state-machine (FSM) extraction and recoding. The {\tt fsm}
pass simply executes the following other passes:
\begin{itemize}
\item Identify and extract FSMs:
\begin{itemize}
\item {\tt fsm\_detect}
\item {\tt fsm\_extract}
\end{itemize}
\item Basic optimizations:
\begin{itemize}
\item {\tt fsm\_opt}
\item {\tt opt\_clean}
\item {\tt fsm\_opt}
\end{itemize}
\item Expanding to nearby gate-logic (if called with {\tt -expand}):
\begin{itemize}
\item {\tt fsm\_expand}
\item {\tt opt\_clean}
\item {\tt fsm\_opt}
\end{itemize}
\item Re-code FSM states (unless called with {\tt -norecode}):
\begin{itemize}
\item {\tt fsm\_recode}
\end{itemize}
\item Print information about FSMs:
\begin{itemize}
\item {\tt fsm\_info}
\end{itemize}
\item Export FSMs in KISS2 file format (if called with {\tt -export}):
\begin{itemize}
\item {\tt fsm\_export}
\end{itemize}
\item Map FSMs to RTL cells (unless called with {\tt -nomap}):
\begin{itemize}
\item {\tt fsm\_map}
\end{itemize}
\end{itemize}
The {\tt fsm\_detect} pass identifies FSM state registers and marks them using the
\B{fsm\_encoding}{\tt = "auto"} attribute. The {\tt fsm\_extract} extracts all
FSMs marked using the \B{fsm\_encoding} attribute (unless \B{fsm\_encoding} is
set to {\tt "none"}) and replaces the corresponding RTL cells with a {\tt \$fsm}
cell. All other {\tt fsm\_*} passes operate on these {\tt \$fsm} cells. The
{\tt fsm\_map} call finally replaces the {\tt \$fsm} cells with RTL cells.
Note that these optimizations operate on an RTL netlist. I.e.~the {\tt fsm} pass
should be executed after the {\tt proc} pass has transformed all
{\tt RTLIL::Process} objects to RTL cells.
The algorithms used for FSM detection and extraction are influenced by a more
general reported technique \cite{fsmextract}.
\subsection{FSM Detection}
The {\tt fsm\_detect} pass identifies FSM state registers. It sets the
\B{fsm\_encoding}{\tt = "auto"} attribute on any (multi-bit) wire that matches
the following description:
\begin{itemize}
\item Does not already have the \B{fsm\_encoding} attribute.
\item Is not an output of the containing module.
\item Is driven by single {\tt \$dff} or {\tt \$adff} cell.
\item The \B{D}-Input of this {\tt \$dff} or {\tt \$adff} cell is driven by a multiplexer
tree that only has constants or the old state value on its leaves.
\item The state value is only used in the said multiplexer tree or by simple relational
cells that compare the state value to a constant (usually {\tt \$eq} cells).
\end{itemize}
This heuristic has proven to work very well. It is possible to overwrite it by setting
\B{fsm\_encoding}{\tt = "auto"} on registers that should be considered FSM state registers
and setting \B{fsm\_encoding}{\tt = "none"} on registers that match the above criteria
but should not be considered FSM state registers.
\subsection{FSM Extraction}
The {\tt fsm\_extract} pass operates on all state signals marked with the
\B{fsm\_encoding} ({\tt != "none"}) attribute. For each state signal the following
information is determined:
\begin{itemize}
\item The state registers
\item The asynchronous reset state if the state registers use asynchronous reset
\item All states and the control input signals used in the state transition functions
\item The control output signals calculated from the state signals and control inputs
\item A table of all state transitions and corresponding control inputs- and outputs
\end{itemize}
The state registers (and asynchronous reset state, if applicable) is simply determined
by identifying the driver for the state signal.
From there the {\tt \$mux}-tree driving the state register inputs is
recursively traversed. All select inputs are control signals and the leaves of the
{\tt \$mux}-tree are the states. The algorithm fails if a non-constant leaf
that is not the state signal itself is found.
The list of control outputs is initialized with the bits from the state signal.
It is then extended by adding all values that are calculated by cells that
compare the state signal with a constant value.
In most cases this will cover all uses of the state register, thus rendering the
state encoding arbitrary. If however a design uses e.g.~a single bit of the state
value to drive a control output directly, this bit of the state signal will be
transformed to a control output of the same value.
Finally, a transition table for the FSM is generated. This is done by using the
{\tt ConstEval} C++ helper class (defined in {\tt kernel/consteval.h}) that can
be used to evaluate parts of the design. The {\tt ConstEval} class can be asked
to calculate a given set of result signals using a set of signal-value
assignments. It can also be passed a list of stop-signals that abort the {\tt
ConstEval} algorithm if the value of a stop-signal is needed in order to
calculate the result signals.
The {\tt fsm\_extract} pass uses the {\tt ConstEval} class in the following way
to create a transition table. For each state:
\begin{enumerate}
\item Create a {\tt ConstEval} object for the module containing the FSM
\item Add all control inputs to the list of stop signals
\item Set the state signal to the current state
\item Try to evaluate the next state and control output \label{enum:fsm_extract_cealg_try}
\item If step~\ref{enum:fsm_extract_cealg_try} was not successful:
\begin{itemize}
\item Recursively goto step~\ref{enum:fsm_extract_cealg_try} with the offending stop-signal set to 0.
\item Recursively goto step~\ref{enum:fsm_extract_cealg_try} with the offending stop-signal set to 1.
\end{itemize}
\item If step~\ref{enum:fsm_extract_cealg_try} was successful: Emit transition
\end{enumerate}
Finally a {\tt \$fsm} cell is created with the generated transition table and added to the
module. This new cell is connected to the control signals and the old drivers for the
control outputs are disconnected.
\subsection{FSM Optimization}
The {\tt fsm\_opt} pass performs basic optimizations on {\tt \$fsm} cells (not including state
recoding). The following optimizations are performed (in this order):
\begin{itemize}
\item Unused control outputs are removed from the {\tt \$fsm} cell. The attribute \B{unused\_bits}
(that is usually set by the {\tt opt\_clean} pass) is used to determine which control
outputs are unused.
\item Control inputs that are connected to the same driver are merged.
\item When a control input is driven by a control output, the control input is removed and the transition
table altered to give the same performance without the external feedback path.
\item Entries in the transition table that yield the same output and only
differ in the value of a single control input bit are merged and the different bit is removed
from the sensitivity list (turned into a don't-care bit).
\item Constant inputs are removed and the transition table is alterered to give an unchanged behaviour.
\item Unused inputs are removed.
\end{itemize}
\subsection{FSM Recoding}
The {\tt fsm\_recode} pass assigns new bit pattern to the states. Usually this
also implies a change in the width of the state signal. At the moment of this
writing only one-hot encoding with all-zero for the reset state is supported.
The {\tt fsm\_recode} pass can also write a text file with the changes performed
by it that can be used when verifying designs synthesized by Yosys using Synopsys
Formality \citeweblink{Formality}.
\section{Logic Optimization}
Yosys can perform multi-level combinational logic optimization on gate-level netlists using the
external program ABC \citeweblink{ABC}. The {\tt abc} pass extracts the combinational gate-level
parts of the design, passes it through ABC, and re-integrates the results. The {\tt abc} pass
can also be used to perform other operations using ABC, such as technology mapping (see
Sec.~\ref{sec:techmap_extern} for details).

525
manual/CHAPTER_Overview.tex Normal file
View File

@ -0,0 +1,525 @@
\chapter{Implementation Overview}
\label{chapter:overview}
Yosys is an extensible open source hardware synthesis tool. It is aimed at
designers who are looking for an easy accessible, universal, and vendor
independent synthesis tool, and scientists who do research in
electronic design automation (EDA) and are looking for an open synthesis
framework that can be used to test algorithms on complex real-world designs.
Yosys can synthesize a large subset of Verilog 2005 and has been tested with a
wide range of real-world designs, including the OpenRISC 1200 CPU
\citeweblink{OR1200}, the openMSP430 CPU \citeweblink{openMSP430}, the
OpenCores I$^2$C master \citeweblink{i2cmaster} and the k68 CPU \citeweblink{k68}.
As of this writing a Yosys VHDL frontend is in development.
Yosys is written in C++ (using some features from the new C++11 standard). This
chapter describes some of the fundamental Yosys data structures. For the sake
of simplicity the C++ type names used in the Yosys implementation are used in
this chapter, even though the chapter only explains the conceptual idea behind
it and can be used as reference to implement a similar system in any language.
\section{Simplified Data Flow}
Figure~\ref{fig:Overview_flow} shows the simplified data flow within Yosys.
Rectangles in the figure represent program modules and ellipses internal
data structures that are used to exchange design data between the program
modules.
Design data is read in using one of the frontend modules. The high-level HDL
frontends for Verilog and VHDL code generate an abstract syntax tree (AST) that
is then passed to the AST frontend. Note that both HDL frontends use the same
AST representation that is powerful enough to cover the Verilog HDL and VHDL
language.
The AST Frontend then compiles the AST to Yosys's main internal data format,
the RTL Intermediate Language (RTLIL). A more detailed description of this format
is given in the next section.
There is also a text representation of the RTLIL data structure that can be
parsed using the ILANG Frontend.
The design data may then be transformed using a series of passes that all
operate on the RTLIL representation of the design.
Finally the design in RTLIL representation is converted back to text by one
of the backends, namely the Verilog Backend for generating Verilog netlists
and the ILANG Backend for writing the RTLIL data in the same format that is
understood by the ILANG Frontend.
With the exception of the AST Frontend, that is called by the high-level HDL
frontends and can't be called directly by the user, all program modules are
called by the user (usually using a synthesis script that contains text
commands for Yosys).
By combining passes in different ways and/or adding additional passes to Yosys
it is possible to adapt Yosys to a wide range of applications. For this to be
possible it is key that (1) all passes operate on the same data structure
(RTLIL) and (2) that this data structure is powerful enough represent the design
in different stages of the synthesis.
\begin{figure}[t]
\hfil
\begin{tikzpicture}
\tikzstyle{process} = [draw, fill=green!10, rectangle, minimum height=3em, minimum width=10em, node distance=15em]
\tikzstyle{data} = [draw, fill=blue!10, ellipse, minimum height=3em, minimum width=7em, node distance=15em]
\node[process] (vlog) {Verilog Frontend};
\node[process, dashed, fill=green!5] (vhdl) [right of=vlog] {VHDL Frontend};
\node[process] (ilang) [right of=vhdl] {ILANG Frontend};
\node[data] (ast) [below of=vlog, node distance=5em, xshift=7.5em] {AST};
\node[process] (astfe) [below of=ast, node distance=5em] {AST Frontend};
\node[data] (rtlil) [below of=astfe, node distance=5em, xshift=7.5em] {RTLIL};
\node[process] (pass) [right of=rtlil, node distance=5em, xshift=7.5em] {Passes};
\node[process] (vlbe) [below of=rtlil, node distance=5em, xshift=-7.5em] {Verilog Backend};
\node[process] (ilangbe) [below of=rtlil, node distance=5em, xshift=+7.5em] {ILANG Backend};
\draw[-latex] (vlog) -- (ast);
\draw[-latex] (vhdl) -- (ast);
\draw[-latex] (ast) -- (astfe);
\draw[-latex] (astfe) -- (rtlil);
\draw[-latex] (ilang) -- (rtlil);
\draw[latex-latex] (rtlil) -- (pass);
\draw[-latex] (rtlil) -- (vlbe);
\draw[-latex] (rtlil) -- (ilangbe);
\end{tikzpicture}
\caption{Yosys simplified data flow (ellipses: data structures, rectangles: program modules)}
\label{fig:Overview_flow}
\end{figure}
\section{The RTL Intermediate Language}
All frontends, passes and backends in Yosys operate on a design in RTLIL\footnote{The {\it Language} in {\it RTL Intermediate Language}
refers to the fact, that RTLIL also has a text representation, usually referred to as {\it Intermediate Language} (ILANG).} representation.
The only exception are the high-level frontends that use the AST representation as an intermediate step before generating RTLIL
data.
In order to avoid re-inventing names for the RTLIL classes, they are simply referred to by their full C++ name, i.e.~including
the {\tt RTLIL::} namespace prefix, in this document.
Figure~\ref{fig:Overview_RTLIL} shows a simplified Entity-Relationship Diagram (ER Diagram) of RTLIL. In $1:N$ relationships the arrow
points from the $N$ side to the $1$. For example one RTLIL::Design contains $N$ (zero to many) instances of RTLIL::Module.
A two-pointed arrow indicates a $1:1$ relationship.
The RTLIL::Design is the root object of the RTLIL data structure. There is always one ``current design'' in memory
on which passes operate, frontends add data to it and backends convert to exportable formats. But in some cases passes
internally generate additional RTLIL::Design objects. For example when a pass is reading an auxiliary Verilog file such
as a cell library, it might create an additional RTLIL::Design object and call the Verilog frontend with this
other object to parse the cell library.
\begin{figure}[t]
\hfil
\begin{tikzpicture}
\tikzstyle{entity} = [draw, fill=gray!10, rectangle, minimum height=3em, minimum width=7em, node distance=5em, font={\ttfamily}]
\node[entity] (design) {RTLIL::Design};
\node[entity] (module) [right of=design, node distance=11em] {RTLIL::Module} edge [-latex] node[above] {\tiny 1 \hskip3em N} (design);
\node[entity] (process) [fill=green!10, right of=module, node distance=10em] {RTLIL::Process} (process.west) edge [-latex] (module);
\node[entity] (memory) [fill=red!10, below of=process] {RTLIL::Memory} edge [-latex] (module);
\node[entity] (wire) [fill=blue!10, above of=process] {RTLIL::Wire} (wire.west) edge [-latex] (module);
\node[entity] (cell) [fill=blue!10, above of=wire] {RTLIL::Cell} (cell.west) edge [-latex] (module);
\node[entity] (case) [fill=green!10, right of=process, node distance=10em] {RTLIL::CaseRule} edge [latex-latex] (process);
\node[entity] (sync) [fill=green!10, above of=case] {RTLIL::SyncRule} edge [-latex] (process);
\node[entity] (switch) [fill=green!10, below of=case] {RTLIL::SwitchRule} edge [-latex] (case);
\draw[latex-] (switch.east) -- ++(1em,0) |- (case.east);
\end{tikzpicture}
\caption{Simplified RTLIL Entity-Relationship Diagram}
\label{fig:Overview_RTLIL}
\end{figure}
There is only one active RTLIL::Design object that is used by all frontends,
passes and backends called by the user, e.g.~using a synthesis script. The RTLIL::Design then contains
zero to many RTLIL::Module objects. This corresponds to modules in Verilog or entities in VHDL. Each
module in turn contains objects from three different categories:
\begin{itemize}
\item RTLIL::Cell and RTLIL::Wire objects represent classical netlist data.
\item RTLIL::Process objects represent the decision trees (if-then-else statements, etc.) and synchronization
declarations (clock signals and sensitivity) from Verilog {\tt always} and VHDL {\tt process} blocks.
\item RTLIL::Memory objects represent addressable memories (arrays).
\end{itemize}
\begin{sloppypar}
Usually the output of the synthesis procedure is a netlist, i.e. all
RTLIL::Process and RTLIL::Memory objects must be replaced by RTLIL::Cell and
RTLIL::Wire objects by synthesis passes.
\end{sloppypar}
All features of the HDL that cannot be mapped directly to these RTLIL classes must be
transformed to an RTLIL-compatible representation by the HDL frontend. This includes
Verilog-features such as generate-blocks, loops and parameters.
The following sections contain a more detailed description of the different
parts of RTLIL and rationales behind some of the design decisions.
\subsection{RTLIL Identifiers}
All identifiers in RTLIL (such as module names, port names, signal names, cell
types, etc.) follow the following naming convention: They must either start with
a backslash (\textbackslash) or a dollar sign (\$).
Identifiers starting with a backslash are public visible identifiers. Usually
they originate from one of the HDL input files. For example the signal name ``{\tt \textbackslash sig42}''
is most likely a signal that was declared using the name ``{\tt sig42}'' in an HDL input file.
On the other hand the signal name ``{\tt \$sig42}'' is an auto-generated signal name. The backends
convert all identifiers that start with a dollar sign to identifiers that do not collide with
identifiers that start with a backslash.
This has three advantages:
\begin{itemize}
\item Firstly it is impossible that an auto-generated identifier collides with
an identifier that was provided by the user.
\item Secondly the information about which identifiers were originally
provided by the user is always available which can help guide some optimizations. For example the ``opt\_rmunused''
is trying to preserve signals with a user-provided name but doesn't hesitate to delete signals that have
auto-generated names when they just duplicate other signals.
\item Thirdly the delicate job of finding suitable auto-generated public visible
names is deferred to one central location. Internally auto-generated names that
may hold important information for Yosys developers can be used without
disturbing external tools. For example the Verilog backend assigns names in the form {\tt \_{\it integer}\_}.
\end{itemize}
In order to avoid programming errors, the RTLIL data structures check if all
identifiers start with either a backslash or a dollar sign and generate a
runtime error if this rule is violated.
All RTLIL identifiers are case sensitive.
\subsection{RTLIL::Design and RTLIL::Module}
The RTLIL::Design object is basically just a container for RTLIL::Module objects. In addition to
a list of RTLIL::Module objects the RTLIL::Design also keeps a list of {\it selected objects}, i.e.
the objects that passes should operate on. In most cases the whole design is selected and therefore
passes operate on the whole design. But this mechanism can be useful for more complex synthesis jobs
in which only parts of the design should be affected by certain passes.
Besides the objects shown in the ER diagram in Fig.~\ref{fig:Overview_RTLIL} an RTLIL::Module object
contains the following additional properties:
\begin{itemize}
\item The module name
\item A list of attributes
\item A list of connections between wires
\item An optional frontend callback used to derive parametrized variations of the module
\end{itemize}
The attributes can be Verilog attributes imported by the Verilog frontend or attributes assigned
by passes. They can be used to store additional metadata about modules or just mark them to be
used by certain part of the synthesis script but not by others.
Verilog and VHDL both support parametric modules (known as ``generic entities'' in VHDL). The RTLIL
format does not support parametric modules itself. Instead each module contains a callback function
into the AST frontend to generate a parametrized variation of the RTLIL::Module as needed. This
callback then returns the auto-generated name of the parametrized variation of the module. (A hash
over the parameters and the module name is used to prohibit the same parametrized variation to be
generated twice. For modules with only a few parameters, a name directly containing all parameters
is generated instead of a hash string.)
\subsection{RTLIL::Cell and RTLIL::Wire}
A module contains zero to many RTLIL::Cell and RTLIL::Wire objects. Objects of
these types are used to model netlists. Usually the goal of all synthesis efforts is to convert
all modules to a state where the functionality of the module is implemented only by cells
from a given cell library and wires to connect these cells with each other. Note that module
ports are just wires with a special property.
An RTLIL::Wire object has the following properties:
\begin{itemize}
\item The wire name
\item A list of attributes
\item A width (busses are just wires with a width > 1)
\item If the wire is a port: port number and direction (input/output/inout)
\end{itemize}
As with modules, the attributes can be Verilog attributes imported by the
Verilog frontend or attributes assigned by passees.
In Yosys, busses (signal vectors) are represented using a single wire object
with a width > 1. So Yosys does not convert signal vectors to individual signals.
This makes some aspects of RTLIL more complex but enables Yosys to be used for
coarse grain synthesis where the cells of the target architecture operate on
entire signal vectors instead of single bit wires.
An RTLIL::Cell object has the following properties:
\begin{itemize}
\item The cell name and type
\item A list of attributes
\item A list of parameters (for parametric cells)
\item Cell ports and the connections of ports to wires and constants
\end{itemize}
The connections of ports to wires are coded by assigning an RTLIL::SigSpec
to each cell ports. The RTLIL::SigSpec data type is described in the next section.
\subsection{RTLIL::SigSpec}
A ``signal'' is everything that can be applied to a cell port. I.e.
\begin{itemize}
\item Any constant value of arbitrary bit-width \\
\null\hskip1em For example: \lstinline[language=Verilog]{1337, 16'b0000010100111001, 1'b1, 1'bx}
\item All bits of a wire or a selection of bits from a wire \\
\null\hskip1em For example: \lstinline[language=Verilog]{mywire, mywire[24], mywire[15:8]}
\item Concatenations of the above \\
\null\hskip1em For example: \lstinline[language=Verilog]|{16'd1337, mywire[15:8]}|
\end{itemize}
The RTLIL::SigSpec data type is used to represent signals. The RTLIL::Cell
object contains one RTLIL::SigSpec for each cell port.
In addition, connections between wires are represented using a pair of
RTLIL::SigSpec objects. Such pairs are needed in different locations. Therefore
the type name RTLIL::SigSig was defined for such a pair.
\subsection{RTLIL::Process}
When a high-level HDL frontend processes behavioural code it splits it up into
data path logic (e.g.~the expression {\tt a + b} is replaced by the output of an
adder that takes {\tt a} and {\tt b} as inputs) and an RTLIL::Process that models
the control logic of the behavioural code. Let's consider a simple example:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
module ff_with_en_and_async_reset(clock, reset, enable, d, q);
input clock, reset, enable, d;
output reg q;
always @(posedge clock, posedge reset)
if (reset)
q <= 0;
else if (enable)
q <= d;
endmodule
\end{lstlisting}
In this example there is no data path and therefore the RTLIL::Module generated by
the frontend only contains a few RTLIL::Wire objects and an RTLIL::Process.
The RTLIL::Process in ILANG syntax:
\begin{lstlisting}[numbers=left,frame=single]
process $proc$ff_with_en_and_async_reset.v:4$1
assign $0\q[0:0] \q
switch \reset
case 1'1
assign $0\q[0:0] 1'0
case
switch \enable
case 1'1
assign $0\q[0:0] \d
case
end
end
sync posedge \clock
update \q $0\q[0:0]
sync posedge \reset
update \q $0\q[0:0]
end
\end{lstlisting}
This RTLIL::Process contains two RTLIL::SyncRule objects, two RTLIL::SwitchRule
objects and five RTLIL::CaseRule objects. The wire {\tt \$0\textbackslash{}q[0:0]}
is an automatically created wire that holds the next value of {\tt \textbackslash{}q}. The lines
$2 \dots 12$ describe how {\tt \$0\textbackslash{}q[0:0]} should be calculated. The
lines $13 \dots 16$ describe how the value of {\tt \$0\textbackslash{}q[0:0]} is used
to update {\tt \textbackslash{}q}.
An RTLIL::Process is a container for zero or more RTLIL::SyncRule objects and
exactly one RTLIL::CaseRule object, which is called the {\it root case}.
An RTLIL::SyncRule object contains an (optional) synchronization condition
(signal and edge-type) and zero or more assignments (RTLIL::SigSig).
An RTLIL::CaseRule is a container for zero or more assignments (RTLIL::SigSig)
and zero or more RTLIL::SwitchRule objects. An RTLIL::SwitchRule objects is a
container for zero or more RTLIL::CaseRule objects.
In the above example the lines $2 \dots 12$ are the root case. Here {\tt \$0\textbackslash{}q[0:0]} is first
assigned the old value {\tt \textbackslash{}q} as default value (line 2). The root case
also contains an RTLIL::SwitchRule object (lines $3 \dots 12$). Such an object is very similar to the C {\tt switch}
statement as it uses a control signal ({\tt \textbackslash{}reset} in this case) to determine
which of its cases should be active. The RTLIL::SwitchRule object then contains one RTLIL::CaseRule
object per case. In this example there is a case\footnote{The
syntax {\tt 1'1} in the ILANG code specifies a constant with a length of one bit (the first ``1''),
and this bit is a one (the second ``1'').} for {\tt \textbackslash{}reset == 1} that causes
{\tt \$0\textbackslash{}q[0:0]} to be set (lines 4 and 5) and a default case that in turn contains a switch that
sets {\tt \$0\textbackslash{}q[0:0]} to the value of {\tt \textbackslash{}d} if {\tt
\textbackslash{}enable} is active (lines $6 \dots 11$).
The lines $13 \dots 16$ then cause {\tt \textbackslash{}q} to be updated whenever there is
a positive clock edge on {\tt \textbackslash{}clock} or {\tt \textbackslash{}reset}.
In order to generate such a representation, the language frontend must be able to handle blocking
and nonblocking assignments correctly. However, the language frontend does not need to identify
the correct type of storage element for the output signal or generate multiplexers for the
decision tree. This is done by passes that work on the RTLIL representation. Therefore it is
relatively easy to substitute these steps with other algorithms that target different target
architectures or perform optimizations or other transformations on the decision trees before
further processing them.
One of the first actions performed on a design in RTLIL representation in most
synthesis scripts is identifying asynchronous resets. This is usually done using the {\tt proc\_arst}
pass. This pass transforms the above example to the following RTLIL::Process:
\begin{lstlisting}[numbers=left,frame=single]
process $proc$ff_with_en_and_async_reset.v:4$1
assign $0\q[0:0] \q
switch \enable
case 1'1
assign $0\q[0:0] \d
case
end
sync posedge \clock
update \q $0\q[0:0]
sync high \reset
update \q 1'0
end
\end{lstlisting}
This pass has transformed the outer RTLIL::SwitchRule into a modified RTLIL::SyncRule object
for the {\tt \textbackslash{}reset} signal. Further processing converts the RTLIL::Process
e.g.~into a d-type flip-flop with asynchronous reset and a multiplexer for the enable signal:
\begin{lstlisting}[numbers=left,frame=single]
cell $adff $procdff$6
parameter \ARST_POLARITY 1'1
parameter \ARST_VALUE 1'0
parameter \CLK_POLARITY 1'1
parameter \WIDTH 1
connect \ARST \reset
connect \CLK \clock
connect \D $0\q[0:0]
connect \Q \q
end
cell $mux $procmux$3
parameter \WIDTH 1
connect \A \q
connect \B \d
connect \S \enable
connect \Y $0\q[0:0]
end
\end{lstlisting}
Different combinations of passes may yield different results. Note that {\tt \$adff} and {\tt
\$mux} are internal cell types that still need to be mapped to cell types from the
target cell library.
Some passes refuse to operate on modules that still contain RTLIL::Process objects as the
presence of these objects in a module increases the complexity. Therefore the passes to translate
processes to a netlist of cells are usually called early in a synthesis script. The {\tt proc}
pass calls a series of other passes that together perform this conversion in a way that is suitable
for most synthesis taks.
\subsection{RTLIL::Memory}
For every array (memory) in the HDL code an RTLIL::Memory object is created. A
memory object has the following properties:
\begin{itemize}
\item The memory name
\item A list of attributes
\item The width of an addressable word
\item The size of the memory in number of words
\end{itemize}
All read accesses to the memory are transformed to {\tt \$memrd} cells and all write accesses to
{\tt \$memwr} cells by the language frontend. These cells consist of independent read- and write-ports
to the memory. The \B{MEMID} parameter on these cells is used to link them together and to the
RTLIL::Memory object they belong to.
The rationale behind using separate cells for the individual ports versus
creating a large multiport memory cell right in the language frontend is that
the separate {\tt \$memrd} and {\tt \$memwr} cells can be consolidated using resource sharing.
As resource sharing is a non-trivial optimization problem where different synthesis tasks
can have different requirements it lends itself to do the optimisation in separate passes and merge
the RTLIL::Memory objects and {\tt \$memrd} and {\tt \$memwr} cells to multiport memory blocks after resource sharing is completed.
The {\tt memory} pass performs this conversion and can (depending on the options passed
to it) transform the memories directly to d-type flip-flops and address logic or yield
multiport memory blocks (represented using {\tt \$mem} cells).
See Sec.~\ref{sec:memcells} for details on the memory cell types.
\section{Command Interface and Synthesis Scripts}
Yosys reads and processes commands from synthesis scripts, command line arguments and
an interactive command prompt. Yosys commands consist of a command name and an optional
whitespace sparated list of arguments. Commands are terminated using the newline character
or a semicolon ({\tt ;}). Empty lines and lines starting with the hash sign ({\tt \#}) are ignored.
See Sec.~\ref{sec:typusecase} for an example synthesis script.
The command {\tt help} can be used to access the command reference manual.
Most commands can operate not only on the entire design but also only on {\it selected}
parts of the design. For example the command {\tt dump} will print all selected objects
in the current design while {\tt dump foobar} will only print the module {\tt foobar}
and {\tt dump *} will print the entire design regardless of the current selection.
The selection mechanism is very powerful. For example the command {\tt dump */t:\$add
\%x:+[A] */w:* \%i} will print all wires that are connected to the \B{A} port of
a {\tt \$add} cell. A detailed documentation of the select framework can be
found in the command reference for the {\tt select} command.
\section{Source Tree and Build System}
The Yosys source tree is organized in the following top-level directories:
\begin{itemize}
\item {\tt backends/} \\
This directory contains a subdirectory for each of the backend modules.
\item {\tt frontends/} \\
This directory contains a subdirectory for each of the frontend modules.
\item {\tt kernel/} \\
This directory contains all the core functionality of Yosys. This includes the
functions and definitions for working with the RTLIL data structures ({\tt
rtlil.h} and {\tt rtlil.cc}), the main() function ({\tt driver.cc}), the
internal framework for generating log messages ({\tt log.h} and {\tt log.cc}),
the internal framework for registering and calling passes ({\tt register.h} and
{\tt register.cc}), some core commands that are not really passes ({\tt
select.cc}, {\tt show.cc}, \dots) and a couple of other small utility libraries.
\item {\tt passes/} \\
This directory contains a subdirectory for each pass or group of passes. For example as
of this writing the directory {\tt passes/opt/} contains the code for seven
passes: {\tt opt}, {\tt opt\_const}, {\tt opt\_muxtree}, {\tt opt\_reduce},
{\tt opt\_rmdff}, {\tt opt\_rmunused} and {\tt opt\_share}.
\item {\tt techlibs/} \\
This directory contains simulation models and standard implementations for the
cells from the internal cell library.
\item {\tt tests/} \\
This directory contains a couple of test cases. Most of the smaller tests are executed
automatically when {\tt make test} is called. The larger tests must be executed
manually. Most of the larger tests require downloading external HDL source code
and/or external tools. The tests range from comparing simulation results of the synthesized
design to the original sources to logic equivalence checking of entire CPU cores.
\end{itemize}
\begin{sloppypar}
The top-level Makefile includes {\tt frontends/*/Makefile.inc}, {\tt passes/*/Makefile.inc}
and {\tt backends/*/Makefile.inc}. So when extending Yosys it is enough to create
a new directory in {\tt frontends/}, {\tt passes/} or {\tt backends/} with your sources
and a {\tt Makefile.inc}. The Yosys kernel automatically detects all commands linked with
Yosys. So it is not needed to add additional commands to a central list of commands.
\end{sloppypar}
A good starting point for reading example source code for learning how to write passes
are {\tt passes/opt/opt\_rmdff.cc} and {\tt passes/opt/opt\_share.cc}.
See the top-level README file for a quick {\it Getting Started} guide and build
instructions. Yosys is a pure Makefile based project.
Users of the Qt Creator IDE can generate a QT Creator project file using {\tt
make qtcreator}. Users of the Eclipse IDE can use the ``Makefile Project with
Existing Code'' project type in the Eclipse ``New Project'' dialog (only
available after the CDT plugin has been installed) to create an Eclipse Project
for programming extensions to Yosys or just browsing the Yosys code base.

13
manual/CHAPTER_Prog.tex Normal file
View File

@ -0,0 +1,13 @@
\chapter{Programming Yosys Extensions}
\label{chapter:prog}
\begin{fixme}
This chapter will contain a guided tour to the Yosys APIs and conclude
with an example module.
\end{fixme}
\section{Programming with RTLIL}
\section{Internal Utility Libraries}
\section{Loadable Modules}

289
manual/CHAPTER_StateOfTheArt.tex Normal file
View File

@ -0,0 +1,289 @@
\chapter{Evaluation of other OSS Verilog Synthesis Tools}
\label{chapter:sota}
In this appendix\footnote{This appendix is an updated version of an
unpublished student research paper. \cite{VerilogFossEval}}
the existing FOSS Verilog synthesis tools\footnote{To the
author's best knowledge, all relevant tools that existed at the time of this
writing are included. But as there is no formal channel through which such
tools are published it is hard to give any guarantees in that matter.} are
evaluated. Extremely limited or application specific tools (e.g.~pure Verilog
Netlist parsers) as well as Verilog simulators are not included. These existing
solutions are tested using a set of representative Verilog code snippets. It is
shown that no existing FOSS tool implements even close to a sufficient subset
of Verilog to be usable as synthesis tool for a wide range existing Verilog code.
The packages evaluated are:
\begin{itemize}
\item Icarus Verilog \citeweblink{Icarus}\footnote{Icarus Verilog is mainly a simulation
tool but also supported synthesis up to version 0.8. Therefore version 0.8.7 is used
for this evaluation.)}
\item Verilog-to-Routing (VTR) / Odin-II \cite{vtr2012}\cite{Odin}\citeweblink{VTR}
\item HDL Analyzer and Netlist Architect (HANA) \citeweblink{HANA}
\item Verilog front-end to VIS (vl2mv) \cite{Cheng93vl2mv:a}\citeweblink{VIS}
\end{itemize}
In each of the following sections Verilog modules that test a certain Verilog
language feature are presented and the support for these features is tested in all
the tools mentioned above. It is evaluated whether the tools under test
successfully generate netlists for the Verilog input and whether these netlists
match the simulation behavior of the designs using testbenches.
All test cases are verified to be synthesizeable using Xilinx XST from the Xilinx
WebPACK \citeweblink{XilinxWebPACK} suite.
Trivial features such as support for simple structural Verilog are not explicitly tested.
Vl2mv and Odin-II generate output in the BLIF (Berkeley Logic Interchange
Format) and BLIF-MV (an extended version of BLIF) formats respectively.
ABC \citeweblink{ABC} is used to convert this output to Verilog for verification
using testbenches.
Icarus Verilog generates EDIF (Electronic Design Interchange Format) output
utilizing LPM (Library of Parameterized Modules) cells. The EDIF files are
converted to Verilog using edif2ngd and netgen from Xilinx WebPACK. A
hand-written implementation of the LPM cells utilized by the generated netlists
is used for verification.
Following these functional tests, a quick analysis of the extensibility of the tools
under test is provided in a separate section.
The last section of this chapter finally concludes these series of evaluations
with a summary of the results.
\begin{figure}[t!]
\begin{minipage}{7.7cm}
\lstinputlisting[numbers=left,frame=single,language=Verilog]{FILES_StateOfTheArt/always01_pub.v}
\end{minipage}
\hfill
\begin{minipage}{7.7cm}
\lstinputlisting[frame=single,language=Verilog]{FILES_StateOfTheArt/always02_pub.v}
\end{minipage}
\caption{1st and 2nd Verilog always examples}
\label{fig:StateOfTheArt_always12}
\end{figure}
\begin{figure}[!]
\lstinputlisting[numbers=left,frame=single,language=Verilog]{FILES_StateOfTheArt/always03.v}
\caption{3rd Verilog always example}
\label{fig:StateOfTheArt_always3}
\end{figure}
\section{Always blocks and blocking vs.~nonblocking assignments}
\label{sec:blocking_nonblocking}
The ``always''-block is one of the most fundamental non-trivial Verilog
language features. It can be used to model a combinatorial path (with optional
registers on the outputs) in a way that mimics a regular programming language.
Within an always block, if- and case-statements can be used to model multiplexers.
Blocking assignments ($=$) and nonblocking assignments ($<=$) are used to populate the
leaf-nodes of these multiplexer trees. Unassigned leaf-nodes default to feedback
paths that cause the output register to hold the previous value. More advanced
synthesis tools often convert these feedback paths to register enable signals or
even generate circuits with clock gating.
Registers assigned with nonblocking assignments ($<=$) behave differently from
variables in regular programming languages: In a simulation they are not
updated immediately after being assigned. Instead the right-hand sides are
evaluated and the results stored in temporary memory locations. After all
pending updates have been prepared in this way they are executed, thus yielding
semi-parallel execution of all nonblocking assignments.
For synthesis this means that every occurrence of that register in an expression
addresses the output port of the corresponding register regardless of the question whether the register
has been assigned a new value in an earlier command in the same always block.
Therefore with nonblocking assignments the order of the assignments has no effect
on the resulting circuit as long as the left-hand sides of the assignments are
unique.
The three example codes in Fig.~\ref{fig:StateOfTheArt_always12} and
Fig.~\ref{fig:StateOfTheArt_always3} use all these features and can thus be used
to test the synthesis tools capabilities to synthesize always blocks correctly.
The first example is only using the most fundamental Verilog features. All
tools under test were able to successfully synthesize this design.
\begin{figure}[b!]
\lstinputlisting[numbers=left,frame=single,language=Verilog]{FILES_StateOfTheArt/arrays01.v}
\caption{Verilog array example}
\label{fig:StateOfTheArt_arrays}
\end{figure}
The 2nd example is functionally identical to the 1st one but is using an
if-statement inside the always block. Odin-II fails to synthesize it and
instead produces the following error message:
\begin{verbatim}
ERROR: (File: always02.v) (Line number: 13)
You've defined the driver "count~0" twice
\end{verbatim}
Vl2mv does not produce an error message but outputs an invalid synthesis result
that is not using the reset input at all.
Icarus Verilog also doesn't produce an error message but generates an invalid output
for this 2nd example. The code generated by Icarus Verilog only implements the reset
path for the count register, effectively setting the output to constant 0.
So of all tools under test only HANA was able to create correct synthesis results
for the 2nd example.
The 3rd example is using blocking and nonblocking assignments and many if statements.
Odin also fails to synthesize this example:
\begin{verbatim}
ERROR: (File: always03.v) (Line number: 8)
ODIN doesn't handle blocking statements in Sequential blocks
\end{verbatim}
HANA, Icarus Verilog and vl2mv create invalid synthesis results for the 3rd example.
So unfortunately none of the tools under test provide a complete and correct
implementation of blocking and nonblocking assignments.
\section{Arrays for memory modelling}
Verilog arrays are part of the synthesizeable subset of Verilog and are
commonly used to model addressable memory. The Verilog code in
Fig.~\ref{fig:StateOfTheArt_arrays} demonstrates this by implementing a single
port memory.
For this design HANA, vl2m and ODIN-II generate error messages indicating that
arrays are not supported.
\begin{figure}[t!]
\lstinputlisting[numbers=left,frame=single,language=Verilog]{FILES_StateOfTheArt/forgen01.v}
\caption{Verilog for loop example}
\label{fig:StateOfTheArt_for}
\end{figure}
Icarus Verilog produces an invalid output that is using the address only for
reads. Instead of using the address input for writes, the generated design
simply loads the data to all memory locations whenever the write-enable input
is active, effectively turning the design into a single 4-bit D-Flip-Flop with
enable input.
As all tools under test already fail this simple test, there is nothing to gain
by continuing tests on this aspect of Verilog synthesis such as synthesis of dual port
memories, correct handling of write collisions, and so forth.
\begin{figure}[t!]
\lstinputlisting[numbers=left,frame=single,language=Verilog]{FILES_StateOfTheArt/forgen02.v}
\caption{Verilog generate example}
\label{fig:StateOfTheArt_gen}
\end{figure}
\section{For-loops and generate blocks}
For-loops and generate blocks are more advanced Verilog features. These features
allow the circuit designer to add program code to her design that is evaluated
during synthesis to generate (parts of) the circuits description; something that
could only be done using a code generator otherwise.
For-loops are only allowed in synthesizeable Verilog if they can be completely
unrolled. Then they can be a powerful tool to generate array logic or static
lookup tables. The code in Fig.~\ref{fig:StateOfTheArt_for} generates a circuit that
tests a 5 bit value for being a prime number using a static lookup table.
Generate blocks can be used to model array logic in complex parametric designs. The
code in Fig.~\ref{fig:StateOfTheArt_gen} implements a ripple-carry adder with
parametric width from simple assign-statements and logic operations using a Verilog
generate block.
All tools under test failed to synthesize both test cases. HANA creates invalid
output in both cases. Icarus Verilog creates invalid output for the first
test and fails with an error for the second case. The other two tools fail with
error messages for both tests.
\section{Extensibility}
This section briefly discusses the extensibility of the tools under test and
their internal data- and control-flow. As all tools under test already failed
to synthesize simple Verilog always-blocks correctly, not much resources have
been spent on evaluating the extensibility of these tools and therefore only a
very brief discussion of the topic is provided here.
HANA synthesizes for a built-in library of standard cells using two passes over
an AST representation of the Verilog input. This approach executes fast but
limits the extensibility as everything happens in only two comparable complex
AST walks and there is no universal intermediate representation that is flexible
enough to be used in arbitrary optimizations.
Odin-II and vl2m are both front ends to existing synthesis flows. As such they
only try to quickly convert the Verilog input into the internal representation
of their respective flows (BLIF). So extensibility is less of an issue here as
potential extensions would likely be implemented in other components of the
flow.
Icarus Verilog is clearly designed to be a simulation tool rather than a
synthesis tool. The synthesis part of Icarus Verilog is an ad-hoc add-on to
Icarus Verilog that aims at converting an internal representation that is meant
for generation of a virtual machine based simulation code to netlists.
\section{Summary and Outlook}
Table~\ref{tab:StateOfTheArt_sum} summarizes the tests performed. Clearly none
of the tools under test make a serious attempt at providing a feature-complete
implementation of Verilog. It can be argued that Odin-II performed best in the
test as it never generated incorrect code but instead produced error messages
indicating that unsupported Verilog features where used in the Verilog input.
In conclusion, to the best knowledge of the author, there is no FOSS Verilog
synthesis tool other than Yosys that is anywhere near feature completeness and
therefore there is no other candidate for a generic Verilog front end and/or
synthesis framework to be used as a basis for custom synthesis tools.
Yosys could also replace vl2m and/or Odin-II in their respective flows or
function as a pre-compiler that can translate full-featured Verilog code to the
simple subset of Verilog that is understood by vl2m and Odin-II.
Yosys is designed for extensibility. It can be used as-is to synthesize Verilog
code to netlists, but its main purpose is to be used as basis for custom tools.
Yosys is structured in a language dependent Verilog front end and language
independent synthesis code (which is in itself structured in independent
passes). This architecture will simplify implementing additional HDL front
ends and/or additional synthesis passes.
Chapter~\ref{chapter:eval} contains a more detailed evaluation of Yosys using real-world
designes that are far out of reach for any of the other tools discussed in this appendix.
\vskip2cm
\begin{table}[h]
% yosys hana vis icarus odin
% always01 ok ok ok ok ok
% always02 ok ok failed failed error
% always03 ok failed failed missing error
% arrays01 ok error error failed error
% forgen01 ok failed error failed error
% forgen02 ok failed error error error
\def\ok{\ding{52}}
\def\error{\ding{56}}
\def\failed{$\skull$}
\def\missing{$\skull$}
\rowcolors{2}{gray!25}{white}
\centerline{
\begin{tabular}{|l|cccc|c|}
\hline
& \bf HANA & \bf VIS / vl2m & \bf Icarus Verilog & \bf Odin-II & \bf Yosys \\
\hline
\tt always01 & \ok & \ok & \ok & \ok & \ok \\
\tt always02 & \ok & \failed & \failed & \error & \ok \\
\tt always03 & \failed & \failed & \missing & \error & \ok \\
\tt arrays01 & \error & \error & \failed & \error & \ok \\
\tt forgen01 & \failed & \error & \failed & \error & \ok \\
\tt forgen02 & \failed & \error & \error & \error & \ok \\
\hline
\end{tabular}
}
\centerline{
\ding{52} \dots passed \hskip2em
\ding{56} \dots produced error \hskip2em
$\skull$ \dots incorrect output
}
\caption{Summary of all test results}
\label{tab:StateOfTheArt_sum}
\end{table}

102
manual/CHAPTER_Techmap.tex Normal file
View File

@ -0,0 +1,102 @@
\chapter{Technology Mapping}
\label{chapter:techmap}
Previous chapters outlined how HDL code is transformed into an RTL netlist. The
RTL netlist is still based on abstract coarse-grain cell types like arbitrary
width adders and even multipliers. This chapter covers how an RTL netlist is
transformed into a functionally equivialent netlist utililizing the cell types
available in the target architecture.
Technology mapping is often performed in two phases. In the first phase RTL cells
are mapped to an internal library of single-bit cells (see Sec.~\ref{sec:celllib_gates}).
In the second phase this netlist of internal gate types is transformed to a netlist
of gates from the target technology library.
When the target architecture provides coarse-grain cells (such as block ram
or ALUs), these must be mapped to directly form the RTL netlist, as information
on the coarse-grain structure of the design is lost when it is mapped to
bit-width gate types.
\section{Cell Substitution}
The simplest form of technology mapping is cell substitution, as performed by
the {\tt techmap} pass. This pass, when provided with a Verilog file that
implements the RTL cell types using simpler cells, simply replaces the RTL
cells with the provided implementation.
When no map file is provided, {\tt techmap} uses a built-in map file that
maps the Yosys RTL cell types to the internal gate library used by Yosys.
The curious reader may find this map file as {\tt techlibs/stdcells.v} in
the Yosys source tree.
Additional features have been added to {\tt techmap} to allow for conditional
mapping of cells (see {\tt help techmap} or Sec.~\ref{cmd:techmap}). This can
for example be usefull if the target architecture supports hardware multipliers for
certain bit-widths but not for others.
A usual synthesis flow would first use the {\tt techmap} pass to directly map
some RTL cells to coarse-grain cells provided by the target architecture (if
any) and then use techmap with the built-in default file to map the remaining
RTL cells to gate logic.
\section{Subcircuit Substitution}
Sometimes the target architecture provides cells that are more powerful than
the RTL cells used by Yosys. For example a cell in the target architecture that can
calculate the absolute-difference of two numbers does not match any single
RTL cell type but only combinations of cells.
For these cases Yosys provides the {\tt extract} pass that can match a given set
of modules against a design and identify the portions of the design that are
identical (i.e.~isomorphic subcircuits) to any of the given modules. These
matched subcircuits are then replaced by instances of the given modules.
The {\tt extract} pass also finds basic variations of the given modules,
such as swapped inputs on commutative cell types.
In addition to this the {\tt extract} pass also has limited support for
frequent subcircuit mining, i.e.~the process of finding recurring subcircuits
in the design. This has a few applications, including the design of new
coarse-grain architectures \cite{intersynthFdlBookChapter}.
The hard algorithmic work done by the {\tt extract} pass (solving the
isomorphic subcircuit problem and frequent subcircuit mining) is performed
using the SubCircuit library that can also be used stand-alone without Yosys
(see Sec.~\ref{sec:SubCircuit}).
\section{Gate-Level Technology Mapping}
\label{sec:techmap_extern}
On the gate-level the target architecture is usually described by a ``Liberty
file''. The Liberty file format is an industry standard format that can be
used to describe the behaviour and other properties of standard library cells
\citeweblink{LibertyFormat}.
Mapping a design utilizing the Yosys internal gate library (e.g.~as a result
of mapping it to this representation using the {\tt techmap} pass) is
performed in two phases.
First the register cells must be mapped to the registers that are available
on the target architectures. The target architecture might not provide all
variations of d-type flip-flops with positive and negative clock edge,
high-active and low-active asynchronous set and/or reset, etc. Therefore the
process of mapping the registers might add additional inverters to the design
and thus it is important to map the register cells first.
Mapping of the register cells may be performed by using the {\tt dfflibmap}
pass. This pass expects a Liberty file as argument (using the {\tt -liberty}
option) and only uses the register cells from the Liberty file.
Secondly the combinational logic must be mapped to the target architecture.
This is done using the external program ABC \citeweblink{ABC} via the
{\tt abc} pass by using the {\tt -liberty} option to the pass. Note that
in this case only the combinatorial cells are used from the cell library.
Occasionally Liberty files contain trade secrets (such as sensitive timing
information) that cannot be shared freely. This complicates processes such as
reporting bugs in the tools involved. When the information in the Liberty file
used by Yosys and ABC are not part of the sensitive information, the additional
tool {\tt yosys-filterlib} (see Sec.~\ref{sec:filterlib}) can be used to strip
the sensitive information from the Liberty file.

849
manual/CHAPTER_Verilog.tex Normal file
View File

@ -0,0 +1,849 @@
\chapter{The Verilog and AST Frontends}
\label{chapter:verilog}
This chapter provides an overview of the implementation of the Yosys Verilog
and AST frontends. The Verilog frontend reads Verilog-2005 code and creates
an abstract syntax tree (AST) representation of the input. This AST representation
is then passed to the AST frontend that converts it to RTLIL data, as illustrated
in Fig.~\ref{fig:Verilog_flow}.
\begin{figure}[b!]
\hfil
\begin{tikzpicture}
\tikzstyle{process} = [draw, fill=green!10, rectangle, minimum height=3em, minimum width=10em, node distance=5em, font={\ttfamily}]
\tikzstyle{data} = [draw, fill=blue!10, ellipse, minimum height=3em, minimum width=7em, node distance=5em, font={\ttfamily}]
\node[data] (n1) {Verilog Source};
\node[process] (n2) [below of=n1] {Verilog Frontend};
\node[data] (n3) [below of=n2] {AST};
\node[process] (n4) [below of=n3] {AST Frontend};
\node[data] (n5) [below of=n4] {RTLIL};
\draw[-latex] (n1) -- (n2);
\draw[-latex] (n2) -- (n3);
\draw[-latex] (n3) -- (n4);
\draw[-latex] (n4) -- (n5);
\tikzstyle{details} = [draw, fill=yellow!5, rectangle, node distance=6cm, font={\ttfamily}]
\node[details] (d1) [right of=n2] {\begin{minipage}{5cm}
\hfil
\begin{tikzpicture}
\tikzstyle{subproc} = [draw, fill=green!10, rectangle, minimum height=2em, minimum width=10em, node distance=3em, font={\ttfamily}]
\node (s0) {};
\node[subproc] (s1) [below of=s0] {Preprocessor};
\node[subproc] (s2) [below of=s1] {Lexer};
\node[subproc] (s3) [below of=s2] {Parser};
\node[node distance=3em] (s4) [below of=s3] {};
\draw[-latex] (s0) -- (s1);
\draw[-latex] (s1) -- (s2);
\draw[-latex] (s2) -- (s3);
\draw[-latex] (s3) -- (s4);
\end{tikzpicture}
\end{minipage}};
\draw[dashed] (n2.north east) -- (d1.north west);
\draw[dashed] (n2.south east) -- (d1.south west);
\node[details] (d2) [right of=n4] {\begin{minipage}{5cm}
\hfil
\begin{tikzpicture}
\tikzstyle{subproc} = [draw, fill=green!10, rectangle, minimum height=2em, minimum width=10em, node distance=3em, font={\ttfamily}]
\node (s0) {};
\node[subproc] (s1) [below of=s0] {Simplifier};
\node[subproc] (s2) [below of=s1] {RTLIL Generator};
\node[node distance=3em] (s3) [below of=s2] {};
\draw[-latex] (s0) -- (s1);
\draw[-latex] (s1) -- (s2);
\draw[-latex] (s2) -- (s3);
\end{tikzpicture}
\end{minipage}};
\draw[dashed] (n4.north east) -- (d2.north west);
\draw[dashed] (n4.south east) -- (d2.south west);
\end{tikzpicture}
\caption{Simplified Verilog to RTLIL data flow}
\label{fig:Verilog_flow}
\end{figure}
\section{Transforming Verilog to AST}
The {\it Verilog frontend} converts the Verilog sources to an internal AST representation that closely resembles
the structure of the original Verilog code. The Verilog frontend consists of three components, the
{\it Preprocessor}, the {\it Lexer} and the {\it Parser}.
The source code to the Verilog frontend can be found in {\tt frontends/verilog/} in the Yosys source tree.
\subsection{The Verilog Preprocessor}
The Verilog preprocessor scans over the Verilog source code and interprets some of the Verilog compiler
directives such as \lstinline[language=Verilog]{`include}, \lstinline[language=Verilog]{`define} and
\lstinline[language=Verilog]{`ifdef}.
It is implemented as a C++ function that is passed a file descriptor as input and returns the
pre-processed Verilog code as a \lstinline[language=C++]{std::string}.
The source code to the Verilog Preprocessor can be found in {\tt
frontends/verilog/preproc.cc} in the Yosys source tree.
\subsection{The Verilog Lexer}
\begin{sloppypar}
The Verilog Lexer is written using the lexer generator {\it flex} \citeweblink{flex}. Its source code
can be found in {\tt frontends/verilog/lexer.l} in the Yosys source tree.
The lexer does little more than identifying all keywords and literals
recognised by the Yosys Verilog frontend.
\end{sloppypar}
The lexer keeps track of the current location in the verilog source code using
some global variables. These variables are used by the constructor of AST nodes
to annotate each node with the source code location it originated from.
\begin{sloppypar}
Finally the lexer identifies and handles special comments such as
``\lstinline[language=Verilog]{// synopsys translate_off}'' and
``\lstinline[language=Verilog]{// synopsys full_case}''. (It is recommended to
use \lstinline[language=Verilog]{`ifdef} constructs instead of the Synsopsys
translate\_on/off comments and attributes such as
\lstinline[language=Verilog]{(* full_case *)} over ``\lstinline[language=Verilog]{// synopsys full_case}''
whenever possible.)
\end{sloppypar}
\subsection{The Verilog Parser}
The Verilog Parser is written using the parser generator {\it bison} \citeweblink{bison}. Its source code
can be found in {\tt frontends/verilog/parser.y} in the Yosys source tree.
It generates an AST using the \lstinline[language=C++]{AST::AstNode} data structure
defined in {\tt frontends/ast/ast.h}. An \lstinline[language=C++]{AST::AstNode} object has
the following properties:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table}[b!]
\hfil
\begin{tabular}{>{\raggedright\arraybackslash}p{7cm}>{\raggedright\arraybackslash}p{8cm}}
AST Node Type & Corresponding Verilog Construct \\
\hline
\hline
\arrayrulecolor{gray}
{\tt AST\_NONE} & This Node type should never be used. \\
\hline
%
{\tt AST\_DESIGN} & This node type is used for the top node of the AST tree. It
has no corresponding Verilog construct. \\
\hline
%
{\tt AST\_MODULE},
{\tt AST\_TASK},
{\tt AST\_FUNCTION} &
\lstinline[language=Verilog];module;,
\lstinline[language=Verilog];task; and
\lstinline[language=Verilog];function; \\
\hline
%
{\tt AST\_WIRE} &
\lstinline[language=Verilog];input;,
\lstinline[language=Verilog];output;,
\lstinline[language=Verilog];wire;,
\lstinline[language=Verilog];reg; and
\lstinline[language=Verilog];integer; \\
\hline
%
{\tt AST\_MEMORY} &
Verilog Arrays \\
\hline
%
{\tt AST\_AUTOWIRE} &
Created by the simplifier when an undeclared signal name is used. \\
\hline
%
{\tt AST\_PARAMETER},
{\tt AST\_LOCALPARAM} &
\lstinline[language=Verilog];parameter; and
\lstinline[language=Verilog];localparam; \\
\hline
%
{\tt AST\_PARASET} &
Parameter set in cell instanciation \\
\hline
%
{\tt AST\_ARGUMENT} &
Port connection in cell instanciation \\
\hline
%
{\tt AST\_RANGE} &
Bit-Index in a signal or element index in array \\
\hline
%
{\tt AST\_CONSTANT} &
A literal value \\
\hline
%
{\tt AST\_CELLTYPE} &
The type of cell in cell instanciation \\
\hline
%
{\tt AST\_IDENTIFIER} &
An Identifier (signal name in expression or cell/task/etc. name in other contexts) \\
\hline
%
{\tt AST\_PREFIX} &
Construct an identifier in the form {\tt <prefix>[<index>].<suffix>} (used only in
advanced generate constructs) \\
\hline
%
{\tt AST\_FCALL},
{\tt AST\_TCALL} &
Call to function or task \\
\hline
%
{\tt AST\_TO\_SIGNED},
{\tt AST\_TO\_UNSIGNED} &
The \lstinline[language=Verilog];$signed(); and
\lstinline[language=Verilog];$unsigned(); functions \\
\hline
\end{tabular}
\caption{AST node types with their corresponding Verilog constructs. \\ (continued on next page)}
\label{tab:Verilog_AstNodeType}
\end{table}
\begin{table}[t!]
\ContinuedFloat
\hfil
\begin{tabular}{>{\raggedright\arraybackslash}p{7cm}>{\raggedright\arraybackslash}p{8cm}}
AST Node Type & Corresponding Verilog Construct \\
\hline
\hline
\arrayrulecolor{gray}
{\tt AST\_CONCAT}
{\tt AST\_REPLICATE} &
The \lstinline[language=Verilog];{...}; and
\lstinline[language=Verilog];{...{...}}; operators \\
\hline
%
{\tt AST\_BIT\_NOT},
{\tt AST\_BIT\_AND},
{\tt AST\_BIT\_OR},
{\tt AST\_BIT\_XOR},
{\tt AST\_BIT\_XNOR} &
The bitwise operators \break
\lstinline[language=Verilog];~;,
\lstinline[language=Verilog];&;,
\lstinline[language=Verilog];|;,
\lstinline[language=Verilog];^; and
\lstinline[language=Verilog];~^; \\
\hline
%
{\tt AST\_REDUCE\_AND},
{\tt AST\_REDUCE\_OR},
{\tt AST\_REDUCE\_XOR},
{\tt AST\_REDUCE\_XNOR} &
The unary reduction operators \break
\lstinline[language=Verilog];~;,
\lstinline[language=Verilog];&;,
\lstinline[language=Verilog];|;,
\lstinline[language=Verilog];^; and
\lstinline[language=Verilog];~^; \\
\hline
%
{\tt AST\_REDUCE\_BOOL} &
Conversion from multi-bit value to boolian value
(equivialent to {\tt AST\_REDUCE\_OR}) \\
\hline
%
{\tt AST\_SHIFT\_LEFT},
{\tt AST\_SHIFT\_RIGHT},
{\tt AST\_SHIFT\_SLEFT},
{\tt AST\_SHIFT\_SRIGHT} &
The shift operators \break
\lstinline[language=Verilog];<<;,
\lstinline[language=Verilog];>>;,
\lstinline[language=Verilog];<<<; and
\lstinline[language=Verilog];>>>; \\
\hline
%
{\tt AST\_LT},
{\tt AST\_LE},
{\tt AST\_EQ},
{\tt AST\_NE},
{\tt AST\_GE},
{\tt AST\_GT} &
The relational operators \break
\lstinline[language=Verilog];<;,
\lstinline[language=Verilog];<=;,
\lstinline[language=Verilog];==;,
\lstinline[language=Verilog];!=;,
\lstinline[language=Verilog];>=; and
\lstinline[language=Verilog];>; \\
\hline
%
{\tt AST\_ADD},
{\tt AST\_SUB},
{\tt AST\_MUL},
{\tt AST\_DIV},
{\tt AST\_MOD},
{\tt AST\_POW} &
The binary operators \break
\lstinline[language=Verilog];+;,
\lstinline[language=Verilog];-;,
\lstinline[language=Verilog];*;,
\lstinline[language=Verilog];/;,
\lstinline[language=Verilog];%; and
\lstinline[language=Verilog];**; \\
\hline
%
{\tt AST\_POS},
{\tt AST\_NEG} &
The prefix operators
\lstinline[language=Verilog];+; and
\lstinline[language=Verilog];-; \\
\hline
%
{\tt AST\_LOGIC\_AND},
{\tt AST\_LOGIC\_OR},
{\tt AST\_LOGIC\_NOT} &
The logic operators
\lstinline[language=Verilog];&&;,
\lstinline[language=Verilog];||; and
\lstinline[language=Verilog];!; \\
\hline
%
{\tt AST\_TERNARY} &
The ternary \lstinline[language=Verilog];?:;-operator \\
\hline
%
{\tt AST\_MEMRD}
{\tt AST\_MEMWR} &
Read and write memories. These nodes are generated by
the AST simplifier for writes/reads to/from Verilog arrays. \\
\hline
%
{\tt AST\_ASSIGN} &
An \lstinline[language=Verilog];assign; statement \\
\hline
%
{\tt AST\_CELL} &
A cell instanciation \\
\hline
%
{\tt AST\_PRIMITIVE} &
A primitive cell (\lstinline[language=Verilog];and;,
\lstinline[language=Verilog];nand;,
\lstinline[language=Verilog];or;, etc.) \\
\hline
%
{\tt AST\_ALWAYS},
{\tt AST\_INITIAL} &
Verilog \lstinline[language=Verilog];always;- and \lstinline[language=Verilog];initial;-blocks \\
\hline
%
{\tt AST\_BLOCK} &
A \lstinline[language=Verilog];begin;-\lstinline[language=Verilog];end;-block \\
\hline
%
{\tt AST\_ASSIGN\_EQ}.
{\tt AST\_ASSIGN\_LE} &
Blocking (\lstinline[language=Verilog];=;) and nonblocking (\lstinline[language=Verilog];<=;)
assignments within an \lstinline[language=Verilog];always;- or \lstinline[language=Verilog];initial;-block \\
\hline
%
{\tt AST\_CASE}.
{\tt AST\_COND},
{\tt AST\_DEFAULT} &
The \lstinline[language=Verilog];case; (\lstinline[language=Verilog];if;) statements, conditions within a case
and the default case respectively \\
\hline
%
{\tt AST\_FOR} &
A \lstinline[language=Verilog];for;-loop witn an
\lstinline[language=Verilog];always;- or
\lstinline[language=Verilog];initial;-block \\
\hline
%
{\tt AST\_GENVAR},
{\tt AST\_GENBLOCK},
{\tt AST\_GENFOR},
{\tt AST\_GENIF} &
The \lstinline[language=Verilog];genvar; and
\lstinline[language=Verilog];generate; keywords and
\lstinline[language=Verilog];for; and \lstinline[language=Verilog];if; within a
generate block. \\
\hline
%
{\tt AST\_POSEDGE},
{\tt AST\_NEGEDGE},
{\tt AST\_EDGE} &
Event conditions for \lstinline[language=Verilog];always; blocks. \\
\hline
\end{tabular}
\caption{AST node types with their corresponding Verilog constructs. \\ (continuation from previous page)}
\label{tab:Verilog_AstNodeTypeCont}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{itemize}
\item {\bf The node type} \\
This enum (\lstinline[language=C++]{AST::AstNodeType}) specifies the role of the node.
Table~\ref{tab:Verilog_AstNodeType} contains a list of all node types.
\item {\bf The child nodes} \\
This is a list of pointers to all children in the abstract syntax tree.
\item {\bf Attributes} \\
As almost every AST node might have Verilog attributes assigned to it, the
\lstinline[language=C++]{AST::AstNode} has direct support for attributes. Note that the
attribute values are again AST nodes.
\item {\bf Node content} \\
Each node might have additional content data. A series of member variables exist to hold such data.
For example the member \lstinline[language=C++]{std::string str} can hold a string value and is
used e.g.~in the {\tt AST\_IDENTIFIER} node type to store the identifier name.
\item {\bf Source code location} \\
Each \lstinline[language=C++]{AST::AstNode} is automatically annotated with the current
source code location by the \lstinline[language=C++]{AST::AstNode} constructor. It is
stored in the \lstinline[language=C++]{std::string filename} and \lstinline[language=C++]{int linenum}
member variables.
\end{itemize}
The \lstinline[language=C++]{AST::AstNode} constructor can be called with up to
two child nodes that are automatically added to the list of child nodes for the new object.
This simplifies the creation of AST nodes for simple expressions a bit. For example the bison
code for parsing multiplications:
\begin{lstlisting}[numbers=left,frame=single]
basic_expr '*' attr basic_expr {
$$ = new AstNode(AST_MUL, $1, $4);
append_attr($$, $3);
} |
\end{lstlisting}
The generated AST data structure is then passed directly to the AST frontend
that performs the actual conversion to RTLIL.
Note that the Yosys command {\tt read\_verilog} provides the options {\tt -yydebug}
and {\tt -dump\_ast} that can be used to print the parse tree or abstract syntax tree
respectively.
\section{Transforming AST to RTLIL}
The {\it AST Frontend} converts a set of modules in AST representation to
modules in RTLIL representation and adds them to the current design. This is done
in two steps: {\it simplification} and {\it RTLIL generation}.
The source code to the AST frontend can be found in {\tt frontends/ast/} in the Yosys source tree.
\subsection{AST Simplification}
A full-featured AST is too complex to be transformed into RTLIL directly. Therefore it must
first be brought into a simpler form. This is done by calling the \lstinline[language=C++]{AST::AstNode::simplify()}
method of all {\tt AST\_MODULE} nodes in the AST. This initiates a recursive process that performs the following transformations
on the AST data structure:
\begin{itemize}
\item Inline all task and function calls.
\item Evaluate all \lstinline[language=Verilog]{generate}-statements and unroll all \lstinline[language=Verilog]{for}-loops.
\item Perform const folding where it is neccessary (e.g.~in the value part of {\tt AST\_PARAMETER}, {\tt AST\_LOCALPARAM},
{\tt AST\_PARASET} and {\tt AST\_RANGE} nodes).
\item Replace {\tt AST\_PRIMITIVE} nodes with appropriate {\tt AST\_ASSIGN} nodes.
\item Replace dynamic bit ranges in the left-hand-side of assignments with {\tt AST\_CASE} nodes with {\tt AST\_COND} children
for each possible case.
\item Detect array access patterns that are too complicated for the {\tt RTLIL::Memory} abstraction and replace them
with a set of signals and cases for all reads and/or writes.
\item Otherwise replace array accesses with {\tt AST\_MEMRD} and {\tt AST\_MEMWR} nodes.
\end{itemize}
In addition to these transformations, the simplifier also annotates the AST with additional information that is needed
for the RTLIL generator, namely:
\begin{itemize}
\item All ranges (width of signals and bit selections) are not only const folded but (when a constant value
is found) are also written to member variables in the {\tt AST\_RANGE} node.
\item All identifiers are resolved and all {\tt AST\_IDENTIFIER} nodes are annotated with a pointer to the AST node
that contains the declaration of the identifier. If no declaration has been found, an {\tt AST\_AUTOWIRE} node
is created and used for the annotation.
\end{itemize}
This produces an AST that is fairly easy to convert to the RTLIL format.
\subsection{Generating RTLIL}
After AST simplification, the \lstinline[language=C++]{AST::AstNode::genRTLIL()} method of each {\tt AST\_MODULE} node
in the AST is called. This initiates a recursive process that generates equivialent RTLIL data for the AST data.
The \lstinline[language=C++]{AST::AstNode::genRTLIL()} method returns an \lstinline[language=C++]{RTLIL::SigSpec} structure.
For nodes that represent expressions (operators, constants, signals, etc.), the cells needed to implement the calculation
described by the expression are created and the resulting signal is returned. That way it is easy to generate the circuits
for large expressions using depth-first recursion. For nodes that do not represent an expression (such as {\tt
AST\_CELL}), the corresponding circuit is generated and an empty \lstinline[language=C++]{RTLIL::SigSpec} is returned.
\section{Synthesizing Verilog always Blocks}
For behavioural Verilog code (code utilizing \lstinline[language=Verilog]{always}- and
\lstinline[language=Verilog]{initial}-blocks) it is necessary to also generate \lstinline[language=C++]{RTLIL::Process}
objects. This is done in the following way:
\begin{itemize}
\item Whenever \lstinline[language=C++]{AST::AstNode::genRTLIL()} encounters an \lstinline[language=Verilog]{always}-
or \lstinline[language=Verilog]{initial}-block, it creates an instance of
\lstinline[language=Verilog]{AST_INTERNAL::ProcessGenerator}. This object then generates the
\lstinline[language=C++]{RTLIL::Process} object for the block. It also calls \lstinline[language=C++]{AST::AstNode::genRTLIL()}
for all right-hand-side expressions contained within the block.
%
\begin{sloppypar}
\item First the \lstinline[language=Verilog]{AST_INTERNAL::ProcessGenerator} creates a list of all signals assigned
within the block. It then creates a set of temporary signals using the naming scheme {\tt \$\it<number>\tt
\textbackslash\it <original\_name>} for each of the assigned signals.
\end{sloppypar}
%
\item Then an \lstinline[language=C++]{RTLIL::Process} is created that assigns all intermediate values for each left-hand-side
signal to the temporary signal in its \lstinline[language=C++]{RTLIL::CaseRule}/\lstinline[language=C++]{RTLIL::SwitchRule} tree.
%
\item Finally a \lstinline[language=C++]{RTLIL::SyncRule} is created for the \lstinline[language=C++]{RTLIL::Process} that
assigns the temporary signals for the final values to the actual signals.
%
\item Calls to \lstinline[language=C++]{AST::AstNode::genRTLIL()} are generated for right hand sides as needed. When blocking
assignments are used, \lstinline[language=C++]{AST::AstNode::genRTLIL()} is configured using global variables to use
the temporary signals that hold the correct intermediate values whenever one of the previously assigned signals is used
in an expression.
\end{itemize}
Unfortunately the generation of a correct \lstinline[language=C++]{RTLIL::CaseRule}/\lstinline[language=C++]{RTLIL::SwitchRule}
tree for behavioural code is a non-trivial task. The AST frontend solves the problem using the approach described on the following
pages. The following example illustrates what the algorithm is supposed to do. Consider the following Verilog code:
\begin{lstlisting}[numbers=left,frame=single,language=Verilog]
always @(posedge clock) begin
out1 = in1;
if (in2)
out1 = !out1;
out2 <= out1;
if (in3)
out2 <= out2;
if (in4)
if (in5)
out3 <= in6;
else
out3 <= in7;
out1 = out1 ^ out2;
end
\end{lstlisting}
This is translated by the Verilog and AST frontends into the following RTLIL code (attributes, cell parameters
and wire declarations not included):
\begin{lstlisting}[numbers=left,frame=single]
cell $logic_not $logic_not$<input>:4$2
connect \A \in1
connect \Y $logic_not$<input>:4$2_Y
end
cell $xor $xor$<input>:13$3
connect \A $1\out1[0:0]
connect \B \out2
connect \Y $xor$<input>:13$3_Y
end
process $proc$<input>:1$1
assign $0\out3[0:0] \out3
assign $0\out2[0:0] $1\out1[0:0]
assign $0\out1[0:0] $xor$<input>:13$3_Y
switch \in2
case 1'1
assign $1\out1[0:0] $logic_not$<input>:4$2_Y
case
assign $1\out1[0:0] \in1
end
switch \in3
case 1'1
assign $0\out2[0:0] \out2
case
end
switch \in4
case 1'1
switch \in5
case 1'1
assign $0\out3[0:0] \in6
case
assign $0\out3[0:0] \in7
end
case
end
sync posedge \clock
update \out1 $0\out1[0:0]
update \out2 $0\out2[0:0]
update \out3 $0\out3[0:0]
end
\end{lstlisting}
Note that the two operators are translated into separate cells outside the generated process. The signal
\lstinline[language=Verilog]{out1} is assigned using blocking assignments and therefore \lstinline[language=Verilog]{out1}
has been replaced with a different signal in all expressions after the initial assignment. The signal
\lstinline[language=Verilog]{out2} is assigned using nonblocking assignments and therefore is not substituted
on the right-hand-side expressions.
The \lstinline[language=C++]{RTLIL::CaseRule}/\lstinline[language=C++]{RTLIL::SwitchRule}
tree must be interpreted the following way:
\begin{itemize}
\item On each case level (the body of the process is the {\it root case}), first the actions on this level are
evaluated and then the switches within the case are evaluated. (Note that the last assignment on line 13 of the
Verilog code has been moved to the beginning of the RTLIL process to line 13 of the RTLIL listing.)
I.e.~the special cases deeper in the switch hierarchy override the defaults on the upper levels. The assignments
in lines 12 and 22 of the RTLIL code serve as an example for this.
Note that in contrast to this, the order within the \lstinline[language=C++]{RTLIL::SwitchRule} objects
within a \lstinline[language=C++]{RTLIL::CaseRule} is preserved with respect to the original AST and
Verilog code.
%
\item \begin{sloppypar}
The whole \lstinline[language=C++]{RTLIL::CaseRule}/\lstinline[language=C++]{RTLIL::SwitchRule} tree
describes an asynchronous circuit. I.e.~the decision tree formed by the switches can be seen independently for
each assigned signal. Whenever one assigned signal changes, all signals that depend on the changed signals
are to be updated. For example the assignments in lines 16 and 18 in the RTLIL code in fact influence the assignment
in line 12, even though they are in the ``wrong order''.
\end{sloppypar}
\end{itemize}
The only synchronous part of the process is in the \lstinline[language=C++]{RTLIL::SyncRule} object generated at line
35 in the RTLIL code. The sync rule is the only part of the process where the original signals are assigned. The
synchronization event from the original Verilog code has been translated into the synchronization type ({\tt posedge})
and signal ({\tt \textbackslash clock}) for the \lstinline[language=C++]{RTLIL::SyncRule} object. In the case of
this simple example the \lstinline[language=C++]{RTLIL::SyncRule} object is later simply transformed into a set of
d-type flip-flops and the \lstinline[language=C++]{RTLIL::CaseRule}/\lstinline[language=C++]{RTLIL::SwitchRule} tree
to a decision tree using multiplexers.
\begin{sloppypar}
In more complex examples (e.g.~asynchronous resets) the part of the
\lstinline[language=C++]{RTLIL::CaseRule}/\lstinline[language=C++]{RTLIL::SwitchRule}
tree that describes the asynchronous reset must first be transformed to the
correct \lstinline[language=C++]{RTLIL::SyncRule} objects. This is done by the {\tt proc\_adff} pass.
\end{sloppypar}
\subsection{The ProcessGenerator Algorithm}
The \lstinline[language=C++]{AST_INTERNAL::ProcessGenerator} uses the following internal state variables:
\begin{itemize}
\item \begin{sloppypar}
\lstinline[language=C++]{subst_rvalue_from} and \lstinline[language=C++]{subst_rvalue_to} \\
These two variables hold the replacement pattern that should be used by \lstinline[language=C++]{AST::AstNode::genRTLIL()}
for signals with blocking assignments. After initialization of \lstinline[language=C++]{AST_INTERNAL::ProcessGenerator}
these two variables are empty.
\end{sloppypar}
%
\item \lstinline[language=C++]{subst_lvalue_from} and \lstinline[language=C++]{subst_lvalue_to} \\
These two variables contain the mapping from left-hand-side signals ({\tt \textbackslash \it <name>}) to the current
temporary signal for the same thing (initially {\tt \$0\textbackslash \it <name>}).
%
\item \lstinline[language=C++]{current_case} \\
A pointer to a \lstinline[language=C++]{RTLIL::CaseRule} object. Initially this is the root case of the
generated \lstinline[language=C++]{RTLIL::Process}.
\end{itemize}
As the algorithm runs these variables are continously modified as well as pushed
to the stack and later restored to their earlier values by popping from the stack.
On startup the ProcessGenerator generates a new
\lstinline[language=C++]{RTLIL::Process} object with an empty root case and
initializes its state variables as described above. Then the \lstinline[language=C++]{RTLIL::SyncRule} objects
are created using the synchronization events from the {\tt AST\_ALWAYS} node and the initial values of
\lstinline[language=C++]{subst_lvalue_from} and \lstinline[language=C++]{subst_lvalue_to}. Then the
AST for this process is evaluated recursively.
During this recursive evaluation, three different relevant types of AST nodes can be discovered:
{\tt AST\_ASSIGN\_LE} (nonblocking assignments), {\tt AST\_ASSIGN\_EQ} (blocking assignments) and
{\tt AST\_CASE} (\lstinline[language=Verilog]{if} or \lstinline[language=Verilog]{case} statement).
\subsubsection{Handling of Nonblocking Assignments}
When an {\tt AST\_ASSIGN\_LE} node is discovered, the following actions are performed by the
ProcessGenerator:
\begin{itemize}
\item The left-hand-side is evaluated using \lstinline[language=C++]{AST::AstNode::genRTLIL()} and mapped to
a temporary signal name using \lstinline[language=C++]{subst_lvalue_from} and \lstinline[language=C++]{subst_lvalue_to}.
%
\item The right-hand-side is evaluated using \lstinline[language=C++]{AST::AstNode::genRTLIL()}. For this call,
the values of \lstinline[language=C++]{subst_rvalue_from} and \lstinline[language=C++]{subst_rvalue_to} are used to
map blocking-assigned signals correctly.
%
\item Remove all assignments to the same left-hand-side as this assignment from the \lstinline[language=C++]{current_case}
and all cases within it.
%
\item Add the new assignment to the \lstinline[language=C++]{current_case}.
\end{itemize}
\subsubsection{Handling of Blocking Assignments}
When an {\tt AST\_ASSIGN\_EQ} node is discovered, the following actions are performed by
the ProcessGenerator:
\begin{itemize}
\item Perform all the steps that would be performed for a nonblocking assignment (see above).
%
\item Remove the found left-hand-side (before lvalue mapping) from
\lstinline[language=C++]{subst_rvalue_from} and also remove the respective
bits from \lstinline[language=C++]{subst_rvalue_to}.
%
\item Append the found left-hand-side (before lvalue mapping) to \lstinline[language=C++]{subst_rvalue_from}
and append the found right-hand-side to \lstinline[language=C++]{subst_rvalue_to}.
\end{itemize}
\subsubsection{Handling of Cases and if-Statements}
\begin{sloppypar}
When an {\tt AST\_CASE} node is discovered, the following actions are performed by
the ProcessGenerator:
\begin{itemize}
\item The values of \lstinline[language=C++]{subst_rvalue_from}, \lstinline[language=C++]{subst_rvalue_to},
\lstinline[language=C++]{subst_lvalue_from} and \lstinline[language=C++]{subst_lvalue_to} are pushed to the stack.
%
\item A new \lstinline[language=C++]{RTLIL::SwitchRule} object is generated, the selection expression is evaluated using
\lstinline[language=C++]{AST::AstNode::genRTLIL()} (with the use of \lstinline[language=C++]{subst_rvalue_from} and
\lstinline[language=C++]{subst_rvalue_to}) and added to the \lstinline[language=C++]{RTLIL::SwitchRule} object and the
obect is added to the \lstinline[language=C++]{current_case}.
%
\item All lvalues assigned to within the {\tt AST\_CASE} node using blocking assignments are collected and
saved in the local variable \lstinline[language=C++]{this_case_eq_lvalue}.
%
\item New temporary signals are generated for all signals in \lstinline[language=C++]{this_case_eq_lvalue} and stored
in \lstinline[language=C++]{this_case_eq_ltemp}.
%
\item The signals in \lstinline[language=C++]{this_case_eq_lvalue} are mapped using \lstinline[language=C++]{subst_rvalue_from}
and \lstinline[language=C++]{subst_rvalue_to} and the resulting set of signals is stored in
\lstinline[language=C++]{this_case_eq_rvalue}.
\end{itemize}
Then the following steps are performed for each {\tt AST\_COND} node within the {\tt AST\_CASE} node:
\begin{itemize}
\item Set \lstinline[language=C++]{subst_rvalue_from}, \lstinline[language=C++]{subst_rvalue_to},
\lstinline[language=C++]{subst_lvalue_from} and \lstinline[language=C++]{subst_lvalue_to} to the values
that have been pushed to the stack.
%
\item Remove \lstinline[language=C++]{this_case_eq_lvalue} from
\lstinline[language=C++]{subst_lvalue_from}/\lstinline[language=C++]{subst_lvalue_to}.
%
\item Append \lstinline[language=C++]{this_case_eq_lvalue} to \lstinline[language=C++]{subst_lvalue_from} and append
\lstinline[language=C++]{this_case_eq_ltemp} to \lstinline[language=C++]{subst_lvalue_to}.
%
\item Push the value of \lstinline[language=C++]{current_case}.
%
\item Create a new \lstinline[language=C++]{RTLIL::CaseRule}. Set \lstinline[language=C++]{current_case} to the
new object and add the new object to the \lstinline[language=C++]{RTLIL::SwitchRule} created above.
%
\item Add an assignment from \lstinline[language=C++]{this_case_eq_rvalue} to \lstinline[language=C++]{this_case_eq_ltemp}
to the new \lstinline[language=C++]{current_case}.
%
\item Evaluate the compare value for this case using \lstinline[language=C++]{AST::AstNode::genRTLIL()} (with the use of
\lstinline[language=C++]{subst_rvalue_from} and \lstinline[language=C++]{subst_rvalue_to}) modify the new
\lstinline[language=C++]{current_case} accordingly.
%
\item Recursion into the children of the {\tt AST\_COND} node.
%
\item Restore \lstinline[language=C++]{current_case} by popping the old value from the stack.
\end{itemize}
Finally the following steps are performed:
\begin{itemize}
\item The values of \lstinline[language=C++]{subst_rvalue_from}, \lstinline[language=C++]{subst_rvalue_to},
\lstinline[language=C++]{subst_lvalue_from} and \lstinline[language=C++]{subst_lvalue_to} are popped from the stack.
%
\item The signals from \lstinline[language=C++]{this_case_eq_lvalue} are removed from the
\lstinline[language=C++]{subst_rvalue_from}/\lstinline[language=C++]{subst_rvalue_to}-pair.
%
\item The value of \lstinline[language=C++]{this_case_eq_lvalue} is appended to \lstinline[language=C++]{subst_rvalue_from}
and the value of \lstinline[language=C++]{this_case_eq_ltemp} is appended to \lstinline[language=C++]{subst_rvalue_to}.
%
\item Map the signals in \lstinline[language=C++]{this_case_eq_lvalue} using
\lstinline[language=C++]{subst_lvalue_from}/\lstinline[language=C++]{subst_lvalue_to}.
%
\item Remove all assignments to signals in \lstinline[language=C++]{this_case_eq_lvalue} in \lstinline[language=C++]{current_case}
and all cases within it.
%
\item Add an assignment from \lstinline[language=C++]{this_case_eq_ltemp} to \lstinline[language=C++]{this_case_eq_lvalue}
to \lstinline[language=C++]{current_case}.
\end{itemize}
\end{sloppypar}
\subsubsection{Further Analysis of the Algorithm for Cases and if-Statements}
With respect to nonblocking assignments the algorithm is easy: later assignments invalidate earlier assignments.
For each signal assigned using nonblocking assignments exactly one temporary variable is generated (with the
{\tt \$0}-prefix) and this variable is used for all assignments of the variable.
Note how all the \lstinline[language=C++]{_eq_}-variables become empty when no blocking assignments are used
and many of the steps in the algorithm can then be ignored as a result of this.
For a variable with blocking assignments the algorithm shows the following behaviour: First a new temporary variable
is created. This new temporary variable is then registered as the assignment target for all assignments for this
variable within the cases for this {\tt AST\_CASE} node. Then for each case the new temporary variable is first
assigned the old temporary variable. This assignment is overwritten if the variable is actually assigned in this
case and is kept as a default value otherwise.
This yields an \lstinline[language=C++]{RTLIL::CaseRule} that assigns the new temporary variable in all branches.
So when all cases have been processed a final assignment is added to the containing block that assigns the new
temporary variable to the old one. Note how this step always overrides a previous assignment to the old temporary
variable. Other than nonblocking assignments, the old assignment could still have an effect somewhere
in the design, as there have been calls to \lstinline[language=C++]{AST::AstNode::genRTLIL()} with a
\lstinline[language=C++]{subst_rvalue_from}/\lstinline[language=C++]{subst_rvalue_to}-tuple that contained
the right-hand-side of the old assignment.
\subsection{The proc pass}
The ProcessGenerator converts a behavioural model in AST representation to a behavioural model in
\lstinline[language=C++]{RTLIL::Process} representation. The actual conversion from a behavioural
model to an RTL representation is performed by the {\tt proc} pass and the passes it launches:
\begin{itemize}
\item {\tt proc\_clean} and {\tt proc\_rmdead} \\
These two passes just clean up the \lstinline[language=C++]{RTLIL::Process} structure. The {\tt proc\_clean}
pass removes empty parts (eg. empty assignments) from the process and {\tt proc\_rmdead} detects and removes
unreachable branches from the process's decision trees.
%
\item {\tt proc\_arst} \\
This pass detects processes that describe d-type flip-flops with asynchronous
resets and rewrites the process to better reflect what they are modelling:
Before this pass, an asynchronous reset has two edge-sensitive sync rules and
one top-level \C{RTLIL::SwitchRule} for the reset path. After this pass the
sync rule for the reset is level-sensitive and the top-level
\C{RTLIL::SwitchRule} has been removed.
%
\item {\tt proc\_mux} \\
This pass converts the \C{RTLIL::CaseRule}/\C{RTLIL::SwitchRule}-tree to a tree
of multiplexers per written signal. After this, the \C{RTLIL::Process} structure only contains
the \C{RTLIL::SyncRule}s that describe the output registers.
%
\item {\tt proc\_dff} \\
This pass replaces the \C{RTLIL::SyncRule}s to d-type flip-flops (with
asynchronous resets if neccessary).
%
\item {\tt proc\_clean} \\
A final call to {\tt proc\_clean} removes the now empty \C{RTLIL::Process} objects.
\end{itemize}
Performing these last processing steps in passes instead of in the Verilog frontend has two important benefits:
First it improves the transparency of the process. Everything that happens in a seperate pass is easier to debug,
as the RTLIL data structures can be easily investigated before and after each of the steps.
Second it improves flexibility. This scheme can easily be extended to support other types of storage-elements, such
as sr-latches or d-latches, without having to extend the actual Verilog frontend.
\section{Synthesizing Verilog Arrays}
\begin{fixme}
Add some information on the generation of {\tt \$memrd} and {\tt \$memwr} cells
and how they are processsed in the {\tt memory} pass.
\end{fixme}
\section{Synthesizing Parametric Designs}
\begin{fixme}
Add some information on the \lstinline[language=C++]{RTLIL::Module::derive()} method and how it
is used to synthesize parametric modules via the {\tt hierarchy} pass.
\end{fixme}

84
manual/FILES_Eval/grep-it.sh Normal file
View File

@ -0,0 +1,84 @@
#!/bin/bash
openmsp430_mods="
omsp_alu
omsp_clock_module
omsp_dbg
omsp_dbg_uart
omsp_execution_unit
omsp_frontend
omsp_mem_backbone
omsp_multiplier
omsp_register_file
omsp_sfr
omsp_sync_cell
omsp_sync_reset
omsp_watchdog
openMSP430"
or1200_mods="
or1200_alu
or1200_amultp2_32x32
or1200_cfgr
or1200_ctrl
or1200_dc_top
or1200_dmmu_tlb
or1200_dmmu_top
or1200_du
or1200_except
or1200_fpu
or1200_freeze
or1200_ic_fsm
or1200_ic_ram
or1200_ic_tag
or1200_ic_top
or1200_if
or1200_immu_tlb
or1200_lsu
or1200_mem2reg
or1200_mult_mac
or1200_operandmuxes
or1200_pic
or1200_pm
or1200_qmem_top
or1200_reg2mem
or1200_rf
or1200_sb
or1200_sprs
or1200_top
or1200_tt
or1200_wbmux"
grep_regs() {
x=$(grep '^ Number of Slice Registers:' $1.syr | sed 's/.*: *//;' | cut -f1 -d' ')
echo $x | sed 's,^ *$,-1,'
}
grep_luts() {
x=$(grep '^ Number of Slice LUTs:' $1.syr | sed 's/.*: *//;' | cut -f1 -d' ')
echo $x | sed 's,^ *$,-1,'
}
grep_freq() {
x=$(grep 'Minimum period.*Maximum Frequency' $1.syr | sed 's/\.[0-9]*MHz.*//;' | cut -f3 -d:)
echo $x | sed 's,^ *$,-1,'
}
for mod in $openmsp430_mods $or1200_mods; do
printf '%-30s s,$, \\& %6d \\& %6d \\& %4d MHz \\& %6d \\& %6d \\& %4d MHz \\\\\\\\,;\n' "/${mod//_/\\\\_}}/" \
$(grep_regs ${mod}) $(grep_luts ${mod}) $(grep_freq ${mod}) \
$(grep_regs ${mod}_ys) $(grep_luts ${mod}_ys) $(grep_freq ${mod}_ys)
done
# for mod in $openmsp430_mods $or1200_mods; do
# [ $mod = "or1200_top" -o $mod = "or1200_dmmu_top" -o $mod = or1200_dmmu_tlb -o $mod = or1200_immu_tlb ] && continue
# regs=$(grep_regs ${mod}) regs_ys=$(grep_regs ${mod}_ys)
# luts=$(grep_luts ${mod}) luts_ys=$(grep_luts ${mod}_ys)
# freq=$(grep_freq ${mod}) freq_ys=$(grep_freq ${mod}_ys)
# if [ $regs -gt 0 -a $regs_ys -gt 0 ]; then regs_p=$(( 100*regs_ys / regs )); else regs_p=NaN; fi
# if [ $luts -gt 0 -a $luts_ys -gt 0 ]; then luts_p=$(( 100*luts_ys / luts )); else luts_p=NaN; fi
# if [ $freq -gt 0 -a $freq_ys -gt 0 ]; then freq_p=$(( 100*freq_ys / freq )); else freq_p=NaN; fi
# printf '%-30s %3s %3s %3s\n' $mod $regs_p $luts_p $freq_p
#
# done

14
manual/FILES_Eval/openmsp430.prj Normal file
View File

@ -0,0 +1,14 @@
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_sync_cell.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_sync_reset.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_register_file.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_dbg_uart.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_alu.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_watchdog.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_sfr.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_multiplier.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_mem_backbone.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_frontend.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_execution_unit.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_dbg.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/omsp_clock_module.v"
verilog work "../../../../../Work/yosys-tests/openmsp430/rtl/openMSP430.v"

1
manual/FILES_Eval/openmsp430_ys.prj Normal file
View File

@ -0,0 +1 @@
verilog work "openmsp430_ys.v"

37
manual/FILES_Eval/or1200.prj Normal file
View File

@ -0,0 +1,37 @@
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_spram.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_reg2mem.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_mem2reg.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_dpram.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_amultp2_32x32.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_wbmux.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_sprs.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_rf.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_operandmuxes.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_mult_mac.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_lsu.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_immu_tlb.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_if.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_ic_tag.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_ic_ram.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_ic_fsm.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_genpc.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_freeze.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_fpu.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_except.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_dmmu_tlb.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_ctrl.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_cfgr.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_alu.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_wb_biu.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_tt.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_sb.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_qmem_top.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_pm.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_pic.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_immu_top.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_ic_top.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_du.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_dmmu_top.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_dc_top.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_cpu.v"
verilog work "../../../../../Work/yosys-tests/or1200/rtl/or1200_top.v"

1
manual/FILES_Eval/or1200_ys.prj Normal file
View File

@ -0,0 +1 @@
verilog work "or1200_ys.v"

74
manual/FILES_Eval/run-it.sh Normal file
View File

@ -0,0 +1,74 @@
#!/bin/bash
openmsp430_mods="
omsp_alu
omsp_clock_module
omsp_dbg
omsp_dbg_uart
omsp_execution_unit
omsp_frontend
omsp_mem_backbone
omsp_multiplier
omsp_register_file
omsp_sfr
omsp_sync_cell
omsp_sync_reset
omsp_watchdog
openMSP430"
or1200_mods="
or1200_alu
or1200_amultp2_32x32
or1200_cfgr
or1200_ctrl
or1200_dc_top
or1200_dmmu_tlb
or1200_dmmu_top
or1200_du
or1200_except
or1200_fpu
or1200_freeze
or1200_ic_fsm
or1200_ic_ram
or1200_ic_tag
or1200_ic_top
or1200_if
or1200_immu_tlb
or1200_lsu
or1200_mem2reg
or1200_mult_mac
or1200_operandmuxes
or1200_pic
or1200_pm
or1200_qmem_top
or1200_reg2mem
or1200_rf
or1200_sb
or1200_sprs
or1200_top
or1200_tt
or1200_wbmux"
yosys_cmds="hierarchy -check; proc; opt; fsm; opt; memory; opt; techmap; opt; abc; opt"
yosys -p "$yosys_cmds" -o openmsp430_ys.v $( cut -f2 -d'"' openmsp430.prj )
yosys -p "$yosys_cmds" -o or1200_ys.v $( cut -f2 -d'"' or1200.prj )
. /opt/Xilinx/14.5/ISE_DS/settings64.sh
run_single() {
prj_file=$1 top_module=$2 out_file=$3
sed "s/@prj_file@/$prj_file/g; s/@out_file@/$out_file/g; s/@top_module@/$top_module/g;" < settings.xst > ${out_file}.xst
xst -ifn ${out_file}.xst -ofn ${out_file}.syr
}
for mod in $openmsp430_mods; do
run_single openmsp430.prj ${mod} ${mod}
run_single openmsp430_ys.prj ${mod} ${mod}_ys
done
for mod in $or1200_mods; do
run_single or1200.prj ${mod} ${mod}
run_single or1200_ys.prj ${mod} ${mod}_ys
done

2
manual/FILES_Eval/settings.xst Normal file
View File

@ -0,0 +1,2 @@
run -ifn @prj_file@ -ofn @out_file@ -ofmt NGC -top @top_module@ -p artix7
-use_dsp48 NO -iobuf NO -ram_extract NO -rom_extract NO -fsm_extract YES -fsm_encoding Auto

14
manual/FILES_Prog/Makefile Normal file
View File

@ -0,0 +1,14 @@
test: stubnets.so
yosys -q -l test1.log -m ./stubnets.so test.v -p "proc; stubnets"
yosys -q -l test2.log -m ./stubnets.so test.v -p "proc; opt; stubnets"
yosys -q -l test3.log -m ./stubnets.so test.v -p "proc; techmap; opt; stubnets -report_bits"
tail test1.log test2.log test3.log
stubnets.so: stubnets.cc
$(shell yosys-config --cxx --cxxflags --ldflags -o stubnets.so -shared stubnets.cc --ldlibs )
clean:
rm -f test1.log test2.log test3.log
rm -f stubnets.so stubnets.d

132
manual/FILES_Prog/stubnets.cc Normal file
View File

@ -0,0 +1,132 @@
// This is free and unencumbered software released into the public domain.
//
// Anyone is free to copy, modify, publish, use, compile, sell, or
// distribute this software, either in source code form or as a compiled
// binary, for any purpose, commercial or non-commercial, and by any
// means.
#include "kernel/rtlil.h"
#include "kernel/register.h"
#include "kernel/sigtools.h"
#include "kernel/log.h"
#include <string>
#include <map>
#include <set>
// this function is called for each module in the design
static void find_stub_nets(RTLIL::Design *design, RTLIL::Module *module, bool report_bits)
{
// use a SigMap to convert nets to a unique representation
SigMap sigmap(module);
// count how many times a single-bit signal is used
std::map<RTLIL::SigSpec, int> bit_usage_count;
// count ouput lines for this module (needed only for summary output at the end)
int line_count = 0;
log("Looking for stub wires in module %s:\n", RTLIL::id2cstr(module->name));
// For all ports on all cells
for (auto &cell_iter : module->cells)
for (auto &conn : cell_iter.second->connections)
{
// Get the signals on the port
// (use sigmap to get a uniqe signal name)
RTLIL::SigSpec sig = sigmap(conn.second);
// split the signal up into single-bit chunks
sig.expand();
// add each chunk to bit_usage_count, unless it is a constant
for (auto &c : sig.chunks)
if (c.wire != NULL)
bit_usage_count[c]++;
}
// for each wire in the module
for (auto &wire_iter : module->wires)
{
RTLIL::Wire *wire = wire_iter.second;
// .. but only selected wires
if (!design->selected(module, wire))
continue;
// add +1 usage if this wire actually is a port
int usage_offset = wire->port_id > 0 ? 1 : 0;
// we will record which bits of the (possibly multi-bit) wire are stub signals
std::set<int> stub_bits;
// get a signal description for this wire and split it into seperate bits
RTLIL::SigSpec sig = sigmap(wire);
sig.expand();
// for each bit (unless it is a constant):
// check if it is used at least two times and add to stub_bits otherwise
for (size_t i = 0; i < sig.chunks.size(); i++)
if (sig.chunks[i].wire != NULL && (bit_usage_count[sig.chunks[i]] + usage_offset) < 2)
stub_bits.insert(i);
// continue if no stub bits found
if (stub_bits.size() == 0)
continue;
// report stub bits and/or stub wires, don't report single bits
// if called with report_bits set to false.
if (int(stub_bits.size()) == sig.width) {
log(" found stub wire: %s\n", RTLIL::id2cstr(wire->name));
} else {
if (!report_bits)
continue;
log(" found wire with stub bits: %s [", RTLIL::id2cstr(wire->name));
for (int bit : stub_bits)
log("%s%d", bit == *stub_bits.begin() ? "" : ", ", bit);
log("]\n");
}
// we have outputted a line, increment summary counter
line_count++;
}
// report summary
if (report_bits)
log(" found %d stub wires or wires with stub bits.\n", line_count);
else
log(" found %d stub wires.\n", line_count);
}
// each pass contains a singleton object that is derived from Pass
struct StubnetsPass : public Pass {
StubnetsPass() : Pass("stubnets") { }
virtual void execute(std::vector<std::string> args, RTLIL::Design *design)
{
// variables to mirror information from passed options
bool report_bits = 0;
log_header("Executing STUBNETS pass (find stub nets).\n");
// parse options
size_t argidx;
for (argidx = 1; argidx < args.size(); argidx++) {
std::string arg = args[argidx];
if (arg == "-report_bits") {
report_bits = true;
continue;
}
break;
}
// handle extra options (e.g. selection)
extra_args(args, argidx, design);
// call find_stub_nets() for each module that is either
// selected as a whole or contains selected objects.
for (auto &it : design->modules)
if (design->selected_module(it.first))
find_stub_nets(design, it.second, report_bits);
}
} StubnetsPass;

8
manual/FILES_Prog/test.v Normal file
View File

@ -0,0 +1,8 @@
module uut(in1, in2, in3, out1, out2);
input [8:0] in1, in2, in3;
output [8:0] out1, out2;
assign out1 = in1 + in2 + (in3 >> 4);
endmodule

12
manual/FILES_StateOfTheArt/always01.v Normal file
View File

@ -0,0 +1,12 @@
module uut_always01(clock, reset, c3, c2, c1, c0);
input clock, reset;
output c3, c2, c1, c0;
reg [3:0] count;
assign {c3, c2, c1, c0} = count;
always @(posedge clock)
count <= reset ? 0 : count + 1;
endmodule

14
manual/FILES_StateOfTheArt/always01_pub.v Normal file
View File

@ -0,0 +1,14 @@
module uut_always01(clock,
reset, count);
input clock, reset;
output [3:0] count;
reg [3:0] count;
always @(posedge clock)
count <= reset ?
0 : count + 1;
endmodule

15
manual/FILES_StateOfTheArt/always02.v Normal file
View File

@ -0,0 +1,15 @@
module uut_always02(clock, reset, c3, c2, c1, c0);
input clock, reset;
output c3, c2, c1, c0;
reg [3:0] count;
assign {c3, c2, c1, c0} = count;
always @(posedge clock) begin
count <= count + 1;
if (reset)
count <= 0;
end
endmodule

14
manual/FILES_StateOfTheArt/always02_pub.v Normal file
View File

@ -0,0 +1,14 @@
module uut_always02(clock,
reset, count);
input clock, reset;
output [3:0] count;
reg [3:0] count;
always @(posedge clock) begin
count <= count + 1;
if (reset)
count <= 0;
end
endmodule

23
manual/FILES_StateOfTheArt/always03.v Normal file
View File

@ -0,0 +1,23 @@
module uut_always03(clock, in1, in2, in3, in4, in5, in6, in7,
out1, out2, out3);
input clock, in1, in2, in3, in4, in5, in6, in7;
output out1, out2, out3;
reg out1, out2, out3;
always @(posedge clock) begin
out1 = in1;
if (in2)
out1 = !out1;
out2 <= out1;
if (in3)
out2 <= out2;
if (in4)
if (in5)
out3 <= in6;
else
out3 <= in7;
out1 = out1 ^ out2;
end
endmodule

16
manual/FILES_StateOfTheArt/arrays01.v Normal file
View File

@ -0,0 +1,16 @@
module uut_arrays01(clock, we, addr, wr_data, rd_data);
input clock, we;
input [3:0] addr, wr_data;
output [3:0] rd_data;
reg [3:0] rd_data;
reg [3:0] memory [15:0];
always @(posedge clock) begin
if (we)
memory[addr] <= wr_data;
rd_data <= memory[addr];
end
endmodule

67
manual/FILES_StateOfTheArt/cmp_tbdata.c Normal file
View File

@ -0,0 +1,67 @@
#include <stdio.h>
#include <stdlib.h>
#include <stdbool.h>
#include <string.h>
int line = 0;
char buffer1[1024];
char buffer2[1024];
void check(bool ok)
{
if (ok)
return;
// fprintf(stderr, "Error in testbench output compare (line=%d):\n-%s\n+%s\n", line, buffer1, buffer2);
exit(1);
}
int main(int argc, char **argv)
{
FILE *f1, *f2;
bool eof1, eof2;
int i;
check(argc == 3);
f1 = fopen(argv[1], "r");
f2 = fopen(argv[2], "r");
check(f1 && f2);
while (!feof(f1) && !feof(f2))
{
line++;
buffer1[0] = 0;
buffer2[0] = 0;
eof1 = fgets(buffer1, 1024, f1) == NULL;
eof2 = fgets(buffer2, 1024, f2) == NULL;
if (*buffer1 && buffer1[strlen(buffer1)-1] == '\n')
buffer1[strlen(buffer1)-1] = 0;
if (*buffer2 && buffer2[strlen(buffer2)-1] == '\n')
buffer2[strlen(buffer2)-1] = 0;
check(eof1 == eof2);
for (i = 0; buffer1[i] || buffer2[i]; i++)
{
check(buffer1[i] != 0 && buffer2[i] != 0);
// first argument is the reference. An 'z' or 'x'
// here means we don't care about the result.
if (buffer1[i] == 'z' || buffer1[i] == 'x')
continue;
check(buffer1[i] == buffer2[i]);
}
}
check(feof(f1) && feof(f2));
fclose(f1);
fclose(f2);
return 0;
}

20
manual/FILES_StateOfTheArt/forgen01.v Normal file
View File

@ -0,0 +1,20 @@
module uut_forgen01(a, y);
input [4:0] a;
output y;
integer i, j;
reg [31:0] lut;
initial begin
for (i = 0; i < 32; i = i+1) begin
lut[i] = i > 1;
for (j = 2; j*j <= i; j = j+1)
if (i % j == 0)
lut[i] = 0;
end
end
assign y = lut[a];
endmodule

30
manual/FILES_StateOfTheArt/forgen02.v Normal file
View File

@ -0,0 +1,30 @@
module uut_forgen02(a, b, cin, y, cout);
parameter WIDTH = 8;
input [WIDTH-1:0] a, b;
input cin;
output [WIDTH-1:0] y;
output cout;
genvar i;
wire [WIDTH-1:0] carry;
generate
for (i = 0; i < WIDTH; i=i+1) begin:adder
wire [2:0] D;
assign D[1:0] = { a[i], b[i] };
if (i == 0) begin:chain
assign D[2] = cin;
end else begin:chain
assign D[2] = carry[i-1];
end
assign y[i] = ^D;
assign carry[i] = &D[1:0] | (^D[1:0] & D[2]);
end
endgenerate
assign cout = carry[WIDTH-1];
endmodule

20
manual/FILES_StateOfTheArt/iverilog-0.8.7-buildfixes.patch Normal file
View File

@ -0,0 +1,20 @@
--- ./elab_net.cc.orig 2012-10-27 22:11:05.345688820 +0200
+++ ./elab_net.cc 2012-10-27 22:12:23.398075860 +0200
@@ -29,6 +29,7 @@
# include <iostream>
# include <cstring>
+# include <memory>
/*
* This is a state flag that determines whether an elaborate_net must
--- ./syn-rules.y.orig 2012-10-27 22:25:38.890020489 +0200
+++ ./syn-rules.y 2012-10-27 22:25:49.146071350 +0200
@@ -25,6 +25,7 @@
# include "config.h"
# include <iostream>
+# include <stdio.h>
/*
* This file implements synthesis based on matching threads and

36
manual/FILES_StateOfTheArt/mvsis-1.3.6-buildfixes.patch Normal file
View File

@ -0,0 +1,36 @@
--- ./helpers/config.sub.orig 2012-10-27 22:09:04.429089223 +0200
+++ ./helpers/config.sub 2012-10-27 22:09:11.501124295 +0200
@@ -158,6 +158,7 @@
| sparc | sparclet | sparclite | sparc64)
basic_machine=$basic_machine-unknown
;;
+ x86_64-pc) ;;
# We use `pc' rather than `unknown'
# because (1) that's what they normally are, and
# (2) the word "unknown" tends to confuse beginning users.
--- ./src/base/ntki/ntkiFrames.c.orig 2012-10-27 22:09:26.961200963 +0200
+++ ./src/base/ntki/ntkiFrames.c 2012-10-27 22:09:32.901230409 +0200
@@ -23,7 +23,7 @@
////////////////////////////////////////////////////////////////////////
static void Ntk_NetworkAddFrame( Ntk_Network_t * pNetNew, Ntk_Network_t * pNet, int iFrame );
-static void Ntk_NetworkReorderCiCo( Ntk_Network_t * pNet );
+// static void Ntk_NetworkReorderCiCo( Ntk_Network_t * pNet );
extern int Ntk_NetworkVerifyVariables( Ntk_Network_t * pNet1, Ntk_Network_t * pNet2, int fVerbose );
--- ./src/graph/wn/wnStrashBin.c.orig 2012-10-27 22:27:29.966571294 +0200
+++ ./src/graph/wn/wnStrashBin.c 2012-10-27 22:27:55.898699881 +0200
@@ -76,8 +76,10 @@
// assert( RetValue );
// clean the data of the nodes in the window
- Ntk_NetworkForEachNodeSpecial( pWnd->pNet, pNode )
- pNode->pCopy = (Ntk_Node_t *)pNode->pData = NULL;
+ Ntk_NetworkForEachNodeSpecial( pWnd->pNet, pNode ) {
+ pNode->pData = NULL;
+ pNode->pCopy = NULL;
+ }
// set the leaves
pgInputs = Sh_ManagerReadVars( pMan );

1139
manual/FILES_StateOfTheArt/simlib_hana.v Normal file
View File

File diff suppressed because it is too large Load Diff

224
manual/FILES_StateOfTheArt/simlib_icarus.v Normal file
View File

@ -0,0 +1,224 @@
module cell0(Result0);
output Result0;
assign Result0 = 0;
endmodule
module cell1(Result0);
output Result0;
assign Result0 = 1;
endmodule
module ADD4(
DataA0, DataA1, DataA2, DataA3,
DataB0, DataB1, DataB2, DataB3,
Result0, Result1, Result2, Result3, Cout
);
input DataA0, DataA1, DataA2, DataA3;
input DataB0, DataB1, DataB2, DataB3;
output Result0, Result1, Result2, Result3, Cout;
assign {Cout, Result3, Result2, Result1, Result0} = {DataA3, DataA2, DataA1, DataA0} + {DataB3, DataB2, DataB1, DataB0};
endmodule
module BUF(DATA, RESULT);
input DATA;
output RESULT;
assign RESULT = DATA;
endmodule
module INV(DATA, RESULT);
input DATA;
output RESULT;
assign RESULT = ~DATA;
endmodule
module fd4(
Clock,
Data0, Data1, Data2, Data3,
Q0, Q1, Q2, Q3
);
input Clock;
input Data0, Data1, Data2, Data3;
output reg Q0, Q1, Q2, Q3;
always @(posedge Clock)
{Q0, Q1, Q2, Q3} <= {Data0, Data1, Data2, Data3};
endmodule
module fdce1(
Clock, Enable,
Data0,
Q0
);
input Clock, Enable;
input Data0;
output reg Q0;
always @(posedge Clock)
if (Enable)
Q0 <= Data0;
endmodule
module fdce4(
Clock, Enable,
Data0, Data1, Data2, Data3,
Q0, Q1, Q2, Q3
);
input Clock, Enable;
input Data0, Data1, Data2, Data3;
output reg Q0, Q1, Q2, Q3;
always @(posedge Clock)
if (Enable)
{Q0, Q1, Q2, Q3} <= {Data0, Data1, Data2, Data3};
endmodule
module mux4_1_2(
Sel0,
Data0x0, Data0x1, Data0x2, Data0x3,
Data1x0, Data1x1, Data1x2, Data1x3,
Result0, Result1, Result2, Result3
);
input Sel0;
input Data0x0, Data0x1, Data0x2, Data0x3;
input Data1x0, Data1x1, Data1x2, Data1x3;
output Result0, Result1, Result2, Result3;
assign {Result0, Result1, Result2, Result3} = Sel0 ? {Data1x0, Data1x1, Data1x2, Data1x3} : {Data0x0, Data0x1, Data0x2, Data0x3};
endmodule
module mux1_1_2(
Sel0,
Data0x0,
Data1x0,
Result0
);
input Sel0;
input Data0x0;
input Data1x0;
output Result0;
assign Result0 = Sel0 ? Data1x0 : Data0x0;
endmodule
module xor2(
DATA0X0,
DATA1X0,
RESULT0
);
input DATA0X0;
input DATA1X0;
output RESULT0;
assign RESULT0 = DATA1X0 ^ DATA0X0;
endmodule
module fdce64(
Clock, Enable,
Data0, Data1, Data2, Data3, Data4, Data5, Data6, Data7, Data8, Data9, Data10, Data11, Data12, Data13, Data14, Data15, Data16, Data17, Data18, Data19, Data20, Data21, Data22, Data23, Data24, Data25, Data26, Data27, Data28, Data29, Data30, Data31, Data32, Data33, Data34, Data35, Data36, Data37, Data38, Data39, Data40, Data41, Data42, Data43, Data44, Data45, Data46, Data47, Data48, Data49, Data50, Data51, Data52, Data53, Data54, Data55, Data56, Data57, Data58, Data59, Data60, Data61, Data62, Data63,
Q0, Q1, Q2, Q3, Q4, Q5, Q6, Q7, Q8, Q9, Q10, Q11, Q12, Q13, Q14, Q15, Q16, Q17, Q18, Q19, Q20, Q21, Q22, Q23, Q24, Q25, Q26, Q27, Q28, Q29, Q30, Q31, Q32, Q33, Q34, Q35, Q36, Q37, Q38, Q39, Q40, Q41, Q42, Q43, Q44, Q45, Q46, Q47, Q48, Q49, Q50, Q51, Q52, Q53, Q54, Q55, Q56, Q57, Q58, Q59, Q60, Q61, Q62, Q63
);
input Clock, Enable;
input Data0, Data1, Data2, Data3, Data4, Data5, Data6, Data7, Data8, Data9, Data10, Data11, Data12, Data13, Data14, Data15, Data16, Data17, Data18, Data19, Data20, Data21, Data22, Data23, Data24, Data25, Data26, Data27, Data28, Data29, Data30, Data31, Data32, Data33, Data34, Data35, Data36, Data37, Data38, Data39, Data40, Data41, Data42, Data43, Data44, Data45, Data46, Data47, Data48, Data49, Data50, Data51, Data52, Data53, Data54, Data55, Data56, Data57, Data58, Data59, Data60, Data61, Data62, Data63;
output reg Q0, Q1, Q2, Q3, Q4, Q5, Q6, Q7, Q8, Q9, Q10, Q11, Q12, Q13, Q14, Q15, Q16, Q17, Q18, Q19, Q20, Q21, Q22, Q23, Q24, Q25, Q26, Q27, Q28, Q29, Q30, Q31, Q32, Q33, Q34, Q35, Q36, Q37, Q38, Q39, Q40, Q41, Q42, Q43, Q44, Q45, Q46, Q47, Q48, Q49, Q50, Q51, Q52, Q53, Q54, Q55, Q56, Q57, Q58, Q59, Q60, Q61, Q62, Q63;
always @(posedge Clock)
if (Enable)
{ Q0, Q1, Q2, Q3, Q4, Q5, Q6, Q7, Q8, Q9, Q10, Q11, Q12, Q13, Q14, Q15, Q16, Q17, Q18, Q19, Q20, Q21, Q22, Q23, Q24, Q25, Q26, Q27, Q28, Q29, Q30, Q31, Q32, Q33, Q34, Q35, Q36, Q37, Q38, Q39, Q40, Q41, Q42, Q43, Q44, Q45, Q46, Q47, Q48, Q49, Q50, Q51, Q52, Q53, Q54, Q55, Q56, Q57, Q58, Q59, Q60, Q61, Q62, Q63 } <= { Data0, Data1, Data2, Data3, Data4, Data5, Data6, Data7, Data8, Data9, Data10, Data11, Data12, Data13, Data14, Data15, Data16, Data17, Data18, Data19, Data20, Data21, Data22, Data23, Data24, Data25, Data26, Data27, Data28, Data29, Data30, Data31, Data32, Data33, Data34, Data35, Data36, Data37, Data38, Data39, Data40, Data41, Data42, Data43, Data44, Data45, Data46, Data47, Data48, Data49, Data50, Data51, Data52, Data53, Data54, Data55, Data56, Data57, Data58, Data59, Data60, Data61, Data62, Data63 };
endmodule
module mux4_4_16(
Sel0, Sel1, Sel2, Sel3,
Result0, Result1, Result2, Result3,
Data0x0, Data0x1, Data0x2, Data0x3,
Data1x0, Data1x1, Data1x2, Data1x3,
Data2x0, Data2x1, Data2x2, Data2x3,
Data3x0, Data3x1, Data3x2, Data3x3,
Data4x0, Data4x1, Data4x2, Data4x3,
Data5x0, Data5x1, Data5x2, Data5x3,
Data6x0, Data6x1, Data6x2, Data6x3,
Data7x0, Data7x1, Data7x2, Data7x3,
Data8x0, Data8x1, Data8x2, Data8x3,
Data9x0, Data9x1, Data9x2, Data9x3,
Data10x0, Data10x1, Data10x2, Data10x3,
Data11x0, Data11x1, Data11x2, Data11x3,
Data12x0, Data12x1, Data12x2, Data12x3,
Data13x0, Data13x1, Data13x2, Data13x3,
Data14x0, Data14x1, Data14x2, Data14x3,
Data15x0, Data15x1, Data15x2, Data15x3
);
input Sel0, Sel1, Sel2, Sel3;
output Result0, Result1, Result2, Result3;
input Data0x0, Data0x1, Data0x2, Data0x3;
input Data1x0, Data1x1, Data1x2, Data1x3;
input Data2x0, Data2x1, Data2x2, Data2x3;
input Data3x0, Data3x1, Data3x2, Data3x3;
input Data4x0, Data4x1, Data4x2, Data4x3;
input Data5x0, Data5x1, Data5x2, Data5x3;
input Data6x0, Data6x1, Data6x2, Data6x3;
input Data7x0, Data7x1, Data7x2, Data7x3;
input Data8x0, Data8x1, Data8x2, Data8x3;
input Data9x0, Data9x1, Data9x2, Data9x3;
input Data10x0, Data10x1, Data10x2, Data10x3;
input Data11x0, Data11x1, Data11x2, Data11x3;
input Data12x0, Data12x1, Data12x2, Data12x3;
input Data13x0, Data13x1, Data13x2, Data13x3;
input Data14x0, Data14x1, Data14x2, Data14x3;
input Data15x0, Data15x1, Data15x2, Data15x3;
assign {Result0, Result1, Result2, Result3} =
{Sel3, Sel2, Sel1, Sel0} == 0 ? { Data0x0, Data0x1, Data0x2, Data0x3 } :
{Sel3, Sel2, Sel1, Sel0} == 1 ? { Data1x0, Data1x1, Data1x2, Data1x3 } :
{Sel3, Sel2, Sel1, Sel0} == 2 ? { Data2x0, Data2x1, Data2x2, Data2x3 } :
{Sel3, Sel2, Sel1, Sel0} == 3 ? { Data3x0, Data3x1, Data3x2, Data3x3 } :
{Sel3, Sel2, Sel1, Sel0} == 4 ? { Data4x0, Data4x1, Data4x2, Data4x3 } :
{Sel3, Sel2, Sel1, Sel0} == 5 ? { Data5x0, Data5x1, Data5x2, Data5x3 } :
{Sel3, Sel2, Sel1, Sel0} == 6 ? { Data6x0, Data6x1, Data6x2, Data6x3 } :
{Sel3, Sel2, Sel1, Sel0} == 7 ? { Data7x0, Data7x1, Data7x2, Data7x3 } :
{Sel3, Sel2, Sel1, Sel0} == 8 ? { Data8x0, Data8x1, Data8x2, Data8x3 } :
{Sel3, Sel2, Sel1, Sel0} == 9 ? { Data9x0, Data9x1, Data9x2, Data9x3 } :
{Sel3, Sel2, Sel1, Sel0} == 10 ? { Data10x0, Data10x1, Data10x2, Data10x3 } :
{Sel3, Sel2, Sel1, Sel0} == 11 ? { Data11x0, Data11x1, Data11x2, Data11x3 } :
{Sel3, Sel2, Sel1, Sel0} == 12 ? { Data12x0, Data12x1, Data12x2, Data12x3 } :
{Sel3, Sel2, Sel1, Sel0} == 13 ? { Data13x0, Data13x1, Data13x2, Data13x3 } :
{Sel3, Sel2, Sel1, Sel0} == 14 ? { Data14x0, Data14x1, Data14x2, Data14x3 } :
{Sel3, Sel2, Sel1, Sel0} == 15 ? { Data15x0, Data15x1, Data15x2, Data15x3 } : 'bx;
endmodule
module mux1_5_32(
Sel0, Sel1, Sel2, Sel3, Sel4,
Data0x0, Data1x0, Data2x0, Data3x0, Data4x0, Data5x0, Data6x0, Data7x0, Data8x0, Data9x0, Data10x0, Data11x0, Data12x0, Data13x0, Data14x0, Data15x0,
Data16x0, Data17x0, Data18x0, Data19x0, Data20x0, Data21x0, Data22x0, Data23x0, Data24x0, Data25x0, Data26x0, Data27x0, Data28x0, Data29x0, Data30x0, Data31x0,
Result0
);
input Sel0, Sel1, Sel2, Sel3, Sel4;
input Data0x0, Data1x0, Data2x0, Data3x0, Data4x0, Data5x0, Data6x0, Data7x0, Data8x0, Data9x0, Data10x0, Data11x0, Data12x0, Data13x0, Data14x0, Data15x0;
input Data16x0, Data17x0, Data18x0, Data19x0, Data20x0, Data21x0, Data22x0, Data23x0, Data24x0, Data25x0, Data26x0, Data27x0, Data28x0, Data29x0, Data30x0, Data31x0;
output Result0;
assign Result0 =
{Sel4, Sel3, Sel2, Sel1, Sel0} == 0 ? Data0x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 1 ? Data1x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 2 ? Data2x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 3 ? Data3x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 4 ? Data4x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 5 ? Data5x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 6 ? Data6x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 7 ? Data7x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 8 ? Data8x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 9 ? Data9x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 10 ? Data10x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 11 ? Data11x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 12 ? Data12x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 13 ? Data13x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 14 ? Data14x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 15 ? Data15x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 16 ? Data16x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 17 ? Data17x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 18 ? Data18x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 19 ? Data19x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 20 ? Data20x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 21 ? Data21x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 22 ? Data22x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 23 ? Data23x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 24 ? Data24x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 25 ? Data25x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 26 ? Data26x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 27 ? Data27x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 28 ? Data28x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 29 ? Data29x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 30 ? Data30x0 :
{Sel4, Sel3, Sel2, Sel1, Sel0} == 31 ? Data31x0 : 'bx;
endmodule

166
manual/FILES_StateOfTheArt/simlib_yosys.v Normal file
View File

@ -0,0 +1,166 @@
/*
* yosys -- Yosys Open SYnthesis Suite
*
* Copyright (C) 2012 Clifford Wolf <clifford@clifford.at>
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* ---
*
* The internal logic cell simulation library.
*
* This verilog library contains simple simulation models for the internal
* logic cells (_INV_, _AND_, ...) that are generated by the default technology
* mapper (see "stdcells.v" in this directory) and expected by the "abc" pass.
*
*/
module _INV_(A, Y);
input A;
output Y;
assign Y = ~A;
endmodule
module _AND_(A, B, Y);
input A, B;
output Y;
assign Y = A & B;
endmodule
module _OR_(A, B, Y);
input A, B;
output Y;
assign Y = A | B;
endmodule
module _XOR_(A, B, Y);
input A, B;
output Y;
assign Y = A ^ B;
endmodule
module _MUX_(A, B, S, Y);
input A, B, S;
output reg Y;
always @* begin
if (S)
Y = B;
else
Y = A;
end
endmodule
module _DFF_N_(D, Q, C);
input D, C;
output reg Q;
always @(negedge C) begin
Q <= D;
end
endmodule
module _DFF_P_(D, Q, C);
input D, C;
output reg Q;
always @(posedge C) begin
Q <= D;
end
endmodule
module _DFF_NN0_(D, Q, C, R);
input D, C, R;
output reg Q;
always @(negedge C or negedge R) begin
if (R == 0)
Q <= 0;
else
Q <= D;
end
endmodule
module _DFF_NN1_(D, Q, C, R);
input D, C, R;
output reg Q;
always @(negedge C or negedge R) begin
if (R == 0)
Q <= 1;
else
Q <= D;
end
endmodule
module _DFF_NP0_(D, Q, C, R);
input D, C, R;
output reg Q;
always @(negedge C or posedge R) begin
if (R == 1)
Q <= 0;
else
Q <= D;
end
endmodule
module _DFF_NP1_(D, Q, C, R);
input D, C, R;
output reg Q;
always @(negedge C or posedge R) begin
if (R == 1)
Q <= 1;
else
Q <= D;
end
endmodule
module _DFF_PN0_(D, Q, C, R);
input D, C, R;
output reg Q;
always @(posedge C or negedge R) begin
if (R == 0)
Q <= 0;
else
Q <= D;
end
endmodule
module _DFF_PN1_(D, Q, C, R);
input D, C, R;
output reg Q;
always @(posedge C or negedge R) begin
if (R == 0)
Q <= 1;
else
Q <= D;
end
endmodule
module _DFF_PP0_(D, Q, C, R);
input D, C, R;
output reg Q;
always @(posedge C or posedge R) begin
if (R == 1)
Q <= 0;
else
Q <= D;
end
endmodule
module _DFF_PP1_(D, Q, C, R);
input D, C, R;
output reg Q;
always @(posedge C or posedge R) begin
if (R == 1)
Q <= 1;
else
Q <= D;
end
endmodule

113
manual/FILES_StateOfTheArt/sis-1.3.6-buildfixes.patch Normal file
View File

@ -0,0 +1,113 @@
Some minor build fixes for sis-1.3.6 as it can be downloaded from
http://www-cad.eecs.berkeley.edu/~pchong/sis.html or
http://embedded.eecs.berkeley.edu/Alumni/pchong/sis.html
diff --git a/sis/io/read_kiss.c b/sis/io/read_kiss.c
index 814e526..c862892 100644
--- a/sis/io/read_kiss.c
+++ b/sis/io/read_kiss.c
@@ -10,7 +10,6 @@
#ifdef SIS
#include "sis.h"
-extern void read_error();
extern int read_lineno;
extern char *read_filename;
diff --git a/sis/pld/act_bdd.c b/sis/pld/act_bdd.c
index 4fb4415..a5cd74c 100644
--- a/sis/pld/act_bdd.c
+++ b/sis/pld/act_bdd.c
@@ -141,6 +141,8 @@ char *name;
return p_vertex;
}
+static int compare();
+
/* Or 2 ACT's*/
act_t *
my_or_act_F(array_b,cover, array)
@@ -148,7 +150,6 @@ array_t *array_b;
array_t *array;
sm_row *cover;
{
- static int compare();
int i;
act_t *up_vertex, *down_vertex, *vertex;
sm_element *p;
diff --git a/sis/pld/act_ite.c b/sis/pld/act_ite.c
index a35f2fb..7b824df 100644
--- a/sis/pld/act_ite.c
+++ b/sis/pld/act_ite.c
@@ -125,6 +125,8 @@ node_t *fanin;
and the minimum column cover variables in cover, generates an ite for the
original function. */
+static int compare();
+
ite_vertex *
my_or_ite_F(array_b, cover, array, network)
array_t *array_b;
@@ -132,7 +134,6 @@ array_t *array;
sm_row *cover;
network_t *network;
{
- static int compare();
int i;
ite_vertex *vertex;
sm_element *p;
diff --git a/sis/pld/xln_merge.c b/sis/pld/xln_merge.c
index 075e6c5..16f4d61 100644
--- a/sis/pld/xln_merge.c
+++ b/sis/pld/xln_merge.c
@@ -284,6 +284,7 @@ array_t *match1_array, *match2_array;
}
+static sm_row *xln_merge_find_neighbor_of_row1_with_minimum_neighbors();
/*----------------------------------------------------------------------------------------------------
An alternate to lindo option. Uses greedy merging. A node with minimum mergeable nodes is picked
@@ -296,7 +297,6 @@ xln_merge_nodes_without_lindo(coeff, cand_node_array, match1_array, match2_array
{
node_t *n1, *n2;
sm_row *row1, *row2;
- static sm_row *xln_merge_find_neighbor_of_row1_with_minimum_neighbors();
while (TRUE) {
row1 = sm_shortest_row(coeff);
diff --git a/sis/pld/xln_part_dec.c b/sis/pld/xln_part_dec.c
index 1c856bd..b78828a 100644
--- a/sis/pld/xln_part_dec.c
+++ b/sis/pld/xln_part_dec.c
@@ -49,13 +49,14 @@ int size;
+static int kernel_value();
+
int
split_node(network, node, size)
network_t *network;
node_t *node;
int size;
{
- static int kernel_value();
int i, value = 1;
kern_node *sorted;
divisor_t *div, *best_div;
diff --git a/xsis/Makefile.am b/xsis/Makefile.am
index 196d98b..686fdf4 100644
--- a/xsis/Makefile.am
+++ b/xsis/Makefile.am
@@ -1,8 +1,8 @@
xsis_SOURCES_local = NetPlot.c NetPlot.h NetPlotP.h main.c xastg.c \
xblif.c xcmd.c xhelp.c xsis.c xsis.h xutil.c \
blif50.px ghost.px help50.px sis50.px
-AM_CPPFLAGS = -I../sis/include -I@SIS_X_INCLUDES@
-AM_LDFLAGS = -L@SIS_X_LIBRARIES@
+AM_CPPFLAGS = -I../sis/include
+AM_LDFLAGS =
LDADD = ../sis/libsis.a -lXaw -lXmu -lXt -lXext -lX11 -lm
if SIS_COND_X

64
manual/FILES_StateOfTheArt/synth.sh Executable file
View File

@ -0,0 +1,64 @@
#!/bin/bash
yosys_bin="/usr/local/synthesis/src/yosys/yosys"
hana_bin="/usr/local/synthesis/src/hana/bin/hana"
vl2mv_bin="/usr/local/synthesis/bin/vl2mv"
vis_bin="/usr/local/synthesis/bin/vis"
iverilog_bin="/usr/local/synthesis/bin/iverilog-0.8"
odin_bin="/usr/local/synthesis/src/vtr_release/ODIN_II/odin_II.exe"
abc_bin="/usr/local/synthesis/src/alanmi-abc-b5750272659f/abc"
edif2ngd="/opt/Xilinx/14.3/ISE_DS/ISE/bin/lin64/edif2ngd"
netgen="/opt/Xilinx/14.3/ISE_DS/ISE/bin/lin64/netgen"
all_modes="yosys hana vis icarus odin"
all_sources="always01 always02 always03 arrays01 forgen01 forgen02"
if [ "$*" == "ALL" ]; then
for mode in $all_modes; do
for src in $all_sources; do
echo "synth.sh $mode $src.v ${src}_${mode}.v"
( set -x; bash synth.sh $mode $src.v ${src}_${mode}.v || rm -f ${src}_${mode}.v; ) > ${src}_${mode}.log 2>&1
done
done
exit
fi
mode="$1"
source="$2"
output="$3"
prefix="${output%.v}"
help() {
echo "$0 ALL" >&2
echo "$0 {yosys|hana|vis|icarus|odin} <source-file> <output-file>" >&2
exit 1
}
if [ "$#" != 3 -o ! -f "$source" ]; then
help
fi
set -ex
case "$mode" in
yosys)
$yosys_bin -o $output -b "verilog -noattr" -p proc -p opt -p memory -p opt -p techmap -p opt $source ;;
hana)
$hana_bin -s $output $source ;;
vis)
$vl2mv_bin -o $prefix.mv $source
{ echo "read_blif_mv $prefix.mv"; echo "write_verilog $output"; } | $abc_bin ;;
icarus)
rm -f $prefix.ngo $prefix.v
$iverilog_bin -t fpga -o $prefix.edif $source
$edif2ngd $prefix.edif $prefix.ngo
$netgen -ofmt verilog $prefix.ngo $prefix.v
sed -re '/timescale/ s,^,//,;' -i $prefix.v ;;
odin)
$odin_bin -o $prefix.blif -V $source
sed -re 's,top\^,,g; s,clock,_clock,g;' -i $prefix.blif
{ echo "read_blif $prefix.blif"; echo "write_verilog $output"; } | $abc_bin ;;
*)
help
esac

55
manual/FILES_StateOfTheArt/validate_tb.sh Executable file
View File

@ -0,0 +1,55 @@
#!/bin/bash
set -ex
yosys_bin="/usr/local/synthesis/src/yosys/yosys"
iverilog_bin="iverilog"
all_modes="yosys hana vis icarus odin"
all_sources="always01 always02 always03 arrays01 forgen01 forgen02"
gcc -o cmp_tbdata cmp_tbdata.c
for src in $all_sources; do
echo; echo
$yosys_bin -o ${src}_tb.v -b autotest ${src}.v
$iverilog_bin -o ${src}_tb ${src}_tb.v ${src}.v
./${src}_tb > ${src}_tb.out
for mode in $all_modes; do
simlib=""
[ -f ${src}_${mode}.v ] || continue
[ -f simlib_${mode}.v ] && simlib="simlib_${mode}.v"
if $iverilog_bin -o ${src}_${mode}_tb -s testbench ${src}_tb.v ${src}_${mode}.v $simlib; then
./${src}_${mode}_tb > ${src}_${mode}_tb.out
else
rm -f ${src}_${mode}_tb.out
fi
done
done
set +x
echo; echo; echo
{
for mode in $all_modes; do
echo -en "\t$mode"
done; echo
for src in $all_sources; do
echo -n "$src"
for mode in $all_modes; do
if [ -f ${src}_${mode}.v ]; then
if [ ! -s ${src}_${mode}_tb.out ]; then
echo -en "\tmissing"
elif ./cmp_tbdata ${src}_tb.out ${src}_${mode}_tb.out; then
echo -en "\tok"
else
echo -en "\tfailed"
fi
else
echo -en "\terror"
fi
done; echo
done
} | expand -t12

1135
manual/command-reference-manual.tex Normal file
View File

File diff suppressed because it is too large Load Diff

163
manual/literature.bib Normal file
View File

@ -0,0 +1,163 @@
@inproceedings{intersynth,
title={Example-driven interconnect synthesis for heterogeneous coarse-grain reconfigurable logic},
author={Clifford Wolf and Johann Glaser and Florian Schupfer and Jan Haase and Christoph Grimm},
booktitle={FDL Proceeding of the 2012 Forum on Specification and Design Languages},
pages={194--201},
year={2012}
}
@incollection{intersynthFdlBookChapter,
title={Methodology and Example-Driven Interconnect Synthesis for Designing Heterogeneous Coarse-Grain Reconfigurable Architectures},
author={Johann Glaser and Clifford Wolf},
booktitle={Advances in Models, Methods, and Tools for Complex Chip Design --- Selected contributions from FDL'12},
editor={Jan Haase},
publisher={Springer},
year={2013},
note={to appear}
}
@unpublished{BACC,
author = {Clifford Wolf},
title = {Design and Implementation of the Yosys Open SYnthesis Suite},
note = {Bachelor Thesis, Vienna University of Technology},
year = {2013}
}
@unpublished{VerilogFossEval,
author = {Clifford Wolf},
title = {Evaluation of Open Source Verilog Synthesis Tools for Feature-Completeness and Extensibility},
note = {Unpublished Student Research Paper, Vienna University of Technology},
year = {2012}
}
@article{ABEL,
title={A High-Level Design Language for Programmable Logic Devices},
author={Kyu Y. Lee and Michael Holley and Mary Bailey and Walter Bright},
journal={VLSI Design (Manhasset NY: CPM Publications)},
year={June 1985},
pages={50-62}
}
@MISC{Cheng93vl2mv:a,
author = {S-T Cheng and G York and R K Brayton},
title = {VL2MV: A Compiler from Verilog to BLIF-MV},
year = {1993}
}
@MISC{Odin,
author = {Peter Jamieson and Jonathan Rose},
title = {A VERILOG RTL SYNTHESIS TOOL FOR HETEROGENEOUS FPGAS},
year = {2005}
}
@inproceedings{vtr2012,
title={The VTR Project: Architecture and CAD for FPGAs from Verilog to Routing},
author={Jonathan Rose and Jason Luu and Chi Wai Yu and Opal Densmore and Jeff Goeders and Andrew Somerville and Kenneth B. Kent and Peter Jamieson and Jason Anderson},
booktitle={Proceedings of the 20th ACM/SIGDA International Symposium on Field-Programmable Gate Arrays},
pages={77--86},
year={2012},
organization={ACM}
}
@MISC{LogicSynthesis,
author = {G D Hachtel and F Somenzi},
title = {Logic Synthesis and Verification Algorithms},
year = {1996}
}
@ARTICLE{Verilog2005,
journal={IEEE Std 1364-2005 (Revision of IEEE Std 1364-2001)},
title={IEEE Standard for Verilog Hardware Description Language},
year={2006},
doi={10.1109/IEEESTD.2006.99495}
}
@ARTICLE{VerilogSynth,
journal={IEEE Std 1364.1-2002},
title={IEEE Standard for Verilog Register Transfer Level Synthesis},
year={2002},
doi={10.1109/IEEESTD.2002.94220}
}
@ARTICLE{VHDL,
journal={IEEE Std 1076-2008 (Revision of IEEE Std 1076-2002)}, title={IEEE Standard VHDL Language Reference Manual},
year={2009},
month={26},
doi={10.1109/IEEESTD.2009.4772740}
}
@ARTICLE{VHDLSynth,
journal={IEEE Std 1076.6-2004 (Revision of IEEE Std 1076.6-1999)}, title={IEEE Standard for VHDL Register Transfer Level (RTL) Synthesis},
year={2004},
doi={10.1109/IEEESTD.2004.94802}
}
@ARTICLE{IP-XACT,
journal={IEEE Std 1685-2009}, title={IEEE Standard for IP-XACT, Standard Structure for Packaging, Integrating, and Reusing IP within Tools Flows},
year={2010},
pages={C1-360},
keywords={abstraction definitions, address space specification, bus definitions, design environment, EDA, electronic design automation, electronic system level, ESL, implementation constraints, IP-XACT, register transfer level, RTL, SCRs, semantic consistency rules, TGI, tight generator interface, tool and data interoperability, use models, XML design meta-data, XML schema},
doi={10.1109/IEEESTD.2010.5417309},}
@book{Dragonbook,
author = {Aho, Alfred V. and Sethi, Ravi and Ullman, Jeffrey D.},
title = {Compilers: principles, techniques, and tools},
year = {1986},
isbn = {0-201-10088-6},
publisher = {Addison-Wesley Longman Publishing Co., Inc.},
address = {Boston, MA, USA},
}
@INPROCEEDINGS{Cummings00,
author = {Clifford E. Cummings and Sunburst Design Inc},
title = {Nonblocking Assignments in Verilog Synthesis, Coding Styles That Kill},
booktitle = {SNUG (Synopsys Users Group) 2000 User Papers, section-MC1 (1 st paper},
year = {2000}
}
@ARTICLE{MURPHY,
author={D. L. Klipstein},
journal={Cahners Publishing Co., EEE Magazine, Vol. 15, No. 8},
title={The Contributions of Edsel Murphy to the Understanding of the Behavior of Inanimate Objects},
year={August 1967}
}
@INPROCEEDINGS{fsmextract,
author={Yiqiong Shi and Chan Wai Ting and Bah-Hwee Gwee and Ye Ren},
booktitle={Circuits and Systems (ISCAS), Proceedings of 2010 IEEE International Symposium on},
title={A highly efficient method for extracting FSMs from flattened gate-level netlist},
year={2010},
pages={2610-2613},
keywords={circuit CAD;finite state machines;microcontrollers;FSM;control-intensive circuits;finite state machines;flattened gate-level netlist;state register elimination technique;Automata;Circuit synthesis;Continuous wavelet transforms;Design automation;Digital circuits;Hardware design languages;Logic;Microcontrollers;Registers;Signal processing},
doi={10.1109/ISCAS.2010.5537093},}
@ARTICLE{MultiLevelLogicSynth,
author={Brayton, R.K. and Hachtel, G.D. and Sangiovanni-Vincentelli, A.L.},
journal={Proceedings of the IEEE},
title={Multilevel logic synthesis},
year={1990},
volume={78},
number={2},
pages={264-300},
keywords={circuit layout CAD;integrated logic circuits;logic CAD;capsule summaries;definitions;detailed analysis;in-depth background;logic decomposition;logic minimisation;logic synthesis;logic synthesis techniques;multilevel combinational logic;multilevel logic synthesis;notation;perspective;survey;synthesis methods;technology mapping;testing;Application specific integrated circuits;Design automation;Integrated circuit synthesis;Logic design;Logic devices;Logic testing;Network synthesis;Programmable logic arrays;Signal synthesis;Silicon},
doi={10.1109/5.52213},
ISSN={0018-9219},}
@article{UllmannSubgraphIsomorphism,
author = {Ullmann, J. R.},
title = {An Algorithm for Subgraph Isomorphism},
journal = {J. ACM},
issue_date = {Jan. 1976},
volume = {23},
number = {1},
month = jan,
year = {1976},
issn = {0004-5411},
pages = {31--42},
numpages = {12},
doi = {10.1145/321921.321925},
acmid = {321925},
publisher = {ACM},
address = {New York, NY, USA},
}

22
manual/make.sh Normal file
View File

@ -0,0 +1,22 @@
#!/bin/bash
PDFTEX_OPT="-shell-escape -halt-on-error"
md5sum *.aux *.bbl *.blg > autoloop.old
set -ex
pdflatex $PDFTEX_OPT manual.tex
bibtex manual.aux
bibtex weblink.aux
while
md5sum *.aux *.bbl *.blg > autoloop.new
! cmp autoloop.old autoloop.new
do
cp autoloop.new autoloop.old
pdflatex $PDFTEX_OPT manual.tex
done
rm -f autoloop.old
rm -f autoloop.new

211
manual/manual.tex Normal file
View File

@ -0,0 +1,211 @@
\documentclass[oneside,a4paper]{book}
\usepackage[T1]{fontenc} % required for luximono!
\usepackage{lmodern}
\usepackage[scaled=0.8]{luximono} % typewriter font with bold face
% To install the luximono font files:
% getnonfreefonts-sys --all or
% getnonfreefonts-sys luximono
%
% when there are trouble you might need to:
% - Create /etc/texmf/updmap.d/99local-luximono.cfg
% containing the single line: Map ul9.map
% - Run update-updmap followed by mktexlsr and updmap-sys
%
% This commands must be executed as root with a root environment
% (i.e. run "sudo su" and then execute the commands in the root
% shell, don't just prefix the commands with "sudo").
% formats the text accourding the set language
\usepackage[english]{babel}
\usepackage[table,usenames]{xcolor}
% generates indices with the "\index" command
\usepackage{makeidx}
% enables import of graphics. We use pdflatex here so do the pdf optimisation.
%\usepackage[dvips]{graphicx}
\usepackage[pdftex]{graphicx}
\usepackage{pdfpages}
% includes floating objects like tables and figures.
\usepackage{float}
% for generating subfigures with ohne indented captions
\usepackage[hang]{subfigure}
% redefines and smartens captions of figures and tables (indentation, smaller and boldface)
\usepackage[hang,small,bf,center]{caption}
% enables tabstops and the numeration of lines
\usepackage{moreverb}
% enables user defined header and footer lines (former "fancyheadings")
\usepackage{fancyhdr}
% Some smart mathematical stuff
\usepackage{amsmath}
% Package for rotating several objects
\usepackage{rotating}
\usepackage{natbib}
\usepackage{epsf}
\usepackage{dsfont}
\usepackage[algochapter, boxruled, vlined]{algorithm2e}
%Activating and setting of character protruding - if you like
%\usepackage[activate,DVIoutput]{pdfcprot}
% If you really need special chars...
\usepackage[latin1]{inputenc}
% Hyperlinks
\usepackage[colorlinks,hyperindex,plainpages=false,%
pdftitle={Yosys Manual},%
pdfauthor={Clifford Wolf},%
%pdfkeywords={keyword},%
pdfpagelabels,%
pagebackref,%
bookmarksopen=false%
]{hyperref}
% For the two different reference lists ...
\usepackage{multibib}
\usepackage{multirow}
\usepackage{booktabs}
\usepackage{listings}
\usepackage{pifont}
\usepackage{skull}
% \usepackage{draftwatermark}
\usepackage{tikz}
\usetikzlibrary{calc}
\usetikzlibrary{arrows}
\usetikzlibrary{scopes}
\usetikzlibrary{through}
\usetikzlibrary{shapes.geometric}
\lstset{basicstyle=\ttfamily}
\def\B#1{{\tt\textbackslash{}#1}}
\def\C#1{\lstinline[language=C++]{#1}}
\def\V#1{\lstinline[language=Verilog]{#1}}
\newsavebox{\fixmebox}
\newenvironment{fixme}%
{\newcommand\colboxcolor{FFBBBB}%
\begin{lrbox}{\fixmebox}%
\begin{minipage}{\dimexpr\columnwidth-2\fboxsep\relax}}
{\end{minipage}\end{lrbox}\textbf{FIXME: }\\%
\colorbox[HTML]{\colboxcolor}{\usebox{\fixmebox}}}
\newcites{weblink}{Internet References}
\setcounter{secnumdepth}{3}
\makeindex
\setlength{\oddsidemargin}{4mm}
\setlength{\evensidemargin}{-6mm}
\setlength{\textwidth}{162mm}
\setlength{\textheight}{230mm}
\setlength{\topmargin}{-5mm}
\setlength{\parskip}{1.5ex plus 1ex minus 0.5ex}
\setlength{\parindent}{0pt}
\begin{document}
\fancypagestyle{mypagestyle}{%
\fancyhf{}%
\fancyhead[C]{\leftmark}%
\fancyfoot[C]{\thepage}%
\renewcommand{\headrulewidth}{0pt}%
\renewcommand{\footrulewidth}{0pt}}
\pagestyle{mypagestyle}
\thispagestyle{empty}
\null\vfil
\begin{center}
\bf\Huge Yosys Manual
\bigskip
\large Clifford Wolf
\end{center}
\vfil\null
\eject
\chapter*{Abstract}
Most of todays digital design is done in HDL code (mostly Verilog or VHDL) and
with the help of HDL synthesis tools.
In special cases such as synthesis for coarse-grain cell libraries or when
testing new synthesis algorithms it might be neccessary to write a custom HDL
synthesis tool or add new features to an existing one. It this cases the
availability of a Free and Open Source (FOSS) synthesis tool that can be used
as basis for custom tools would be helpful.
In the absence of such a tool, the Yosys Open SYnthesis Suite (Yosys) was
developped. This document covers the design and implementation of this tool.
At the moment the main focus of Yosys lies on the high-level aspects of
digital synthesis. The pre-existing FOSS logic-synthesis tool ABC is used
by Yosys to perform advanced gate-level optimizations.
An evaluation of Yosys based on real-world designs is included. It is shown
that Yosys can be used as-is to synthesize such designs. The results produced
by Yosys in this tests where successflly verified using formal verification
and are compareable in quality to the results produced by a commercial
synthesis tool.
\bigskip
This document was originally published as bachelor thesis at the Vienna
University of Technology \cite{BACC}.
\chapter*{Abbreviations}
\begin{tabular}{ll}
AIG & And-Inverter-Graph \\
ASIC & Application-Specific Integrated Circuit \\
AST & Abstract Syntax Tree \\
BDD & Binary Decicion Diagram \\
BLIF & Berkeley Logic Interchange Format \\
EDA & Electronic Design Automation \\
EDIF & Electronic Design Interchange Format \\
ER Diagram & Entity-Relationship Diagram \\
FOSS & Free and Open-Source Software \\
FPGA & Field-Programmable Gate Array \\
FSM & Finite-state machine \\
HDL & Hardware Description Language \\
LPM & Library of Parameterized Modules \\
RTLIL & RTL Intermediate Language \\
RTL & Register Transfer Level \\
SAT & Satisfiability Problem \\
% SSA & Static Single Assignment Form \\
VHDL & VHSIC Hardware Description Language \\
VHSIC & Very-High-Speed Integrated Circuit \\
YOSYS & Yosys Open SYnthesis Suite \\
\end{tabular}
\tableofcontents
\include{CHAPTER_Intro}
\include{CHAPTER_Basics}
\include{CHAPTER_Approach}
\include{CHAPTER_Overview}
\include{CHAPTER_CellLib}
\include{CHAPTER_Prog}
\include{CHAPTER_Verilog}
\include{CHAPTER_Optimize}
\include{CHAPTER_Techmap}
\include{CHAPTER_Eval}
\appendix
\include{CHAPTER_Auxlibs}
\include{CHAPTER_Auxprogs}
\chapter{Command Reference Manual}
\label{commandref}
\input{command-reference-manual}
\include{CHAPTER_Appnotes}
\include{CHAPTER_StateOfTheArt}
\bibliography{literature}
\bibliographystyle{alphadin}
\bibliographyweblink{weblinks}
\bibliographystyleweblink{abbrv}
\end{document}

140
manual/weblinks.bib Normal file
View File

@ -0,0 +1,140 @@
@misc{YosysGit,
author = {Clifford Wolf},
title = {{Yosys Open SYnthesis Suite (YOSYS)}},
note = {\url{http://github.com/cliffordwolf/yosys}}
}
@misc{YosysTestsGit,
author = {Clifford Wolf},
title = {{Yosys Test Bench}},
note = {\url{http://github.com/cliffordwolf/yosys-tests}}
}
@misc{VlogHammer,
author = {Clifford Wolf},
title = {{VlogHammer Verilog Synthesis Regression Tests}},
note = {\url{http://github.com/cliffordwolf/VlogHammer}}
}
@misc{Icarus,
author = {Stephen Williams},
title = {{Icarus Verilog}},
note = {Version 0.8.7, \url{http://iverilog.icarus.com/}}
}
@misc{VTR,
author= {Jonathan Rose and Jason Luu and Chi Wai Yu and Opal Densmore and Jeff Goeders and Andrew Somerville and Kenneth B. Kent and Peter Jamieson and Jason Anderson},
title = {{The Verilog-to-Routing (VTR) Project for FPGAs}},
note = {Version 1.0, \url{https://code.google.com/p/vtr-verilog-to-routing/}}
}
@misc{HANA,
author = {Parvez Ahmad},
title = {{HDL Analyzer and Netlist Architect (HANA)}},
note = {Verison linux64-1.0-alpha (2012-10-14), \url{http://sourceforge.net/projects/sim-sim/}}
}
@misc{MVSIS,
author = {MVSIS group at Berkeley studies logic synthesis and verification for VLSI design},
title = {{MVSIS: Logic Synthesis and Verification}},
note = {Version 3.0, \url{http://embedded.eecs.berkeley.edu/mvsis/}}
}
@misc{VIS,
author = {{The VIS group}},
title = {{VIS: A system for Verification and Synthesis}},
note = {Version 2.4, \url{http://vlsi.colorado.edu/~vis/}}
}
@misc{ABC,
author = {{Berkeley Logic Synthesis and Verification Group}},
title = {{ABC: A System for Sequential Synthesis and Verification}},
note = {HQ Rev b5750272659f, 2012-10-28, \url{http://www.eecs.berkeley.edu/~alanmi/abc/}}
}
@misc{AIGER,
author = {{Armin Biere, Johannes Kepler University Linz, Austria}},
title = {{AIGER}},
note = {\url{http://fmv.jku.at/aiger/}}
}
@misc{XilinxWebPACK,
author = {{Xilinx, Inc.}},
title = {{ISE WebPACK Design Software}},
note = {\url{http://www.xilinx.com/products/design-tools/ise-design-suite/ise-webpack.htm}}
}
@misc{QuartusWeb,
author = {{Altera, Inc.}},
title = {{Quartus II Web Edition Software}},
note = {\url{http://www.altera.com/products/software/quartus-ii/web-edition/qts-we-index.html}}
}
@misc{OR1200,
title = {{OpenRISC 1200 CPU}},
note = {\url{http://opencores.org/or1k/OR1200\_OpenRISC\_Processor}}
}
@misc{openMSP430,
title = {{openMSP430 CPU}},
note = {\url{http://opencores.org/project,openmsp430}}
}
@misc{i2cmaster,
title = {{OpenCores I$^2$C Core}},
note = {\url{http://opencores.org/project,i2c}}
}
@misc{k68,
title = {{OpenCores k68 Core}},
note = {\url{http://opencores.org/project,k68}}
}
@misc{bison,
title = {{GNU Bison}},
note = {\url{http://www.gnu.org/software/bison/}}
}
@misc{flex,
title = {{Flex}},
note = {\url{http://flex.sourceforge.net/}}
}
@misc{C_to_Verilog,
title = {{C-to-Verilog}},
note = {\url{http://www.c-to-verilog.com/}}
}
@misc{LegUp,
title = {{LegUp}},
note = {\url{http://legup.eecg.utoronto.ca/}}
}
@misc{LibertyFormat,
title = {{The Liberty Library Modeling Standard}},
note = {\url{http://www.opensourceliberty.org/}}
}
@misc{ASIC-WORLD,
title = {{World of ASIC}},
note = {\url{http://www.asic-world.com/}}
}
@misc{Formality,
title = {{Synopsys Formality Equivalence Checking}},
note = {\url{http://www.synopsys.com/Tools/Verification/FormalEquivalence/Pages/Formality.aspx}},
}
@misc{bigint,
author = {Matt McCutchen},
title = {{C++ Big Integer Library}},
note = {\url{http://mattmccutchen.net/bigint/}}
}
@misc{smallsha1,
author = {Micael Hildenborg},
title = {{smallsha1}},
note = {\url{https://code.google.com/p/smallsha1/}}
}