Merge branch 'master' into ipa_end_user_doc

Author: w0lek

.github/workflows/test.yml

@@ -184,17 +184,17 @@ 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'
           },
           {
@@ -204,32 +204,32 @@ jobs:
           },
           {
             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'
           }
         ]

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.
 
@@ -1352,5 +1469,4 @@ The following outlines the procedure to following when making an official VTR re
  * GitHub will automatically create a release based on the tag
  * Add the new change log entry to the [GitHub release description](https://github.com/verilog-to-routing/vtr-verilog-to-routing/releases)
  * Update the [ReadTheDocs configuration](https://readthedocs.org/projects/vtr/versions/) to build and serve documentation for the relevant tag (e.g. `v8.0.0`)
- * Send a release announcement email to the [vtr-announce](mailto:[email protected]) mailing list (make sure to thank all contributors!)
-
+ * Send a release announcement email to the [vtr-announce](mailto:[email protected]) mailing list (make sure to thank all contributors!)

libs/libarchfpga/CMakeLists.txt

@@ -57,7 +57,7 @@ target_link_libraries(read_arch libarchfpga)
 
 #Supress IPO link warnings if IPO is enabled
 get_target_property(READ_ARCH_USES_IPO read_arch INTERPROCEDURAL_OPTIMIZATION)
-if (READ_ARCH_USES_IPO)
+if(READ_ARCH_USES_IPO)
     set_property(TARGET read_arch APPEND PROPERTY LINK_FLAGS ${IPO_LINK_WARN_SUPRESS_FLAGS})
 endif()
 
@@ -70,3 +70,8 @@ install(FILES ${LIB_HEADERS} DESTINATION include/libarchfpga)
 file(GLOB_RECURSE TEST_SOURCES test/*.cpp)
 add_executable(test_archfpga ${TEST_SOURCES})
 target_link_libraries(test_archfpga Catch2::Catch2WithMain libarchfpga)
+
+add_test(NAME test_archfpga
+    COMMAND test_archfpga
+    --colour-mode ansi
+    )

libs/libarchfpga/src/read_fpga_interchange_arch.cpp

@@ -5,29 +5,28 @@
 
 #ifdef VTR_ENABLE_CAPNPROTO
 
-#include <algorithm>
-#include <kj/std/iostream.h>
-#include <limits>
-#include <map>
-#include <regex>
-#include <set>
-#include <stdlib.h>
-#include <string>
-#include <string.h>
-#include <zlib.h>
-#include <sstream>
-
-#include "vtr_assert.h"
-#include "vtr_digest.h"
-#include "vtr_log.h"
-#include "vtr_memory.h"
-#include "vtr_util.h"
-
-#include "arch_check.h"
-#include "arch_error.h"
-#include "arch_util.h"
-#include "arch_types.h"
-
+#    include <algorithm>
+#    include <kj/std/iostream.h>
+#    include <limits>
+#    include <map>
+#    include <regex>
+#    include <set>
+#    include <stdlib.h>
+#    include <string>
+#    include <string.h>
+#    include <zlib.h>
+#    include <sstream>
+
+#    include "vtr_assert.h"
+#    include "vtr_digest.h"
+#    include "vtr_log.h"
+#    include "vtr_memory.h"
+#    include "vtr_util.h"
+
+#    include "arch_check.h"
+#    include "arch_error.h"
+#    include "arch_util.h"
+#    include "arch_types.h"
 
 /*
  * FPGA Interchange Device frontend
@@ -2503,7 +2502,7 @@ struct ArchReader {
     }
 };
 
-#endif  // VTR_ENABLE_CAPNPROTO
+#endif // VTR_ENABLE_CAPNPROTO
 
 void FPGAInterchangeReadArch(const char* FPGAInterchangeDeviceFile,
                              const bool /*timing_enabled*/,
@@ -2551,12 +2550,12 @@ void FPGAInterchangeReadArch(const char* FPGAInterchangeDeviceFile,
 
     ArchReader reader(arch, device_reader, FPGAInterchangeDeviceFile, PhysicalTileTypes, LogicalBlockTypes);
     reader.read_arch();
-#else   // VTR_ENABLE_CAPNPROTO
+#else  // VTR_ENABLE_CAPNPROTO
     // If CAPNPROTO is disabled, throw an error.
     (void)FPGAInterchangeDeviceFile;
     (void)arch;
     (void)PhysicalTileTypes;
     (void)LogicalBlockTypes;
     throw vtr::VtrError("Unable to read FPGA interchange if CAPNPROTO is not enabled", __FILE__, __LINE__);
-#endif  // VTR_ENABLE_CAPNPROTO
+#endif // VTR_ENABLE_CAPNPROTO
 }

libs/libarchfpga/src/read_fpga_interchange_arch.h

@@ -5,14 +5,14 @@
 
 #ifdef VTR_ENABLE_CAPNPROTO
 
-#include "DeviceResources.capnp.h"
-#include "LogicalNetlist.capnp.h"
-#include "capnp/serialize.h"
-#include "capnp/serialize-packed.h"
-#include <fcntl.h>
-#include <unistd.h>
-
-#endif  // VTR_ENABLE_CAPNPROTO
+#    include "DeviceResources.capnp.h"
+#    include "LogicalNetlist.capnp.h"
+#    include "capnp/serialize.h"
+#    include "capnp/serialize-packed.h"
+#    include <fcntl.h>
+#    include <unistd.h>
+
+#endif // VTR_ENABLE_CAPNPROTO
 
 #ifdef __cplusplus
 extern "C" {

libs/librrgraph/src/base/rr_graph_obj.cpp

@@ -1041,7 +1041,7 @@ void RRGraph::set_node_segment(const RRNodeId& node, const RRSegmentId& segment_
  */
 void RRGraph::partition_node_in_edges(const RRNodeId& node) {
     //Partition the edges so the first set of edges are all configurable, and the later are not
-    auto first_non_config_edge = std::partition(node_in_edges_[node].begin(), node_in_edges_[node].end(),
+    auto first_non_config_edge = std::stable_partition(node_in_edges_[node].begin(), node_in_edges_[node].end(),
                                                 [&](const RREdgeId edge) { return edge_is_configurable(edge); }); /* Condition to partition edges */
 
     size_t num_conf_edges = std::distance(node_in_edges_[node].begin(), first_non_config_edge);
@@ -1060,7 +1060,7 @@ void RRGraph::partition_node_in_edges(const RRNodeId& node) {
  */
 void RRGraph::partition_node_out_edges(const RRNodeId& node) {
     //Partition the edges so the first set of edges are all configurable, and the later are not
-    auto first_non_config_edge = std::partition(node_out_edges_[node].begin(), node_out_edges_[node].end(),
+    auto first_non_config_edge = std::stable_partition(node_out_edges_[node].begin(), node_out_edges_[node].end(),
                                                 [&](const RREdgeId edge) { return edge_is_configurable(edge); }); /* Condition to partition edges */
 
     size_t num_conf_edges = std::distance(node_out_edges_[node].begin(), first_non_config_edge);

libs/librrgraph/src/base/rr_node_impl.h

@@ -3,28 +3,35 @@
 // This file provides the inline proxy implemenation for t_rr_node.
 // See the t_rr_node class comment for additional details.
 
-#include "rr_node_types.h"
+#include <cstddef>
+#include <iterator>
 #include "rr_node.h"
 #include "rr_graph_storage.h"
 
-class node_idx_iterator : public std::iterator<std::bidirectional_iterator_tag, const t_rr_node> {
+class node_idx_iterator {
   public:
+    using iterator_category = std::bidirectional_iterator_tag;
+    using difference_type = std::ptrdiff_t;
+    using value_type = const t_rr_node;
+    using pointer = value_type*;
+    using reference = value_type&;
+
     node_idx_iterator(t_rr_node value)
         : value_(value) {}
 
-    iterator operator++() {
+    node_idx_iterator& operator++() {
         value_.next_node();
         return *this;
     }
-    iterator operator--() {
+    node_idx_iterator& operator--() {
         value_.prev_node();
         return *this;
     }
     reference operator*() const { return value_; }
     pointer operator->() const { return &value_; }
 
-    friend bool operator==(const node_idx_iterator lhs, const node_idx_iterator rhs) { return lhs.value_.id() == rhs.value_.id(); }
-    friend bool operator!=(const node_idx_iterator lhs, const node_idx_iterator rhs) { return !(lhs == rhs); }
+    friend bool operator==(const node_idx_iterator& lhs, const node_idx_iterator& rhs) { return lhs.value_.id() == rhs.value_.id(); }
+    friend bool operator!=(const node_idx_iterator& lhs, const node_idx_iterator& rhs) { return !(lhs == rhs); }
 
   private:
     t_rr_node value_;