FPGA-Research · KelvinChung2000 · Aug 1, 2024 · Jul 2, 2024 · Jul 2, 2024 · Jul 2, 2024
diff --git a/docs/source/Building fabric.rst b/docs/source/Building fabric.rst
@@ -78,7 +78,7 @@ The above command will generate the configuration storage for the ``LUT4AB`` til
 
 The above command will generate the actual tiles for the ``LUT4AB`` tile and the ``RAM_IO`` tile.
 
-All the files generated will be located in the respective tile directory. i.e RTL for ``LUT4AB`` will be in ``Tile/LUT4AB/``
+All the files generated will be located in the respective tile directory. i.e. RTL for ``LUT4AB`` will be in ``Tile/LUT4AB/``
 
 We will need to run the above commands for all the tiles to get all the RTL of all the tiles, which is quite tedious to 
 do. As a result, the following command will generate all the RTL for all the tiles in the fabric including all the super 
@@ -114,7 +114,7 @@ tiles within the fabric.
 
         gen_model_vpr
 
-#. Generate the meta data list for FASM --> Bitstream
+#. Generate the metadata list for FASM → Bitstream
 
    .. prompt:: bash FABulous>
 

diff --git a/docs/source/FPGA-to-bitstream/Bitstream generation.rst b/docs/source/FPGA-to-bitstream/Bitstream generation.rst
@@ -23,7 +23,7 @@ the user had also run synthesis and place and route for the design, which genera
 To generate the bitstream, the user can call the ``gen_bitstream_binary <design.fasm>`` command from the CLI, where the
 ``design.fasm`` is the ``.fasm`` file generated by synthesis and place and route.
 
-The resulting bitstream is placed in the same directory as where the  ``fasm`` file is located and named as 
+The resulting bitstream is placed in the same directory as where the ``fasm`` file is located and named as
 ``design.bin``.
 
 Manually generate bitstream

diff --git a/docs/source/FPGA-to-bitstream/Nextpnr compilation.rst b/docs/source/FPGA-to-bitstream/Nextpnr compilation.rst
@@ -1,7 +1,8 @@
 Nextpnr compilation
 ===================
 
-Compile JSON to FASM by nextpnr <-- bels.txt + pips.txt
+Nextpnr can compile a JSON description of a circuit to FASM [#]_ using the
+architectural description in bels.txt and pips.txt
 
 Our nextpnr implementation uses nextpnr-generic for place and route. 
 
@@ -144,7 +145,8 @@ The following example is a 16-bit counter output to Block_RAM, and then Block_RA
 
         endmodule
 
+Footnotes
+---------
 
-
-
-
+.. [#] The FPGA Assembly format, describing a concrete list of features on a
+   specific FPGA fabric to be enabled
diff --git a/docs/source/FPGA-to-bitstream/VPR compilation.rst b/docs/source/FPGA-to-bitstream/VPR compilation.rst
@@ -1,10 +1,11 @@
 VPR compilation
 ===============
 
-Compile BLIF to FASM by VPR <-- architecture.xml + routing_resources.xml
-
-
-VPR (Versatile Place and Route) is a place and route tool from the VTR project that can be used to program a fabric generated by FABulous, using either Yosys or ODIN II for the logic synthesis. The VTR genfasm tool can then be used to generate an FPGA Assembly (FASM) file from which the bitstream can be generated.
+VPR (Versatile Place and Route) is a place and route tool from the VTR project
+that can be used to program a fabric generated by FABulous, using either Yosys
+or ODIN II for the logic synthesis. The VTR genfasm tool can then be used to
+generate an FPGA Assembly (FASM) file from a Berkeley Logic Interchange Format
+(BLIF) file. The bitstream can then be generated from the FASM file.
 
 To generate the necessary materials to program using VPR, run ``$FAB_ROOT/fabric_generator/fabric_gen.py`` with the -genVPRModel flag. In the ``$FAB_ROOT/fabric_generator/vproutput`` directory, two files will be created - ``architecture.xml`` and ``routing_resources.xml``. 
 
@@ -18,7 +19,7 @@ To use Yosys (recommended with FABulous for improved functionality), follow the
 
 When generating the VPR model, FABulous will print out a maximum width for routing channels in the form ``Max Width: <max_width>``. This number should be noted, as it will be used as an argument when calling VPR.
 
-To run the VPR flow (with VPR 8.1.0 installed) , the following command can be used:
+To run the VPR flow (with VPR 8.1.0 installed), the following command can be used:
 
 .. code-block:: console
 

diff --git a/docs/source/FPGA_CAD-tools/index.rst b/docs/source/FPGA_CAD-tools/index.rst
@@ -1,3 +1,5 @@
+.. _fpga_cad_tool_parametrization:
+
 FPGA CAD-tool parameterization
 ==============================
 

diff --git a/docs/source/FPGA_CAD-tools/vpr.rst b/docs/source/FPGA_CAD-tools/vpr.rst
@@ -1,7 +1,7 @@
 VPR models
 ==========
 
-To generate the necessary materials to program using VPR, run ``$FAB_ROOT/fabric_generator/fabric_gen.py`` with the -genVPRModel flag followed by the location of your custom information XML file (an description an example of which can be found below). In the ``$FAB_ROOT/fabric_generator/vproutput`` directory, two files will be created: ``architecture.xml`` and ``routing_resources.xml``. 
+To generate the necessary materials to program using VPR, run ``$FAB_ROOT/fabric_generator/fabric_gen.py`` with the -genVPRModel flag followed by the location of your custom information XML file (a description an example of which can be found below). In the ``$FAB_ROOT/fabric_generator/vproutput`` directory, two files will be created: ``architecture.xml`` and ``routing_resources.xml``.
 
 architecture.xml contains a description of the various tiles, ports and BELs - everything in the architecture except for the routing resources. 
 
@@ -16,7 +16,7 @@ The custom XML file should open and close with ``<custom_xml_spec>`` and ``</cus
 
 **<bel_pb> content <\bel_pb>**
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This tag should contain the exact XML that should be inserted to define the second-level ``pb_type`` that represents this bel, including the ``<pb_type>`` tag itself. This should represent only one instance of the BEL (i.e. ``num_pb`` should be 1) as different instances are now represented by FABulous as individual subtiles, each of which has the ``pb_type`` as its equivalent site. Your XML will be automatically inserted inside a top-level wrapper ``pb_type``, and all inputs/outputs will be routed through into your description - therefore, it is required that your custom ``pb_type`` has at least the inputs and outputs described in your HDL model.
+This tag should contain the exact XML that should be inserted to define the second-level ``pb_type`` that represents this BEL, including the ``<pb_type>`` tag itself. This should represent only one instance of the BEL (i.e. ``num_pb`` should be 1) as different instances are now represented by FABulous as individual subtiles, each of which has the ``pb_type`` as its equivalent site. Your XML will be automatically inserted inside a top-level wrapper ``pb_type``, and all inputs/outputs will be routed through into your description - therefore, it is required that your custom ``pb_type`` has at least the inputs and outputs described in your HDL model.
 
 **<bel_model> content <\bel_model>**
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -153,7 +153,7 @@ Notes for developers
 
 The ptc number provided for each node in the routing resource (RR) graph represents the pin, track or class of the node. With SOURCE, SINK, IPIN and OPIN nodes, this is the ptc of the appropriate pin in the block type definition, however with CHANY and CHANX nodes it is more arbitrary. Here, each wire's ptc number should be different from any wire it overlaps with **anywhere along its length**. Previously, every wire had a separate PTC number, but this was recently updated so that no horizontal wire has the same number as any vertical wire, no two horizontal wires in the same row share a number, and no two vertical wires in the same column share a number. More information on the meaning of the PTC number can be found in `this Google Group discussion <https://groups.google.com/g/vtr-users/c/ZFXPn-W3SxA/m/ROkfD2oEAQAJ>`_.
 
-Although no meaningful routing connections are specified in the architecture.xml file, it is important that all pins do not have an Fc value of 0. This is because VPR uses the Fc value to gauge how well connected to the fabric a pin is, and so will not be able to find any routing candidates with 0 Fc pins. Currently FABulous is set up with a default fractional Fc of 1 such that all pins are connected to the fabric and are viable candidates.
+Although no meaningful routing connections are specified in the architecture.xml file, it is important that all pins do not have an Fc value of 0. This is because VPR uses the Fc value to gauge how well-connected to the fabric a pin is, and so will not be able to find any routing candidates with 0 Fc pins. Currently, FABulous is set up with a default fractional Fc of 1 such that all pins are connected to the fabric and are viable candidates.
 
 Due to the techmapping complexity, the multiplexers in the LUT4AB tiles are currently ignored and it is assumed each LUT is routed to a separate output - at the time of writing, the same assumption is made for the nextpnr model.
 
diff --git a/docs/source/Usage.rst b/docs/source/Usage.rst
@@ -24,13 +24,13 @@ The following packages need to be installed for generating fabric HDLs
 
     pip3 install -r requirements.txt
 
-This will also require to install `Tkinter` for the TCL facilities. To install `Tkinter` on Ubuntu, run:
+This will also require installing `Tkinter` for the TCL facilities. To install `Tkinter` on Ubuntu, run:
 
 .. code-block:: console
 
     sudo apt-get install python3-tk
 
-The following packages need to be installed for the CAD toolchain
+The following packages need to be installed for the CAD toolchain:
 
 :`Yosys <https://github.com/YosysHQ/yosys>`_:
  version > 0.26+0

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,36 +1,38 @@
 import os
 import sys
+
 # Configuration file for the Sphinx documentation builder.
 
 # -- Project information
 
-project = 'FABulous Documentation'
-copyright = '2021, University of Manchester'
-author = 'Jing, Nguyen, Bea, Bardia, Dirk'
+project = "FABulous Documentation"
+copyright = "2021, University of Manchester"
+author = "Jing, Nguyen, Bea, Bardia, Dirk"
 
-release = '0.1'
-version = '0.1.0'
+release = "0.1"
+version = "0.1.0"
 
 # -- General configuration
 
 extensions = [
-    'sphinx.ext.duration',
-    'sphinx.ext.doctest',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.intersphinx',
-    'sphinxcontrib.bibtex',
-    'sphinx.ext.napoleon',
-    'sphinx-prompt'
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinxcontrib.bibtex",
+    "sphinx.ext.napoleon",
+    "sphinx-prompt",
+    "sphinx.ext.todo",
 ]
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
 }
-intersphinx_disabled_domains = ['std']
+intersphinx_disabled_domains = ["std"]
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 sys.path.append(os.getcwd() + "/../../")
 
@@ -52,12 +54,12 @@
 
 # -- Options for HTML output
 
-html_theme = 'sphinx_materialdesign_theme'
+html_theme = "sphinx_materialdesign_theme"
 
-html_logo = 'figs/FAB_logo.png'
+html_logo = "figs/FAB_logo.png"
 
 
 # -- Options for EPUB output
-epub_show_urls = 'footnote'
+epub_show_urls = "footnote"
 
-bibtex_bibfiles = ['publications.bib']
+bibtex_bibfiles = ["publications.bib"]