\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
+designers who are looking for an easily accessible, universal, and
+vendor-independent synthesis tool, as well as 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.
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
+With the exception of the AST Frontend, which 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
+(RTLIL) and (2) that this data structure is powerful enough to represent the design
in different stages of the synthesis.
\begin{figure}[t]
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
+In order to avoid reinventing 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
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
+which passes operate on, frontends add data to 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.
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.
+parts of RTLIL and rationale 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
+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
This has three advantages:
\begin{itemize}
-\item Firstly it is impossible that an auto-generated identifier collides with
+\item First, 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
+\item Second, 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
+tries 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
+\item Third, 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}\_}.
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
+over the parameters and the module name is used to prohibit the same parametrized variation from being
generated twice. For modules with only a few parameters, a name directly containing all parameters
is generated instead of a hash string.)
\begin{itemize}
\item The wire name
\item A list of attributes
-\item A width (busses are just wires with a width > 1)
+\item A width (buses are just wires with a width > 1)
+\item Bus direction (MSB to LSB or vice versa)
+\item Lowest valid bit index (LSB or MSB depending on bus direction)
\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.
+Verilog frontend or attributes assigned by passes.
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.
coarse grain synthesis where the cells of the target architecture operate on
entire signal vectors instead of single bit wires.
+In Verilog and VHDL, busses may have arbitrary bounds, and LSB can have either
+the lowest or the highest bit index. In RTLIL, bit 0 always corresponds to LSB;
+however, information from the HDL frontend is preserved so that the bus will be
+correctly indexed in error messages, backend output, constraint files, etc.
+
An RTLIL::Cell object has the following properties:
\begin{itemize}
\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.
+to each cell port. The RTLIL::SigSpec data type is described in the next section.
\subsection{RTLIL::SigSpec}
switch \reset
case 1'1
assign $0\q[0:0] 1'0
- case
+ case
switch \enable
case 1'1
assign $0\q[0:0] \d
- case
+ case
end
end
sync posedge \clock
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::SyncRule object contains an (optional) synchronization condition (signal and edge-type) and zero or
+more assignments (RTLIL::SigSig). The {\tt always} synchronization condition is used to break combinatorial
+loops when a latch should be inferred instead.
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
+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
sets {\tt \$0\textbackslash{}q[0:0]} to the value of {\tt \textbackslash{}d} if {\tt
\textbackslash{}enable} is active (lines $6 \dots 11$).
+A case can specify zero or more compare values that will determine whether it matches. Each of the compare values
+must be the exact same width as the control signal. When more than one compare value is specified, the case matches
+if any of them matches the control signal; when zero compare values are specified, the case always matches (i.e.
+it is the default case).
+
+A switch prioritizes cases from first to last: multiple cases can match, but only the first matched case becomes
+active. This normally synthesizes to a priority encoder. The {\tt parallel\_case} attribute allows passes to assume
+that no more than one case will match, and {\tt full\_case} attribute allows passes to assume that exactly one
+case will match; if these invariants are ever dynamically violated, the behavior is undefined. These attributes
+are useful when an invariant invisible to the synthesizer causes the control signal to never take certain
+bit patterns.
+
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}.
switch \enable
case 1'1
assign $0\q[0:0] \d
- case
+ case
end
sync posedge \clock
update \q $0\q[0:0]
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:
+into e.g.~a d-type flip-flop with asynchronous reset and a multiplexer for the enable signal:
\begin{lstlisting}[numbers=left,frame=single,language=rtlil]
cell $adff $procdff$6
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.
+for most synthesis tasks.
\subsection{RTLIL::Memory}
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.
+to the memory. Memory initialization is transformed to {\tt \$meminit} cells by the language frontend.
+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
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.
+See Sec.~\ref{sec:memcells} for details about 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.
+whitespace separated 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}
+Most commands can operate not only on the entire design but also specifically 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
+a {\tt \$add} cell. 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:
+The Yosys source tree is organized into the following top-level directories:
\begin{itemize}
\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}.
+passes: {\tt opt}, {\tt opt\_expr}, {\tt opt\_muxtree}, {\tt opt\_reduce},
+{\tt opt\_rmdff}, {\tt opt\_rmunused} and {\tt opt\_merge}.
\item {\tt techlibs/} \\
This directory contains simulation models and standard implementations for the
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}.
+Good starting points for reading example source code to learn how to write passes
+are {\tt passes/opt/opt\_rmdff.cc} and {\tt passes/opt/opt\_merge.cc}.
See the top-level README file for a quick {\it Getting Started} guide and build
-instructions. Yosys is a pure Makefile based project.
+instructions. The Yosys build is based solely on Makefiles.
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.
+available after the CDT plugin has been installed) to create an Eclipse project
+in order to programming extensions to Yosys or just browse the Yosys code base.
projects / yosys.git / blobdiff