diff options
Diffstat (limited to 'manual')
47 files changed, 7944 insertions, 0 deletions
diff --git a/manual/.gitignore b/manual/.gitignore new file mode 100644 index 00000000..15063c48 --- /dev/null +++ b/manual/.gitignore @@ -0,0 +1,8 @@ +*.aux +*.bbl +*.blg +*.idx +*.log +*.out +*.pdf +*.toc diff --git a/manual/CHAPTER_Appnotes.tex b/manual/CHAPTER_Appnotes.tex new file mode 100644 index 00000000..959aabd2 --- /dev/null +++ b/manual/CHAPTER_Appnotes.tex @@ -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} + diff --git a/manual/CHAPTER_Approach.tex b/manual/CHAPTER_Approach.tex new file mode 100644 index 00000000..a2c40bea --- /dev/null +++ b/manual/CHAPTER_Approach.tex @@ -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}. + diff --git a/manual/CHAPTER_Auxlibs.tex b/manual/CHAPTER_Auxlibs.tex new file mode 100644 index 00000000..0726e031 --- /dev/null +++ b/manual/CHAPTER_Auxlibs.tex @@ -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}). + diff --git a/manual/CHAPTER_Auxprogs.tex b/manual/CHAPTER_Auxprogs.tex new file mode 100644 index 00000000..eefd3697 --- /dev/null +++ b/manual/CHAPTER_Auxprogs.tex @@ -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. + diff --git a/manual/CHAPTER_Basics.tex b/manual/CHAPTER_Basics.tex new file mode 100644 index 00000000..9cc4720e --- /dev/null +++ b/manual/CHAPTER_Basics.tex @@ -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 + diff --git a/manual/CHAPTER_CellLib.tex b/manual/CHAPTER_CellLib.tex new file mode 100644 index 00000000..b4f98812 --- /dev/null +++ b/manual/CHAPTER_CellLib.tex @@ -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. + diff --git a/manual/CHAPTER_Eval.tex b/manual/CHAPTER_Eval.tex new file mode 100644 index 00000000..c27a000b --- /dev/null +++ b/manual/CHAPTER_Eval.tex @@ -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. + diff --git a/manual/CHAPTER_Intro.tex b/manual/CHAPTER_Intro.tex new file mode 100644 index 00000000..675d2402 --- /dev/null +++ b/manual/CHAPTER_Intro.tex @@ -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. + + diff --git a/manual/CHAPTER_Optimize.tex b/manual/CHAPTER_Optimize.tex new file mode 100644 index 00000000..c562650b --- /dev/null +++ b/manual/CHAPTER_Optimize.tex @@ -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). + diff --git a/manual/CHAPTER_Overview.tex b/manual/CHAPTER_Overview.tex new file mode 100644 index 00000000..40deabfa --- /dev/null +++ b/manual/CHAPTER_Overview.tex @@ -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. + diff --git a/manual/CHAPTER_Prog.tex b/manual/CHAPTER_Prog.tex new file mode 100644 index 00000000..a1ca383d --- /dev/null +++ b/manual/CHAPTER_Prog.tex @@ -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} + diff --git a/manual/CHAPTER_StateOfTheArt.tex b/manual/CHAPTER_StateOfTheArt.tex new file mode 100644 index 00000000..d6a5c9b1 --- /dev/null +++ b/manual/CHAPTER_StateOfTheArt.tex @@ -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} + diff --git a/manual/CHAPTER_Techmap.tex b/manual/CHAPTER_Techmap.tex new file mode 100644 index 00000000..6a84864e --- /dev/null +++ b/manual/CHAPTER_Techmap.tex @@ -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. + diff --git a/manual/CHAPTER_Verilog.tex b/manual/CHAPTER_Verilog.tex new file mode 100644 index 00000000..80f55a25 --- /dev/null +++ b/manual/CHAPTER_Verilog.tex @@ -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} + diff --git a/manual/FILES_Eval/grep-it.sh b/manual/FILES_Eval/grep-it.sh new file mode 100644 index 00000000..f92eb52c --- /dev/null +++ b/manual/FILES_Eval/grep-it.sh @@ -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 + diff --git a/manual/FILES_Eval/openmsp430.prj b/manual/FILES_Eval/openmsp430.prj new file mode 100644 index 00000000..cb8cd271 --- /dev/null +++ b/manual/FILES_Eval/openmsp430.prj @@ -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" diff --git a/manual/FILES_Eval/openmsp430_ys.prj b/manual/FILES_Eval/openmsp430_ys.prj new file mode 100644 index 00000000..0009c99d --- /dev/null +++ b/manual/FILES_Eval/openmsp430_ys.prj @@ -0,0 +1 @@ +verilog work "openmsp430_ys.v" diff --git a/manual/FILES_Eval/or1200.prj b/manual/FILES_Eval/or1200.prj new file mode 100644 index 00000000..9496874e --- /dev/null +++ b/manual/FILES_Eval/or1200.prj @@ -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" diff --git a/manual/FILES_Eval/or1200_ys.prj b/manual/FILES_Eval/or1200_ys.prj new file mode 100644 index 00000000..4dd5f41a --- /dev/null +++ b/manual/FILES_Eval/or1200_ys.prj @@ -0,0 +1 @@ +verilog work "or1200_ys.v" diff --git a/manual/FILES_Eval/run-it.sh b/manual/FILES_Eval/run-it.sh new file mode 100644 index 00000000..b4a67ceb --- /dev/null +++ b/manual/FILES_Eval/run-it.sh @@ -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 + diff --git a/manual/FILES_Eval/settings.xst b/manual/FILES_Eval/settings.xst new file mode 100644 index 00000000..2f381d09 --- /dev/null +++ b/manual/FILES_Eval/settings.xst @@ -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 diff --git a/manual/FILES_Prog/Makefile b/manual/FILES_Prog/Makefile new file mode 100644 index 00000000..d7358188 --- /dev/null +++ b/manual/FILES_Prog/Makefile @@ -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 + diff --git a/manual/FILES_Prog/stubnets.cc b/manual/FILES_Prog/stubnets.cc new file mode 100644 index 00000000..00eab1b1 --- /dev/null +++ b/manual/FILES_Prog/stubnets.cc @@ -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; + diff --git a/manual/FILES_Prog/test.v b/manual/FILES_Prog/test.v new file mode 100644 index 00000000..201f7500 --- /dev/null +++ b/manual/FILES_Prog/test.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/always01.v b/manual/FILES_StateOfTheArt/always01.v new file mode 100644 index 00000000..4719ed47 --- /dev/null +++ b/manual/FILES_StateOfTheArt/always01.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/always01_pub.v b/manual/FILES_StateOfTheArt/always01_pub.v new file mode 100644 index 00000000..6a6a4b23 --- /dev/null +++ b/manual/FILES_StateOfTheArt/always01_pub.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/always02.v b/manual/FILES_StateOfTheArt/always02.v new file mode 100644 index 00000000..63f1ce31 --- /dev/null +++ b/manual/FILES_StateOfTheArt/always02.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/always02_pub.v b/manual/FILES_StateOfTheArt/always02_pub.v new file mode 100644 index 00000000..91f1ca16 --- /dev/null +++ b/manual/FILES_StateOfTheArt/always02_pub.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/always03.v b/manual/FILES_StateOfTheArt/always03.v new file mode 100644 index 00000000..53386acd --- /dev/null +++ b/manual/FILES_StateOfTheArt/always03.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/arrays01.v b/manual/FILES_StateOfTheArt/arrays01.v new file mode 100644 index 00000000..bd0eda29 --- /dev/null +++ b/manual/FILES_StateOfTheArt/arrays01.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/cmp_tbdata.c b/manual/FILES_StateOfTheArt/cmp_tbdata.c new file mode 100644 index 00000000..b188144d --- /dev/null +++ b/manual/FILES_StateOfTheArt/cmp_tbdata.c @@ -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; +} + diff --git a/manual/FILES_StateOfTheArt/forgen01.v b/manual/FILES_StateOfTheArt/forgen01.v new file mode 100644 index 00000000..70ee7e66 --- /dev/null +++ b/manual/FILES_StateOfTheArt/forgen01.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/forgen02.v b/manual/FILES_StateOfTheArt/forgen02.v new file mode 100644 index 00000000..14af070c --- /dev/null +++ b/manual/FILES_StateOfTheArt/forgen02.v @@ -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 diff --git a/manual/FILES_StateOfTheArt/iverilog-0.8.7-buildfixes.patch b/manual/FILES_StateOfTheArt/iverilog-0.8.7-buildfixes.patch new file mode 100644 index 00000000..63a03e59 --- /dev/null +++ b/manual/FILES_StateOfTheArt/iverilog-0.8.7-buildfixes.patch @@ -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 diff --git a/manual/FILES_StateOfTheArt/mvsis-1.3.6-buildfixes.patch b/manual/FILES_StateOfTheArt/mvsis-1.3.6-buildfixes.patch new file mode 100644 index 00000000..4b44320f --- /dev/null +++ b/manual/FILES_StateOfTheArt/mvsis-1.3.6-buildfixes.patch @@ -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 ); diff --git a/manual/FILES_StateOfTheArt/simlib_hana.v b/manual/FILES_StateOfTheArt/simlib_hana.v new file mode 100644 index 00000000..fc82f138 --- /dev/null +++ b/manual/FILES_StateOfTheArt/simlib_hana.v @@ -0,0 +1,1139 @@ +/* +Copyright (C) 2009-2010 Parvez Ahmad +Written by Parvez Ahmad <parvez_ahmad@yahoo.co.uk>. + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see <http://www.gnu.org/licenses/>. */ + + +module BUF (input in, output out); + +assign out = in; + +endmodule + +module TRIBUF(input in, enable, output out); + +assign out = enable ? in : 1'bz; + +endmodule + +module INV(input in, output out); + +assign out = ~in; + +endmodule + +module AND2 #(parameter SIZE = 2) (input [SIZE-1:0] in, output out); + +assign out = ∈ + +endmodule + +module AND3 #(parameter SIZE = 3) (input [SIZE-1:0] in, output out); + +assign out = ∈ + +endmodule + +module AND4 #(parameter SIZE = 4) (input [SIZE-1:0] in, output out); + +assign out = ∈ + +endmodule + +module OR2 #(parameter SIZE = 2) (input [SIZE-1:0] in, output out); + +assign out = |in; + +endmodule + +module OR3 #(parameter SIZE = 3) (input [SIZE-1:0] in, output out); + +assign out = |in; + +endmodule + +module OR4 #(parameter SIZE = 4) (input [SIZE-1:0] in, output out); + +assign out = |in; + +endmodule + + +module NAND2 #(parameter SIZE = 2) (input [SIZE-1:0] in, output out); + +assign out = ~∈ + +endmodule + +module NAND3 #(parameter SIZE = 3) (input [SIZE-1:0] in, output out); + +assign out = ~∈ + +endmodule + +module NAND4 #(parameter SIZE = 4) (input [SIZE-1:0] in, output out); + +assign out = ~∈ + +endmodule + +module NOR2 #(parameter SIZE = 2) (input [SIZE-1:0] in, output out); + +assign out = ~|in; + +endmodule + +module NOR3 #(parameter SIZE = 3) (input [SIZE-1:0] in, output out); + +assign out = ~|in; + +endmodule + +module NOR4 #(parameter SIZE = 4) (input [SIZE-1:0] in, output out); + +assign out = ~|in; + +endmodule + + +module XOR2 #(parameter SIZE = 2) (input [SIZE-1:0] in, output out); + +assign out = ^in; + +endmodule + +module XOR3 #(parameter SIZE = 3) (input [SIZE-1:0] in, output out); + +assign out = ^in; + +endmodule + +module XOR4 #(parameter SIZE = 4) (input [SIZE-1:0] in, output out); + +assign out = ^in; + +endmodule + + +module XNOR2 #(parameter SIZE = 2) (input [SIZE-1:0] in, output out); + +assign out = ~^in; + +endmodule + +module XNOR3 #(parameter SIZE = 3) (input [SIZE-1:0] in, output out); + +assign out = ~^in; + +endmodule + +module XNOR4 #(parameter SIZE = 4) (input [SIZE-1:0] in, output out); + +assign out = ~^in; + +endmodule + +module DEC1 (input in, enable, output reg [1:0] out); + +always @(in or enable) + if(!enable) + out = 2'b00; + else begin + case (in) + 1'b0 : out = 2'b01; + 1'b1 : out = 2'b10; + endcase + end +endmodule + +module DEC2 (input [1:0] in, input enable, output reg [3:0] out); + +always @(in or enable) + if(!enable) + out = 4'b0000; + else begin + case (in) + 2'b00 : out = 4'b0001; + 2'b01 : out = 4'b0010; + 2'b10 : out = 4'b0100; + 2'b11 : out = 4'b1000; + endcase + end +endmodule + +module DEC3 (input [2:0] in, input enable, output reg [7:0] out); + +always @(in or enable) + if(!enable) + out = 8'b00000000; + else begin + case (in) + 3'b000 : out = 8'b00000001; + 3'b001 : out = 8'b00000010; + 3'b010 : out = 8'b00000100; + 3'b011 : out = 8'b00001000; + 3'b100 : out = 8'b00010000; + 3'b101 : out = 8'b00100000; + 3'b110 : out = 8'b01000000; + 3'b111 : out = 8'b10000000; + endcase + end +endmodule + +module DEC4 (input [3:0] in, input enable, output reg [15:0] out); + +always @(in or enable) + if(!enable) + out = 16'b0000000000000000; + else begin + case (in) + 4'b0000 : out = 16'b0000000000000001; + 4'b0001 : out = 16'b0000000000000010; + 4'b0010 : out = 16'b0000000000000100; + 4'b0011 : out = 16'b0000000000001000; + 4'b0100 : out = 16'b0000000000010000; + 4'b0101 : out = 16'b0000000000100000; + 4'b0110 : out = 16'b0000000001000000; + 4'b0111 : out = 16'b0000000010000000; + 4'b1000 : out = 16'b0000000100000000; + 4'b1001 : out = 16'b0000001000000000; + 4'b1010 : out = 16'b0000010000000000; + 4'b1011 : out = 16'b0000100000000000; + 4'b1100 : out = 16'b0001000000000000; + 4'b1101 : out = 16'b0010000000000000; + 4'b1110 : out = 16'b0100000000000000; + 4'b1111 : out = 16'b1000000000000000; + endcase + end +endmodule +module DEC5 (input [4:0] in, input enable, output reg [31:0] out); + +always @(in or enable) + if(!enable) + out = 32'b00000000000000000000000000000000; + else begin + case (in) + 5'b00000 : out = 32'b00000000000000000000000000000001; + 5'b00001 : out = 32'b00000000000000000000000000000010; + 5'b00010 : out = 32'b00000000000000000000000000000100; + 5'b00011 : out = 32'b00000000000000000000000000001000; + 5'b00100 : out = 32'b00000000000000000000000000010000; + 5'b00101 : out = 32'b00000000000000000000000000100000; + 5'b00110 : out = 32'b00000000000000000000000001000000; + 5'b00111 : out = 32'b00000000000000000000000010000000; + 5'b01000 : out = 32'b00000000000000000000000100000000; + 5'b01001 : out = 32'b00000000000000000000001000000000; + 5'b01010 : out = 32'b00000000000000000000010000000000; + 5'b01011 : out = 32'b00000000000000000000100000000000; + 5'b01100 : out = 32'b00000000000000000001000000000000; + 5'b01101 : out = 32'b00000000000000000010000000000000; + 5'b01110 : out = 32'b00000000000000000100000000000000; + 5'b01111 : out = 32'b00000000000000001000000000000000; + 5'b10000 : out = 32'b00000000000000010000000000000000; + 5'b10001 : out = 32'b00000000000000100000000000000000; + 5'b10010 : out = 32'b00000000000001000000000000000000; + 5'b10011 : out = 32'b00000000000010000000000000000000; + 5'b10100 : out = 32'b00000000000100000000000000000000; + 5'b10101 : out = 32'b00000000001000000000000000000000; + 5'b10110 : out = 32'b00000000010000000000000000000000; + 5'b10111 : out = 32'b00000000100000000000000000000000; + 5'b11000 : out = 32'b00000001000000000000000000000000; + 5'b11001 : out = 32'b00000010000000000000000000000000; + 5'b11010 : out = 32'b00000100000000000000000000000000; + 5'b11011 : out = 32'b00001000000000000000000000000000; + 5'b11100 : out = 32'b00010000000000000000000000000000; + 5'b11101 : out = 32'b00100000000000000000000000000000; + 5'b11110 : out = 32'b01000000000000000000000000000000; + 5'b11111 : out = 32'b10000000000000000000000000000000; + endcase + end +endmodule + +module DEC6 (input [5:0] in, input enable, output reg [63:0] out); + +always @(in or enable) + if(!enable) + out = 64'b0000000000000000000000000000000000000000000000000000000000000000; + else begin + case (in) + 6'b000000 : out = 64'b0000000000000000000000000000000000000000000000000000000000000001; + 6'b000001 : out = 64'b0000000000000000000000000000000000000000000000000000000000000010; + 6'b000010 : out = 64'b0000000000000000000000000000000000000000000000000000000000000100; + 6'b000011 : out = 64'b0000000000000000000000000000000000000000000000000000000000001000; + 6'b000100 : out = 64'b0000000000000000000000000000000000000000000000000000000000010000; + 6'b000101 : out = 64'b0000000000000000000000000000000000000000000000000000000000100000; + 6'b000110 : out = 64'b0000000000000000000000000000000000000000000000000000000001000000; + 6'b000111 : out = 64'b0000000000000000000000000000000000000000000000000000000010000000; + 6'b001000 : out = 64'b0000000000000000000000000000000000000000000000000000000100000000; + 6'b001001 : out = 64'b0000000000000000000000000000000000000000000000000000001000000000; + 6'b001010 : out = 64'b0000000000000000000000000000000000000000000000000000010000000000; + 6'b001011 : out = 64'b0000000000000000000000000000000000000000000000000000100000000000; + 6'b001100 : out = 64'b0000000000000000000000000000000000000000000000000001000000000000; + 6'b001101 : out = 64'b0000000000000000000000000000000000000000000000000010000000000000; + 6'b001110 : out = 64'b0000000000000000000000000000000000000000000000000100000000000000; + 6'b001111 : out = 64'b0000000000000000000000000000000000000000000000001000000000000000; + 6'b010000 : out = 64'b0000000000000000000000000000000000000000000000010000000000000000; + 6'b010001 : out = 64'b0000000000000000000000000000000000000000000000100000000000000000; + 6'b010010 : out = 64'b0000000000000000000000000000000000000000000001000000000000000000; + 6'b010011 : out = 64'b0000000000000000000000000000000000000000000010000000000000000000; + 6'b010100 : out = 64'b0000000000000000000000000000000000000000000100000000000000000000; + 6'b010101 : out = 64'b0000000000000000000000000000000000000000001000000000000000000000; + 6'b010110 : out = 64'b0000000000000000000000000000000000000000010000000000000000000000; + 6'b010111 : out = 64'b0000000000000000000000000000000000000000100000000000000000000000; + 6'b011000 : out = 64'b0000000000000000000000000000000000000001000000000000000000000000; + 6'b011001 : out = 64'b0000000000000000000000000000000000000010000000000000000000000000; + 6'b011010 : out = 64'b0000000000000000000000000000000000000100000000000000000000000000; + 6'b011011 : out = 64'b0000000000000000000000000000000000001000000000000000000000000000; + 6'b011100 : out = 64'b0000000000000000000000000000000000010000000000000000000000000000; + 6'b011101 : out = 64'b0000000000000000000000000000000000100000000000000000000000000000; + 6'b011110 : out = 64'b0000000000000000000000000000000001000000000000000000000000000000; + 6'b011111 : out = 64'b0000000000000000000000000000000010000000000000000000000000000000; + + 6'b100000 : out = 64'b0000000000000000000000000000000100000000000000000000000000000000; + 6'b100001 : out = 64'b0000000000000000000000000000001000000000000000000000000000000000; + 6'b100010 : out = 64'b0000000000000000000000000000010000000000000000000000000000000000; + 6'b100011 : out = 64'b0000000000000000000000000000100000000000000000000000000000000000; + 6'b100100 : out = 64'b0000000000000000000000000001000000000000000000000000000000000000; + 6'b100101 : out = 64'b0000000000000000000000000010000000000000000000000000000000000000; + 6'b100110 : out = 64'b0000000000000000000000000100000000000000000000000000000000000000; + 6'b100111 : out = 64'b0000000000000000000000001000000000000000000000000000000000000000; + 6'b101000 : out = 64'b0000000000000000000000010000000000000000000000000000000000000000; + 6'b101001 : out = 64'b0000000000000000000000100000000000000000000000000000000000000000; + 6'b101010 : out = 64'b0000000000000000000001000000000000000000000000000000000000000000; + 6'b101011 : out = 64'b0000000000000000000010000000000000000000000000000000000000000000; + 6'b101100 : out = 64'b0000000000000000000100000000000000000000000000000000000000000000; + 6'b101101 : out = 64'b0000000000000000001000000000000000000000000000000000000000000000; + 6'b101110 : out = 64'b0000000000000000010000000000000000000000000000000000000000000000; + 6'b101111 : out = 64'b0000000000000000100000000000000000000000000000000000000000000000; + 6'b110000 : out = 64'b0000000000000001000000000000000000000000000000000000000000000000; + 6'b110001 : out = 64'b0000000000000010000000000000000000000000000000000000000000000000; + 6'b110010 : out = 64'b0000000000000100000000000000000000000000000000000000000000000000; + 6'b110011 : out = 64'b0000000000001000000000000000000000000000000000000000000000000000; + 6'b110100 : out = 64'b0000000000010000000000000000000000000000000000000000000000000000; + 6'b110101 : out = 64'b0000000000100000000000000000000000000000000000000000000000000000; + 6'b110110 : out = 64'b0000000001000000000000000000000000000000000000000000000000000000; + 6'b110111 : out = 64'b0000000010000000000000000000000000000000000000000000000000000000; + 6'b111000 : out = 64'b0000000100000000000000000000000000000000000000000000000000000000; + 6'b111001 : out = 64'b0000001000000000000000000000000000000000000000000000000000000000; + 6'b111010 : out = 64'b0000010000000000000000000000000000000000000000000000000000000000; + 6'b111011 : out = 64'b0000100000000000000000000000000000000000000000000000000000000000; + 6'b111100 : out = 64'b0001000000000000000000000000000000000000000000000000000000000000; + 6'b111101 : out = 64'b0010000000000000000000000000000000000000000000000000000000000000; + 6'b111110 : out = 64'b0100000000000000000000000000000000000000000000000000000000000000; + 6'b111111 : out = 64'b1000000000000000000000000000000000000000000000000000000000000000; + endcase + end +endmodule + + +module MUX2(input [1:0] in, input select, output reg out); + +always @( in or select) + case (select) + 0: out = in[0]; + 1: out = in[1]; + endcase +endmodule + + +module MUX4(input [3:0] in, input [1:0] select, output reg out); + +always @( in or select) + case (select) + 0: out = in[0]; + 1: out = in[1]; + 2: out = in[2]; + 3: out = in[3]; + endcase +endmodule + + +module MUX8(input [7:0] in, input [2:0] select, output reg out); + +always @( in or select) + case (select) + 0: out = in[0]; + 1: out = in[1]; + 2: out = in[2]; + 3: out = in[3]; + 4: out = in[4]; + 5: out = in[5]; + 6: out = in[6]; + 7: out = in[7]; + endcase +endmodule + +module MUX16(input [15:0] in, input [3:0] select, output reg out); + +always @( in or select) + case (select) + 0: out = in[0]; + 1: out = in[1]; + 2: out = in[2]; + 3: out = in[3]; + 4: out = in[4]; + 5: out = in[5]; + 6: out = in[6]; + 7: out = in[7]; + 8: out = in[8]; + 9: out = in[9]; + 10: out = in[10]; + 11: out = in[11]; + 12: out = in[12]; + 13: out = in[13]; + 14: out = in[14]; + 15: out = in[15]; + endcase +endmodule + +module MUX32(input [31:0] in, input [4:0] select, output reg out); + +always @( in or select) + case (select) + 0: out = in[0]; + 1: out = in[1]; + 2: out = in[2]; + 3: out = in[3]; + 4: out = in[4]; + 5: out = in[5]; + 6: out = in[6]; + 7: out = in[7]; + 8: out = in[8]; + 9: out = in[9]; + 10: out = in[10]; + 11: out = in[11]; + 12: out = in[12]; + 13: out = in[13]; + 14: out = in[14]; + 15: out = in[15]; + 16: out = in[16]; + 17: out = in[17]; + 18: out = in[18]; + 19: out = in[19]; + 20: out = in[20]; + 21: out = in[21]; + 22: out = in[22]; + 23: out = in[23]; + 24: out = in[24]; + 25: out = in[25]; + 26: out = in[26]; + 27: out = in[27]; + 28: out = in[28]; + 29: out = in[29]; + 30: out = in[30]; + 31: out = in[31]; + endcase +endmodule + +module MUX64(input [63:0] in, input [5:0] select, output reg out); + +always @( in or select) + case (select) + 0: out = in[0]; + 1: out = in[1]; + 2: out = in[2]; + 3: out = in[3]; + 4: out = in[4]; + 5: out = in[5]; + 6: out = in[6]; + 7: out = in[7]; + 8: out = in[8]; + 9: out = in[9]; + 10: out = in[10]; + 11: out = in[11]; + 12: out = in[12]; + 13: out = in[13]; + 14: out = in[14]; + 15: out = in[15]; + 16: out = in[16]; + 17: out = in[17]; + 18: out = in[18]; + 19: out = in[19]; + 20: out = in[20]; + 21: out = in[21]; + 22: out = in[22]; + 23: out = in[23]; + 24: out = in[24]; + 25: out = in[25]; + 26: out = in[26]; + 27: out = in[27]; + 28: out = in[28]; + 29: out = in[29]; + 30: out = in[30]; + 31: out = in[31]; + 32: out = in[32]; + 33: out = in[33]; + 34: out = in[34]; + 35: out = in[35]; + 36: out = in[36]; + 37: out = in[37]; + 38: out = in[38]; + 39: out = in[39]; + 40: out = in[40]; + 41: out = in[41]; + 42: out = in[42]; + 43: out = in[43]; + 44: out = in[44]; + 45: out = in[45]; + 46: out = in[46]; + 47: out = in[47]; + 48: out = in[48]; + 49: out = in[49]; + 50: out = in[50]; + 51: out = in[51]; + 52: out = in[52]; + 53: out = in[53]; + 54: out = in[54]; + 55: out = in[55]; + 56: out = in[56]; + 57: out = in[57]; + 58: out = in[58]; + 59: out = in[59]; + 60: out = in[60]; + 61: out = in[61]; + 62: out = in[62]; + 63: out = in[63]; + endcase +endmodule + +module ADD1(input in1, in2, cin, output out, cout); + +assign {cout, out} = in1 + in2 + cin; + +endmodule + +module ADD2 #(parameter SIZE = 2)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 + in2 + cin; + +endmodule + +module ADD4 #(parameter SIZE = 4)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 + in2 + cin; + +endmodule + +module ADD8 #(parameter SIZE = 8)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 + in2 + cin; + +endmodule + +module ADD16 #(parameter SIZE = 16)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 + in2 + cin; + +endmodule + +module ADD32 #(parameter SIZE = 32)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 + in2 + cin; + +endmodule +module ADD64 #(parameter SIZE = 64)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 + in2 + cin; + +endmodule + +module SUB1(input in1, in2, cin, output out, cout); + +assign {cout, out} = in1 - in2 - cin; + +endmodule + +module SUB2 #(parameter SIZE = 2)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 - in2 - cin; + +endmodule + +module SUB4 #(parameter SIZE = 4)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 - in2 - cin; + +endmodule + +module SUB8 #(parameter SIZE = 8)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 - in2 - cin; + +endmodule + +module SUB16 #(parameter SIZE = 16)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 - in2 - cin; + +endmodule + +module SUB32 #(parameter SIZE = 32)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 - in2 - cin; + +endmodule +module SUB64 #(parameter SIZE = 64)(input [SIZE-1:0] in1, in2, + input cin, output [SIZE-1:0] out, output cout); + +assign {cout, out} = in1 - in2 - cin; + +endmodule + +module MUL1 #(parameter SIZE = 1)(input in1, in2, output [2*SIZE-1:0] out); + +assign out = in1*in2; + +endmodule + +module MUL2 #(parameter SIZE = 2)(input [SIZE-1:0] in1, in2, output [2*SIZE-1:0] out); + +assign out = in1*in2; + +endmodule + +module MUL4 #(parameter SIZE = 4)(input [SIZE-1:0] in1, in2, output [2*SIZE-1:0] out); + +assign out = in1*in2; + +endmodule + +module MUL8 #(parameter SIZE = 8)(input [SIZE-1:0] in1, in2, output [2*SIZE-1:0] out); + +assign out = in1*in2; + +endmodule + +module MUL16 #(parameter SIZE = 16)(input [SIZE-1:0] in1, in2, output [2*SIZE-1:0] out); + +assign out = in1*in2; + +endmodule + +module MUL32 #(parameter SIZE = 32)(input [SIZE-1:0] in1, in2, output [2*SIZE-1:0] out); + +assign out = in1*in2; + +endmodule + +module MUL64 #(parameter SIZE = 64)(input [SIZE-1:0] in1, in2, output [2*SIZE-1:0] out); + +assign out = in1*in2; + +endmodule + +module DIV1 #(parameter SIZE = 1)(input in1, in2, output out, rem); + +assign out = in1/in2; +assign rem = in1%in2; + +endmodule + +module DIV2 #(parameter SIZE = 2)(input [SIZE-1:0] in1, in2, + output [SIZE-1:0] out, rem); + +assign out = in1/in2; +assign rem = in1%in2; + +endmodule + +module DIV4 #(parameter SIZE = 4)(input [SIZE-1:0] in1, in2, + output [SIZE-1:0] out, rem); + +assign out = in1/in2; +assign rem = in1%in2; + +endmodule + +module DIV8 #(parameter SIZE = 8)(input [SIZE-1:0] in1, in2, + output [SIZE-1:0] out, rem); + +assign out = in1/in2; +assign rem = in1%in2; + +endmodule + +module DIV16 #(parameter SIZE = 16)(input [SIZE-1:0] in1, in2, + output [SIZE-1:0] out, rem); + +assign out = in1/in2; +assign rem = in1%in2; + +endmodule + +module DIV32 #(parameter SIZE = 32)(input [SIZE-1:0] in1, in2, + output [SIZE-1:0] out, rem); + +assign out = in1/in2; +assign rem = in1%in2; + +endmodule + +module DIV64 #(parameter SIZE = 64)(input [SIZE-1:0] in1, in2, + output [SIZE-1:0] out, rem); + +assign out = in1/in2; +assign rem = in1%in2; + +endmodule + +module FF (input d, clk, output reg q); +always @( posedge clk) + q <= d; +endmodule + + +module RFF(input d, clk, reset, output reg q); +always @(posedge clk or posedge reset) + if(reset) + q <= 0; + else + q <= d; +endmodule + +module SFF(input d, clk, set, output reg q); +always @(posedge clk or posedge set) + if(set) + q <= 1; + else + q <= d; +endmodule + +module RSFF(input d, clk, set, reset, output reg q); +always @(posedge clk or posedge reset or posedge set) + if(reset) + q <= 0; + else if(set) + q <= 1; + else + q <= d; +endmodule + +module SRFF(input d, clk, set, reset, output reg q); +always @(posedge clk or posedge set or posedge reset) + if(set) + q <= 1; + else if(reset) + q <= 0; + else + q <= d; +endmodule + +module LATCH(input d, enable, output reg q); +always @( d or enable) + if(enable) + q <= d; +endmodule + +module RLATCH(input d, reset, enable, output reg q); +always @( d or enable or reset) + if(enable) + if(reset) + q <= 0; + else + q <= d; +endmodule + +module LSHIFT1 #(parameter SIZE = 1)(input in, shift, val, output reg out); + +always @ (in, shift, val) begin + if(shift) + out = val; + else + out = in; +end + +endmodule + + +module LSHIFT2 #(parameter SIZE = 2)(input [SIZE-1:0] in, + input [SIZE-1:0] shift, input val, + output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in << shift; + if(val) + out = out | ({SIZE-1 {1'b1} } >> (SIZE-1-shift)); +end +endmodule + +module LSHIFT4 #(parameter SIZE = 4)(input [SIZE-1:0] in, + input [2:0] shift, input val, output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in << shift; + if(val) + out = out | ({SIZE-1 {1'b1} } >> (SIZE-1-shift)); +end +endmodule + + +module LSHIFT8 #(parameter SIZE = 8)(input [SIZE-1:0] in, + input [3:0] shift, input val, output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in << shift; + if(val) + out = out | ({SIZE-1 {1'b1} } >> (SIZE-1-shift)); +end +endmodule + +module LSHIFT16 #(parameter SIZE = 16)(input [SIZE-1:0] in, + input [4:0] shift, input val, output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in << shift; + if(val) + out = out | ({SIZE-1 {1'b1} } >> (SIZE-1-shift)); +end +endmodule + +module LSHIFT32 #(parameter SIZE = 32)(input [SIZE-1:0] in, + input [5:0] shift, input val, output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in << shift; + if(val) + out = out | ({SIZE-1 {1'b1} } >> (SIZE-1-shift)); +end +endmodule + +module LSHIFT64 #(parameter SIZE = 64)(input [SIZE-1:0] in, + input [6:0] shift, input val, output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in << shift; + if(val) + out = out | ({SIZE-1 {1'b1} } >> (SIZE-1-shift)); +end +endmodule + +module RSHIFT1 #(parameter SIZE = 1)(input in, shift, val, output reg out); + +always @ (in, shift, val) begin + if(shift) + out = val; + else + out = in; +end + +endmodule + +module RSHIFT2 #(parameter SIZE = 2)(input [SIZE-1:0] in, + input [SIZE-1:0] shift, input val, + output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in >> shift; + if(val) + out = out | ({SIZE-1 {1'b1} } << (SIZE-1-shift)); +end + +endmodule + + +module RSHIFT4 #(parameter SIZE = 4)(input [SIZE-1:0] in, + input [2:0] shift, input val, + output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in >> shift; + if(val) + out = out | ({SIZE-1 {1'b1} } << (SIZE-1-shift)); +end +endmodule + +module RSHIFT8 #(parameter SIZE = 8)(input [SIZE-1:0] in, + input [3:0] shift, input val, + output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in >> shift; + if(val) + out = out | ({SIZE-1 {1'b1} } << (SIZE-1-shift)); +end + +endmodule + +module RSHIFT16 #(parameter SIZE = 16)(input [SIZE-1:0] in, + input [4:0] shift, input val, + output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in >> shift; + if(val) + out = out | ({SIZE-1 {1'b1} } << (SIZE-1-shift)); +end +endmodule + + +module RSHIFT32 #(parameter SIZE = 32)(input [SIZE-1:0] in, + input [5:0] shift, input val, + output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in >> shift; + if(val) + out = out | ({SIZE-1 {1'b1} } << (SIZE-1-shift)); +end +endmodule + +module RSHIFT64 #(parameter SIZE = 64)(input [SIZE-1:0] in, + input [6:0] shift, input val, + output reg [SIZE-1:0] out); + +always @(in or shift or val) begin + out = in >> shift; + if(val) + out = out | ({SIZE-1 {1'b1} } << (SIZE-1-shift)); +end +endmodule + +module CMP1 #(parameter SIZE = 1) (input in1, in2, + output reg equal, unequal, greater, lesser); + +always @ (in1 or in2) begin + if(in1 == in2) begin + equal = 1; + unequal = 0; + greater = 0; + lesser = 0; + end + else begin + equal = 0; + unequal = 1; + + if(in1 < in2) begin + greater = 0; + lesser = 1; + end + else begin + greater = 1; + lesser = 0; + end + end +end +endmodule + + +module CMP2 #(parameter SIZE = 2) (input [SIZE-1:0] in1, in2, + output reg equal, unequal, greater, lesser); + +always @ (in1 or in2) begin + if(in1 == in2) begin + equal = 1; + unequal = 0; + greater = 0; + lesser = 0; + end + else begin + equal = 0; + unequal = 1; + + if(in1 < in2) begin + greater = 0; + lesser = 1; + end + else begin + greater = 1; + lesser = 0; + end + end +end +endmodule + +module CMP4 #(parameter SIZE = 4) (input [SIZE-1:0] in1, in2, + output reg equal, unequal, greater, lesser); + +always @ (in1 or in2) begin + if(in1 == in2) begin + equal = 1; + unequal = 0; + greater = 0; + lesser = 0; + end + else begin + equal = 0; + unequal = 1; + + if(in1 < in2) begin + greater = 0; + lesser = 1; + end + else begin + greater = 1; + lesser = 0; + end + end +end +endmodule + +module CMP8 #(parameter SIZE = 8) (input [SIZE-1:0] in1, in2, + output reg equal, unequal, greater, lesser); + +always @ (in1 or in2) begin + if(in1 == in2) begin + equal = 1; + unequal = 0; + greater = 0; + lesser = 0; + end + else begin + equal = 0; + unequal = 1; + + if(in1 < in2) begin + greater = 0; + lesser = 1; + end + else begin + greater = 1; + lesser = 0; + end + end +end +endmodule + +module CMP16 #(parameter SIZE = 16) (input [SIZE-1:0] in1, in2, + output reg equal, unequal, greater, lesser); + +always @ (in1 or in2) begin + if(in1 == in2) begin + equal = 1; + unequal = 0; + greater = 0; + lesser = 0; + end + else begin + equal = 0; + unequal = 1; + + if(in1 < in2) begin + greater = 0; + lesser = 1; + end + else begin + greater = 1; + lesser = 0; + end + end +end +endmodule + +module CMP32 #(parameter SIZE = 32) (input [SIZE-1:0] in1, in2, + output reg equal, unequal, greater, lesser); + +always @ (in1 or in2) begin + if(in1 == in2) begin + equal = 1; + unequal = 0; + greater = 0; + lesser = 0; + end + else begin + equal = 0; + unequal = 1; + + if(in1 < in2) begin + greater = 0; + lesser = 1; + end + else begin + greater = 1; + lesser = 0; + end + end +end +endmodule + +module CMP64 #(parameter SIZE = 64) (input [SIZE-1:0] in1, in2, + output reg equal, unequal, greater, lesser); + +always @ (in1 or in2) begin + if(in1 == in2) begin + equal = 1; + unequal = 0; + greater = 0; + lesser = 0; + end + else begin + equal = 0; + unequal = 1; + + if(in1 < in2) begin + greater = 0; + lesser = 1; + end + else begin + greater = 1; + lesser = 0; + end + end +end +endmodule + +module VCC (output supply1 out); +endmodule + +module GND (output supply0 out); +endmodule + + +module INC1 #(parameter SIZE = 1) (input in, output [SIZE:0] out); + +assign out = in + 1; + +endmodule + +module INC2 #(parameter SIZE = 2) (input [SIZE-1:0] in, output [SIZE:0] out); + +assign out = in + 1; + +endmodule + +module INC4 #(parameter SIZE = 4) (input [SIZE-1:0] in, output [SIZE:0] out); +assign out = in + 1; + +endmodule + +module INC8 #(parameter SIZE = 8) (input [SIZE-1:0] in, output [SIZE:0] out); +assign out = in + 1; + +endmodule + +module INC16 #(parameter SIZE = 16) (input [SIZE-1:0] in, output [SIZE:0] out); +assign out = in + 1; + +endmodule + +module INC32 #(parameter SIZE = 32) (input [SIZE-1:0] in, output [SIZE:0] out); +assign out = in + 1; + +endmodule +module INC64 #(parameter SIZE = 64) (input [SIZE-1:0] in, output [SIZE:0] out); +assign out = in + 1; + +endmodule + diff --git a/manual/FILES_StateOfTheArt/simlib_icarus.v b/manual/FILES_StateOfTheArt/simlib_icarus.v new file mode 100644 index 00000000..fdd7ef61 --- /dev/null +++ b/manual/FILES_StateOfTheArt/simlib_icarus.v @@ -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 + diff --git a/manual/FILES_StateOfTheArt/simlib_yosys.v b/manual/FILES_StateOfTheArt/simlib_yosys.v new file mode 100644 index 00000000..a2df8f64 --- /dev/null +++ b/manual/FILES_StateOfTheArt/simlib_yosys.v @@ -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 + diff --git a/manual/FILES_StateOfTheArt/sis-1.3.6-buildfixes.patch b/manual/FILES_StateOfTheArt/sis-1.3.6-buildfixes.patch new file mode 100644 index 00000000..ad957d6b --- /dev/null +++ b/manual/FILES_StateOfTheArt/sis-1.3.6-buildfixes.patch @@ -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 diff --git a/manual/FILES_StateOfTheArt/synth.sh b/manual/FILES_StateOfTheArt/synth.sh new file mode 100755 index 00000000..3a7524a2 --- /dev/null +++ b/manual/FILES_StateOfTheArt/synth.sh @@ -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 + diff --git a/manual/FILES_StateOfTheArt/validate_tb.sh b/manual/FILES_StateOfTheArt/validate_tb.sh new file mode 100755 index 00000000..b6409eb1 --- /dev/null +++ b/manual/FILES_StateOfTheArt/validate_tb.sh @@ -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 + diff --git a/manual/command-reference-manual.tex b/manual/command-reference-manual.tex new file mode 100644 index 00000000..ce71ce1e --- /dev/null +++ b/manual/command-reference-manual.tex @@ -0,0 +1,1135 @@ +% Generated using the yosys 'help -write-tex-command-reference-manual' command. + +\section{abc -- use ABC for technology mapping} +\label{cmd:abc} +\begin{lstlisting}[numbers=left,frame=single] + abc [options] [selection] + +This pass uses the ABC tool [1] for technology mapping of yosys's internal gate +library to a target architecture. + + -exe <command> + use the specified command name instead of "yosys-abc" to execute ABC. + This can e.g. be used to call a specific version of ABC or a wrapper. + + -script <file> + use the specified ABC script file instead of the default script. + + -liberty <file> + generate netlists for the specified cell library (using the liberty + file format). Without this option, ABC is used to optimize the netlist + but keeps using yosys's internal gate library. This option is ignored if + the -script option is also used. + + -nocleanup + when this option is used, the temporary files created by this pass + are not removed. this is useful for debugging. + +This pass does not operate on modules with unprocessed processes in it. +(I.e. the 'proc' pass should be used first to convert processes to netlists.) + +[1] http://www.eecs.berkeley.edu/~alanmi/abc/ +\end{lstlisting} + +\section{cd -- a shortcut for 'select -module <name>'} +\label{cmd:cd} +\begin{lstlisting}[numbers=left,frame=single] + cd <modname> + +This is just a shortcut for 'select -module <modname>'. + + + cd <cellname> + +When no module with the specified name is found, but there is a cell +with the specified name in the current module, then this is equivialent +to 'cd <celltype>'. + + cd .. + +This is just a shortcut for 'select -clear'. +\end{lstlisting} + +\section{dfflibmap -- technology mapping of flip-flops} +\label{cmd:dfflibmap} +\begin{lstlisting}[numbers=left,frame=single] + dfflibmap -liberty <file> [selection] + +Map internal flip-flop cells to the flip-flop cells in the technology +library specified in the given liberty file. + +This pass may add inverters as needed. Therefore it is recommended to +first run this pass and then map the logic paths to the target technology. +\end{lstlisting} + +\section{dump -- print parts of the design in ilang format} +\label{cmd:dump} +\begin{lstlisting}[numbers=left,frame=single] + dump [options] [selection] + +Write the selected parts of the design to the console or specified file in +ilang format. + + -outfile <filename> + Write to the specified file. +\end{lstlisting} + +\section{eval -- evaluate the circuit given an input} +\label{cmd:eval} +\begin{lstlisting}[numbers=left,frame=single] + eval [options] [selection] + +This command evaluates the value of a signal given the value of all required +inputs. + + -set <signal> <value> + set the specified signal to the specified value. + + -show <signal> + show the value for the specified signal. if no -show option is passed + then all output ports of the current module are used. +\end{lstlisting} + +\section{extract -- find subcircuits and replace them with cells} +\label{cmd:extract} +\begin{lstlisting}[numbers=left,frame=single] + extract -map <map_file> [options] [selection] + extract -mine <out_file> [options] [selection] + +This pass looks for subcircuits that are isomorphic to any of the modules +in the given map file and replaces them with instances of this modules. The +map file can be a verilog source file (*.v) or an ilang file (*.il). + + -map <map_file> + use the modules in this file as reference + + -verbose + print debug output while analyzing + + -constports + also find instances with constant drivers. this may be much + slower than the normal operation. + + -nodefaultswaps + normally builtin port swapping rules for internal cells are used per + default. This turns that off, so e.g. 'a^b' does not match 'b^a' + when this option is used. + + -compat <needle_type> <haystack_type> + Per default, the cells in the map file (needle) must have the + type as the cells in the active design (haystack). This option + can be used to register additional pairs of types that should + match. This option can be used multiple times. + + -swap <needle_type> <port1>,<port2>[,...] + Register a set of swapable ports for a needle cell type. + This option can be used multiple times. + + -perm <needle_type> <port1>,<port2>[,...] <portA>,<portB>[,...] + Register a valid permutation of swapable ports for a needle + cell type. This option can be used multiple times. + + -cell_attr <attribute_name> + Attributes on cells with the given name must match. + + -wire_attr <attribute_name> + Attributes on wires with the given name must match. + +This pass does not operate on modules with uprocessed processes in it. +(I.e. the 'proc' pass should be used first to convert processes to netlists.) + +This pass can also be used for mining for frequent subcircuits. In this mode +the following options are to be used instead of the -map option. + + -mine <out_file> + mine for frequent subcircuits and write them to the given ilang file + + -mine_cells_span <min> <max> + only mine for subcircuits with the specified number of cells + default value: 3 5 + + -mine_min_freq <num> + only mine for subcircuits with at least the specified number of matches + default value: 10 + + -mine_limit_matches_per_module <num> + when calculating the number of matches for a subcircuit, don't count + more than the specified number of matches per module + + -mine_max_fanout <num> + don't consider internal signals with more than <num> connections + +The modules in the map file may have the attribute 'extract_order' set to an +integer value. Then this value is used to determine the order in which the pass +tries to map the modules to the design (ascending, default value is 0). + +See 'help techmap' for a pass that does the opposite thing. +\end{lstlisting} + +\section{flatten -- flatten design} +\label{cmd:flatten} +\begin{lstlisting}[numbers=left,frame=single] + flatten [selection] + +This pass flattens the design by replacing cells by their implementation. This +pass is very simmilar to the 'techmap' pass. The only difference is that this +pass is using the current design as mapping library. +\end{lstlisting} + +\section{fsm -- extract and optimize finite state machines} +\label{cmd:fsm} +\begin{lstlisting}[numbers=left,frame=single] + fsm [options] [selection] + +This pass calls all the other fsm_* passes in a useful order. This performs +FSM extraction and optimiziation. It also calls opt_clean as needed: + + fsm_detect unless got option -nodetect + fsm_extract + + fsm_opt + opt_clean + fsm_opt + + fsm_expand if got option -expand + opt_clean if got option -expand + fsm_opt if got option -expand + + fsm_recode unless got option -norecode + + fsm_info + + fsm_export if got option -export + fsm_map unless got option -nomap + +Options: + + -expand, -norecode, -export, -nomap + enable or disable passes as indicated above + + -encoding tye + -fm_set_fsm_file file + passed through to fsm_recode pass +\end{lstlisting} + +\section{fsm\_detect -- finding FSMs in design} +\label{cmd:fsm_detect} +\begin{lstlisting}[numbers=left,frame=single] + fsm_detect [selection] + +This pass detects finite state machines by identifying the state signal. +The state signal is then marked by setting the attribute 'fsm_encoding' +on the state signal to "auto". + +Existing 'fsm_encoding' attributes are not changed by this pass. + +Signals can be protected from being detected by this pass by setting the +'fsm_encoding' attribute to "none". +\end{lstlisting} + +\section{fsm\_expand -- expand FSM cells by merging logic into it} +\label{cmd:fsm_expand} +\begin{lstlisting}[numbers=left,frame=single] + fsm_expand [selection] + +The fsm_extract pass is conservative about the cells that belong to a finite +state machine. This pass can be used to merge additional auxiliary gates into +the finate state machine. +\end{lstlisting} + +\section{fsm\_export -- exporting FSMs to KISS2 files} +\label{cmd:fsm_export} +\begin{lstlisting}[numbers=left,frame=single] + fsm_export [-noauto] [-o filename] [-origenc] [selection] + +This pass creates a KISS2 file for every selected FSM. For FSMs with the +'fsm_export' attribute set, the attribute value is used as filename, otherwise +the module and cell name is used as filename. If the parameter '-o' is given, +the first exported FSM is written to the specified filename. This overwrites +the setting as specified with the 'fsm_export' attribute. All other FSMs are +exported to the default name as mentioned above. + + -noauto + only export FSMs that have the 'fsm_export' attribute set + + -o filename + filename of the first exported FSM + + -origenc + use binary state encoding as state names instead of s0, s1, ... +\end{lstlisting} + +\section{fsm\_extract -- extracting FSMs in design} +\label{cmd:fsm_extract} +\begin{lstlisting}[numbers=left,frame=single] + fsm_extract [selection] + +This pass operates on all signals marked as FSM state signals using the +'fsm_encoding' attribute. It consumes the logic that creates the state signal +and uses the state signal to generate control signal and replaces it with an +FSM cell. + +The generated FSM cell still generates the original state signal with its +original encoding. The 'fsm_opt' pass can be used in combination with the +'opt_clean' pass to eliminate this signal. +\end{lstlisting} + +\section{fsm\_info -- print information on finite state machines} +\label{cmd:fsm_info} +\begin{lstlisting}[numbers=left,frame=single] + fsm_info [selection] + +This pass dumps all internal information on FSM cells. It can be useful for +analyzing the synthesis process and is called automatically by the 'fsm' +pass so that this information is included in the synthesis log file. +\end{lstlisting} + +\section{fsm\_map -- mapping FSMs to basic logic} +\label{cmd:fsm_map} +\begin{lstlisting}[numbers=left,frame=single] + fsm_map [selection] + +This pass translates FSM cells to flip-flops and logic. +\end{lstlisting} + +\section{fsm\_opt -- optimize finite state machines} +\label{cmd:fsm_opt} +\begin{lstlisting}[numbers=left,frame=single] + fsm_opt [selection] + +This pass optimizes FSM cells. It detects which output signals are actually +not used and removes them from the FSM. This pass is usually used in +combination with the 'opt_clean' pass (see also 'help fsm'). +\end{lstlisting} + +\section{fsm\_recode -- recoding finite state machines} +\label{cmd:fsm_recode} +\begin{lstlisting}[numbers=left,frame=single] + fsm_recode [-encoding type] [-fm_set_fsm_file file] [selection] + +This pass reassign the state encodings for FSM cells. At the moment only +one-hot encoding and binary encoding is supported. The option -encoding +can be used to specify the encoding scheme used for FSMs without the +`fsm_encoding' attribute (or with the attribute set to `auto'. + +The option -fm_set_fsm_file can be used to generate a file containing the +mapping from old to new FSM encoding in form of Synopsys Formality set_fsm_* +commands. +\end{lstlisting} + +\section{help -- display help messages} +\label{cmd:help} +\begin{lstlisting}[numbers=left,frame=single] + help ............. list all commands + help <command> ... print help message for given command + help -all ........ print complete command reference +\end{lstlisting} + +\section{hierarchy -- check, expand and clean up design hierarchy} +\label{cmd:hierarchy} +\begin{lstlisting}[numbers=left,frame=single] + hierarchy [-check] [-top <module>] + hierarchy -generate <cell-types> <port-decls> + +In parametric designs, a module might exists in serveral variations with +different parameter values. This pass looks at all modules in the current +design an re-runs the language frontends for the parametric modules as +needed. + + -check + also check the design hierarchy. this generates an error when + an unknown module is used as cell type. + + -top <module> + use the specified top module to built a design hierarchy. modules + outside this tree (unused modules) are removed. + +In -generate mode this pass generates placeholder modules for the given cell +types (wildcards supported). For this the design is searched for cells that +match the given types and then the given port declarations are used to +determine the direction of the ports. The syntax for a port declaration is: + + {i|o|io}[@<num>]:<portname> + +Input ports are specified with the 'i' prefix, output ports with the 'o' +prefix and inout ports with the 'io' prefix. The optional <num> specifies +the position of the port in the parameter list (needed when instanciated +using positional arguments). When <num> is not specified, the <portname> can +also contain wildcard characters. + +This pass ignores the current selection and always operates on all modules +in the current design. +\end{lstlisting} + +\section{ls -- list modules or objects in modules} +\label{cmd:ls} +\begin{lstlisting}[numbers=left,frame=single] + ls + +When no active module is selected, this prints a list of all module. + +When an active module is selected, this prints a list of objects in the module. +\end{lstlisting} + +\section{memory -- translate memories to basic cells} +\label{cmd:memory} +\begin{lstlisting}[numbers=left,frame=single] + memory [-nomap] [selection] + +This pass calls all the other memory_* passes in a useful order: + + memory_dff + memory_collect + memory_map (skipped if called with -nomap) + +This converts memories to word-wide DFFs and address decoders +or moultiport memory blocks if called with the -nomap option. +\end{lstlisting} + +\section{memory\_collect -- creating multi-port memory cells} +\label{cmd:memory_collect} +\begin{lstlisting}[numbers=left,frame=single] + memory_collect [selection] + +This pass collects memories and memory ports and creates generic multiport +memory cells. +\end{lstlisting} + +\section{memory\_dff -- merge input/output DFFs into memories} +\label{cmd:memory_dff} +\begin{lstlisting}[numbers=left,frame=single] + memory_dff [selection] + +This pass detects DFFs at memory ports and merges them into the memory port. +I.e. it consumes an asynchronous memory port and the flip-flops at its +interface and yields a synchronous memory port. +\end{lstlisting} + +\section{memory\_map -- translate multiport memories to basic cells} +\label{cmd:memory_map} +\begin{lstlisting}[numbers=left,frame=single] + memory_map [selection] + +This pass converts multiport memory cells as generated by the memory_collect +pass to word-wide DFFs and address decoders. +\end{lstlisting} + +\section{opt -- perform simple optimizations} +\label{cmd:opt} +\begin{lstlisting}[numbers=left,frame=single] + opt [selection] + +This pass calls all the other opt_* passes in a useful order. This performs +a series of trivial optimizations and cleanups. This pass executes the other +passes in the following order: + + opt_const + opt_share -nomux + + do + opt_muxtree + opt_reduce + opt_share + opt_rmdff + opt_clean + opt_const + while [changed design] +\end{lstlisting} + +\section{opt\_clean -- remove unused cells and wires} +\label{cmd:opt_clean} +\begin{lstlisting}[numbers=left,frame=single] + opt_clean [options] [selection] + +This pass identifies wires and cells that are unused and removes them. Other +passes often remove cells but leave the wires in the design or reconnect the +wires but leave the old cells in the design. This pass can be used to clean up +after the passes that do the actual work. + +This pass only operates on completely selected modules without processes. + + -purge + also remove internal nets if they have a public name +\end{lstlisting} + +\section{opt\_const -- perform const folding} +\label{cmd:opt_const} +\begin{lstlisting}[numbers=left,frame=single] + opt_const [selection] + +This pass performs const folding on internal cell types with constant inputs. +\end{lstlisting} + +\section{opt\_muxtree -- eliminate dead trees in multiplexer trees} +\label{cmd:opt_muxtree} +\begin{lstlisting}[numbers=left,frame=single] + opt_muxtree [selection] + +This pass analyzes the control signals for the multiplexer trees in the design +and identifies inputs that can never be active. It then removes this dead +branches from the multiplexer trees. + +This pass only operates on completely selected modules without processes. +\end{lstlisting} + +\section{opt\_reduce -- simplify large MUXes and AND/OR gates} +\label{cmd:opt_reduce} +\begin{lstlisting}[numbers=left,frame=single] + opt_reduce [selection] + +This pass performs two interlinked optimizations: + +1. it consolidates trees of large AND gates or OR gates and eliminates +duplicated inputs. + +2. it identifies duplicated inputs to MUXes and replaces them with a single +input with the original control signals OR'ed together. +\end{lstlisting} + +\section{opt\_rmdff -- remove DFFs with constant inputs} +\label{cmd:opt_rmdff} +\begin{lstlisting}[numbers=left,frame=single] + opt_rmdff [selection] + +This pass identifies flip-flops with constant inputs and replaces them with +a constant driver. +\end{lstlisting} + +\section{opt\_share -- consolidate identical cells} +\label{cmd:opt_share} +\begin{lstlisting}[numbers=left,frame=single] + opt_share [-nomux] [selection] + +This pass identifies cells with identical type and input signals. Such cells +are then merged to one cell. + + -nomux + Do not merge MUX cells. +\end{lstlisting} + +\section{proc -- translate processes to netlists} +\label{cmd:proc} +\begin{lstlisting}[numbers=left,frame=single] + proc [selection] + +This pass calls all the other proc_* passes in the most common order. + + proc_clean + proc_rmdead + proc_arst + proc_mux + proc_dff + proc_clean + +This replaces the processes in the design with multiplexers and flip-flops. +\end{lstlisting} + +\section{proc\_arst -- detect asynchronous resets} +\label{cmd:proc_arst} +\begin{lstlisting}[numbers=left,frame=single] + proc_arst [selection] + +This pass identifies asynchronous resets in the processes and converts them +to a different internal representation that is suitable for generating +flip-flop cells with asynchronous resets. +\end{lstlisting} + +\section{proc\_clean -- remove empty parts of processes} +\label{cmd:proc_clean} +\begin{lstlisting}[numbers=left,frame=single] + proc_clean [selection] + +This pass removes empty parts of processes and ultimately removes a process +if it contains only empty structures. +\end{lstlisting} + +\section{proc\_dff -- extract flip-flops from processes} +\label{cmd:proc_dff} +\begin{lstlisting}[numbers=left,frame=single] + proc_dff [selection] + +This pass identifies flip-flops in the processes and converts them to +d-type flip-flop cells. +\end{lstlisting} + +\section{proc\_mux -- convert decision trees to multiplexers} +\label{cmd:proc_mux} +\begin{lstlisting}[numbers=left,frame=single] + proc_mux [selection] + +This pass converts the decision trees in processes (originating from if-else +and case statements) to trees of multiplexer cells. +\end{lstlisting} + +\section{proc\_rmdead -- eliminate dead trees in decision trees} +\label{cmd:proc_rmdead} +\begin{lstlisting}[numbers=left,frame=single] + proc_rmdead [selection] + +This pass identifies unreachable branches in decision trees and removes them. +\end{lstlisting} + +\section{read\_ilang -- read modules from ilang file} +\label{cmd:read_ilang} +\begin{lstlisting}[numbers=left,frame=single] + read_ilang [filename] + +Load modules from an ilang file to the current design. (ilang is a text +representation of a design in yosys's internal format.) +\end{lstlisting} + +\section{read\_verilog -- read modules from verilog file} +\label{cmd:read_verilog} +\begin{lstlisting}[numbers=left,frame=single] + read_verilog [filename] + +Load modules from a verilog file to the current design. A large subset of +Verilog-2005 is supported. + + -dump_ast + dump abstract syntax tree (after simplification) + + -dump_ast_diff + dump ast differences before and after simplification + + -dump_vlog + dump ast as verilog code (after simplification) + + -yydebug + enable parser debug output + + -nolatches + usually latches are synthesized into logic loops + this option prohibits this and sets the output to 'x' + in what would be the latches hold condition + + this behavior can also be achieved by setting the + 'nolatches' attribute on the respective module or + always block. + + -nomem2reg + under certain conditions memories are converted to registers + early during simplification to ensure correct handling of + complex corner cases. this option disables this behavior. + + this can also be achieved by setting the 'nomem2reg' + attribute on the respective module or register. + + -mem2reg + always convert memories to registers. this can also be + achieved by setting the 'mem2reg' attribute on the respective + module or register. + + -ppdump + dump verilog code after pre-processor + + -nopp + do not run the pre-processor + + -lib + only create empty placeholder modules + + -noopt + don't perform basic optimizations (such as const folding) in the + high-level front-end. + + -Dname[=definition] + define the preprocessor symbol 'name' and set its optional value + 'definition' +\end{lstlisting} + +\section{rename -- rename object in the design} +\label{cmd:rename} +\begin{lstlisting}[numbers=left,frame=single] + rename old_name new_name + +Rename the specified object. Note that selection patterns are not supported +by this command. +\end{lstlisting} + +\section{sat -- solve a SAT problem in the circuit} +\label{cmd:sat} +\begin{lstlisting}[numbers=left,frame=single] + sat [options] [selection] + +This command solves a SAT problem defined over the currently selected circuit +and additional constraints passed as parameters. + + -all + show all solutions to the problem (this can grow exponentially, use + -max <N> instead to get <N> solutions) + + -max <N> + like -all, but limit number of solutions to <N> + + -set <signal> <value> + set the specified signal to the specified value. + + -show <signal> + show the model for the specified signal. if no -show option is + passed then a set of signals to be shown is automatically selected. + +The following options can be used to set up a sequential problem: + + -seq <N> + set up a sequential problem with <N> time steps. The steps will + be numbered from 1 to N. + + -set-at <N> <signal> <value> + -unset-at <N> <signal> + set or unset the specified signal to the specified value in the + given timestep. this has priority over a -set for the same signal. + +The following additional options can be used to set up a proof. If also -seq +is passed, a temporal induction proof is performed. + + -prove <signal> <value> + Attempt to proof that <signal> is always <value>. In a temporal + induction proof it is proven that the condition holds forever after + the number of time steps passed using -seq. + + -maxsteps <N> + Set a maximum length for the induction. + + -timeout <N> + Maximum number of seconds a single SAT instance may take. + + -verify + Return an error and stop the synthesis script if the proof fails. + + -verify-no-timeout + Like -verify but do not return an error for timeouts. +\end{lstlisting} + +\section{scatter -- add additional intermediate nets} +\label{cmd:scatter} +\begin{lstlisting}[numbers=left,frame=single] + scatter [selection] + +This command adds additional intermediate nets on all cell ports. This is used +for testing the correct use of the SigMap halper in passes. If you don't know +what this means: don't worry -- you only need this pass when testing your own +extensions to Yosys. + +Use the opt_clean command to get rid of the additional nets. +\end{lstlisting} + +\section{scc -- detect strongly connected components (logic loops)} +\label{cmd:scc} +\begin{lstlisting}[numbers=left,frame=single] + scc [options] [selection] + +This command identifies strongly connected components (aka logic loops) in the +design. + + -max_depth <num> + limit to loops not longer than the specified number of cells. This can + e.g. be useful in identifying local loops in a module that turns out + to be one gigantic SCC. + + -all_cell_types + Usually this command only considers internal non-memory cells. With + this option set, all cells are considered. For unkown cells all ports + are assumed to be bidirectional 'inout' ports. + + -set_attr <name> <value> + -set_cell_attr <name> <value> + -set_wire_attr <name> <value> + set the specified attribute on all cells and/or wires that are part of + a logic loop. the special token {} in the value is replaced with a + unique identifier for the logic loop. + + -select + replace the current selection with a selection of all cells and wires + that are part of a found logic loop +\end{lstlisting} + +\section{script -- execute commands from script file} +\label{cmd:script} +\begin{lstlisting}[numbers=left,frame=single] + script <filename> + +This command executes the yosys commands in the specified file. +\end{lstlisting} + +\section{select -- modify and view the list of selected objects} +\label{cmd:select} +\begin{lstlisting}[numbers=left,frame=single] + select [ -add | -del | -set <name> ] <selection> + select [ -list | -write <filename> | -count | -clear ] + select -module <modname> + +Most commands use the list of currently selected objects to determine which part +of the design to operate on. This command can be used to modify and view this +list of selected objects. + +Note that many commands support an optional [selection] argument that can be +used to override the global selection for the command. The syntax of this +optional argument is identical to the syntax of the <selection> argument +described here. + + -add, -del + add or remove the given objects to the current selection. + without this options the current selection is replaced. + + -set <name> + do not modify the current selection. instead save the new selection + under the given name (see @<name> below). + + -list + list all objects in the current selection + + -write <filename> + like -list but write the output to the specified file + + -count + count all objects in the current selection + + -clear + clear the current selection. this effectively selects the + whole design. + + -module <modname> + limit the current scope to the specified module. + the difference between this and simply selecting the module + is that all object names are interpreted relative to this + module after this command until the selection is cleared again. + +When this command is called without an argument, the current selection +is displayed in a compact form (i.e. only the module name when a whole module +is selected). + +The <selection> argument itself is a series of commands for a simple stack +machine. Each element on the stack represents a set of selected objects. +After this commands have been executed, the union of all remaining sets +on the stack is computed and used as selection for the command. + +Pushing (selecting) object when not in -module mode: + + <mod_pattern> + select the specified module(s) + + <mod_pattern>/<obj_pattern> + select the specified object(s) from the module(s) + +Pushing (selecting) object when in -module mode: + + <obj_pattern> + select the specified object(s) from the current module + +A <mod_pattern> can be a module name or wildcard expression (*, ?, [..]) +matching module names. + +An <obj_pattern> can be an object name, wildcard expression, or one of +the following: + + w:<pattern> + all wires with a name matching the given wildcard pattern + + m:<pattern> + all memories with a name matching the given pattern + + c:<pattern> + all cells with a name matching the given pattern + + t:<pattern> + all cells with a type matching the given pattern + + p:<pattern> + all processes with a name matching the given pattern + + a:<pattern> + all objects with an attribute name matching the given pattern + + a:<pattern>=<pattern> + all objects with a matching attribute name-value-pair + + n:<pattern> + all objects with a name matching the given pattern + (i.e. 'n:' is optional as it is the default matching rule) + + @<name> + push the selection saved prior with 'select -set <name> ...' + +The following actions can be performed on the top sets on the stack: + + % + push a copy of the current selection to the stack + + %% + replace the stack with a union of all elements on it + + %n + replace top set with its invert + + %u + replace the two top sets on the stack with their union + + %i + replace the two top sets on the stack with their intersection + + %d + pop the top set from the stack and subtract it from the new top + + %x[<num1>|*][.<num2>][:<rule>[:<rule>..]] + expand top set <num1> num times according to the specified rules. + (i.e. select all cells connected to selected wires and select all + wires connected to selected cells) The rules specify which cell + ports to use for this. the syntax for a rule is a '-' for exclusion + and a '+' for inclusion, followed by an optional comma seperated + list of cell types followed by an optional comma separated list of + cell ports in square brackets. a rule can also be just a cell or wire + name that limits the expansion (is included but does not go beyond). + select at most <num2> objects. a warning message is printed when this + limit is reached. When '*' is used instead of <num1> then the process + is repeated until no further object are selected. + + %ci[<num1>|*][.<num2>][:<rule>[:<rule>..]] + %co[<num1>|*][.<num2>][:<rule>[:<rule>..]] + simmilar to %x, but only select input (%ci) or output cones (%co) + +Example: the following command selects all wires that are connected to a +'GATE' input of a 'SWITCH' cell: + + select */t:SWITCH %x:+[GATE] */t:SWITCH %d +\end{lstlisting} + +\section{shell -- enter interactive command mode} +\label{cmd:shell} +\begin{lstlisting}[numbers=left,frame=single] + shell + +This command enters the interactive command mode. This can be useful +in a script to interrupt the script at a certain point and allow for +interactive inspection or manual synthesis of the design at this point. + +The command prompt of the interactive shell indicates the current +selection (see 'help select'): + + yosys> + the entire design is selected + + yosys*> + only part of the design is selected + + yosys [modname]> + the entire module 'modname' is selected using 'select -module modname' + + yosys [modname]*> + only part of current module 'modname' is selected + +When in interactive shell, some errors (e.g. invalid command arguments) +do not terminate yosys but return to the command prompt. + +This command is the default action if nothing else has been specified +on the command line. + +Press Ctrl-D or type 'exit' to leave the interactive shell. +\end{lstlisting} + +\section{show -- generate schematics using graphviz} +\label{cmd:show} +\begin{lstlisting}[numbers=left,frame=single] + show [options] [selection] + +Create a graphviz DOT file for the selected part of the design and compile it +to a graphics file (usually SVG or PostScript). + + -viewer <viewer> + Run the specified command with the graphics file as parameter. + + -format <format> + Generate a graphics file in the specified format. + Usually <format> is 'svg' or 'ps'. + + -lib <verilog_or_ilang_file> + Use the specified library file for determining whether cell ports are + inputs or outputs. This option can be used multiple times to specify + more than one library. + + -prefix <prefix> + generate <prefix>.dot and <prefix>.ps instead of ~/.yosys_show.{dot,ps} + + -color <color> <wire> + assign the specified color to the specified wire. The object can be + a single selection wildcard expressions or a saved set of objects in + the @<name> syntax (see "help select" for details). + + -colors <seed> + Randomly assign colors to the wires. The integer argument is the seed + for the random number generator. Change the seed value if the colored + graph still is ambigous. A seed of zero deactivates the coloring. + + -width + annotate busses with a label indicating the width of the bus. + + -stretch + stretch the graph so all inputs are on the left side and all outputs + (including inout ports) are on the right side. + +When no <format> is specified, SVG is used. When no <format> and <viewer> is +specified, 'yosys-svgviewer' is used to display the schematic. + +The generated output files are '~/.yosys_show.dot' and '~/.yosys_show.<format>', +unless another prefix is specified using -prefix <prefix>. +\end{lstlisting} + +\section{splitnets -- split up multi-bit nets} +\label{cmd:splitnets} +\begin{lstlisting}[numbers=left,frame=single] + splitnets [options] [selection] + +This command splits multi-bit nets into single-bit nets. + + -ports + also split module ports. per default only internal signals are split. +\end{lstlisting} + +\section{submod -- moving part of a module to a new submodule} +\label{cmd:submod} +\begin{lstlisting}[numbers=left,frame=single] + submod [selection] + +This pass identifies all cells with the 'submod' attribute and moves them to +a newly created module. The value of the attribute is used as name for the +cell that replaces the group of cells with the same attribute value. + +This pass can be used to create a design hierarchy in flat design. This can +be useful for analyzing or reverse-engineering a design. + +This pass only operates on completely selected modules with no processes +or memories. + + + submod -name <name> [selection] + +As above, but don't use the 'submod' attribute but instead use the selection. +Only objects from one module might be selected. The value of the -name option +is used as the value of the 'submod' attribute above. +\end{lstlisting} + +\section{tcl -- execute a TCL script file} +\label{cmd:tcl} +\begin{lstlisting}[numbers=left,frame=single] + tcl <filename> + +This command executes the tcl commands in the specified file. +Use 'yosys cmd' to run the yosys command 'cmd' from tcl. + +The tcl command 'yosys -import' can be used to import all yosys +commands directly as tcl commands to the tcl shell. The yosys +command 'proc' is wrapped using the tcl command 'procs' in order +to avoid a name collision with the tcl builting command 'proc'. +\end{lstlisting} + +\section{techmap -- simple technology mapper} +\label{cmd:techmap} +\begin{lstlisting}[numbers=left,frame=single] + techmap [-map filename] [selection] + +This pass implements a very simple technology mapper that replaces cells in +the design with implementations given in form of a verilog or ilang source +file. + + -map filename + the library of cell implementations to be used. + without this parameter a builtin library is used that + transforms the internal RTL cells to the internal gate + library. + +When a module in the map file has the 'celltype' attribute set, it will match +cells with a type that match the text value of this attribute. + +When a module in the map file contains a wire with the name 'TECHMAP_FAIL' (or +one matching '*.TECHMAP_FAIL') then no substitution will be performed. The +modules in the map file are tried in alphabetical order. + +When a module in the map file has a parameter where the according cell in the +design has a port, the module from the map file is only used if the port in +the design is connected to a constant value. The parameter is then set to the +constant value. + +See 'help extract' for a pass that does the opposite thing. + +See 'help flatten' for a pass that does flatten the design (which is +esentially techmap but using the design itself as map library). +\end{lstlisting} + +\section{write\_autotest -- generate simple test benches} +\label{cmd:write_autotest} +\begin{lstlisting}[numbers=left,frame=single] + write_autotest [filename] + +Automatically create primitive verilog test benches for all modules in the +design. The generated testbenches toggle the input pins of the module in +a semi-random manner and dumps the resulting output signals. + +This can be used to check the synthesis results for simple circuits by +comparing the testbench output for the input files and the synthesis results. + +The backend automatically detects clock signals. Additionally a signal can +be forced to be interpreted as clock signal by setting the attribute +'gentb_clock' on the signal. + +The attribute 'gentb_constant' can be used to force a signal to a constant +value after initialization. This can e.g. be used to force a reset signal +low in order to explore more inner states in a state machine. +\end{lstlisting} + +\section{write\_ilang -- write design to ilang file} +\label{cmd:write_ilang} +\begin{lstlisting}[numbers=left,frame=single] + write_ilang [filename] + +Write the current design to an 'ilang' file. (ilang is a text representation +of a design in yosys's internal format.) +\end{lstlisting} + +\section{write\_intersynth -- write design to InterSynth netlist file} +\label{cmd:write_intersynth} +\begin{lstlisting}[numbers=left,frame=single] + write_intersynth [options] [filename] + +Write the current design to an 'intersynth' netlist file. InterSynth is +a tool for Coarse-Grain Example-Driven Interconnect Synthesis. + + -notypes + do not generate celltypes and conntypes commands. i.e. just output + the netlists. this is used for postsilicon synthesis. + + -lib <verilog_or_ilang_file> + Use the specified library file for determining whether cell ports are + inputs or outputs. This option can be used multiple times to specify + more than one library. + +http://www.clifford.at/intersynth/ +\end{lstlisting} + +\section{write\_verilog -- write design to verilog file} +\label{cmd:write_verilog} +\begin{lstlisting}[numbers=left,frame=single] + write_verilog [options] [filename] + +Write the current design to a verilog file. + + -norename + without this option all internal object names (the ones with a dollar + instead of a backslash prefix) are changed to short names in the + format '_<number>_'. + + -noattr + with this option no attributes are included in the output + + -attr2comment + with this option attributes are included as comments in the output + + -noexpr + without this option all internal cells are converted to verilog + expressions. + + -placeholders + usually modules with the 'placeholder' attribute are ignored. with + this option set only the modules with the 'placeholder' attribute + are written to the output file. +\end{lstlisting} + diff --git a/manual/literature.bib b/manual/literature.bib new file mode 100644 index 00000000..91bc1f38 --- /dev/null +++ b/manual/literature.bib @@ -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},
+}
diff --git a/manual/make.sh b/manual/make.sh new file mode 100644 index 00000000..e8263c7b --- /dev/null +++ b/manual/make.sh @@ -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 + diff --git a/manual/manual.tex b/manual/manual.tex new file mode 100644 index 00000000..857c54ab --- /dev/null +++ b/manual/manual.tex @@ -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} diff --git a/manual/weblinks.bib b/manual/weblinks.bib new file mode 100644 index 00000000..9b6032ed --- /dev/null +++ b/manual/weblinks.bib @@ -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/}}
+}
+
|