diff --git a/docs/_static/images/EDA.svg b/docs/_static/images/EDA.svg index f278a9c85..ec4b1fadb 100644 --- a/docs/_static/images/EDA.svg +++ b/docs/_static/images/EDA.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/_static/images/parts.svg b/docs/_static/images/parts.svg index 97296def8..5d97c9238 100644 --- a/docs/_static/images/parts.svg +++ b/docs/_static/images/parts.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/community.rst b/docs/community.rst new file mode 100644 index 000000000..50d3dd362 --- /dev/null +++ b/docs/community.rst @@ -0,0 +1,70 @@ +Community +######### + +`FOSS Flows For FPGA (F4PGA) `__ project is a `Workgroup `__ +under the `CHIPS Alliance `__. +The F4PGA Workgroup consists of members from different backgrounds, including FPGA vendors +(`Xilinx `__ +and `QuickLogic `__), +industrial users +(`Google `__ +and `Antmicro `__) +and academia +(`University of Toronto `__), +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] `__ + +* `Slack [chipsalliance.slack.com] `__ + + .. TIP:: + To register to CHIPS Alliance Slack workspace, use the following `Slack Invite `__. + +* `IRC [irc.libera.chat/#F4PGA] `__ + +* `Mailing list [lists.chipsalliance.org/g/f4pga-wg] `__ + +Souces +====== + +* `github.com/chipsalliance `__ + +* `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! diff --git a/docs/conf.py b/docs/conf.py index 4f6210311..3906f48b2 100644 --- a/docs/conf.py +++ b/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, diff --git a/docs/flows/bitstream.rst b/docs/flows/bitstream.rst new file mode 100644 index 000000000..dcb457bd2 --- /dev/null +++ b/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! diff --git a/docs/flows/f4pga.rst b/docs/flows/f4pga.rst new file mode 100644 index 000000000..7caa1bec1 --- /dev/null +++ b/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. diff --git a/docs/flows/index.rst b/docs/flows/index.rst new file mode 100644 index 000000000..6afae870e --- /dev/null +++ b/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 diff --git a/docs/flows/pnr.rst b/docs/flows/pnr.rst new file mode 100644 index 000000000..6c865e70f --- /dev/null +++ b/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. diff --git a/docs/flows/synthesis.rst b/docs/flows/synthesis.rst new file mode 100644 index 000000000..4c7e918a8 --- /dev/null +++ b/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. diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 000000000..0f9819da0 --- /dev/null +++ b/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 ➚ `__ (for users) + * `Architecture Definitions ➚ `__ (for developers) + +* Other resources: + + * `X-Ray Quickstart ➚ `__ + * `F4PGA Architectures Visualizer ➚ `__ diff --git a/docs/introduction.rst b/docs/how.rst similarity index 50% rename from docs/introduction.rst rename to docs/how.rst index 2eee56941..ab5735307 100644 --- a/docs/introduction.rst +++ b/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 `__. + 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 `__ or `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 `__, which is developed as part of + F4PGA. + The fasm file is then translated to bitstream using the information from the bitstream documentation projects. diff --git a/docs/index.rst b/docs/index.rst index 3b0b7c728..50189ca69 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,17 +1,45 @@ -F4PGA documentation +FOSS Flows For FPGA ################### +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. + +The project aim is to design tools that are highly extendable and multiplatform. + +.. toctree:: + :caption: About F4PGA + + 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) ➚ + .. toctree:: + :caption: Other - introduction - toolchain-desc/index - Architecture Definitions ➚ - Project X-Ray ➚ - Project Trellis ➚ - FPGA Assembly (FASM) ➚ + yosys + VPR ➚ + Architecture Definitions ➚ + Project X-Ray ➚ + Project Trellis ➚ .. toctree:: - :caption: Contributing + :caption: Contributing - contributing/building-docs - contributing/venv + contributing/building-docs + contributing/venv diff --git a/docs/requirements.txt b/docs/requirements.txt index 2a38f8663..325f714a0 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ Sphinx==3.0.4 http://github.com/SymbiFlow/sphinx_symbiflow_theme/archive/chips.zip#sphinx-symbiflow-theme http://github.com/SymbiFlow/sphinx-verilog-domain/archive/master.zip#sphinx-verilog-domain +tabulate diff --git a/docs/status.rst b/docs/status.rst new file mode 100644 index 000000000..6d8fae8dd --- /dev/null +++ b/docs/status.rst @@ -0,0 +1,31 @@ +Supported Architectures +####################### + + +* `Xilinx 7-Series `__: + the most popular Xilinx FPGA family. + +* `Lattice ice40 `__: + world's smallest FPGAs for mobile devices. + +* `Lattice ecp5 `__: + low cost FPGAs with high performance features. + +* `QuickLogic EOS S3 `__: + FPGA + CPU sensor processing platform. + +* `QuickLogic QLF K4N8 `__: + a 24x24 eFPGA with 6144 flip-flops, 4608 LUT4s, adder and shift-register support. + +* Do you want to add more? :ref:`Help us! ` + + +Bitstream documentation +======================= + +.. include:: status.inc + +Boards +====== + +See `f4pga.org: Supported boards `__. diff --git a/docs/toolchain-desc/design-flow.rst b/docs/toolchain-desc/design-flow.rst deleted file mode 100644 index 469245593..000000000 --- a/docs/toolchain-desc/design-flow.rst +++ /dev/null @@ -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! diff --git a/docs/toolchain-desc/index.rst b/docs/toolchain-desc/index.rst deleted file mode 100644 index c79c34e89..000000000 --- a/docs/toolchain-desc/index.rst +++ /dev/null @@ -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 ➚ - design-flow - yosys - VPR ➚ diff --git a/docs/toolchain-desc/yosys.rst b/docs/yosys.rst similarity index 100% rename from docs/toolchain-desc/yosys.rst rename to docs/yosys.rst