Merge branch 'master' of github.com:verilog-to-routing/vtr-verilog-to-routing into openfpga

Author: Tulong4Dev

.github/workflows/test.yml

@@ -184,47 +184,52 @@ jobs:
         include: [
           {
             name: 'Basic',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on',
             suite: 'vtr_reg_basic'
           },
           {
             name: 'Basic_odin',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DWITH_PARMYS=OFF -DWITH_ODIN=on',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DWITH_PARMYS=OFF -DWITH_ODIN=on',
             suite: 'vtr_reg_basic_odin'
           },
           {
             name: 'Basic with NO_GRAPHICS',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVPR_USE_EZGL=off',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVPR_USE_EZGL=off',
+            suite: 'vtr_reg_basic'
+          },
+          {
+            name: 'Basic with NO_SERVER',
+            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVPR_USE_EZGL=on -DVPR_USE_SERVER=off',
             suite: 'vtr_reg_basic'
           },
           {
             name: 'Basic with CAPNPROTO disabled',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVTR_ENABLE_CAPNPROTO=off',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVTR_ENABLE_CAPNPROTO=off',
             suite: 'vtr_reg_basic'
           },
           {
             name: 'Basic with VTR_ENABLE_DEBUG_LOGGING',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVTR_ENABLE_DEBUG_LOGGING=on',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVTR_ENABLE_DEBUG_LOGGING=on',
             suite: 'vtr_reg_basic'
           },
           {
             name: 'Basic_odin with VTR_ENABLE_DEBUG_LOGGING',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVTR_ENABLE_DEBUG_LOGGING=on -DWITH_PARMYS=OFF -DWITH_ODIN=on',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DVTR_ENABLE_DEBUG_LOGGING=on -DWITH_PARMYS=OFF -DWITH_ODIN=on',
             suite: 'vtr_reg_basic_odin'
           },
           {
             name: 'Strong',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on',
             suite: 'vtr_reg_strong'
           },
           {
             name: 'Strong_odin',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DWITH_PARMYS=OFF -DWITH_ODIN=on',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DWITH_PARMYS=OFF -DWITH_ODIN=on',
             suite: 'vtr_reg_strong_odin'
           },
           {
             name: 'Valgrind Memory',
-            params: '-DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DWITH_ODIN=on',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DWITH_ODIN=on',
             suite: 'vtr_reg_valgrind_small'
           }
         ]

.gitmodules

@@ -1,3 +1,7 @@
 [submodule "libs/EXTERNAL/libcatch2"]
 	path = libs/EXTERNAL/libcatch2
 	url = https://github.com/catchorg/Catch2.git
+[submodule "libs/EXTERNAL/sockpp"]
+	path = libs/EXTERNAL/sockpp
+	#url = [email protected]:fpagliughi/sockpp.git
+	url = [email protected]:w0lek/sockpp.git # fork where in branch v1.0.0_no_complication_warnings there are compilation warnings fixes for upstream tag v1.0.0 of sockpp

CMakeLists.txt

@@ -40,6 +40,9 @@ set(VPR_USE_EZGL "auto" CACHE STRING "Specify whether vpr uses the graphics libr
 set_property(CACHE VPR_USE_EZGL PROPERTY STRINGS auto off on)
 option(VTR_ENABLE_CAPNPROTO "Enable capnproto binary serialization support in VPR." ON)
 
+#Allow the user to decide whether to compile the server module
+option(VPR_USE_SERVER "Specify whether vpr enables the server mode" ON)
+
 #Allow the user to enable/disable VPR analytic placement
 #VPR option --enable_analytic_placer is also required for Analytic Placement
 option(VPR_ANALYTIC_PLACE "Enable analytic placement in VPR." ON)

Dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:20.04
+FROM ubuntu:22.04
 ARG DEBIAN_FRONTEND=noninteractive
 # set out workspace
 ENV WORKSPACE=/workspace
@@ -19,6 +19,7 @@ RUN apt-get update -qq \
     libtbb-dev \
     python3-pip \
     git \
+    time \
 # Install python packages
     && pip install -r requirements.txt \
 # Cleanup

README.developers.md

@@ -344,11 +344,70 @@ and should be used when making changes to Odin.
 ## Unit Tests
 
 VTR also has a limited set of unit tests, which can be run with:
+
 ```shell
 #From the VTR root directory
 $ make && make test
 ```
 
+This will run `test_vtrutil`, `test_vpr`, `test_fasm`, and `test_archfpga`. Each test suite is added in their CMake
+files.
+
+### Running Individual Testers
+
+To run one of the four testers listed above on its own, navigate to the appropriate folder:
+
+| Test            | Directory                          |
+|-----------------|------------------------------------|
+| `test_archfpga` | `$VTR_ROOT/build/libs/libarchfpga` |
+| `test_vtrutil`  | `$VTR_ROOT/build/libs/libvtrutil`  |
+| `test_fasm`     | `$VTR_ROOT/build/utils/fasm`       |
+| `test_vpr`      | `$VTR_ROOT/build/vpr`              |
+
+To see tester options, run it with `-h`:
+
+```shell
+# Using test_vpr as an example
+# From $VTR_ROOT/build/vpr
+$ ./test_vpr -h
+```
+
+To see the names of each unit test, use `--list-tests`:
+
+```shell
+# From $VTR_ROOT/build/vpr
+$ ./test_vpr --list-tests
+```
+
+The output should look similar to this:
+
+```shell
+All available test cases:
+  test_route_flow
+      [vpr_noc_bfs_routing]
+  test_find_block_with_matching_name
+      [vpr_clustered_netlist]
+  connection_router
+      [vpr]
+  binary_heap
+      [vpr]
+  edge_groups_create_sets
+      [vpr]
+  read_interchange_models
+      [vpr]
+      
+... # many more test cases
+
+52 test cases
+```
+
+To run specific unit tests, pass them as arguments. For example:
+
+```shell
+# From $VTR_ROOT/build/vpr
+$ ./test_vpr test_route_flow connection_router
+```
+
 # Evaluating Quality of Result (QoR) Changes
 VTR uses highly tuned and optimized algorithms and data structures.
 Changes which effect these can have significant impacts on the quality of VTR's design implementations (timing, area etc.) and VTR's run-time/memory usage.
@@ -972,6 +1031,64 @@ This describes adding a test to `vtr_reg_strong`, but the process is similar for
     $ git commit
     ```
 
+## Creating Unit Tests
+
+You can find the source code for the unit tests in their respective directories. New unit tests must also be created in
+these directories.
+
+| Test            | Directory                         |
+|-----------------|-----------------------------------|
+| `test_archfpga` | `$VTR_ROOT/libs/libarchfpga/test` |
+| `test_vtrutil`  | `$VTR_ROOT/libs/libvtrutil/test`  |
+| `test_fasm`     | `$VTR_ROOT/utils/fasm/test`       |
+| `test_vpr`      | `$VTR_ROOT/vpr/test`              |
+
+VTR uses [Catch2](https://github.com/catchorg/Catch2) for its unit testing framework. For a full tutorial of how to use
+the framework, see `$VTR_ROOT/libs/EXTERNAL/libcatch2/docs/Readme.md`.
+
+### Example: Creating and Running a VPR Test Case
+
+Navigate to `$VTR_ROOT/vpr/test`.
+
+```shell
+$ cd $VTR_ROOT/vpr/test
+```
+
+From here, let's create and open a new file `test_new_vpr.cpp` (begin the file name with `test_`). Be sure to `#include "catch2/catch_test_macros.hpp"`.
+Introduce a test case using the `TEST_CASE` macro, and include a name and a tag. For boolean assertions, use `REQUIRE`.
+
+```shell
+#include "catch2/catch_test_macros.hpp"
+
+// To choose a tag (written with square brackets "[tag]"), see examples from when you run ./test_vpr
+// --list-tests in the tester exectuable directory, as shown earlier. A good default tag name is the name
+// of the tester: in this case, [vpr].
+TEST_CASE("a_vpr_test_name", "[vpr]") {
+  int x = 0;
+  REQUIRE(x == 0);
+}
+```
+
+To run our test case, we must navigate back to `$VTR_ROOT/build/vpr` (from the table
+under [Running Individual Testers](#running-individual-testers)). Since we created a test, we need to rebuild the
+tester. Then, we can run our test.
+
+```shell
+$ cd $VTR_ROOT/build/vpr
+$ make                         // rebuild tester
+$ ./test_vpr a_vpr_test_name   // run new unit test
+```
+
+Output:
+
+```shell
+Filters: "a_vpr_test_name"
+Randomness seeded to: 2089861684
+===============================================================================
+All tests passed (1 assertion in 1 test case)
+```
+
+
 # Debugging Aids
 VTR has support for several additional tools/features to aid debugging.
 
@@ -1213,7 +1330,7 @@ Instead changes should be made in the relevant up-stream repository, and then sy
 
     For example to update the `libtatum` subtree:
     ```shell
-    ./dev/external_subtrees.py --update libtatum
+    ./dev/external_subtrees.py --update libtatum -m "commit message describing why component is being updated"
     ```
 
 ## Adding a new Subtree
@@ -1255,8 +1372,66 @@ To add a new external subtree to VTR do the following:
     This will create two commits to the repository.
     The first will squash all the upstream changes, the second will merge those changes into the current branch.
 
+## Pushing VTR Changes Back to Upstream Subtree
+
+If there are changes in the VTR repo in a subtree that should be merged back
+into the source repo of the subtree, the changes can be pushed back manually.
+
+The instructions above used a Python script to simplify updating subtrees in
+VTR. This is fine for pulling in changes from a remote repo; however, it is not
+good for pushing changes back. This is because these changes need to be pushed
+somewhere, and it is not a good idea to just push it back to the master branch
+directly. Instead, it should be pushed to a temporary branch. Then a PR can be
+made to bring the changes into the target repo.
+
+To push changes VTR made to a subtree do the following:
+
+1. Create a fork of the target repo. Optionally you can create a branch to be
+   the target of the push, or you can just use master.
+
+2. Run:
+   ```shell
+   cd $VTR_ROOT
+   git subtree push --prefix=<subtree_path> <forked_repo_url> <branch_name>
+   ```
+   The prefix is the internal path to the subtree, as written in
+   `dev/subtree_config.xml`.
+
+3. Create a PR from your forked repo to the main repo, sharing the amazing
+   changes with the world.
+
+## Tutorial: Syncing Tatum with VTR
+
+This tutorial will show you how to synchronize `libtatum` in VTR and
+[Tatum](https://github.com/verilog-to-routing/tatum); however, similar steps
+can be done to synchronize any subtree in VTR.
+
+First, we will pull in (update) any changes in Tatum that are not in VTR yet.
+On a clean branch (based off master), execute the following:
+```shell
+cd $VTR_ROOT
+./dev/external_subtrees.py --update libtatum -m "Pulling in changes from Tatum."
+```
+If the output in the terminal says `Subtree is already at commit <commit_hash>`,
+then there is nothing to pull in. If it says changes were pulled in, a commit
+would have already been made for you. Push these changes to your branch and
+raise a PR on VTR to merge these changes in.
+
+After pulling in all the changes from Tatum, without changing branches, we will
+push our VTR changes to Tatum. This is a bit more complicated since, as stated
+in the section on pushing to subtrees, the changes cannot just be pushed to
+master.
+
+Create a fork of Tatum and make sure the master branch of that fork is
+synchronized with Tatum's master branch. Then execute the following:
+```shell
+cd $VTR_ROOT
+git subtree push --prefix=libs/EXTERNAL/libtatum <forked_repo_url> master
+```
+After that command finishes, raise a PR from your forked repo onto the Tatum
+repo for the changes to be reviewed and merged in.
 
-## Subtree Rational
+## Subtree Rationale
 
 VTR uses subtrees to allow easy tracking of upstream dependencies.
 

dev/DOCKER_DEPLOY.md

@@ -1,52 +1,62 @@
-Overview
-========
+# Building VTR on Docker
 
+## Overview
 Docker creates an isolated container on your system so you know that VTR will run without further configurations nor affecting any other work.
 
 Our Docker file sets up this enviroment by installing all necessary Linux packages and applications as well as Perl modules.
 
-Additionally, Cloud9 is installed, which enables the remote management of your container through browser. With Cloud9, VTR can be started easier (and even modified and recompiled) without the need to logging into a terminal. If the Cloud9 endpoint is published outside your LAN, you can also execute VTR remotely or share your screen with other users.
+## Setup
 
+1. Install docker (Community Edition is free and sufficient for VTR): https://docs.docker.com/engine/install/
 
-Setup
-=====
+2. Clone the VTR project:
 
-Install docker (Community Edition is free and sufficient for VTR): https://docs.docker.com/engine/installation/
+    ```
+    git clone https://github.com/verilog-to-routing/vtr-verilog-to-routing
+    ```
 
-Clone the VTR project:
+3. CD to the VTR folder and build the docker image:
 
-`git clone https://github.com/verilog-to-routing/vtr-verilog-to-routing`
+    ```
+    docker build . -t vtrimg
+    ```
 
-CD to the VTR folder and build the docker image:
+4. Start docker with the new image:
 
-`docker build . -t vtrimg`
+    ```
+    docker run -it -d --name vtr vtrimg
+    ```
 
-Start docker with the new image and connect the current volume with the workspace volume of the container:
 
-`sudo docker run -it -d -p <port-to-open-on-host>:8080 -v <absolute-path-to-VTR-folder>:/workspace vtrimg`
+## Running
 
+1. Attach to the Docker container. Attaching will open a shell on the `/workspace` directory within the container.
+The project root directory from the docker build process is copied and placed in the `/workspace` directory.
 
-Running
-=======
+    ```sh
+    # from host computer
+    docker exec -it vtr /bin/bash
+    ```
 
-Open a browser (Google Chrome for example) and navigate to your host's url at the port you opened up. For example:
-http://192.168.1.30:8080
+1. Verfiy that VTR has been installed correctly:
 
-First, use one of the terminals and compile VTR:
-make && make installation/
+    ```sh
+    # in container
+    ./vtr_flow/scripts/run_vtr_task.py regression_tests/vtr_reg_basic/basic_timing
+    ```
 
-Second, ensure that a basic regression test passes:
-./run_reg_test.py vtr_reg_basic
+    The expected output is:
 
-Third, run and/or modify VTR in the usual way.
+    ```
+    k6_N10_mem32K_40nm/single_ff            OK
+    k6_N10_mem32K_40nm/single_ff            OK
+    k6_N10_mem32K_40nm/single_wire          OK
+    k6_N10_mem32K_40nm/single_wire          OK
+    k6_N10_mem32K_40nm/diffeq1              OK
+    k6_N10_mem32K_40nm/diffeq1              OK
+    k6_N10_mem32K_40nm/ch_intrinsics                OK
+    k6_N10_mem32K_40nm/ch_intrinsics                OK
+    ```
 
-Developpement Debugging
-=======================
-the container already comes with clang as the default compiler and with scan-build the do statistical analysis on the build
-set to `debug` in makefile
-
-run `scan-build make -j4` from the root VTR directory.
-to output the html analysis to a specific folder, run `scan-build make -j4 -o /some/folder`
-
-the output is html and viewable in any browser.
+2. Run and/or modify VTR in the usual way.