diff --git a/.gitmodules b/.gitmodules
index 3f4cfbd..0dcbfef 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -9,3 +9,9 @@
[submodule "source/prjxray"]
path = source/prjxray
url = ../prjxray
+[submodule "source/fasm"]
+ path = source/fasm
+ url = ../fasm
+[submodule "source/vtr-verilog-to-routing"]
+ path = source/vtr-verilog-to-routing
+ url = ../vtr-verilog-to-routing
diff --git a/source/fasm b/source/fasm
new file mode 160000
index 0000000..b8db365
--- /dev/null
+++ b/source/fasm
@@ -0,0 +1 @@
+Subproject commit b8db36518534a7c204f80d785a893055258205cb
diff --git a/source/fasm-specification.rst b/source/fasm-specification.rst
deleted file mode 100644
index 6ca45d6..0000000
--- a/source/fasm-specification.rst
+++ /dev/null
@@ -1,217 +0,0 @@
-FPGA ASM (FASM) Specification
-=============================
-
-Introduction
-------------
-
-The FASM is a file format designed to specify the bits in an FPGA bitstream that need to be set (e.g. binary 1) or cleared (e.g. binary 0).
-
-A FASM file declares that specific "Features" within the bitstream should be enabled. Enabling a feature will cause bits within the bitstream to be set or cleared.
-
-A FASM file is illegal if a bit in the final bitstream must be set and cleared to respect the set of features specified in the FASM file.
-
-An empty FASM file will generate a platform specific "default" bitstream. The FASM file will specify zero or more features that mutate the "default" bitstream into the target bitstream.
-
-File Syntax description
------------------------
-
-FASM is a line oriented format.
-
-* A single FASM line will do nothing (blank or comments or annotations) or enable a set of features.
-* The FASM file format does not support line continuations. Enabling a feature will always be contained within one line.
-* Constants and arrays follow verilog syntax
-
-Due to the line orientated format, a FASM file has the following properties:
-
-* Removing a line from a FASM file, produces a FASM file.
-* Concatenating two FASM files together, produces a FASM file.
-* Sorting a FASM file does not change the resulting bitstream.
-
-If two FASM files are identical, then the resulting bitstream should have identical set of features are enabled. FASM does support various equivalent forms for enabling features, so there is a "canonical" form of a FASM file that removes this variation. If the canonical forms of two FASM files are the same, then they must generate the same bitstream.
-
-Lines
-+++++
-
-Examples FASM feature lines
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Canonical enabling of feature
-`````````````````````````````
-
-.. code-block:: text
-
- # Set a single feature bit to 1 (with an implicit 1)
- INT_L_X10Y146.SW6BEG0.WW2END0
- CLBLL_L_X12Y124.SLICEL_X0.BLUT.INIT[17]
-
-Recommended bitarray
-````````````````````
-
-.. code-block:: text
-
- # Setting a bitarray
- CLBLL_R_X13Y132.SLICEL_X0.ALUT.INIT[63:32] = 32'b11110000111100001111000011110000
-
-Permitted advanced variations
-`````````````````````````````
-
-.. code-block:: text
-
- # The bitarray syntax also allows explicit 1 and explicit 0, if verbosity is desired.
- # An explicit 1 is the same as an implicit 1.
- INT_L_X10Y146.SW6BEG0.WW2END0 = 1
- CLBLL_L_X12Y124.SLICEL_X0.BLUT.INIT[17] = 1
- # Explicit bit range to 1
- INT_L_X10Y146.SW6BEG0.WW2END0[0:0] = 1'b1
- CLBLL_L_X12Y124.SLICEL_X0.BLUT.INIT[17:17] = 1'b1
-
- # An explicit 0 has no effect on the bitstream output.
- INT_L_X10Y146.SW6BEG0.WW2END0 = 0
- CLBLL_L_X12Y124.SLICEL_X0.BLUT.INIT[17] = 0
- # Explicit bit range to 0
- INT_L_X10Y146.SW6BEG0.WW2END0[0:0] = 1'b0
- CLBLL_L_X12Y124.SLICEL_X0.BLUT.INIT[17:17] = 1'b0
-
-Annotations
-+++++++++++
-
-To allow tools to output machine usable annotations (e.g. compiler metadata), annotations are supported. Annotations can be on the line with a FASM feature, or on a line by itself. An annotations must not change the output bitstream. If an annotation would have an affect on the output bitstream, it should be a FASM feature.
-
-Annotations that are on the same line as a FASM feature are associated with the feature. Annotations that are on a line with no FASM feature as associated with the FASM file itself.
-
-Example Annotations
-~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: text
-
- # Annotation on a FASM feature
- INT_L_X10Y146.SW6BEG0.WW2END0 { .attr = "" }
- INT_L_X10Y146.SW6BEG0.WW2END0 { .filename = "/a/b/c.txt" }
- INT_L_X10Y146.SW6BEG0.WW2END0 { module = "top", file = "/a/b/d.txt", line_number = "123" }
-
- # Annotation by itself
- { .top_module = "/a/b/c/d.txt" }
-
- # Annotation with FASM feature and comment
- INT_L_X10Y146.SW6BEG0.WW2END0 { .top_module = "/a/b/c/d.txt" } # This is a comment
-
-Formal syntax specification of a line of a FASM file
-++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. code-block:: text
-
- Identifier ::= [a-zA-Z] [0-9a-zA-Z]*
- Feature ::= Identifier ( '.' Identifier )*
- S ::= #x9 | #x20
-
- DecimalValue ::= [0-9_]*
- HexidecimalValue ::= [0-9a-fA-F_]+
- OctalValue ::= [0-7_]+
- BinaryValue ::= [01_]+
-
- VerilogValue ::= (( DecimalValue? S* "'" ( 'h' S* HexidecimalValue | 'b' S* BinaryValue | 'd' S* DecimalValue | 'o' S* OctalValue ) | DecimalValue )
-
- FeatureAddress ::= '[' DecimalValue (':' DecimalValue)? ']'
-
- Any ::= [^#xA#]
- Comment ::= '#' Any*
-
- AnnotationName ::= [.a-zA-Z] [_0-9a-zA-Z]*
- NonEscapeCharacters ::= [^\"]
- EscapeSequences ::= '\\' | '\"'
- Annotation ::= AnnotationName S* '=' S* '"' (NonEscapeCharacters | EscapeSequences)* '"'
- Annotations ::= '{' S* Annotation ( ',' S* Annotation )* S* '}'
-
- SetFasmFeature ::= Feature FeatureAddress? S* ('=' S* VerilogValue)?
- FasmLine ::= S* SetFasmFeature? S* Annotations? S* Comment?
-
-Canonicalization
-++++++++++++++++
-
-If two FASM files have been canonicalized, then they enable an identical set of features. The canonical FASM file is also equivalent to the FASM file that would be generated by taking the output bitstream and converting it back into a FASM file.
-
-The canonicalization process is as follows:
-
-#. Flatten any ``FeatureAddress`` with width greater than 1.
-
- * For ``SetFasmFeature`` lines with a ``FeatureAddress`` width greater than 1 bit, 1 ``SetFasmFeature`` for the width the original ``FeatureAddress``.
- * When flattening, if the flattened address is 0, do not emit the address.
-#. Remove all comments and annotations.
-#. If the ``FeatureValue`` is 0, remove the FASM line.
-#. If the ``FeatureValue`` is 1, only output the ``Feature`` and the ``FeatureAddress`` if the ``Feature`` has addresses other than 0.
-#. Remove any lines that do not modify the default bitstream.
-
- * Example are psuedo-pips in Xilinx parts.
-#. Sort the lines in the FASM file.
-
-Example Canonicalization
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-``ALUT.INIT[0] = 1``
-
-becomes
-
-``ALUT.INIT``
-
-----
-
-``ALUT.SMALL = 1``
-
-becomes
-
-``ALUT.SMALL``
-
-----
-
-``ALUT.INIT[3:0] = 4'b1101``
-
-becomes
-
-``ALUT.INIT``
-
-``ALUT.INIT[2]``
-
-``ALUT.INIT[3]``
-
-Meaning of a FASM line
-----------------------
-
-.. csv-table:: Simplified ``SetFasmFeature``
- :delim: |
- :header-rows: 1
-
- YYYY.XXXXX | [A:B] | = C
- ``Feature`` | ``FeatureAddress`` | ``FeatureValue``
- **Required** | *Optional* | *Optional*
-
-Each line of a FASM file that enables a feature is defined by a ``SetFasmFeature``. Table 1 provides a simplified ``SetFasmFeature`` parse has three parts, the feature to be set (``Feature``), the address within the feature to be set (``FeatureAddress``) and the value of the feature (``FeatureValue``). Both the ``FeatureAddress`` and ``FeatureValue`` are optional.
-
-When a FASM file declares that a feature is to be enabled or disabled, then specific bits in the bitstream will be cleared or set.
-
-This section describes how the state of the bits are determined.
-
-Feature
-+++++++
-
-The ``Feature`` should uniquely specify a feature within the bitstream. If the feature is repeated across FPGA elements, a prefix identifier is required to uniquely identify where a feature is located.
-
-For example all SLICEL tiles have ALUT.INIT feature, however each tile CLBLL_L tile actually have two SLICEL, and there are many CLBLL_L tiles with a 7-series FPGA. So a unique path would required to both clarify which tile is being set, and which SLICEL within the tile is being set.
-
-FeatureAddress and FeatureValue
-+++++++++++++++++++++++++++++++
-
-If the ``FeatureAddress`` is not specified, then the address selected is 0.
-
-If the ``FeatureValue`` is not specified, then the value is 1.
-
-If the ``FeatureAddress`` is specified as a specific bit rather than a range (e.g. "[5]"), then the ``FeatureValue`` width must be 1-bit wide (e.g. 0 or 1). If the ``FeatureAddress`` is a range (e.g. "[15:0]"), then the ``FeatureValue`` width must be equal or less than the ``FeatureAddress`` width. It is invalid to specific a ``FeatureValue`` wider than the ``FeatureAddress``.
-
-For example, if the ``FeatureAddress`` was [15:0], then the address width is 16 bits, and the ``FeatureValue`` must be 16 bits or less. So a ``FeatureValue`` of 16'hFFFF is valid, but a ``FeatureValue`` of 17'h10000 is invalid.
-
-When the ``FeatureAddress`` is wider than 1 bit, the ``FeatureValue`` is shifted and masked for each specific address before enabling or disabling the feature. So for a ``FeatureAddress`` of [7:4], the feature at address 4 is set with a value of (``FeatureValue`` >> 0) & 1, and the feature at address 5 is set with a value of (``FeatureValue`` >> 1) & 1, etc.
-
-If the value of a feature is 1, then the output bitstream must clear and set all bits as specified.
-If the value of a feature is 0, then no change to the "default" bitstream is made.
-
-Note that the absence of a FASM feature line does not imply that the feature is set to 0. It only means that the relevant bits are used from the implementation specific "default" bitstream.
-
diff --git a/source/images/EDA.svg b/source/images/EDA.svg
new file mode 100644
index 0000000..f278a9c
--- /dev/null
+++ b/source/images/EDA.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/source/images/parts.svg b/source/images/parts.svg
new file mode 100644
index 0000000..97296de
--- /dev/null
+++ b/source/images/parts.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/source/images/toolchain-flow.svg b/source/images/toolchain-flow.svg
new file mode 100644
index 0000000..1355658
--- /dev/null
+++ b/source/images/toolchain-flow.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/source/index.rst b/source/index.rst
index 3348b9f..7c99cf8 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -6,7 +6,8 @@ SymbiFlow documentation
:maxdepth: 3
introduction
- fasm-specification
+ toolchain-desc
symbiflow-arch-defs/docs/source/index
prjxray/docs/index
prjtrellis/docs/index
+ fasm/docs/specification
diff --git a/source/introduction.rst b/source/introduction.rst
index 789e745..2b87743 100644
--- a/source/introduction.rst
+++ b/source/introduction.rst
@@ -1,8 +1,84 @@
Introduction
============
-This is the documentation for the SymbiFlow open FPGA toolchain project.
+SymbiFlow is a Open Source Verilog-to-Bitstream FPGA synthesis flow,
+currently targeting Xilinx 7-Series, Lattice iCE40 and Lattice ECP5 FPGAs.
+Think of it as the GCC of FPGAs.
-A useful diagram that explains the relationship between various parts/files/programs of the project:
+The project aim is to design tools that are highly extendable and multiplatform.
-https://docs.google.com/drawings/d/1GwzV6Rs0gbiGI4DznWwG4000BLOcsuYYgYQ0YDqgXHY/edit
+EDA Tooling Ecosystem
+---------------------
+
+For both ASIC- and FPGA-oriented EDA tooling, there are three major areas that
+the workflow needs to cover: hardware description, frontend and backend.
+
+Hardware description languages are generally open, with both established HDLs
+such as Verilog and VHDL and emerging software-inspired paradigms like
+`Chisel `_,
+`SpinalHDL `_ or
+`Migen `_.
+The major problem lies however in the front- and backend, where previously
+there was no established standard, vendor-neutral tooling that would cover
+all the necessary components for an end-to-end flow.
+
+This pertains both to ASIC and FPGA workflows, although SymbiFlow focuses
+on the latter (some parts of SymbiFlow will also be useful in the former).
+
+.. figure:: images/EDA.svg
+
+Project structure
+-----------------
+
+To achieve SymbiFlow's goal of a complete FOSS FPGA toolchain,
+a number of tools and projects are necessary to provide all the needed
+components of an end-to-end flow. Thus, SymbiFlow serves as an umbrella
+project for several activities, the central of which pertains to the
+creation of so-called FPGA "architecture definitions",
+i.e. documentation of how specific FPGAs work internally.
+More information can be found in the :doc:`Symbiflow Architecture Definitions
+<../symbiflow-arch-defs/docs/source/index>` project.
+
+Those definitions and serve as input to backend tools like
+`nextpnr `_ and
+`Verilog to Routing `_, and frontend tools
+like `Yosys `_. They are created within separate
+collaborating projects targeting different FPGAs - :doc:`Project X-Ray
+<../prjxray/docs/index>` for Xilinx 7-Series, `Project IceStorm
+`_ for Lattice iCE40 and :doc:`Project Trellis
+<../prjtrellis/docs/index>` for Lattice ECP5 FPGAs.
+
+.. figure:: images/parts.svg
+
+Current status of bitstream documentation
+-----------------------------------------
+
+.. table::
+ :align: center
+ :widths: 40 20 20 20
+
+ +-----------------+----------+----------+---------+
+ | Projects | IceStorm | X-Ray | Trellis |
+ +=================+==========+==========+=========+
+ | **Basic Tiles** |
+ +-----------------+----------+----------+---------+
+ | Logic | Yes | Yes | Yes |
+ +-----------------+----------+----------+---------+
+ | Block RAM | Yes | Partial | N/A |
+ +-----------------+----------+----------+---------+
+ | **Advanced Tiles** |
+ +-----------------+----------+----------+---------+
+ | DSP | Yes | No | Yes |
+ +-----------------+----------+----------+---------+
+ | Hard Blocks | Yes | No | Yes |
+ +-----------------+----------+----------+---------+
+ | Clock Tiles | Yes | Partial | Yes |
+ +-----------------+----------+----------+---------+
+ | IO Tiles | Yes | Partial | Yes |
+ +-----------------+----------+----------+---------+
+ | **Routing** |
+ +-----------------+----------+----------+---------+
+ | Logic | Yes | Yes | Yes |
+ +-----------------+----------+----------+---------+
+ | Clock | Yes | Partial | Yes |
+ +-----------------+----------+----------+---------+
diff --git a/source/symbiflow-arch-defs b/source/symbiflow-arch-defs
index 9c494d1..f25b843 160000
--- a/source/symbiflow-arch-defs
+++ b/source/symbiflow-arch-defs
@@ -1 +1 @@
-Subproject commit 9c494d1f43f87330d7eb3a7e6063f39b0933722b
+Subproject commit f25b843cd5fd28807a74188302d197db17119ea0
diff --git a/source/toolchain-desc.rst b/source/toolchain-desc.rst
new file mode 100644
index 0000000..9608ba4
--- /dev/null
+++ b/source/toolchain-desc.rst
@@ -0,0 +1,13 @@
+Toolchain description
+=====================
+
+This section provides a description of the Symbiflow toolchain
+as well as the basic concepts of the FPGA design flow.
+
+.. toctree::
+ :maxdepth: 3
+
+ symbiflow-arch-defs/docs/source/getting-started
+ toolchain-desc/design-flow
+ toolchain-desc/yosys
+ vtr-verilog-to-routing/doc/src/vpr/index
diff --git a/source/toolchain-desc/design-flow.rst b/source/toolchain-desc/design-flow.rst
new file mode 100644
index 0000000..d17f337
--- /dev/null
+++ b/source/toolchain-desc/design-flow.rst
@@ -0,0 +1,159 @@
+FPGA Design Flow
+================
+
+SymbiFlow is an end-to-end FPGA synthesis toolchain, because of that it provides
+all the necessary tools to convert input Verilog design into a final bitstream.
+It is simple to use however, the whole synthesis and implementation process
+is not trivial.
+
+The final bitstream format depends on the used platform.
+What's more, every platform has different resources and even if some of them
+provide similar functionality, they can be implemented in a different way.
+In order to be able to match all that variety of possible situations,
+the creation of the final bitstream is divided into few steps.
+SymbiFlow uses different programs to create the bitstream and is
+responsible for their proper integration. The procedure of converting
+Verilog file into the bitstream is described in the next sections.
+
+.. figure:: ../images/toolchain-flow.svg
+ :align: center
+
+ Symbiflow Toolchain design flow
+
+Synthesis
+---------
+
+Synthesis is the process of converting input Verilog file into a netlist,
+which describes the connections between different block available on the
+desired FPGA chip. However, it is worth to notice that these are only
+logical connections. So the synthesized model is only a draft of the final
+design, made with the use of available resources.
+
+RTL Generation
+++++++++++++++
+
+the input Verilog file is often really complicated. Usually it is written in
+a way that it is hard to distinguish the digital circuit standing behind
+the implemented functionality. Designers often use a so-called
+*Behavioral Level* of abstraction, in their designs, which means that the whole
+description is mostly event-driven. In Verilog, support for behavioral models
+is made with use of ``always`` statements.
+
+However, FPGA mostly consist of Look Up Tables (LUT) and flip-flops.
+Look Up Tables implement only the functionality of logic gates.
+Due to that, the synthesis process has to convert the complicated
+Behavioral model to a simpler description.
+
+Firstly, the design is described in terms of registers and logical operations.
+This is the so-called *Register-Transfer Level* (*RTL*).
+Secondly, in order to simplify the design even more, some complex logic is
+rewritten in the way that the final result contain only logic gates
+and registers. This model is on *Logical Gate level* of abstraction.
+
+The process of simplification is quite complicated, because of that it often
+demands additional simulations between mentioned steps to prove that the input
+design is equivalent to its simplified form.
+
+Technology mapping
+++++++++++++++++++
+
+FPGAs from different architectures may have different architecture. For example,
+they may contain some complicated functional blocks (i.e. RAM, DSP blocks)
+and even some of the basic blocks like LUT tables and flip-flops may vary
+between chips. Because of that, there is a need to describe the final design
+in terms of platform-specific resources. This is the next step in the process
+of synthesis. The simplified description containing i.e. logic gates, flip-flops
+and a few more complicated blocks like RAM is taken and used "general" blocks
+are substituted with that physically located in the chosen FPGA.
+The vendor-specific definitions of these blocks are often located
+in a separate library.
+
+Optimization
+++++++++++++
+
+Optimization is the key factor that allows to better utilize resources
+of an FPGA. There are some universal situations in which the design
+can be optimized, for example by substituting a bunch of logic gates
+in terms of fewer, different gates. However, some operations can be performed
+only after certain steps i.e. after technology mapping.
+As a result, optimization is an integral part of most of the synthesis steps.
+
+Synthesis in SymbiFlow
+++++++++++++++++++++++
+
+In the SymbiFlow toolchain synthesis is made with the use of Yosys,
+that is able to perform all the mentioned steps and convert Verilog to netlist
+description. The result of these steps is written to a file in ``.eblif``
+format.
+
+Place & Route
+-------------
+
+The Synthesis process results in an output containing logical elements
+available on the desired FPGA chip with the specified connections between them.
+However, it does not specify the physical layout of those elements in the
+final design. The goal of the Place and Route (PnR) process is to take the
+synthesized design and implement it into the target FPGA device. The PnR tool
+needs to have information about the physical composition of the device, routing
+paths between the different logical blocks and signal propagation timings.
+The working flow of different PnR tools may vary, however, the process presented
+below represents the typical one, adopted by most of these tools. Usually, it
+consists of four steps - packing, placing, routing and analysis.
+
+Packing
++++++++
+
+In the first step, the tool collects and analyzes the primitives present
+in the synthesized design (e.g. Flip-Flops, Muxes, Carry-chains, etc), and
+organizes them in clusters, each one belonging to a physical tile of the device.
+The PnR tool makes the best possible decision, based on the FPGA routing
+resources and timings between different points in the chip.
+
+Placing
++++++++
+
+After having clustered all the various primitives into the physical tiles of the
+device, the tool begins the placement process. This step consists in assigning a
+physical location to every cluster generated in the packing stage. The choice of
+the locations is based on the chosen algorithm and on the user's parameters, but
+generally, the final goal is to find the best placement that allows the routing
+step to find more optimal solutions.
+
+Routing
++++++++
+
+Routing is one of the most demanding tasks of the the whole process.
+All possible connections between the placed blocks and the information on
+the signals propagation timings, form a complex graph.
+The tool tries to find the optimal path connecting all the placed
+clusters using the information provided in the routing graph. Once all the nets
+have been routed, an output file containing the implemented design is produced.
+
+Analysis
+++++++++
+
+This last step usually checks the whole design in terms of timings and power
+consumption.
+
+Place & Route in SymbiFlow
+++++++++++++++++++++++++++
+
+The SymbiFlow Project uses two different tools for the PnR process - ``nextpnr``
+and ``Versatile Place and Route`` (VPR). Both of them write their final result
+to a file in the ``.fasm`` format.
+
+Bitstream translation
+---------------------
+
+The routing process results in an output file specifying the used blocks
+and routing paths. It contains the resources that needs to be instantiated
+on the FPGA chip, however, the output format is not understood
+by the FPGA chip itself.
+
+In the last step, the description of the chip is translated into
+the appropriate format, suitable for the chosen FPGA.
+That final file contains instructions readable by the configuration block of
+the desired chip.
+
+Documenting the bitstream format for different FPGA chips is one of the
+most important tasks in the SymbiFlow Project!
diff --git a/source/toolchain-desc/yosys.rst b/source/toolchain-desc/yosys.rst
new file mode 100644
index 0000000..de70a6b
--- /dev/null
+++ b/source/toolchain-desc/yosys.rst
@@ -0,0 +1,136 @@
+Yosys
+=====
+
+Yosys is a Free and Open Source Verilog HDL synthesis tool. It was designed
+to be highly extensible and multiplatform. In SymbiFlow toolchain,
+it is responsible for the whole synthesis process described in `FPGA Design Flow
+<./design-flow.html>`_
+
+It is not necessary to call Yosys directly using the SymbiFlow
+toolchain. Nevertheless, the following description, should provide
+sufficient introduction to Yosys usage inside the project.
+It is also a good starting point for a deeper understanding of the whole
+Toolchain.
+
+Short description
+-----------------
+
+Yosys consists of several subsystems. Most distinguishable are the
+first and last one used in the synthesis process, called respectively
+*frontend* and *backend*. Intermediate subsystems are called *passes*.
+
+The *frontend* is responsible for changing the Verilog input file into
+internal Yosys, representation which is common for all *passes* used
+by the program. The *passes* are responsible for variety of optimizations
+(``opt_``) and simplifications (``proc_``).
+
+Two *passes*, that are worth
+to mention separately are ``ABC`` and ``techmap``. The first one optimizes
+logic functions from the design and assigns obtained results into Look Up Tables
+(LUTs) of chosen width. The second mentioned *pass* - ``techmap``
+is responsible for mapping the synthesized design from Yosys internal
+blocks to that located on FPGA chip including i.e. RAM, DSP and LUTs.
+Recommended synthesis flows for different FPGAs are combined into
+macros i.e. ``synth_ice40`` (for Lattice iCE40 FPGA) or ``synth_xilinx``
+(for Xilinx 7-series FPGAs).
+
+The *backend* on the other hand, is responsible
+for converting internal Yosys representation into one of the standardized
+formats. Symbiflow uses ``.eblif`` as its output file format.
+
+Usage in Toolchain
+------------------
+
+All operations performed by Yosys are written in ``.tcl`` script. Commands used
+in the scripts are responsible for preparing output file to match with the
+expectations of other toolchain tools.
+There is no need to change it even for big designs.
+Example of configuration script can be found below:
+
+.. code-block:: tcl
+
+ yosys -import
+
+ synth_ice40 -nocarry
+
+ opt_expr -undriven
+ opt_clean
+
+ setundef -zero -params
+ write_blif -attr -cname -param $::env(OUT_EBLIF)
+ write_verilog $::env(OUT_SYNTH_V)
+
+It can be seen that this script perform a platform-specific process of
+synthesis, some optimization steps (``opt_`` commands), and writes the final file in
+``.eblif`` and Verilog formats. Yosys synthesis configuration scripts are platform-specific
+and can by found in ``/yosys/synth.tcl``
+in `Symbiflow Architecture Definitions `_
+repository.
+
+To understand performed operations it is worth to look at log file. Usually it
+is generated in the project build directory. It should be named ``top.eblif.log``.
+
+Output analysis
+---------------
+
+Input file:
+
+.. code-block:: verilog
+
+ module top (
+ input clk,
+ output LD7,
+ );
+ localparam BITS = 1;
+ localparam LOG2DELAY = 25;
+
+ reg [BITS+LOG2DELAY-1:0] counter = 0;
+ always @(posedge clk) begin
+ counter <= counter + 1;
+ end
+
+ assign {LD7} = counter >> LOG2DELAY;
+ endmodule
+
+
+after synthesis is described only with use of primitives appropriate for
+chosen platform:
+
+.. code-block:: verilog
+
+ module top(clk, LD7);
+ wire [25:0] _000_;
+ wire _001_;
+
+ ...
+
+ FDRE_ZINI #(
+ .IS_C_INVERTED(1'h0),
+ .ZINI(1'h1)
+ ) _073_ (
+ .C(clk),
+ .CE(_012_),
+ .D(_000_[0]),
+ .Q(counter[0]),
+ .R(_013_)
+ );
+
+ ...
+
+ SR_GND _150_ (
+ .GND(_062_)
+ );
+ assign _003_[25:0] = _000_;
+ assign counter[25] = LD7;
+ endmodule
+
+The same structure is described by the ``.eblif`` file.
+
+More information
+----------------
+
+Additional information about Yosys can be found on the `Yosys Project Website
+`_ , or in `Yosys Manual
+`_. You can also compile
+one of the tests described in Getting Started section and watch the log file
+to understand which operations are performed by Yosys.
diff --git a/source/vtr-verilog-to-routing b/source/vtr-verilog-to-routing
new file mode 160000
index 0000000..80ae77e
--- /dev/null
+++ b/source/vtr-verilog-to-routing
@@ -0,0 +1 @@
+Subproject commit 80ae77ed4254782d220ed89261c8ca31d3a7c2ff