Merge pull request #531 from umarcor/umarcor/docs/reorganise

docs: reorganise

docs/community.rst

@@ -0,0 +1,70 @@
+Community
+#########
+
+`FOSS Flows For FPGA (F4PGA) <https://f4pga.org>`__ project is a `Workgroup <https://chipsalliance.org/workgroups/>`__
+under the `CHIPS Alliance <https://chipsalliance.com/>`__.
+The F4PGA Workgroup consists of members from different backgrounds, including FPGA vendors
+(`Xilinx <https://www.xilinx.com/>`__
+and `QuickLogic <https://www.quicklogic.com/>`__),
+industrial users
+(`Google <https://www.google.com/>`__
+and `Antmicro <https://antmicro.com/>`__)
+and academia
+(`University of Toronto <https://www.utoronto.ca/>`__),
+who collaborate to build a more open source and software-driven FPGA ecosystem (IP, tools and workflows) to drive the
+adoption of FPGAs in existing and new use cases, and eliminate barriers of entry.
+
+Communication
+=============
+
+* `Twitter [@f4pga] <https://twitter.com/f4pga>`__
+
+* `Slack [chipsalliance.slack.com] <https://chipsalliance.slack.com/>`__
+
+  .. TIP::
+    To register to CHIPS Alliance Slack workspace, use the following `Slack Invite <https://slack-invite.chipsalliance.org/>`__.
+
+* `IRC [irc.libera.chat/#F4PGA] <https://kiwiirc.com/nextclient/#irc://irc.libera.chat/#F4PGA>`__
+
+* `Mailing list [lists.chipsalliance.org/g/f4pga-wg] <https://lists.chipsalliance.org/g/f4pga-wg>`__
+
+Souces
+======
+
+* `github.com/chipsalliance <https://github.com/chipsalliance/?q=f4pga>`__
+
+* `github.com/F4PGA <https://github.com/F4PGA>`__
+
+.. _Contributing:
+
+Contributing
+============
+
+Are you interested in helping this project move forward?
+F4PGA is a collaborative project and we welcome your contributions.
+The code is available on GitHub, while the HTML documentation is available on Read The Docs.
+There are multiple areas and technologies we need help with - reach out to us, we're sure we will find something for you.
+
+* Do you know **Python**?
+  Almost all scripts are written in Python!
+
+* Do you know **C++**?
+  VPR & nextpnr & libraries written in C++!
+
+* Do you know **TCL**?
+  All the EDA tools use TCL!
+
+* Do you know **(System) Verilog**, **VHDL**, **Chisel**, **Migen** and/or **Amaranth**?
+  Simulation and models are written in Hardware Description Languages (HDLs)!
+
+* Do you know **XML**?
+  Most file formats are XML!
+
+* Do you know English?
+  Documentation is written in English!
+
+* Do you know **Docker** and/or **Podman**?
+  Help make it easier to set up F4PGA!
+
+* Do you have time?
+  We will find you a task!

docs/conf.py

@@ -6,9 +6,33 @@
 import sys, os
 from pathlib import Path
 
+from tabulate import tabulate
+
+ROOT = Path(__file__).resolve().parent
+
 #sys.path.insert(0, os.path.abspath('.'))
 
-# -- General configuration -----------------------------------------------------
+# -- Generate status.inc -----------------------------------------------------------------------------------------------
+
+with (ROOT / "status.inc").open("w", encoding="utf-8") as wfptr:
+    wfptr.write(
+        tabulate(
+            [
+                ["[Basic Tiles] Logic", "Yes", "Yes", "Yes", "Yes"],
+                ["[Basic Tiles] Block RAM", "Yes", "Yes", "Partial", "Yes"],
+                ["[Advanced Tiles] DSP", "Yes", "Yes", "Partial", "Yes"],
+                ["[Advanced Tiles] Hard Blocks", "Yes", "Yes", "Partial", "Yes"],
+                ["[Advanced Tiles] Clock Tiles", "Yes", "Yes", "Yes", "Yes"],
+                ["[Advanced Tiles] IO Tiles", "Yes", "Yes", "Yes", "Yes"],
+                ["[Routing] Logic", "Yes", "Yes", "Yes", "Yes"],
+                ["[Routing] Clock", "Yes", "Yes", "Yes", "Yes"],
+            ],
+            headers=["", "Project Icestorm", "Project Trellis ", "Project X-Ray", "QuickLogic Database"],
+            tablefmt="rst",
+        )
+    )
+
+# -- General configuration ---------------------------------------------------------------------------------------------
 
 project = 'F4PGA'
 basic_filename = 'f4pga-docs'
@@ -47,7 +71,7 @@
    :format: html
 """
 
-# -- Options for HTML output ---------------------------------------------------
+# -- Options for HTML output -------------------------------------------------------------------------------------------
 
 html_show_sourcelink = True
 
@@ -66,7 +90,7 @@
 html_logo = str(Path(html_static_path[0]) / 'logo.svg')
 html_favicon = str(Path(html_static_path[0]) / 'favicon.svg')
 
-# -- Options for LaTeX output --------------------------------------------------
+# -- Options for LaTeX output ------------------------------------------------------------------------------------------
 
 latex_documents = [
   ('index', basic_filename+'.tex', project,
@@ -99,7 +123,7 @@
     '''
 }
 
-# -- Options for manual page output --------------------------------------------
+# -- Options for manual page output ------------------------------------------------------------------------------------
 
 man_pages = [
     ('index', basic_filename, project,

docs/flows/bitstream.rst

@@ -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!

docs/flows/f4pga.rst

@@ -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.

docs/flows/index.rst

@@ -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

docs/flows/pnr.rst

@@ -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.

docs/flows/synthesis.rst

@@ -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.

docs/getting-started.rst

@@ -0,0 +1,16 @@
+Getting started
+###############
+
+To begin using F4PGA, you might want to take a look at the tutorials below, which make for a good starting point.
+They will guide you through the process of using the toolchain, explaining how to generate and load a bitstream into
+your FPGA.
+
+* User guide and examples how to use the toolchain:
+
+  * `Examples ➚ <https://f4pga-examples.readthedocs.io>`__ (for users)
+  * `Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/getting-started.html>`__ (for developers)
+
+* Other resources:
+
+  * `X-Ray Quickstart ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/db_dev_process/readme.html#quickstart-guide>`__
+  * `F4PGA Architectures Visualizer ➚ <https://chipsalliance.github.io/f4pga-database-visualizer/>`__

docs/introduction.rst → docs/how.rst

@@ -1,14 +1,11 @@
-Introduction
-============
+How it works
+############
 
-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.
+To understand how F4PGA works, it is best to start with an overview of the general EDA tooling ecosystem and then
+proceed to see what the F4PGA project consists of.
 
 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 +25,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 +44,26 @@ collaborating projects targeting different FPGAs - :doc:`Project X-Ray
 
 .. figure:: _static/images/parts.svg
 
-Current status of bitstream documentation
------------------------------------------
+The F4PGA toolchain consists of logic synthesis and implementation tools, as well as chip documentation projects for
+chips of various vendors.
+To prepare a working bitstream for a particular FPGA chip, the toolchain goes through the following stages:
+
+* First, a description of the FPGA chip is created with the information from the relevant bitstream documentation
+  project.
+  This part is done within the `F4PGA Architecture Definitions <https://github.com/chipsalliance/f4pga-arch-defs>`__.
+  The project prepares information about the timings and resources available in the chip needed at the implementation
+  stage, as well as techmaps for the synthesis tools.
+
+* The second step is logic synthesis.
+  It is carried out in the Yosys framework, which expresses the input Verilog file by means of the block and connection
+  types available in the chosen chip.
 
-.. table::
-    :align: center
-    :widths: 40 20 20 20
+* The next step is implementation.
+  Placement and routing tools put individual blocks from the synthesis description in the specific chip locations and
+  create paths between them.
+  To do that, F4PGA uses either `nextpnr <https://github.com/YosysHQ/nextpnr>`__ or `Verilog to Routing <https://github.com/verilog-to-routing/vtr-verilog-to-routing>`__.
 
-    +-----------------+----------+----------+---------+
-    | 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     |
-    +-----------------+----------+----------+---------+
+* Finally, the design properties are translated into a set of features available in the given FPGA chip.
+  These features are saved in the `fasm format <https://github.com/chipsalliance/fasm>`__, which is developed as part of
+  F4PGA.
+  The fasm file is then translated to bitstream using the information from the bitstream documentation projects.