Hardware
/
f4pga
mirror of https://github.com/chipsalliance/f4pga.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: reorganise 

Signed-off-by: Unai Martinez-Corral <umartinezcorral@antmicro.com>
This commit is contained in:
Unai Martinez-Corral 2022-03-10 10:46:21 +01:00
parent cb160a26a0
commit f56547ea60
13 changed files with 249 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/community.rst Normal file
View File

@ -0,0 +1,4 @@
Community
#########
*TBC*

15
docs/flows/bitstream.rst Normal file
View File

@ -0,0 +1,15 @@
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 F4PGA Project!

15
docs/flows/f4pga.rst Normal file
View File

@ -0,0 +1,15 @@
In F4PGA
########
Synthesis
=========
In the F4PGA toolchain synthesis is made with the use of Yosys, that is able to perform all the mentioned steps and
convert HDL to netlist description.
The result of these steps is written to a file in ``.eblif`` format.
Place & Route
=============
The F4PGA 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.

21
docs/flows/index.rst Normal file
View File

@ -0,0 +1,21 @@
Introduction
============
This section provides a description of the F4PGA toolchain as well as the basic concepts of the FPGA design flow.
F4PGA is an end-to-end FPGA synthesis toolchain, because of that it provides all the necessary tools to convert input
Hardware Description Language (HDL) sources 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.
F4PGA uses different programs to create the bitstream and is responsible for their proper integration.
The procedure of converting HDL files into the bitstream is described in the next sections.
.. figure:: ../_static/images/toolchain-flow.svg
:align: center
F4PGA Toolchain design flow

48
docs/flows/pnr.rst Normal file
View File

@ -0,0 +1,48 @@
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.

57
docs/flows/synthesis.rst Normal file
View File

@ -0,0 +1,57 @@
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.

6
docs/getting-started.rst Normal file
View File

@ -0,0 +1,6 @@
Getting started
###############
*TBC*
* For developers ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/getting-started.html>

46
docs/introduction.rst → docs/how.rst
View File

@ -1,14 +1,8 @@
Introduction
============
F4PGA 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.
The project aim is to design tools that are highly extendable and multiplatform.
How it works
############
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.
@ -28,7 +22,7 @@ on the latter (some parts of F4PGA will also be useful in the former).
.. figure:: _static/images/EDA.svg
Project structure
-----------------
=================
To achieve F4PGA'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.
@ -47,35 +41,3 @@ collaborating projects targeting different FPGAs - :doc:`Project X-Ray
.. figure:: _static/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 |
+-----------------+----------+----------+---------+

50
docs/index.rst
View File

@ -1,17 +1,45 @@
F4PGA documentation
FOSS Flows For FPGA
###################
.. toctree::
F4PGA is an Open Source HDL-to-Bitstream FPGA synthesis solution, currently targeting Xilinx 7-Series, Lattice iCE40 and
Lattice ECP5 FPGAs.
Think of it as the GCC of FPGAs.
introduction
toolchain-desc/index
Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/>
Project X-Ray ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/>
Project Trellis ➚ <https://prjtrellis.readthedocs.io/en/latest/>
FPGA Assembly (FASM) ➚ <https://fasm.readthedocs.io/en/latest/>
The project aim is to design tools that are highly extendable and multiplatform.
.. toctree::
:caption: Contributing
:caption: About F4PGA
contributing/building-docs
contributing/venv
community
how
status
getting-started
.. toctree::
:caption: Design Flows
flows/index
flows/synthesis
flows/pnr
flows/bitstream
flows/f4pga
.. toctree::
:caption: Specifications
FPGA Assembly (FASM) ➚ <https://fasm.readthedocs.io/en/latest/>
.. toctree::
:caption: Other
yosys
VPR ➚ <https://docs.verilogtorouting.org/en/latest/vpr/>
Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/>
Project X-Ray ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/>
Project Trellis ➚ <https://prjtrellis.readthedocs.io/en/latest/>
.. toctree::
:caption: Contributing
contributing/building-docs
contributing/venv

40
docs/status.rst Normal file
View File

@ -0,0 +1,40 @@
Supported Architectures
#######################
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 |
+-----------------+----------+----------+---------+
Boards
======
See `f4pga.org: Supported boards <https://f4pga.org/#boards>`__.

159
docs/toolchain-desc/design-flow.rst
View File

@ -1,159 +0,0 @@
FPGA Design Flow
================
F4PGA 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.
F4PGA 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:: ../_static/images/toolchain-flow.svg
:align: center
F4PGA 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 F4PGA
++++++++++++++++++++++
In the F4PGA 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 F4PGA
++++++++++++++++++++++
The F4PGA 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 F4PGA Project!

12
docs/toolchain-desc/index.rst
View File

@ -1,12 +0,0 @@
Toolchain description
=====================
This section provides a description of the F4PGA toolchain as well as the basic concepts of the FPGA design flow.
.. toctree::
:maxdepth: 3
Getting started ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/getting-started.html>
design-flow
yosys
VPR ➚ <https://docs.verilogtorouting.org/en/latest/vpr/>

0
docs/toolchain-desc/yosys.rst → docs/yosys.rst
View File