2 \chapter{Implementation Overview
}
3 \label{chapter:overview
}
5 Yosys is an extensible open source hardware synthesis tool. It is aimed at
6 designers who are looking for an easily accessible, universal, and
7 vendor-independent synthesis tool, as well as scientists who do research in
8 electronic design automation (EDA) and are looking for an open synthesis
9 framework that can be used to test algorithms on complex real-world designs.
11 Yosys can synthesize a large subset of Verilog
2005 and has been tested with a
12 wide range of real-world designs, including the OpenRISC
1200 CPU
13 \citeweblink{OR1200
}, the openMSP430 CPU
\citeweblink{openMSP430
}, the
14 OpenCores I$^
2$C master
\citeweblink{i2cmaster
} and the k68 CPU
\citeweblink{k68
}.
16 As of this writing a Yosys VHDL frontend is in development.
18 Yosys is written in C++ (using some features from the new C++
11 standard). This
19 chapter describes some of the fundamental Yosys data structures. For the sake
20 of simplicity the C++ type names used in the Yosys implementation are used in
21 this chapter, even though the chapter only explains the conceptual idea behind
22 it and can be used as reference to implement a similar system in any language.
24 \section{Simplified Data Flow
}
26 Figure~
\ref{fig:Overview_flow
} shows the simplified data flow within Yosys.
27 Rectangles in the figure represent program modules and ellipses internal
28 data structures that are used to exchange design data between the program
31 Design data is read in using one of the frontend modules. The high-level HDL
32 frontends for Verilog and VHDL code generate an abstract syntax tree (AST) that
33 is then passed to the AST frontend. Note that both HDL frontends use the same
34 AST representation that is powerful enough to cover the Verilog HDL and VHDL
37 The AST Frontend then compiles the AST to Yosys's main internal data format,
38 the RTL Intermediate Language (RTLIL). A more detailed description of this format
39 is given in the next section.
41 There is also a text representation of the RTLIL data structure that can be
42 parsed using the RTLIL Frontend.
44 The design data may then be transformed using a series of passes that all
45 operate on the RTLIL representation of the design.
47 Finally the design in RTLIL representation is converted back to text by one
48 of the backends, namely the Verilog Backend for generating Verilog netlists
49 and the RTLIL Backend for writing the RTLIL data in the same format that is
50 understood by the RTLIL Frontend.
52 With the exception of the AST Frontend, which is called by the high-level HDL
53 frontends and can't be called directly by the user, all program modules are
54 called by the user (usually using a synthesis script that contains text
57 By combining passes in different ways and/or adding additional passes to Yosys
58 it is possible to adapt Yosys to a wide range of applications. For this to be
59 possible it is key that (
1) all passes operate on the same data structure
60 (RTLIL) and (
2) that this data structure is powerful enough to represent the design
61 in different stages of the synthesis.
66 \tikzstyle{process
} =
[draw, fill=green!
10, rectangle, minimum height=
3em, minimum width=
10em, node distance=
15em
]
67 \tikzstyle{data
} =
[draw, fill=blue!
10, ellipse, minimum height=
3em, minimum width=
7em, node distance=
15em
]
68 \node[process
] (vlog)
{Verilog Frontend
};
69 \node[process, dashed, fill=green!
5] (vhdl)
[right of=vlog
] {VHDL Frontend
};
70 \node[process
] (ilang)
[right of=vhdl
] {RTLIL Frontend
};
71 \node[data
] (ast)
[below of=vlog, node distance=
5em, xshift=
7.5em
] {AST
};
72 \node[process
] (astfe)
[below of=ast, node distance=
5em
] {AST Frontend
};
73 \node[data
] (rtlil)
[below of=astfe, node distance=
5em, xshift=
7.5em
] {RTLIL
};
74 \node[process
] (pass)
[right of=rtlil, node distance=
5em, xshift=
7.5em
] {Passes
};
75 \node[process
] (vlbe)
[below of=rtlil, node distance=
7em, xshift=-
13em
] {Verilog Backend
};
76 \node[process
] (ilangbe)
[below of=rtlil, node distance=
7em, xshift=
0em
] {RTLIL Backend
};
77 \node[process, dashed, fill=green!
5] (otherbe)
[below of=rtlil, node distance=
7em, xshift=+
13em
] {Other Backends
};
79 \draw[-latex
] (vlog) -- (ast);
80 \draw[-latex
] (vhdl) -- (ast);
81 \draw[-latex
] (ast) -- (astfe);
82 \draw[-latex
] (astfe) -- (rtlil);
83 \draw[-latex
] (ilang) -- (rtlil);
84 \draw[latex-latex
] (rtlil) -- (pass);
85 \draw[-latex
] (rtlil) -- (vlbe);
86 \draw[-latex
] (rtlil) -- (ilangbe);
87 \draw[-latex
] (rtlil) -- (otherbe);
89 \caption{Yosys simplified data flow (ellipses: data structures, rectangles: program modules)
}
90 \label{fig:Overview_flow
}
93 \section{The RTL Intermediate Language
}
95 All frontends, passes and backends in Yosys operate on a design in RTLIL representation.
96 The only exception are the high-level frontends that use the AST representation as an intermediate step before generating RTLIL
99 In order to avoid reinventing names for the RTLIL classes, they are simply referred to by their full C++ name, i.e.~including
100 the
{\tt RTLIL::
} namespace prefix, in this
document.
102 Figure~
\ref{fig:Overview_RTLIL
} shows a simplified Entity-Relationship Diagram (ER Diagram) of RTLIL. In $
1:N$ relationships the arrow
103 points from the $N$ side to the $
1$. For example one RTLIL::Design contains $N$ (zero to many) instances of RTLIL::Module.
104 A two-pointed arrow indicates a $
1:
1$ relationship.
106 The RTLIL::Design is the root object of the RTLIL data structure. There is always one ``current design'' in memory
107 which passes operate on, frontends add data to and backends convert to exportable formats. But in some cases passes
108 internally generate additional RTLIL::Design objects. For example when a pass is reading an auxiliary Verilog file such
109 as a cell library, it might create an additional RTLIL::Design object and call the Verilog frontend with this
110 other object to parse the cell library.
115 \tikzstyle{entity
} =
[draw, fill=gray!
10, rectangle, minimum height=
3em, minimum width=
7em, node distance=
5em, font=
{\ttfamily}]
116 \node[entity
] (design)
{RTLIL::Design
};
117 \node[entity
] (module)
[right of=design, node distance=
11em
] {RTLIL::Module
} edge
[-latex
] node
[above
] {\tiny 1 \hskip3em N
} (design);
119 \node[entity
] (process)
[fill=green!
10, right of=module, node distance=
10em
] {RTLIL::Process
} (process.west) edge
[-latex
] (module);
120 \node[entity
] (memory)
[fill=red!
10, below of=process
] {RTLIL::Memory
} edge
[-latex
] (module);
121 \node[entity
] (wire)
[fill=blue!
10, above of=process
] {RTLIL::Wire
} (wire.west) edge
[-latex
] (module);
122 \node[entity
] (cell)
[fill=blue!
10, above of=wire
] {RTLIL::Cell
} (cell.west) edge
[-latex
] (module);
124 \node[entity
] (case)
[fill=green!
10, right of=process, node distance=
10em
] {RTLIL::CaseRule
} edge
[latex-latex
] (process);
125 \node[entity
] (sync)
[fill=green!
10, above of=case
] {RTLIL::SyncRule
} edge
[-latex
] (process);
126 \node[entity
] (switch)
[fill=green!
10, below of=case
] {RTLIL::SwitchRule
} edge
[-latex
] (case);
127 \draw[latex-
] (switch.east) -- ++(
1em,
0) |- (case.east);
129 \caption{Simplified RTLIL Entity-Relationship Diagram
}
130 \label{fig:Overview_RTLIL
}
133 There is only one active RTLIL::Design object that is used by all frontends,
134 passes and backends called by the user, e.g.~using a synthesis script. The RTLIL::Design then contains
135 zero to many RTLIL::Module objects. This corresponds to modules in Verilog or entities in VHDL. Each
136 module in turn contains objects from three different categories:
139 \item RTLIL::Cell and RTLIL::Wire objects represent classical netlist data.
140 \item RTLIL::Process objects represent the decision trees (if-then-else statements, etc.) and synchronization
141 declarations (clock signals and sensitivity) from Verilog
{\tt always
} and VHDL
{\tt process
} blocks.
142 \item RTLIL::Memory objects represent addressable memories (arrays).
146 Usually the output of the synthesis procedure is a netlist, i.e. all
147 RTLIL::Process and RTLIL::Memory objects must be replaced by RTLIL::Cell and
148 RTLIL::Wire objects by synthesis passes.
151 All features of the HDL that cannot be mapped directly to these RTLIL classes must be
152 transformed to an RTLIL-compatible representation by the HDL frontend. This includes
153 Verilog-features such as generate-blocks, loops and parameters.
155 The following sections contain a more detailed description of the different
156 parts of RTLIL and rationale behind some of the design decisions.
158 \subsection{RTLIL Identifiers
}
160 All identifiers in RTLIL (such as module names, port names, signal names, cell
161 types, etc.) follow the following naming convention: they must either start with
162 a backslash (
\textbackslash) or a dollar sign (\$).
164 Identifiers starting with a backslash are public visible identifiers. Usually
165 they originate from one of the HDL input files. For example the signal name ``
{\tt \textbackslash sig42
}''
166 is most likely a signal that was declared using the name ``
{\tt sig42
}'' in an HDL input file.
167 On the other hand the signal name ``
{\tt \$sig42
}'' is an auto-generated signal name. The backends
168 convert all identifiers that start with a dollar sign to identifiers that do not collide with
169 identifiers that start with a backslash.
171 This has three advantages:
174 \item First, it is impossible that an auto-generated identifier collides with
175 an identifier that was provided by the user.
176 \item Second, the information about which identifiers were originally
177 provided by the user is always available which can help guide some optimizations. For example the ``opt
\_rmunused''
178 tries to preserve signals with a user-provided name but doesn't hesitate to delete signals that have
179 auto-generated names when they just duplicate other signals.
180 \item Third, the delicate job of finding suitable auto-generated public visible
181 names is deferred to one central location. Internally auto-generated names that
182 may hold important information for Yosys developers can be used without
183 disturbing external tools. For example the Verilog backend assigns names in the form
{\tt \_{\it integer
}\_}.
186 Whitespace and control characters (any character with an ASCII code
32 or less) are not allowed
187 in RTLIL identifiers; most frontends and backends cannot support these characters in identifiers.
189 In order to avoid programming errors, the RTLIL data structures check if all identifiers start
190 with either a backslash or a dollar sign, and contain no whitespace or control characters.
191 Violating these rules results in a runtime error.
193 All RTLIL identifiers are case sensitive.
195 Some transformations, such as flattening, may have to change identifiers provided by the user
196 to avoid name collisions. When that happens, attribute ``
{\tt hdlname
}`` is attached to the object
197 with the changed identifier. This attribute contains one name (if emitted directly by the frontend,
198 or is a result of disambiguation) or multiple names separated by spaces (if a result of flattening).
199 All names specified in the ``
{\tt hdlname
}`` attribute are public and do not include the leading
202 \subsection{RTLIL::Design and RTLIL::Module
}
204 The RTLIL::Design object is basically just a container for RTLIL::Module objects. In addition to
205 a list of RTLIL::Module objects the RTLIL::Design also keeps a list of
{\it selected objects
}, i.e.
206 the objects that passes should operate on. In most cases the whole design is selected and therefore
207 passes operate on the whole design. But this mechanism can be useful for more complex synthesis jobs
208 in which only parts of the design should be affected by certain passes.
210 Besides the objects shown in the ER diagram in Fig.~
\ref{fig:Overview_RTLIL
} an RTLIL::Module object
211 contains the following additional properties:
214 \item The module name
215 \item A list of attributes
216 \item A list of connections between wires
217 \item An optional frontend callback used to derive parametrized variations of the module
220 The attributes can be Verilog attributes imported by the Verilog frontend or attributes assigned
221 by passes. They can be used to store additional metadata about modules or just mark them to be
222 used by certain part of the synthesis script but not by others.
224 Verilog and VHDL both support parametric modules (known as ``generic entities'' in VHDL). The RTLIL
225 format does not support parametric modules itself. Instead each module contains a callback function
226 into the AST frontend to generate a parametrized variation of the RTLIL::Module as needed. This
227 callback then returns the auto-generated name of the parametrized variation of the module. (A hash
228 over the parameters and the module name is used to prohibit the same parametrized variation from being
229 generated twice. For modules with only a few parameters, a name directly containing all parameters
230 is generated instead of a hash string.)
232 \subsection{RTLIL::Cell and RTLIL::Wire
}
233 \label{sec:rtlil_cell_wire
}
235 A module contains zero to many RTLIL::Cell and RTLIL::Wire objects. Objects of
236 these types are used to model netlists. Usually the goal of all synthesis efforts is to convert
237 all modules to a state where the functionality of the module is implemented only by cells
238 from a given cell library and wires to connect these cells with each other. Note that module
239 ports are just wires with a special property.
241 An RTLIL::Wire object has the following properties:
245 \item A list of attributes
246 \item A width (buses are just wires with a width >
1)
247 \item Bus direction (MSB to LSB or vice versa)
248 \item Lowest valid bit index (LSB or MSB depending on bus direction)
249 \item If the wire is a port: port number and direction (input/output/inout)
252 As with modules, the attributes can be Verilog attributes imported by the
253 Verilog frontend or attributes assigned by passes.
255 In Yosys, busses (signal vectors) are represented using a single wire object
256 with a width >
1. So Yosys does not convert signal vectors to individual signals.
257 This makes some aspects of RTLIL more complex but enables Yosys to be used for
258 coarse grain synthesis where the cells of the target architecture operate on
259 entire signal vectors instead of single bit wires.
261 In Verilog and VHDL, busses may have arbitrary bounds, and LSB can have either
262 the lowest or the highest bit index. In RTLIL, bit
0 always corresponds to LSB;
263 however, information from the HDL frontend is preserved so that the bus will be
264 correctly indexed in error messages, backend output, constraint files, etc.
266 An RTLIL::Cell object has the following properties:
269 \item The cell name and type
270 \item A list of attributes
271 \item A list of parameters (for parametric cells)
272 \item Cell ports and the connections of ports to wires and constants
275 The connections of ports to wires are coded by assigning an RTLIL::SigSpec
276 to each cell port. The RTLIL::SigSpec data type is described in the next section.
278 \subsection{RTLIL::SigSpec
}
279 \label{sec:rtlil_sigspec
}
281 A ``signal'' is everything that can be applied to a cell port. I.e.
284 \item Any constant value of arbitrary bit-width \\
285 \null\hskip1em For example:
\lstinline[language=Verilog
]{1337,
16'b0000010100111001,
1'b1,
1'bx
}
286 \item All bits of a wire or a selection of bits from a wire \\
287 \null\hskip1em For example:
\lstinline[language=Verilog
]{mywire, mywire
[24], mywire
[15:
8]}
288 \item Concatenations of the above \\
289 \null\hskip1em For example:
\lstinline[language=Verilog
]|
{16'd1337, mywire
[15:
8]}|
292 The RTLIL::SigSpec data type is used to represent signals. The RTLIL::Cell
293 object contains one RTLIL::SigSpec for each cell port.
295 In addition, connections between wires are represented using a pair of
296 RTLIL::SigSpec objects. Such pairs are needed in different locations. Therefore
297 the type name RTLIL::SigSig was defined for such a pair.
299 \subsection{RTLIL::Process
}
300 \label{sec:rtlil_process
}
302 When a high-level HDL frontend processes behavioural code it splits it up into
303 data path logic (e.g.~the expression
{\tt a + b
} is replaced by the output of an
304 adder that takes
{\tt a
} and
{\tt b
} as inputs) and an RTLIL::Process that models
305 the control logic of the behavioural code. Let's consider a simple example:
307 \begin{lstlisting
}[numbers=left,frame=single,language=Verilog
]
308 module ff_with_en_and_async_reset(clock, reset, enable, d, q);
309 input clock, reset, enable, d;
311 always @(posedge clock, posedge reset)
319 In this example there is no data path and therefore the RTLIL::Module generated by
320 the frontend only contains a few RTLIL::Wire objects and an RTLIL::Process.
321 The RTLIL::Process in RTLIL syntax:
323 \begin{lstlisting
}[numbers=left,frame=single,language=rtlil
]
324 process $proc$ff_with_en_and_async_reset.v:
4$
1
343 This RTLIL::Process contains two RTLIL::SyncRule objects, two RTLIL::SwitchRule
344 objects and five RTLIL::CaseRule objects. The wire
{\tt \$
0\textbackslash{}q
[0:
0]}
345 is an automatically created wire that holds the next value of
{\tt \textbackslash{}q
}. The lines
346 $
2 \dots 12$ describe how
{\tt \$
0\textbackslash{}q
[0:
0]} should be calculated. The
347 lines $
13 \dots 16$ describe how the value of
{\tt \$
0\textbackslash{}q
[0:
0]} is used
348 to update
{\tt \textbackslash{}q
}.
350 An RTLIL::Process is a container for zero or more RTLIL::SyncRule objects and
351 exactly one RTLIL::CaseRule object, which is called the
{\it root case
}.
353 An RTLIL::SyncRule object contains an (optional) synchronization condition (signal and edge-type), zero or
354 more assignments (RTLIL::SigSig), and zero or more memory writes (RTLIL::MemWriteAction).
355 The
{\tt always
} synchronization condition is used to break combinatorial
356 loops when a latch should be inferred instead.
358 An RTLIL::CaseRule is a container for zero or more assignments (RTLIL::SigSig)
359 and zero or more RTLIL::SwitchRule objects. An RTLIL::SwitchRule objects is a
360 container for zero or more RTLIL::CaseRule objects.
362 In the above example the lines $
2 \dots 12$ are the root case. Here
{\tt \$
0\textbackslash{}q
[0:
0]} is first
363 assigned the old value
{\tt \textbackslash{}q
} as default value (line
2). The root case
364 also contains an RTLIL::SwitchRule object (lines $
3 \dots 12$). Such an object is very similar to the C
{\tt switch
}
365 statement as it uses a control signal (
{\tt \textbackslash{}reset
} in this case) to determine
366 which of its cases should be active. The RTLIL::SwitchRule object then contains one RTLIL::CaseRule
367 object per case. In this example there is a case
\footnote{The
368 syntax
{\tt 1'
1} in the RTLIL code specifies a constant with a length of one bit (the first ``
1''),
369 and this bit is a one (the second ``
1'').
} for
{\tt \textbackslash{}reset ==
1} that causes
370 {\tt \$
0\textbackslash{}q
[0:
0]} to be set (lines
4 and
5) and a default case that in turn contains a switch that
371 sets
{\tt \$
0\textbackslash{}q
[0:
0]} to the value of
{\tt \textbackslash{}d
} if
{\tt
372 \textbackslash{}enable
} is active (lines $
6 \dots 11$).
374 A case can specify zero or more compare values that will determine whether it matches. Each of the compare values
375 must be the exact same width as the control signal. When more than one compare value is specified, the case matches
376 if any of them matches the control signal; when zero compare values are specified, the case always matches (i.e.
377 it is the default case).
379 A switch prioritizes cases from first to last: multiple cases can match, but only the first matched case becomes
380 active. This normally synthesizes to a priority encoder. The
{\tt parallel
\_case} attribute allows passes to assume
381 that no more than one case will match, and
{\tt full
\_case} attribute allows passes to assume that exactly one
382 case will match; if these invariants are ever dynamically violated, the behavior is undefined. These attributes
383 are useful when an invariant invisible to the synthesizer causes the control signal to never take certain
386 The lines $
13 \dots 16$ then cause
{\tt \textbackslash{}q
} to be updated whenever there is
387 a positive clock edge on
{\tt \textbackslash{}clock
} or
{\tt \textbackslash{}reset
}.
389 In order to generate such a representation, the language frontend must be able to handle blocking
390 and nonblocking assignments correctly. However, the language frontend does not need to identify
391 the correct type of storage element for the output signal or generate multiplexers for the
392 decision tree. This is done by passes that work on the RTLIL representation. Therefore it is
393 relatively easy to substitute these steps with other algorithms that target different target
394 architectures or perform optimizations or other transformations on the decision trees before
395 further processing them.
397 One of the first actions performed on a design in RTLIL representation in most
398 synthesis scripts is identifying asynchronous resets. This is usually done using the
{\tt proc
\_arst}
399 pass. This pass transforms the above example to the following RTLIL::Process:
401 \begin{lstlisting
}[numbers=left,frame=single,language=rtlil
]
402 process $proc$ff_with_en_and_async_reset.v:
4$
1
416 This pass has transformed the outer RTLIL::SwitchRule into a modified RTLIL::SyncRule object
417 for the
{\tt \textbackslash{}reset
} signal. Further processing converts the RTLIL::Process
418 into e.g.~a d-type flip-flop with asynchronous reset and a multiplexer for the enable signal:
420 \begin{lstlisting
}[numbers=left,frame=single,language=rtlil
]
421 cell $adff $procdff$
6
422 parameter
\ARST_POLARITY 1'
1
423 parameter
\ARST_VALUE 1'
0
424 parameter
\CLK_POLARITY 1'
1
440 Different combinations of passes may yield different results. Note that
{\tt \$adff
} and
{\tt
441 \$mux
} are internal cell types that still need to be mapped to cell types from the
444 Some passes refuse to operate on modules that still contain RTLIL::Process objects as the
445 presence of these objects in a module increases the complexity. Therefore the passes to translate
446 processes to a netlist of cells are usually called early in a synthesis script. The
{\tt proc
}
447 pass calls a series of other passes that together perform this conversion in a way that is suitable
448 for most synthesis tasks.
450 \subsection{RTLIL::Memory
}
451 \label{sec:rtlil_memory
}
453 For every array (memory) in the HDL code an RTLIL::Memory object is created. A
454 memory object has the following properties:
457 \item The memory name
458 \item A list of attributes
459 \item The width of an addressable word
460 \item The size of the memory in number of words
463 All read accesses to the memory are transformed to
{\tt \$memrd
} cells and all write accesses to
464 {\tt \$memwr
} cells by the language frontend. These cells consist of independent read- and write-ports
465 to the memory. Memory initialization is transformed to
{\tt \$meminit
} cells by the language frontend.
466 The
\B{MEMID
} parameter on these cells is used to link them together and to the RTLIL::Memory object they belong to.
468 The rationale behind using separate cells for the individual ports versus
469 creating a large multiport memory cell right in the language frontend is that
470 the separate
{\tt \$memrd
} and
{\tt \$memwr
} cells can be consolidated using resource sharing.
471 As resource sharing is a non-trivial optimization problem where different synthesis tasks
472 can have different requirements it lends itself to do the optimisation in separate passes and merge
473 the RTLIL::Memory objects and
{\tt \$memrd
} and
{\tt \$memwr
} cells to multiport memory blocks after resource sharing is completed.
475 The
{\tt memory
} pass performs this conversion and can (depending on the options passed
476 to it) transform the memories directly to d-type flip-flops and address logic or yield
477 multiport memory blocks (represented using
{\tt \$mem
} cells).
479 See Sec.~
\ref{sec:memcells
} for details about the memory cell types.
481 \section{Command Interface and Synthesis Scripts
}
483 Yosys reads and processes commands from synthesis scripts, command line arguments and
484 an interactive command prompt. Yosys commands consist of a command name and an optional
485 whitespace separated list of arguments. Commands are terminated using the newline character
486 or a semicolon (
{\tt ;
}). Empty lines and lines starting with the hash sign (
{\tt \#
}) are ignored.
487 See Sec.~
\ref{sec:typusecase
} for an example synthesis script.
489 The command
{\tt help
} can be used to access the command reference manual.
491 Most commands can operate not only on the entire design but also specifically on
{\it selected
}
492 parts of the design. For example the command
{\tt dump
} will print all selected objects
493 in the current design while
{\tt dump foobar
} will only print the module
{\tt foobar
}
494 and
{\tt dump *
} will print the entire design regardless of the current selection.
496 The selection mechanism is very powerful. For example the command
{\tt dump */t:\$add
497 \%x:+
[A
] */w:* \%i
} will print all wires that are connected to the
\B{A
} port of
498 a
{\tt \$add
} cell. Detailed documentation of the select framework can be
499 found in the command reference for the
{\tt select
} command.
501 \section{Source Tree and Build System
}
503 The Yosys source tree is organized into the following top-level directories:
507 \item {\tt backends/
} \\
508 This directory contains a subdirectory for each of the backend modules.
510 \item {\tt frontends/
} \\
511 This directory contains a subdirectory for each of the frontend modules.
513 \item {\tt kernel/
} \\
514 This directory contains all the core functionality of Yosys. This includes the
515 functions and definitions for working with the RTLIL data structures (
{\tt
516 rtlil.h
} and
{\tt rtlil.cc
}), the main() function (
{\tt driver.cc
}), the
517 internal framework for generating log messages (
{\tt log.h
} and
{\tt log.cc
}),
518 the internal framework for registering and calling passes (
{\tt register.h
} and
519 {\tt register.cc
}), some core commands that are not really passes (
{\tt
520 select.cc
},
{\tt show.cc
},
\dots) and a couple of other small utility libraries.
522 \item {\tt passes/
} \\
523 This directory contains a subdirectory for each pass or group of passes. For example as
524 of this writing the directory
{\tt passes/opt/
} contains the code for seven
525 passes:
{\tt opt
},
{\tt opt
\_expr},
{\tt opt
\_muxtree},
{\tt opt
\_reduce},
526 {\tt opt
\_rmdff},
{\tt opt
\_rmunused} and
{\tt opt
\_merge}.
528 \item {\tt techlibs/
} \\
529 This directory contains simulation models and standard implementations for the
530 cells from the internal cell library.
532 \item {\tt tests/
} \\
533 This directory contains a couple of test cases. Most of the smaller tests are executed
534 automatically when
{\tt make test
} is called. The larger tests must be executed
535 manually. Most of the larger tests require downloading external HDL source code
536 and/or external tools. The tests range from comparing simulation results of the synthesized
537 design to the original sources to logic equivalence checking of entire CPU cores.
542 The top-level Makefile includes
{\tt frontends/*/Makefile.inc
},
{\tt passes/*/Makefile.inc
}
543 and
{\tt backends/*/Makefile.inc
}. So when extending Yosys it is enough to create
544 a new directory in
{\tt frontends/
},
{\tt passes/
} or
{\tt backends/
} with your sources
545 and a
{\tt Makefile.inc
}. The Yosys kernel automatically detects all commands linked with
546 Yosys. So it is not needed to add additional commands to a central list of commands.
549 Good starting points for reading example source code to learn how to write passes
550 are
{\tt passes/opt/opt
\_rmdff.cc
} and
{\tt passes/opt/opt
\_merge.cc
}.
552 See the top-level README file for a quick
{\it Getting Started
} guide and build
553 instructions. The Yosys build is based solely on Makefiles.
555 Users of the Qt Creator IDE can generate a QT Creator project file using
{\tt
556 make qtcreator
}. Users of the Eclipse IDE can use the ``Makefile Project with
557 Existing Code'' project type in the Eclipse ``New Project'' dialog (only
558 available after the CDT plugin has been installed) to create an Eclipse project
559 in order to programming extensions to Yosys or just browse the Yosys code base.