docs: Update docs for new project setup

Update documentation to install and use FABulous with the new setup.

Signed-off-by: Jonas K. <[email protected]>

README.md

@@ -38,7 +38,7 @@ sudo apt-get install python3-tk
 The following packages need to be installed for the CAD toolchain
  - [Yosys](https://github.com/YosysHQ/yosys)
  - [nextpnr-generic](https://github.com/YosysHQ/nextpnr#nextpnr-generic)
- 
+
  A flow using VPR, the place and route tool from the [VTR project](https://github.com/verilog-to-routing/vtr-verilog-to-routing) is also available. However, this still requires Yosys, as well as the FABulous nextpnr fork, since this contains files for design synthesis.
 
 ## Getting started
@@ -48,14 +48,14 @@ To set up FABulous:
 ```
 git clone https://github.com/FPGA-Research-Manchester/FABulous
 cd FABulous
-export FAB_ROOT=`pwd`
+pip install -e .
 ```
 
 We have provided a Python Command Line Interface (CLI) as well as a project structure for easy access of the FABulous toolchain.
 
 The `Tile` folder contains all the definitions of the fabric primitive as well as the fabric matrix configuration. `fabric.csv` is what defining the architecture of the fabric. The FABulous project folder also contains a `.FABulous` folder which contains all the metadata during the generation of the fabric.
 
-We can initiate the FABulous shell with `python3 FABulous.py <project_dir>`. After that you will see a shell interface which allow for interactive fabric generation. To generate a fabric we first need to run `load_fabric [fabric_CSV]` to load in the fabric definition. Then we can call `run_FABulous_fabric` to generate a fabric.
+We can initiate the FABulous shell with `FABulous <project_dir>`. After that you will see a shell interface which allow for interactive fabric generation. To generate a fabric we first need to run `load_fabric [fabric_CSV]` to load in the fabric definition. Then we can call `run_FABulous_fabric` to generate a fabric.
 
 To generate a model and bitstream for a specific design call `run_FABulous_bitstream npnr <dir_to_top>` which will
 generate a bitstream for the provided design in the same folder as the design.
@@ -65,8 +65,9 @@ To exit the shell simply type `exit` and this will terminate the shell.
 A demo of the whole flow:
 
 ```
-python3 FABulous.py -c demo
-# In the FABulous shell (python3 FABulous.py demo)
+FABulous -c demo # Create a demo project
+FABulous demo # Run Fabulous interactive shell for demo project
+# In the FABulous shell
 load_fabric
 run_FABulous_fabric
 run_FABulous_bitstream npnr ./user_design/sequential_16bit_en.v
@@ -82,7 +83,7 @@ cd demo/Test
 ```
 
 The tool also supports using TCL script to drive the build process. Assuming you have created a demo project using
-`python3 FABulous.py -c demo`, you can call `python3 FABulous.py demo -s ./demo/FABulous.tcl` to run the demo flow with the TCL interface.
+`FABulous -c demo`, you can call `FABulous demo -s ./demo/FABulous.tcl` to run the demo flow with the TCL interface.
 
 More details on bitstream generation can be found [here](https://fabulous.readthedocs.io/en/latest/FPGA-to-bitstream/Bitstream%20generation.html).
 

docs/source/Building fabric.rst

@@ -7,36 +7,36 @@ The user can run the flow step by step as well (see below for instructions on bu
         :width: 80%
         :align: center
 
-Other than building the fabric with the ``run_FABulous_fabric`` command as shown in the :ref:`Quick start`, the user can 
-also build the fabric step by step to suit what they need. We will demonstrate this in the following section from 
+Other than building the fabric with the ``run_FABulous_fabric`` command as shown in the :ref:`Quick start`, the user can
+also build the fabric step by step to suit what they need. We will demonstrate this in the following section from
 creating scratch. The following is assuming your current directory is in `$FAB_ROOT` and all the pre-request set up are
-completed. 
+completed.
 
 #. Create a new project
 
    .. prompt:: bash FABulous>
 
-        python3 FABulous.py -c demo
+        FABulous -c demo
 
 This will create a new project named ``demo`` in the current directory.
 
 #. Running the FABulous shell
 
    .. prompt:: bash FABulous>
 
-        python3 FABulous.py demo
+        FABulous demo
 
 And now, we will be in the FABulous shell. After running the above command, the current working directory will be
 moved into the project directory, which is ``demo`` in this case.
 
 #. Load the fabric CSV definition file
-   
+
    .. prompt:: bash FABulous>
-   
+
         load_fabric
 
-This command will load in the fabric definition file with the name ``fabric.csv`` in the current directory. If the 
-definition file is in another directory or named differently, the user can specify the path as an argument to the 
+This command will load in the fabric definition file with the name ``fabric.csv`` in the current directory. If the
+definition file is in another directory or named differently, the user can specify the path as an argument to the
 command. For example: ``load_fabric fabric2.csv``. From this point onwards, all the files read and write commands, will
 be relative to where the specified directory of the ``<definition>.csv`` is located. For example, if the definition file
 located at ``some_path/<definition>.csv``, then all the file's read and write commands will be relative to ``some_path``.
@@ -47,15 +47,15 @@ located at ``some_path/<definition>.csv``, then all the file's read and write co
 
         gen_switch_matrix LUT4AB RAM_IO
 
-The above command will generate the switch matrix for the ``LUT4AB`` tile and the ``RAM_IO`` tile. The switch matrix 
-generated will be based on the ``MATRIX`` entry of the tile definition in the fabric definition file. If the provided 
-directory is a ``.list`` file, then we will generate a switch matrix for the tile, based on the fabric definition file 
+The above command will generate the switch matrix for the ``LUT4AB`` tile and the ``RAM_IO`` tile. The switch matrix
+generated will be based on the ``MATRIX`` entry of the tile definition in the fabric definition file. If the provided
+directory is a ``.list`` file, then we will generate a switch matrix for the tile, based on the fabric definition file
 and add the content in the ``list`` file to the matrix. If the provided file is a ``.csv`` file, the tool will just load
 the data in, and generate a switch base on the data. Finally, if providing a ``.v`` or ``.vhdl`` file, the tool will skip
-matrix generation for the tile, and will use the provided file as the switch matrix. 
+matrix generation for the tile, and will use the provided file as the switch matrix.
 
         .. note::
-                During model generation, the given file for ``MATRIX`` entry needs to be either a ``.list`` or ``.csv`` 
+                During model generation, the given file for ``MATRIX`` entry needs to be either a ``.list`` or ``.csv``
                 file.
 
 
@@ -80,8 +80,8 @@ The above command will generate the actual tiles for the ``LUT4AB`` tile and the
 
 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 
+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
 tiles within the fabric.
 
    .. prompt:: bash FABulous>
@@ -95,7 +95,7 @@ tiles within the fabric.
 
         gen_fabric
 
-#. Generate Verilog top wrapper. 
+#. Generate Verilog top wrapper.
 
    .. prompt:: bash FABulous>
 
@@ -105,7 +105,7 @@ tiles within the fabric.
 #. Generate the nextpnr model.
 
    .. prompt:: bash FABulous>
-        
+
         gen_model_npnr
 
 #. Generate the VPR model.

docs/source/FPGA-to-bitstream/Bitstream generation.rst

@@ -9,21 +9,21 @@ Generate Bitstream <-- Meta Data
 User guide
 ----------
 
-We have provided two methods for the user to generate bitstreams. The first method is done using the CLI provided and 
+We have provided two methods for the user to generate bitstreams. The first method is done using the CLI provided and
 the second method which the user calls the script manually. The first method is recommended, as it provides all the necessary information to generate the bitstream. The second method is provided for cases where the user has
 decided not to work with the FABulous project structure.
 
 Generate bitstream using CLI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To generate a bitstream using the CLI, the user must first generate the bitstream specification using the CLI. To 
+To generate a bitstream using the CLI, the user must first generate the bitstream specification using the CLI. To
 generate the bitstream specification, we can call the ``gen_bitstream_spec`` command from the CLI. It is expected that
 the user had also run synthesis and place and route for the design, which generates the ``.fasm`` file of the design.
 
 To generate the bitstream, the user can call the ``gen_bitstream_binary <design.fasm>`` command from the CLI, where the
 ``design.fasm`` is the directory of 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
@@ -35,7 +35,7 @@ With the FASM file generated by Nextpnr or VPR, you can run this command for bit
 
 .. code-block:: console
 
-        python3 $FAB_ROOT/nextpnr/fabulous/fab_arch/bit_gen.py -genBitstream <fasm_file> meta_data.txt <bitstream file>
+        bit_gen -genBitstream <fasm_file> meta_data.txt <bitstream file>
 
 +------------------+-----------------------------------------------------------------------+
 | <fasm_file>      | the FASM file generated by Nextpnr or VPR in previous compilation     |
@@ -50,16 +50,16 @@ The following are simple commands to synthesis the netlist ``sequential_16bit_en
 
 .. code-block:: console
 
-        python3 bit_gen.py -genBitstream 16bit_sequential_en.fasm meta_data.txt 16bit_sequential_en_output.bin
+        bit_gen -genBitstream 16bit_sequential_en.fasm meta_data.txt 16bit_sequential_en_output.bin
 
 
 Changes in the primitives or adding new primitives
 --------------------------------------------------
-For a change in the primitives or adding new primitives, you can simply add them within the primitive file. As an 
-example, in the ``LUT4c_frame_config`` primitive description below there are 16 configuration bits for INIT values, 
+For a change in the primitives or adding new primitives, you can simply add them within the primitive file. As an
+example, in the ``LUT4c_frame_config`` primitive description below there are 16 configuration bits for INIT values,
 1 configuration bit ``FF`` for the flip-flop bypass switch, 1 configuration bit ``IOmux`` for the carry input switch and
-1 configuration bit ``SET_NORESET`` for the SET or RESET switch, which means there are 19 configuration bits for each 
-LUT4 parameters setting. The number of entries in the mapping needs to match the ``NoConfigBits`` otherwise, the tool 
+1 configuration bit ``SET_NORESET`` for the SET or RESET switch, which means there are 19 configuration bits for each
+LUT4 parameters setting. The number of entries in the mapping needs to match the ``NoConfigBits`` otherwise, the tool
 will give an error.
 
 .. code-block:: verilog
@@ -90,7 +90,7 @@ will give an error.
         ...
         endmodule
 
-        
+
 (to do)
 
 

docs/source/Usage.rst

@@ -15,7 +15,7 @@ The following packages need to be installed for generating fabric HDLs
 
     git clone https://github.com/FPGA-Research-Manchester/FABulous
 
-:Python: 
+:Python:
  version >= 3.9
 
 :python dependencies:
@@ -38,27 +38,31 @@ The following packages need to be installed for the CAD toolchain
 :`Nextpnr-generic <https://github.com/YosysHQ/nextpnr#nextpnr-generic>`_:
  version > 0.4-28-gac17c36b
 
+Install FABulous with "editable" option:
+.. code-block:: console
+
+    pip3 install -e .
 
 Building Fabric and Bitstream
 -----------------------------
 
 
 .. code-block:: console
 
-   python3 FABulous.py -c <name_of_project>
-   python3 FABulous.py <name_of_project>
+   FABulous -c <name_of_project>
+   FABulous <name_of_project>
    # inside the FABulous shell
    load_fabric
    run_FABulous_fabric
    run_FABulous_bitstream npnr user_design/sequential_16bit_en.v
-   
 
-After a successful call with the command ``run_FABulous_fabric`` the RTL file of each of the tiles can be found in the ``Tile`` folder and the fabric RTL file can be found in the ``Fabric`` folder. 
 
-After a successful call with the command ``run_FABulous_bitstream npnr user_design/sequential_16bit_en.v``. 
-The bitstream and all the log files generated during synthesis and place and route can be found under 
-the ``user_design`` folder. The bitstream will be named as ``sequential_16bit_en.bin`` The above command is using 
-the ``npnr`` options which suggest we are using Yosys for synthesis and Nextpnr for placement and routing. Another 
+After a successful call with the command ``run_FABulous_fabric`` the RTL file of each of the tiles can be found in the ``Tile`` folder and the fabric RTL file can be found in the ``Fabric`` folder.
+
+After a successful call with the command ``run_FABulous_bitstream npnr user_design/sequential_16bit_en.v``.
+The bitstream and all the log files generated during synthesis and place and route can be found under
+the ``user_design`` folder. The bitstream will be named as ``sequential_16bit_en.bin`` The above command is using
+the ``npnr`` options which suggest we are using Yosys for synthesis and Nextpnr for placement and routing. Another
 option would be using ``vpr``, which will allow for using Yosys for synthesis and VPR for placement and routing.
 (currently, the VPR flow is not working after the refactoring)
 

docs/source/simulation/emulation.rst

@@ -3,7 +3,7 @@ Emulation setup
 
 (Emulation function is under built)
 
-The script ``bit_gen.py`` in 
+The script ``bit_gen.py`` in
 :ref:`bitstream generation<bitstream generation>`
 not only generates the binary bitstream for simulation, but also the bitstream files for Verilog and VHDL emulation.
 
@@ -23,8 +23,8 @@ not only generates the binary bitstream for simulation, but also the bitstream f
   .. code-block:: vhdl
      :emphasize-lines: 5
 
-        entity  eFPGA  is 
-                Generic ( 
+        entity  eFPGA  is
+                Generic (
                         MaxFramesPerCol : integer := 20;
                         FrameBitsPerRow : integer := 32;
                         Mode : string := "EMULATE"; -- "ASIC" will use the normal configuration port and "EMULATE" will hardwire a bitstream from emulate_bitstream.vhd