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..0d107f1 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -7,6 +7,7 @@ SymbiFlow documentation
introduction
fasm-specification
+ toolchain-desc
symbiflow-arch-defs/docs/source/index
prjxray/docs/index
prjtrellis/docs/index
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..669a4e1
--- /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
+ toolchain-desc/vpr
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/vpr.rst b/source/toolchain-desc/vpr.rst
new file mode 100644
index 0000000..f8c375e
--- /dev/null
+++ b/source/toolchain-desc/vpr.rst
@@ -0,0 +1,170 @@
+Versatile Place and Route
+=========================
+
+Versatile Place and Route (VPR) is an open-source CAD tool that
+implements different placing and routing algorithms for FPGAs. It can be used
+to prepare a description of a complete chip configuration
+from a given logic design.
+
+As its input, the VPR takes the netlist specified in the `BLIF
+file format `_
+and `architecture definition `_
+in the XML file. The whole process of generating configuration is described in
+`FPGA Design Flow <./design-flow.html>`_. One of the most important goals of
+the SymbiFlow Toolchain is to provide accurate `architecture definitions
+<../symbiflow-arch-defs/docs/source/index.html>`__ that are needed in the
+Place and Route process.
+
+Summary
+-------
+
+The Place and Route process in VPR consists of a few steps:
+
+- Packing (combining primitives into complex logic blocks)
+- Placing (placement of complex block inside FPGA)
+- Routing (planning interconnections between blocks)
+- Analysis
+
+Each of these steps provides additional configuration options that can be used
+for customizing the whole process. Detailed description is avaliable on the
+project website in the `VPR section `_ of the VTR documentation.
+
+Packing
+-------
+
+The packing algorithm tries to combine primitive logic blocks into groups,
+called Complex Logic Blocks. The results from the packing process are written
+into a ``.net`` file. It contains a description of complex blocks with their
+inputs, outputs, used clocks and relations to other signals.
+It can be useful in analyzing how VPR packs primitives together.
+
+A detailed description of the ``.net`` file format can be found in the `VPR documentation
+`_.
+
+Placing
+-------
+
+This step assigns a location to the Complex Logic Block onto the FPGA.
+The output from this step is written in the ``.place`` file, which contains
+the physical location of the blocks from the ``.net`` file.
+
+The File has the following format:
+
+.. code-block:: bash
+
+ block_name x y subblock_number
+
+where ``x`` and ``y`` are positions in VPR grid and ``block_name`` comes from
+the ``.net`` file.
+
+Example placing file:
+
+.. code-block::
+
+ Netlist_File: top.net Netlist_ID: SHA256:ce5217d251e04301759ee5a8f55f67c642de435b6c573148b67c19c5e054c1f9
+ Array size: 149 x 158 logic blocks
+
+ #block name x y subblk block number
+ #---------- -- -- ------ ------------
+ $auto$alumacc.cc:474:replace_alu$24.slice[1].carry4_full 53 32 0 #0
+ $auto$alumacc.cc:474:replace_alu$24.slice[2].carry4_full 53 31 0 #1
+ $auto$alumacc.cc:474:replace_alu$24.slice[3].carry4_full 53 30 0 #2
+ $auto$alumacc.cc:474:replace_alu$24.slice[4].carry4_full 53 29 0 #3
+ $auto$alumacc.cc:474:replace_alu$24.slice[5].carry4_full 53 28 0 #4
+ $auto$alumacc.cc:474:replace_alu$24.slice[6].carry4_part 53 27 0 #5
+ $auto$alumacc.cc:474:replace_alu$24.slice[0].carry4_1st_full 53 33 0 #6
+ out:LD7 9 5 0 #7
+ clk 42 26 0 #8
+ $false 35 26 0 #9
+
+Detailed description of the ``.place`` file format can be found in the `VPR documentation
+`_.
+
+Routing
+-------
+
+This step connects the placed Complex Logic Blocks together,
+according to the netlist specifications and the routing resources
+of the FPGA chip. The description of the routing resources is
+provided in the `architecture definition file
+`__.
+Starting from the architecture definition, VPR generates the Resource
+Routing Graph. SymbiFlow provides a complete graph file for each architecture.
+This `precompiled` file can be directly injected into the routing process.
+The output from this step is written into ``.route`` file.
+
+The file describes each connection from input to its output through
+different routing resources of FPGA. Each net starts with a ``SOURCE`` node and
+ends in a ``SINK`` node. The node name describes the kind of routing resource.
+The pair of numbers in round brackets provides information on the (x, y)
+resource location on the VPR grid. The additional field provides information
+for a specific kind of node.
+
+Example routing file may look similar:
+
+.. code-block::
+
+ Placement_File: top.place Placement_ID: SHA256:88d45f0bf7999e3f9331cdfd3497d0028be58ffa324a019254c2ae7b4f5bfa7a
+ Array size: 149 x 158 logic blocks.
+
+ Routing:
+
+ Net 0 (counter[4])
+
+ Node: 203972 SOURCE (53,32) Class: 40 Switch: 0
+ Node: 204095 OPIN (53,32) Pin: 40 BLK-TL-SLICEL.CQ[0] Switch: 189
+ Node: 1027363 CHANY (52,32) Track: 165 Switch: 7
+ Node: 601704 CHANY (52,32) Track: 240 Switch: 161
+ Node: 955959 CHANY (52,32) to (52,33) Track: 90 Switch: 130
+ Node: 955968 CHANY (52,32) Track: 238 Switch: 128
+ Node: 955976 CHANY (52,32) Track: 230 Switch: 131
+ Node: 601648 CHANY (52,32) Track: 268 Switch: 7
+ Node: 1027319 CHANY (52,32) Track: 191 Switch: 183
+ Node: 203982 IPIN (53,32) Pin: 1 BLK-TL-SLICEL.A2[0] Switch: 0
+ Node: 203933 SINK (53,32) Class: 1 Switch: -1
+
+ Net 1 ($auto$alumacc.cc:474:replace_alu$24.O[6])
+ ...
+
+A detailed description of the ``.route`` file format can be found in the `VPR documentation
+`_.
+
+FASM file
+---------
+
+SymbiFlow makes use of an additional tool provided by VPR, called
+`genfasm `_.
+In fact, genfasm translates the routed design into a FASM format file.
+This file provides the description of the implemented design in terms of
+features that need to be enabled or disabled in the FPGA chip.
+
+These changes are made with respect to the default FPGA configuration.
+Due to that, empty FASM file sets the FPGA to the default configuration.
+
+FASM file contains lines in the format:
+
+.. code-block::
+
+ YYYY.XXXXX [A:B] = C
+
+which corresponds respectively to the feature ID, feature address
+and the feature value. The feature ID unambiguously describes the location of
+the resource that needs to be modified. Within this resource, may exists several
+bits that determine its behaviour. The feature address specifies the set of bits
+in the resource that will be changed to the chosen feature value.
+
+Example of a FASM line:
+
+.. code-block::
+
+ CLBLM_R_X41Y31.SLICEL_X1.ALUT.INIT[63:32]=32'b11110000111100001111000011110000
+
+will initialize the bits ``[63:32]`` of ``ALUT.INIT`` feature, located in the
+``SLICEL_X1`` of the ``CLBLM_R_X41Y31`` tile with the
+``32'b11110000111100001111000011110000`` value.
+
+It is worth to mention that only the feature ID is necessary and setting feature
+value to ``0`` means that feature has a default setting not that it is disabled.
+
+A detailed description of FASM file format used in SymbiFlow could be found
+in the `FASM specification <../used-standards/fasm-specification.html>`_.
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.