mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-11-03 21:09:12 +00:00
Code Activity

Reorganising documentation

Browse source 
Also changing to furo theme.
This commit is contained in:
Krystine Sherwin 2023-08-03 09:20:29 +12:00
parent 4f1cd66829
commit 045c04096e
No known key found for this signature in database
40 changed files with 661 additions and 1282 deletions
Download patch file Download diff file Expand all files Collapse all files

141
docs/source/CHAPTER_Approach.rst
View file

@ -1,141 +0,0 @@
.. _chapter:approach:
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.
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 :numref:`Fig. %s
<fig:approach_flow>`).
.. figure:: ../images/approach_flow.*
:class: width-helper
:name: fig:approach_flow
General data- and control-flow of a synthesis tool
The first subsystem to be called is usually called a 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 produce data for
the next subsystems (usually in the same or a similar format) are called 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 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.
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
AST and is generated by the Verilog Frontend. This data structure is consumed by
a subsystem called AST Frontend [1]_. 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:
- The passes can be rearranged in a different order and passes can be removed
or inserted.
- 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 performs all changes in place.
- 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.
The RTLIL representation is basically a netlist representation with the
following additional features:
- 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).
- Support for multi-bit values that can use individual bits from wires as well
as constant bits to represent coarse-grain netlists.
- Support for basic behavioural constructs (if-then-else structures and
multi-case switches with a sensitivity list for updating the outputs).
- Support for multi-port memories.
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 unsupported 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.
.. _sec:typusecase:
Typical use case
----------------
The following example script may be used in a synthesis flow to convert the
behavioural Verilog code from the input file design.v to a gate-level netlist
synth.v using the cell library described by the Liberty file :
.. code:: yoscrypt
:number-lines:
# read input file to 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
A detailed description of the commands available in Yosys can be found in
:ref:`cmd_ref`.
.. [1]
In Yosys the term pass is only used to refer to commands that operate on the
RTLIL data structure.

233
docs/source/CHAPTER_Eval.rst
View file

@ -1,233 +0,0 @@
.. _chapter:eval:
Evaluation, conclusion, future Work
===================================
The Yosys source tree contains over 200 test cases [1]_ which are used
in the make test make-target. Besides these there is an external Yosys
benchmark and test case package that contains a few larger designs .
This package contains the designs listed in
Tab. \ `[tab:yosys-test-designs] <#tab:yosys-test-designs>`__.
.. table:: Tests included in the yosys-tests package.
=========== ========= ================
======================================================
Test-Design Source Gates Description / Comments
=========== ========= ================
======================================================
aes_core IWLS2005 :math:`41{,}837` AES Cipher written by Rudolf Usselmann
i2c IWLS2005 :math:`1{,}072` WISHBONE compliant I2C Master by Richard Herveille
openmsp430 OpenCores :math:`7{,}173` MSP430 compatible CPU by Olivier Girard
or1200 OpenCores :math:`42{,}675` The OpenRISC 1200 CPU by Damjan Lampret
sasc IWLS2005 :math:`456` Simple Async. Serial Comm. Device by Rudolf Usselmann
simple_spi IWLS2005 :math:`690` MC68HC11E based SPI interface by Richard Herveille
spi IWLS2005 :math:`2{,}478` SPI IP core by Simon Srot
ss_pcm IWLS2005 :math:`279` PCM IO Slave by Rudolf Usselmann
systemcaes IWLS2005 :math:`6{,}893` AES core (using SystemC to Verilog) by Javier Castillo
usb_phy IWLS2005 :math:`515` USB 1.1 PHY by Rudolf Usselmann
=========== ========= ================
======================================================
Correctness of synthesis results
--------------------------------
The following measures were taken to increase the confidence in the
correctness of the Yosys synthesis results:
- Yosys comes with a large selection [2]_ of small test cases that are
evaluated when the command 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 happened,
an appropriate test case was added to the collection of small test
cases for make test to ensure better testability of the feature in
question in the future.
- The designs listed in
Tab. \ `[tab:yosys-test-designs] <#tab:yosys-test-designs>`__ where
validated using the formal verification tool Synopsys 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 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. \ `[tab:yosys-test-designs] <#tab:yosys-test-designs>`__
validate successfully using Formality.
- VlogHammer is a set of scripts that auto-generate a large collection
of test cases [3]_ and synthesize them using Yosys and the following
freely available proprietary synthesis tools.
- Xilinx Vivado WebPack (2013.2)
- Xilinx ISE (XST) WebPack (14.5)
- Altera Quartus II Web Edition (13.0)
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. [4]_ 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.
- Xilinx ISIM (from Xilinx ISE 14.5 )
- Modelsim 10.1d (from Quartus II 13.0 )
- Icarus Verilog (no specific version)
The set of tests performed by VlogHammer systematically verify the
correct behaviour of
- Yosys Verilog Frontend and RTL generation
- Yosys Gate-Level Technology Mapping
- Yosys SAT Models for RTL- and Gate-Level cells
- Yosys Constant Evaluator Models for RTL- and Gate-Level cells
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).
Although complex software can never be expected to be fully bug-free
:cite:p:`MURPHY`, it has been shown that Yosys is mature and
feature-complete enough to handle most real-world cases correctly.
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:
::
hierarchy -check
proc; opt; fsm; opt; memory; opt
techmap; opt; abc; opt
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:
::
-p artix7
-use_dsp48 NO
-iobuf NO
-ram_extract NO
-rom_extract NO
-fsm_extract YES
-fsm_encoding Auto
The results of this comparison is summarized in
Tab. \ `[tab:synth-test] <#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.
.. table:: Synthesis results (as reported by XST) for OpenMSP430 and
OpenRISC 1200
============================ ==== ==== ========== ==== =====
==========
\
Module Regs LUTs Max. Freq. Regs LUTs Max. Freq.
openMSP430 689 2210 71 MHz 719 2779 53 MHz
1em omsp_clock_module 21 30 645 MHz 21 30 644 MHz
1em 1em omsp_sync_cell 2 — 1542 MHz 2 — 1542 MHz
1em 1em omsp_sync_reset 2 — 1542 MHz 2 — 1542 MHz
1em omsp_dbg 143 344 292 MHz 149 430 353 MHz
1em 1em omsp_dbg_uart 76 135 377 MHz 79 139 389 MHz
1em omsp_execution_unit 266 911 80 MHz 266 1034 137 MHz
1em 1em omsp_alu — 202 — — 263 —
1em 1em omsp_register_file 231 478 285 MHz 231 506 293 MHz
1em omsp_frontend 115 340 178 MHz 118 527 206 MHz
1em omsp_mem_backbone 38 141 1087 MHz 38 144 1087 MHz
1em omsp_multiplier 73 397 129 MHz 102 1053 55 MHz
1em omsp_sfr 6 18 1023 MHz 6 20 1023 MHz
1em omsp_watchdog 24 53 362 MHz 24 70 360 MHz
or1200_top 7148 9969 135 MHz 7173 10238 108 MHz
1em or1200_alu — 681 — — 641 —
1em or1200_cfgr — 11 — — 11 —
1em or1200_ctrl 175 186 464 MHz 174 279 377 MHz
1em or1200_except 241 451 313 MHz 241 353 301 MHz
1em or1200_freeze 6 18 507 MHz 6 16 515 MHz
1em or1200_if 68 143 806 MHz 68 139 790 MHz
1em or1200_lsu 8 138 — 12 205 1306 MHz
1em 1em or1200_mem2reg — 60 — — 66 —
1em 1em or1200_reg2mem — 29 — — 29 —
1em or1200_mult_mac 394 2209 240 MHz 394 2230 241 MHz
1em 1em or1200_amultp2_32x32 256 1783 240 MHz 256 1770 241 MHz
1em or1200_operandmuxes 65 129 1145 MHz 65 129 1145 MHz
1em or1200_rf 1041 1722 822 MHz 1042 1722 581 MHz
1em or1200_sprs 18 432 724 MHz 18 469 722 MHz
1em or1200_wbmux 33 93 — 33 78 —
1em or1200_dc_top — 5 — — 5 —
1em or1200_dmmu_top 2445 1004 — 2445 1043 —
1em 1em or1200_dmmu_tlb 2444 975 — 2444 1013 —
1em or1200_du 67 56 859 MHz 67 56 859 MHz
1em or1200_ic_top 39 100 527 MHz 41 136 514 MHz
1em 1em or1200_ic_fsm 40 42 408 MHz 40 75 484 MHz
1em or1200_pic 38 50 1169 MHz 38 50 1177 MHz
1em or1200_tt 64 112 370 MHz 64 186 437 MHz
============================ ==== ==== ========== ==== =====
==========
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 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.
.. [1]
Most of this test cases are copied from HANA or the ASIC-WORLD
website .
.. [2]
At the time of this writing 269 test cases.
.. [3]
At the time of this writing over 6600 test cases.
.. [4]
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. \ \ `[cmd:sat] <#cmd:sat>`__ for details.
.. footbibliography::

96
docs/source/CHAPTER_Intro.rst
View file

@ -1,96 +0,0 @@
.. _chapter:intro:
Introduction
============
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.
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:p:`Verilog2005,VerilogSynth` and :abbr:`VHDL (VHSIC HDL, where
VHSIC is an acronym for Very-High-Speed Integrated Circuits)`
:cite:p:`VHDL,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:p:`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:p:`LogicSynthesis`. Lexing,
parsing and processing of computer languages :cite:p:`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 author's preference for Verilog over VHDL it was decided early on to
go for Verilog instead of VHDL [#]_. So the existing FOSS Verilog synthesis
tools were evaluated. 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.
Structure of this document
--------------------------
The structure of this document is as follows:
:numref:`Chapter %s <chapter:intro>` is this introduction.
:numref:`Chapter %s <chapter:basics>` covers a short introduction to the world
of HDL synthesis. Basic principles and the terminology are outlined in this
chapter.
:numref:`Chapter %s <chapter:approach>` gives the quickest possible outline to
how the problem of implementing a HDL synthesis tool is approached in the case
of Yosys.
:numref:`Chapter %s <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.
:numref:`Chapter %s <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.
:numref:`Chapter %s <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 :numref:`%s <chapter:verilog>`, :numref:`%s <chapter:opt>` and
:numref:`%s <chapter:techmap>` cover three important pieces of the synthesis
pipeline: The Verilog frontend, the optimization passes and the technology
mapping to the target architecture, respectively.
Various appendices, including a :ref:`cmd_ref`, complete this document.
.. [#]
A quick investigation into FOSS VHDL tools yielded similar grim results for
FOSS VHDL synthesis tools.

44
docs/source/_templates/page.html Normal file
View file

@ -0,0 +1,44 @@
{#
See https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/page.html for the original
block this is overwriting.
The part that is customized is between the "begin of custom part" and "end of custom part"
comments below. It uses the same styles as the existing right sidebar code.
#}
{% extends "furo/page.html" %}
{% block right_sidebar %}
<div class="toc-sticky toc-scroll">
{# begin of custom part #}
<div class="toc-title-container">
<span class="toc-title">
YosysHQ
</span>
</div>
<div class="toc-tree-container yosyshq-links" style="padding-bottom: 0">
<div class="toc-tree">
<ul>
<li></li>
<li><a class="reference external" href="https://yosyshq.readthedocs.io">Docs</a></li>
<li><a class="reference external" href="https://blog.yosyshq.com">Blog</a></li>
<li><a class="reference external" href="https://www.yosyshq.com">Website</a></li>
</ul>
</div>
</div>
{# end of custom part #}
{% if not furo_hide_toc %}
<div class="toc-title-container">
<span class="toc-title">
{{ _("On this page") }}
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
{{ toc }}
</div>
</div>
{% endif %}
</div>
{% endblock %}

22
docs/source/appendix.rst Normal file
View file

@ -0,0 +1,22 @@
Appendix
========
.. toctree::
:maxdepth: 2
:includehidden:
appendix/primer
appendix/auxlibs
appendix/auxprogs
appendix/APPNOTE_010_Verilog_to_BLIF.rst
appendix/APPNOTE_011_Design_Investigation.rst
appendix/APPNOTE_012_Verilog_to_BTOR.rst
bib
.. toctree::
:maxdepth: 1
:includehidden:
cmd_ref

410
docs/source/appendix/CHAPTER_StateOfTheArt.rst
View file

@ -1,410 +0,0 @@
.. _chapter:sota:
Evaluation of other OSS Verilog Synthesis Tools
===============================================
In this appendix [1]_ the existing FOSS Verilog synthesis tools [2]_ 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:
- Icarus Verilog [3]_
- Verilog-to-Routing (VTR) / Odin-II
:cite:p:`vtr2012}`:raw-latex:`\cite{Odin`
- HDL Analyzer and Netlist Architect (HANA)
- Verilog front-end to VIS (vl2mv) :cite:p:`Cheng93vl2mv:a`
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 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 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.
.. code:: verilog
:number-lines:
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
.. code:: verilog
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
[fig:StateOfTheArt_always12]
.. code:: verilog
:number-lines:
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
[fig:StateOfTheArt_always3]
.. _sec:blocking_nonblocking:
Always blocks and blocking vs. nonblocking assignments
------------------------------------------------------
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 (:math:`=`) and nonblocking
assignments (:math:`<=`) 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 (:math:`<=`) 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
:numref:`Fig. %s <fig:StateOfTheArt_always12>`
and :numref:`Fig. %s <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.
.. code:: verilog
:number-lines:
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
[fig:StateOfTheArt_arrays]
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:
::
ERROR: (File: always02.v) (Line number: 13)
You've defined the driver "count~0" twice
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:
::
ERROR: (File: always03.v) (Line number: 8)
ODIN doesn't handle blocking statements in Sequential blocks
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.
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
:numref:`Fig. %s <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.
.. code:: verilog
:number-lines:
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
[fig:StateOfTheArt_for]
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.
.. code:: verilog
:number-lines:
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
[fig:StateOfTheArt_gen]
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
:numref:`Fig. %s <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
:numref:`Fig. %s <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.
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.
Summary and Outlook
-------------------
Table \ :numref:`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 \ :numref:`<CHAPTER_eval>` contains a more detailed
evaluation of Yosys using real-world designs that are far out of reach
for any of the other tools discussed in this appendix.
…passed 2em …produced error 2em :math:`\skull` …incorrect output
[tab:StateOfTheArt_sum]
.. [1]
This appendix is an updated version of an unpublished student
research paper. :cite:p:`VerilogFossEval`
.. [2]
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.
.. [3]
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.)

2
docs/source/appendix/CHAPTER_Auxlibs.rst → docs/source/appendix/auxlibs.rst
View file

@ -17,7 +17,7 @@ BigInt
The files in ``libs/bigint/`` provide a library for performing arithmetic with
arbitrary length integers. It is written by Matt McCutchen.
The BigInt library is used for evaluating constant expressions, e.g. using the
The BigInt library is used for evaluating constant expressions, e.g. using the
ConstEval class provided in kernel/consteval.h.
See also: http://mattmccutchen.net/bigint/

4
docs/source/appendix/CHAPTER_Auxprogs.rst → docs/source/appendix/auxprogs.rst
View file

@ -9,7 +9,7 @@ yosys-config
The 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. See Sec. \ :numref:`chapter:prog` for details.
Yosys. See :ref:`chapter:prog` for details.
.. _sec:filterlib:
@ -17,7 +17,7 @@ yosys-filterlib
---------------
The yosys-filterlib tool is a small utility that can be used to strip or extract
information from a Liberty file. See :numref:`Sec. %s <sec:techmap_extern>` for
information from a Liberty file. See :ref:`sec:techmap_extern` for
details.
yosys-abc

30
docs/source/CHAPTER_Basics.rst → docs/source/appendix/primer.rst
View file

@ -3,8 +3,8 @@
.. _chapter:basics:
Basic principles
================
A primer on digital circuit synthesis
=====================================
This chapter contains a short introduction to the basic principles of digital
circuit synthesis.
@ -23,7 +23,7 @@ circuit to a functionally equivalent low-level representation of a circuit.
:numref:`Figure %s <fig:Basics_abstractions>` lists the different levels of
abstraction and how they relate to different kinds of synthesis.
.. figure:: ../images/basics_abstractions.*
.. figure:: ../../images/basics_abstractions.*
:class: width-helper
:name: fig:Basics_abstractions
@ -161,7 +161,7 @@ At 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
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.
@ -172,7 +172,7 @@ good) mapping of the logic gate netlist to an equivalent netlist of physically
available gate types.
The simplest approach to logic synthesis is two-level logic synthesis, where a
logic function is converted into a sum-of-products representation, e.g. using 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 cannot make efficient use of physical gates other than AND/NAND-, OR/NOR-
and NOT-Gates.
@ -196,7 +196,7 @@ 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
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.
@ -345,7 +345,7 @@ 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
(<=) can be used. The concept of blocking vs. non-blocking assignment is one of
the most misunderstood constructs in Verilog :cite:p:`Cummings00`.
The blocking assignment behaves exactly like an assignment in any imperative
@ -498,7 +498,7 @@ 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 :numref:`Fig. %s <fig:Basics_flow>`.
.. figure:: ../images/basics_flow.*
.. figure:: ../../images/basics_flow.*
:class: width-helper
:name: fig:Basics_flow
@ -515,8 +515,8 @@ 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).
(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
@ -572,7 +572,7 @@ of lexical tokens given in :numref:`Tab. %s <tab:Basics_tokens>`.
TOK_SEMICOLON \-
============== ===============
The lexer is usually generated by a lexer generator (e.g. flex ) from a
The lexer is usually generated by a lexer generator (e.g. flex ) from a
description file that is using regular expressions to specify the text pattern
that should match the individual tokens.
@ -586,7 +586,7 @@ 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. bison ) from a
parser is also typically generated by a code generator (e.g. bison ) from a
grammar description in Backus-Naur Form (BNF).
Let's consider the following BNF (in Bison syntax):
@ -597,7 +597,7 @@ Let's consider the following BNF (in Bison syntax):
assign_stmt: TOK_ASSIGN TOK_IDENTIFIER TOK_EQ expr TOK_SEMICOLON;
expr: TOK_IDENTIFIER | TOK_NUMBER | expr TOK_PLUS expr;
.. figure:: ../images/basics_parsetree.*
.. figure:: ../../images/basics_parsetree.*
:class: width-helper
:name: fig:Basics_parsetree
@ -610,7 +610,7 @@ whole as data structure in memory. Instead the parser calls user-specified code
snippets (so-called 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
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
@ -626,7 +626,7 @@ 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:p:`Dragonbook`
.. figure:: ../images/basics_ast.*
.. figure:: ../../images/basics_ast.*
:class: width-helper
:name: fig:Basics_ast

2
docs/source/cmd_ref.rst
View file

@ -8,4 +8,4 @@ Command line reference
:maxdepth: 1
:glob:
cmd/*
../cmd/*

34
docs/source/conf.py
View file

@ -7,11 +7,31 @@ author = 'YosysHQ GmbH'
copyright ='2022 YosysHQ GmbH'
# select HTML theme
html_theme = 'press'
html_theme = 'furo'
templates_path = ["_templates"]
html_logo = '../static/logo.png'
html_favicon = '../static/favico.png'
html_css_files = ['yosyshq.css', 'custom.css']
html_sidebars = {'**': ['util/searchbox.html', 'util/sidetoc.html']}
html_theme_options = {
"sidebar_hide_name": True,
"light_css_variables": {
"color-brand-primary": "#d6368f",
"color-brand-content": "#4b72b8",
"color-api-name": "#8857a3",
"color-api-pre-name": "#4b72b8",
"color-link": "#8857a3",
},
"dark_css_variables": {
"color-brand-primary": "#e488bb",
"color-brand-content": "#98bdff",
"color-api-name": "#8857a3",
"color-api-pre-name": "#4b72b8",
"color-link": "#be95d5",
},
}
# These folders are copied to the documentation's HTML output
html_static_path = ['../static', "../images"]
@ -20,14 +40,6 @@ html_static_path = ['../static', "../images"]
pygments_style = 'colorful'
highlight_language = 'none'
html_theme_options = {
'external_links' : [
('YosysHQ Docs', 'https://yosyshq.readthedocs.io'),
('Blog', 'https://blog.yosyshq.com'),
('Website', 'https://www.yosyshq.com'),
],
}
extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex']
# Ensure that autosectionlabel will produce unique names
@ -41,8 +53,6 @@ bibtex_bibfiles = ['literature.bib']
# unused docs
exclude_patterns = [
"CHAPTER_Eval.rst",
"appendix/CHAPTER_StateOfTheArt.rst"
"test_suites.rst"
]

14
docs/source/getting_started.rst
View file

@ -1,14 +0,0 @@
Getting started with Yosys
==========================
Installation
------------
Supported platforms
~~~~~~~~~~~~~~~~~~~
Introduction to scripting in Yosys
----------------------------------
Example(s)
----------

50
docs/source/getting_started/examples.rst Normal file
View file

@ -0,0 +1,50 @@
Example(s)
----------
.. _sec:typusecase:
Typical use case
~~~~~~~~~~~~~~~~
The following example script may be used in a synthesis flow to convert the
behavioural Verilog code from the input file design.v to a gate-level netlist
synth.v using the cell library described by the Liberty file :
.. code:: yoscrypt
:number-lines:
# read input file to 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
A detailed description of the commands available in Yosys can be found in
:ref:`cmd_ref`.

8
docs/source/getting_started/index.rst Normal file
View file

@ -0,0 +1,8 @@
Getting started with Yosys
==========================
.. toctree::
installation
scripting_intro
examples

63
docs/source/getting_started/installation.rst Normal file
View file

@ -0,0 +1,63 @@
Installation
------------
Supported platforms
~~~~~~~~~~~~~~~~~~~
Source tree and build system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Yosys source tree is organized into the following top-level
directories:
- | backends/
| This directory contains a subdirectory for each of the backend modules.
- | frontends/
| This directory contains a subdirectory for each of the frontend modules.
- | kernel/
| This directory contains all the core functionality of Yosys. This includes
the functions and definitions for working with the RTLIL data structures
(rtlil.h and rtlil.cc), the main() function (driver.cc), the internal
framework for generating log messages (log.h and log.cc), the internal
framework for registering and calling passes (register.h and register.cc),
some core commands that are not really passes (select.cc, show.cc, …) and a
couple of other small utility libraries.
- | passes/
| This directory contains a subdirectory for each pass or group of passes.
For example as of this writing the directory passes/opt/ contains the code
for seven passes: opt, opt_expr, opt_muxtree, opt_reduce, opt_rmdff,
opt_rmunused and opt_merge.
- | techlibs/
| This directory contains simulation models and standard implementations for
the cells from the internal cell library.
- | tests/
| This directory contains a couple of test cases. Most of the smaller tests
are executed automatically when 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.
The top-level Makefile includes frontends/\*/Makefile.inc,
passes/\*/Makefile.inc and backends/\*/Makefile.inc. So when extending Yosys it
is enough to create a new directory in frontends/, passes/ or backends/ with
your sources and a 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.
Good starting points for reading example source code to learn how to write
passes are passes/opt/opt_rmdff.cc and passes/opt/opt_merge.cc.
See the top-level README file for a quick Getting Started guide and build
instructions. The Yosys build is based solely on Makefiles.
Users of the Qt Creator IDE can generate a QT Creator project file using 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 in order to
programming extensions to Yosys or just browse the Yosys code base.

28
docs/source/getting_started/scripting_intro.rst Normal file
View file

@ -0,0 +1,28 @@
Scripting in Yosys
------------------
.. TODO: copypaste
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 separated list of arguments. Commands are
terminated using the newline character or a semicolon (;). Empty lines and lines
starting with the hash sign (#) are ignored. See :ref:`sec:typusecase` for an
example synthesis script.
The command ``help`` can be used to access the command reference manual.
Most commands can operate not only on the entire design but also specifically on
selected parts of the design. For example the command dump will print all
selected objects in the current design while dump foobar will only print the
module foobar and dump \* will print the entire design regardless of the current
selection.
.. code:: yoscrypt
dump */t:$add %x:+[A] \*/w:\* %i
The selection mechanism is very powerful. For example the command above will
print all wires that are connected to the ``\A`` port of a ``$add`` cell.
Detailed documentation of the select framework can be found in the command
reference for the ``select`` command.

82
docs/source/index.rst
View file

@ -1,82 +1,14 @@
:Abstract:
Most of today's 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 necessary to write a
custom HDL synthesis tool or add new features to an existing one. In
these 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 developed. 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 successfully verified
using formal verification and are comparable in quality to the results
produced by a commercial synthesis tool.
This document was originally published as bachelor thesis at the Vienna
University of Technology :cite:p:`BACC`.
================================================================================
Yosys manual
Yosys Open SYnthesis Suite
================================================================================
.. toctree::
:caption: New docs
:maxdepth: 3
introduction
getting_started
using_yosys
yosys_internals
.. test_suites
.. toctree::
:maxdepth: 2
:caption: Manual
:numbered:
CHAPTER_Intro
CHAPTER_Basics.rst
CHAPTER_Approach.rst
CHAPTER_Overview.rst
CHAPTER_CellLib.rst
CHAPTER_Prog.rst
CHAPTER_Verilog.rst
CHAPTER_Optimize.rst
CHAPTER_Techmap.rst
CHAPTER_Memorymap.rst
CHAPTER_Eval.rst
.. raw:: latex
\appendix
.. toctree::
:maxdepth: 2
:includehidden:
:caption: Appendix
appendix/CHAPTER_Auxlibs.rst
appendix/CHAPTER_Auxprogs.rst
appendix/CHAPTER_TextRtlil.rst
appendix/APPNOTE_010_Verilog_to_BLIF.rst
appendix/APPNOTE_011_Design_Investigation.rst
appendix/APPNOTE_012_Verilog_to_BTOR.rst
appendix/CHAPTER_StateOfTheArt.rst
bib
.. toctree::
:maxdepth: 1
:includehidden:
cmd_ref
getting_started/index
using_yosys/index
yosys_internals/index
test_suites
appendix

91
docs/source/introduction.rst
View file

@ -1,8 +1,99 @@
What is Yosys
=============
.. TODO: rewrite to not be a thesis abstract
:Abstract:
Most of today's 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 necessary to write a
custom HDL synthesis tool or add new features to an existing one. In
these 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 developed. 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 successfully verified
using formal verification and are comparable in quality to the results
produced by a commercial synthesis tool.
This document was originally published as bachelor thesis at the Vienna
University of Technology :cite:p:`BACC`.
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.
What you can do with Yosys
--------------------------
The extended Yosys universe
---------------------------
In no particular order:
- SBY for formal verification
- EQY for equivalence checking
- MCY for mutation coverage
History of Yosys
----------------
.. TODO: copypaste
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:p:`Verilog2005,VerilogSynth` and :abbr:`VHDL (VHSIC HDL, where
VHSIC is an acronym for Very-High-Speed Integrated Circuits)`
:cite:p:`VHDL,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:p:`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:p:`LogicSynthesis`. Lexing,
parsing and processing of computer languages :cite:p:`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 author's preference for Verilog over VHDL it was decided early on to
go for Verilog instead of VHDL [#]_. So the existing FOSS Verilog synthesis
tools were evaluated. 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.
.. [#]
A quick investigation into FOSS VHDL tools yielded similar grim results for
FOSS VHDL synthesis tools.

2
docs/source/requirements.txt
View file

@ -1,2 +1,2 @@
sphinx-press-theme
furo
sphinxcontrib-bibtex

25
docs/source/using_yosys.rst
View file

@ -1,25 +0,0 @@
Using Yosys (advanced)
======================
More scripting
--------------
Selections
~~~~~~~~~~
Note on show/viz
Troubleshooting
~~~~~~~~~~~~~~~
Memory map patterns
-------------------
Flows, command types, and order
-------------------------------
Synthesis granularity
~~~~~~~~~~~~~~~~~~~~~
Formal verification
~~~~~~~~~~~~~~~~~~~

9
docs/source/using_yosys/index.rst Normal file
View file

@ -0,0 +1,9 @@
Using Yosys (advanced)
======================
.. toctree::
:maxdepth: 2
more_scripting
memory_mapping
yosys_flows

0
docs/source/CHAPTER_Memorymap.rst → docs/source/using_yosys/memory_mapping.rst
View file

8
docs/source/using_yosys/more_scripting.rst Normal file
View file

@ -0,0 +1,8 @@
More scripting
--------------
.. toctree::
opt_passes
selections
troubleshooting

18
docs/source/CHAPTER_Optimize.rst → docs/source/using_yosys/opt_passes.rst
View file

@ -1,7 +1,9 @@
.. _chapter:opt:
Optimizations
=============
Optimization passes
===================
.. TODO: copypaste
Yosys employs a number of optimizations to generate better and cleaner results.
This chapter outlines these optimizations.
@ -34,7 +36,7 @@ The opt_expr pass
~~~~~~~~~~~~~~~~~
This pass performs const folding on the internal combinational cell types
described in :numref:`Chap. %s <chapter:celllib>`. This means a cell with all
described in :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.
@ -67,7 +69,7 @@ optimizing an $_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:p:`Verilog2005`.
according to Sec. 5.1.10 of IEEE Std. 1364-2005 :cite:p:`Verilog2005`.
The next two lines assume the value 0 for undef states. These two rules are only
used if no other substitutions are possible in the current module. If other
@ -189,7 +191,7 @@ using the ``\fsm_encoding`` attribute (unless ``\fsm_encoding`` is set to
fsm\_ passes operate on these $fsm cells. The fsm_map call finally replaces the
$fsm cells with RTL cells.
Note that these optimizations operate on an RTL netlist. I.e. the fsm pass
Note that these optimizations operate on an RTL netlist. I.e. the fsm pass
should be executed after the proc pass has transformed all RTLIL::Process
objects to RTL cells.
@ -254,7 +256,7 @@ 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 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.
@ -326,5 +328,5 @@ Yosys can perform multi-level combinational logic optimization on gate-level
netlists using the external program ABC . The abc pass extracts the
combinational gate-level parts of the design, passes it through ABC, and
re-integrates the results. The abc pass can also be used to perform other
operations using ABC, such as technology mapping (see :numref:`Sec %s
<sec:techmap_extern>` for details).
operations using ABC, such as technology mapping (see :ref:`sec:techmap_extern`
for details).

6
docs/source/using_yosys/selections.rst Normal file
View file

@ -0,0 +1,6 @@
Selections
~~~~~~~~~~
See :doc:`/cmd/select`
Also :doc:`/cmd/show`

4
docs/source/using_yosys/troubleshooting.rst Normal file
View file

@ -0,0 +1,4 @@
Troubleshooting
~~~~~~~~~~~~~~~
See :doc:`/cmd/bugpoint`

8
docs/source/using_yosys/yosys_flows.rst Normal file
View file

@ -0,0 +1,8 @@
Flows, command types, and order
-------------------------------
Synthesis granularity
~~~~~~~~~~~~~~~~~~~~~
Formal verification
~~~~~~~~~~~~~~~~~~~

23
docs/source/yosys_internals.rst
View file

@ -1,23 +0,0 @@
Yosys internals
===============
Control and data flow
---------------------
Frontends
~~~~~~~~~
Backends
~~~~~~~~
Passes
~~~~~~
RTLIL
-----
Techmap
-------
Writing extensions
------------------

16
docs/source/CHAPTER_Prog.rst → docs/source/yosys_internals/extensions.rst
View file

@ -1,7 +1,9 @@
.. _chapter:prog:
Programming Yosys extensions
============================
Writing extensions
==================
.. TODO: copypaste
This chapter contains some bits and pieces of information about
programming yosys extensions. Also consult the section on programming in
@ -15,11 +17,11 @@ The guidelines directory contains notes on various aspects of Yosys
development. The files GettingStarted and CodingStyle may be of
particular interest, and are reproduced here.
.. literalinclude:: temp/GettingStarted
.. literalinclude:: ../temp/GettingStarted
:language: none
:caption: guidelines/GettingStarted
.. literalinclude:: temp/CodingStyle
.. literalinclude:: ../temp/CodingStyle
:language: none
:caption: guidelines/CodingStyle
@ -30,17 +32,17 @@ The following is the complete code of the "stubsnets" example module. It
is included in the Yosys source distribution as
docs/source/CHAPTER_Prog/stubnets.cc.
.. literalinclude:: CHAPTER_Prog/stubnets.cc
.. literalinclude:: ../CHAPTER_Prog/stubnets.cc
:language: c++
:linenos:
:caption: docs/source/CHAPTER_Prog/stubnets.cc
.. literalinclude:: CHAPTER_Prog/Makefile
.. literalinclude:: ../CHAPTER_Prog/Makefile
:language: makefile
:linenos:
:caption: docs/source/CHAPTER_Prog/Makefile
.. literalinclude:: CHAPTER_Prog/test.v
.. literalinclude:: ../CHAPTER_Prog/test.v
:language: verilog
:linenos:
:caption: docs/source/CHAPTER_Prog/test.v

31
docs/source/yosys_internals/flow/control_and_data.rst Normal file
View file

@ -0,0 +1,31 @@
Control and data flow
=====================
.. TODO: copypaste
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 :numref:`Fig. %s
<fig:approach_flow>`).
.. figure:: ../../../images/approach_flow.*
:class: width-helper
:name: fig:approach_flow
General data- and control-flow of a synthesis tool
The first subsystem to be called is usually called a 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 produce data for
the next subsystems (usually in the same or a similar format) are called 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 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.

10
docs/source/yosys_internals/flow/index.rst Normal file
View file

@ -0,0 +1,10 @@
Internal flow
=============
.. toctree::
:maxdepth: 2
overview
control_and_data
verilog_frontend

48
docs/source/yosys_internals/flow/overview.rst Normal file
View file

@ -0,0 +1,48 @@
Flow overview
=============
.. TODO: copypaste
:numref:`Figure %s <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 RTLIL 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
RTLIL Backend for writing the RTLIL data in the same format that is understood
by the RTLIL Frontend.
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 to represent the
design in different stages of the synthesis.
.. figure:: ../../../images/overview_flow.*
:class: width-helper
:name: fig:Overview_flow
Yosys simplified data flow (ellipses: data structures, rectangles:
program modules)

12
docs/source/CHAPTER_Verilog.rst → docs/source/yosys_internals/flow/verilog_frontend.rst
View file

@ -9,7 +9,7 @@ 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 :numref:`Fig. %s <fig:Verilog_flow>`.
.. figure:: ../images/verilog_flow.*
.. figure:: ../../../images/verilog_flow.*
:class: width-helper
:name: fig:Verilog_flow
@ -167,7 +167,7 @@ properties:
- | Node content
| Each node might have additional content data. A series of member
variables exist to hold such data. For example the member
``std::string str`` can hold a string value and is used e.g. in the
``std::string str`` can hold a string value and is used e.g. in the
AST_IDENTIFIER node type to store the identifier name.
- | Source code location
@ -220,7 +220,7 @@ performs the following transformations on the AST data structure:
- Evaluate all ``generate``-statements and unroll all ``for``-loops.
- Perform const folding where it is necessary (e.g. in the value part
- Perform const folding where it is necessary (e.g. in the value part
of AST_PARAMETER, AST_LOCALPARAM, AST_PARASET and AST_RANGE nodes).
- Replace AST_PRIMITIVE nodes with appropriate AST_ASSIGN nodes.
@ -388,7 +388,7 @@ the following way:
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
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.
@ -397,7 +397,7 @@ the following way:
preserved with respect to the original AST and Verilog code.
- The whole ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree describes an
asynchronous circuit. I.e. the decision tree formed by the switches
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
@ -414,7 +414,7 @@ into the synchronization type (posedge) and signal (\\clock) for the
d-type flip-flops and the ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree
to a decision tree using multiplexers.
In more complex examples (e.g. asynchronous resets) the part of the
In more complex examples (e.g. asynchronous resets) the part of the
``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree that describes the
asynchronous reset must first be transformed to the correct
``RTLIL::SyncRule`` objects. This is done by the proc_adff pass.

8
docs/source/CHAPTER_CellLib.rst → docs/source/yosys_internals/formats/cell_library.rst
View file

@ -1,12 +1,14 @@
.. role:: verilog(code)
:language: Verilog
.. TODO: copypaste
.. _chapter:celllib:
Internal cell library
=====================
Most of the passes in Yosys operate on netlists, i.e. they only care about the
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.
@ -205,7 +207,7 @@ Behavioural code with cascaded if-then-else- and 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
trees (e.g. by replacing a multiplexer between a calculated signal and a
constant zero with an ``$and`` gate).
Registers
@ -814,7 +816,7 @@ techlibs/common/simcells.v in the Yosys source tree.
============== ============== =========
Tables \ :numref:`%s <tab:CellLib_gates>`, :numref:`%s
Tables \ :numref:`%s <tab:CellLib_gates>`, :numref:`%s
<tab:CellLib_gates_dffe>`, :numref:`%s <tab:CellLib_gates_adff>`, :numref:`%s
<tab:CellLib_gates_adffe>`, :numref:`%s <tab:CellLib_gates_dffsr>`, :numref:`%s
<tab:CellLib_gates_dffsre>`, :numref:`%s <tab:CellLib_gates_adlatch>`,

11
docs/source/yosys_internals/formats/index.rst Normal file
View file

@ -0,0 +1,11 @@
Internal formats
================
.. toctree::
:maxdepth: 2
overview
rtlil
rtlil_text
cell_library

53
docs/source/yosys_internals/formats/overview.rst Normal file
View file

@ -0,0 +1,53 @@
Format overview
===============
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
AST and is generated by the Verilog Frontend. This data structure is consumed by
a subsystem called AST Frontend [1]_. 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:
- The passes can be rearranged in a different order and passes can be removed
or inserted.
- 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 performs all changes in place.
- 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.
The RTLIL representation is basically a netlist representation with the
following additional features:
- 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).
- Support for multi-bit values that can use individual bits from wires as well
as constant bits to represent coarse-grain netlists.
- Support for basic behavioural constructs (if-then-else structures and
multi-case switches with a sensitivity list for updating the outputs).
- Support for multi-port memories.
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 unsupported 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.
.. [1]
In Yosys the term pass is only used to refer to commands that operate on the
RTLIL data structure.

189
docs/source/CHAPTER_Overview.rst → docs/source/yosys_internals/formats/rtlil.rst
View file

@ -1,90 +1,12 @@
.. _chapter:overview:
Implementation overview
=======================
Yosys is an extensible open source hardware synthesis tool. It is aimed at
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.
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`_, the
`openMSP430 CPU`_, the `OpenCores I2C master`_, and the `k68 CPU`_.
.. _OpenRISC 1200 CPU: https://github.com/openrisc/or1200
.. _openMSP430 CPU: http://opencores.org/projects/openmsp430
.. _OpenCores I2C master: http://opencores.org/projects/i2c
.. _k68 CPU: http://opencores.org/projects/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.
Simplified data flow
--------------------
:numref:`Figure %s <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 RTLIL 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
RTLIL Backend for writing the RTLIL data in the same format that is understood
by the RTLIL Frontend.
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 to represent the
design in different stages of the synthesis.
.. figure:: ../images/overview_flow.*
:class: width-helper
:name: fig:Overview_flow
Yosys simplified data flow (ellipses: data structures, rectangles:
program modules)
The RTL Intermediate Language (RTLIL)
-------------------------------------
=====================================
All frontends, passes and backends in Yosys operate on a design in RTLIL
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 reinventing names for the RTLIL classes, they are simply
referred to by their full C++ name, i.e. including the RTLIL:: namespace prefix,
referred to by their full C++ name, i.e. including the RTLIL:: namespace prefix,
in this document.
:numref:`Figure %s <fig:Overview_RTLIL>` shows a simplified Entity-Relationship
@ -101,14 +23,14 @@ 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.
.. figure:: ../images/overview_rtlil.*
.. figure:: ../../../images/overview_rtlil.*
:class: width-helper
:name: fig:Overview_RTLIL
Simplified RTLIL Entity-Relationship Diagram
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
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:
@ -133,7 +55,7 @@ The following sections contain a more detailed description of the different
parts of RTLIL and rationale behind some of the design decisions.
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
@ -183,7 +105,7 @@ flattening). All names specified in the "hdlname" attribute are public and do
not include the leading "\".
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
@ -220,7 +142,7 @@ hash string.)
.. _sec:rtlil_cell_wire:
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
@ -265,7 +187,7 @@ each cell port. The RTLIL::SigSpec data type is described in the next section.
.. _sec:rtlil_sigspec:
RTLIL::SigSpec
~~~~~~~~~~~~~~
--------------
A "signal" is everything that can be applied to a cell port. I.e.
@ -288,10 +210,10 @@ the type name RTLIL::SigSig was defined for such a pair.
.. _sec:rtlil_process:
RTLIL::Process
~~~~~~~~~~~~~~
--------------
When a high-level HDL frontend processes behavioural code it splits it up into
data path logic (e.g. the expression a + b is replaced by the output of an adder
data path logic (e.g. the expression a + b is replaced by the output of an adder
that takes a and b as inputs) and an RTLIL::Process that models the control
logic of the behavioural code. Let's consider a simple example:
@ -412,7 +334,7 @@ RTLIL::Process:
This pass has transformed the outer RTLIL::SwitchRule into a modified
RTLIL::SyncRule object for the \\reset signal. Further processing converts the
RTLIL::Process into e.g. a d-type flip-flop with asynchronous reset and a
RTLIL::Process into e.g. a d-type flip-flop with asynchronous reset and a
multiplexer for the enable signal:
.. code:: RTLIL
@ -450,7 +372,7 @@ synthesis tasks.
.. _sec:rtlil_memory:
RTLIL::Memory
~~~~~~~~~~~~~
-------------
For every array (memory) in the HDL code an RTLIL::Memory object is created. A
memory object has the following properties:
@ -479,92 +401,7 @@ The 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 $mem cells).
See :numref:`Sec. %s <sec:memcells>` for details about the memory cell types.
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 separated list of arguments. Commands are
terminated using the newline character or a semicolon (;). Empty lines and lines
starting with the hash sign (#) are ignored. See :numref:`Sec. %s
<sec:typusecase>` for an example synthesis script.
The command help can be used to access the command reference manual.
Most commands can operate not only on the entire design but also specifically on
selected parts of the design. For example the command dump will print all
selected objects in the current design while dump foobar will only print the
module foobar and dump \* will print the entire design regardless of the current
selection.
.. code:: yoscrypt
dump */t:$add %x:+[A] \*/w:\* %i
The selection mechanism is very powerful. For example the command above will
print all wires that are connected to the ``\A`` port of a ``$add`` cell.
Detailed documentation of the select framework can be found in the command
reference for the ``select`` command.
Source tree and build system
----------------------------
The Yosys source tree is organized into the following top-level
directories:
- | backends/
| This directory contains a subdirectory for each of the backend modules.
- | frontends/
| This directory contains a subdirectory for each of the frontend modules.
- | kernel/
| This directory contains all the core functionality of Yosys. This includes
the functions and definitions for working with the RTLIL data structures
(rtlil.h and rtlil.cc), the main() function (driver.cc), the internal
framework for generating log messages (log.h and log.cc), the internal
framework for registering and calling passes (register.h and register.cc),
some core commands that are not really passes (select.cc, show.cc, …) and a
couple of other small utility libraries.
- | passes/
| This directory contains a subdirectory for each pass or group of passes.
For example as of this writing the directory passes/opt/ contains the code
for seven passes: opt, opt_expr, opt_muxtree, opt_reduce, opt_rmdff,
opt_rmunused and opt_merge.
- | techlibs/
| This directory contains simulation models and standard implementations for
the cells from the internal cell library.
- | tests/
| This directory contains a couple of test cases. Most of the smaller tests
are executed automatically when 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.
The top-level Makefile includes frontends/\*/Makefile.inc,
passes/\*/Makefile.inc and backends/\*/Makefile.inc. So when extending Yosys it
is enough to create a new directory in frontends/, passes/ or backends/ with
your sources and a 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.
Good starting points for reading example source code to learn how to write
passes are passes/opt/opt_rmdff.cc and passes/opt/opt_merge.cc.
See the top-level README file for a quick Getting Started guide and build
instructions. The Yosys build is based solely on Makefiles.
Users of the Qt Creator IDE can generate a QT Creator project file using 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 in order to
programming extensions to Yosys or just browse the Yosys code base.
See :ref:`sec:memcells` for details about the memory cell types.
.. [1]
The syntax 1'1 in the RTLIL code specifies a constant with a length of one

53
docs/source/appendix/CHAPTER_TextRtlil.rst → docs/source/yosys_internals/formats/rtlil_text.rst
View file

@ -1,7 +1,7 @@
.. _chapter:textrtlil:
RTLIL text representation
=========================
-------------------------
This appendix documents the text representation of RTLIL in extended Backus-Naur
form (EBNF).
@ -17,10 +17,10 @@ Finally, note that all statements (rules ending in ``-stmt``) terminate in an
end-of-line. Because of this, a statement cannot be broken into multiple lines.
Lexical elements
----------------
~~~~~~~~~~~~~~~~
Characters
~~~~~~~~~~
^^^^^^^^^^
An RTLIL file is a stream of bytes. Strictly speaking, a "character" in an RTLIL
file is a single byte. The lexer treats multi-byte encoded characters as
@ -37,7 +37,7 @@ An ``eol`` is one or more consecutive ASCII newlines (10) and carriage returns
(13).
Identifiers
~~~~~~~~~~~
^^^^^^^^^^^
There are two types of identifiers in RTLIL:
@ -51,7 +51,7 @@ There are two types of identifiers in RTLIL:
<autogen-id> ::= $ <nonws>+
Values
~~~~~~
^^^^^^
A *value* consists of a width in bits and a bit representation, most
significant bit first. Bits may be any of:
@ -76,7 +76,7 @@ error.
<integer> ::= -? <decimal-digit>+
Strings
~~~~~~~
^^^^^^^
A string is a series of characters delimited by double-quote characters. Within
a string, any character except ASCII NUL (0) may be used. In addition, certain
@ -94,13 +94,13 @@ character. Thus:
- ``\r``: An 'r' character
Comments
~~~~~~~~
^^^^^^^^
A comment starts with a ``#`` character and proceeds to the end of the line. All
comments are ignored.
File
----
~~~~
A file consists of an optional autoindex statement followed by zero or more
modules.
@ -110,7 +110,7 @@ modules.
<file> ::= <autoidx-stmt>? <module>*
Autoindex statements
~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^
The autoindex statement sets the global autoindex value used by Yosys when it
needs to generate a unique name, e.g. ``flattenN``. The N part is filled with
@ -123,7 +123,7 @@ would have different properties than just running a pass on a warm design.
<autoidx-stmt> ::= autoidx <integer> <eol>
Modules
~~~~~~~
^^^^^^^
Declares a module, with zero or more attributes, consisting of zero or more
wires, memories, cells, processes, and connections.
@ -142,7 +142,7 @@ wires, memories, cells, processes, and connections.
<module-end-stmt> ::= end <eol>
Attribute statements
~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^
Declares an attribute with the given identifier and value.
@ -151,7 +151,7 @@ Declares an attribute with the given identifier and value.
<attr-stmt> ::= attribute <id> <constant> <eol>
Signal specifications
~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^
A signal is anything that can be applied to a cell port, i.e. a constant value,
all bits or a selection of bits from a wire, or concatenations of those.
@ -161,8 +161,7 @@ all bits or a selection of bits from a wire, or concatenations of those.
``32'11111111111111111111111111111111``, while a constant of :math:`1` is the
same as ``32'1``.
See :numref:`Sec. %s <sec:rtlil_sigspec>` for an overview of signal
specifications.
See :ref:`sec:rtlil_sigspec` for an overview of signal specifications.
.. code:: BNF
@ -172,7 +171,7 @@ specifications.
| { <sigspec>* }
Connections
~~~~~~~~~~~
^^^^^^^^^^^
Declares a connection between the given signals.
@ -181,12 +180,12 @@ Declares a connection between the given signals.
<conn-stmt> ::= connect <sigspec> <sigspec> <eol>
Wires
~~~~~
^^^^^
Declares a wire, with zero or more attributes, with the given identifier and
options in the enclosing module.
See :numref:`Sec. %s <sec:rtlil_cell_wire>` for an overview of wires.
See :ref:`sec:rtlil_cell_wire` for an overview of wires.
.. code:: BNF
@ -202,13 +201,13 @@ See :numref:`Sec. %s <sec:rtlil_cell_wire>` for an overview of wires.
| signed
Memories
~~~~~~~~
^^^^^^^^
Declares a memory, with zero or more attributes, with the given identifier and
options in the enclosing module.
See :numref:`Sec. %s <sec:rtlil_memory>` for an overview of memory cells, and
:numref:`Sec. %s <sec:memcells>` for details about memory cell types.
See :ref:`sec:rtlil_memory` for an overview of memory cells, and
:ref:`sec:memcells` for details about memory cell types.
.. code:: BNF
@ -219,13 +218,13 @@ See :numref:`Sec. %s <sec:rtlil_memory>` for an overview of memory cells, and
| offset <integer>
Cells
~~~~~
^^^^^
Declares a cell, with zero or more attributes, with the given identifier and
type in the enclosing module.
Cells perform functions on input signals. See :numref:`Chap. %s
<chapter:celllib>` for a detailed list of cell types.
Cells perform functions on input signals. See :ref:`chapter:celllib` for a
detailed list of cell types.
.. code:: BNF
@ -239,13 +238,13 @@ Cells perform functions on input signals. See :numref:`Chap. %s
Processes
~~~~~~~~~
^^^^^^^^^
Declares a process, with zero or more attributes, with the given identifier in
the enclosing module. The body of a process consists of zero or more
assignments, exactly one switch, and zero or more syncs.
See :numref:`Sec. %s <sec:rtlil_process>` for an overview of processes.
See :ref:`sec:rtlil_process` for an overview of processes.
.. code:: BNF
@ -258,7 +257,7 @@ See :numref:`Sec. %s <sec:rtlil_process>` for an overview of processes.
<proc-end-stmt> ::= end <eol>
Switches
~~~~~~~~
^^^^^^^^
Switches test a signal for equality against a list of cases. Each case specifies
a comma-separated list of signals to check against. If there are no signals in
@ -277,7 +276,7 @@ attributes.
<switch-end-stmt> ::= end <eol>
Syncs
~~~~~
^^^^^
Syncs update signals with other signals when an event happens. Such an event may
be:

41
docs/source/yosys_internals/index.rst Normal file
View file

@ -0,0 +1,41 @@
.. _chapter:overview:
Yosys internals
===============
.. TODO: copypaste
Yosys is an extensible open source hardware synthesis tool. It is aimed at
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.
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`_, the
`openMSP430 CPU`_, the `OpenCores I2C master`_, and the `k68 CPU`_.
.. _OpenRISC 1200 CPU: https://github.com/openrisc/or1200
.. _openMSP430 CPU: http://opencores.org/projects/openmsp430
.. _OpenCores I2C master: http://opencores.org/projects/i2c
.. _k68 CPU: http://opencores.org/projects/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.
.. toctree::
flow/index
formats/index
techmap
extensions
.. TODO: copypaste

14
docs/source/CHAPTER_Techmap.rst → docs/source/yosys_internals/techmap.rst
View file

@ -1,5 +1,7 @@
.. _chapter:techmap:
.. TODO: copypaste
Technology mapping
==================
@ -10,8 +12,8 @@ transformed into a functionally equivalent netlist utilizing 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 :numref:`Sec.
%s <sec:celllib_gates>`). In the second phase this netlist of internal gate
cells are mapped to an internal library of single-bit cells (see
: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
@ -33,7 +35,7 @@ reader may find this map file as techlibs/common/techmap.v in the Yosys source
tree.
Additional features have been added to techmap to allow for conditional mapping
of cells (see :doc:`cmd/techmap`). This can for example be useful if the target
of cells (see :doc:`/cmd/techmap`). This can for example be useful if the target
architecture supports hardware multipliers for certain bit-widths but not for
others.
@ -52,14 +54,14 @@ cell type but only combinations of cells.
For these cases Yosys provides the 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
identical (i.e. isomorphic subcircuits) to any of the given modules. These
matched subcircuits are then replaced by instances of the given modules.
The extract pass also finds basic variations of the given modules, such as
swapped inputs on commutative cell types.
In addition to this the extract pass also has limited support for frequent
subcircuit mining, i.e. the process of finding recurring subcircuits in the
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:p:`intersynthFdlBookChapter`.
@ -77,7 +79,7 @@ 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 .
Mapping a design utilizing the Yosys internal gate library (e.g. as a result of
Mapping a design utilizing the Yosys internal gate library (e.g. as a result of
mapping it to this representation using the techmap pass) is performed in two
phases.