equivalent tiles: added documentation to new members and functions

Signed-off-by: Alessandro Comodi <[email protected]>

Author: acomodi

libs/libarchfpga/src/physical_types.h

@@ -548,6 +548,19 @@ constexpr int DEFAULT_SWITCH = -2;
  * pb_type: Internal subblocks and routing information for this physical block
  * pb_graph_head: Head of DAG of pb_types_nodes and their edges
  *
+ *
+ * num_equivalent_tiles: Specifies the number of equivalent physical types that can be used during placement.
+ *                       If the value is `0` all the data structures relative to the equivalent tiles will be empty.
+ * equivalent_tiles: Array containing pointers to the equivalent tiles. The number of elements contained is specified
+ *                   by num_equivalent_tiles.
+ * equivalent_tile_pin_mapping: Multi-dimensional array that, for each different equivalent tile contains a mapping between
+ *                              the pins of the two tiles.
+ *                              Example: equivalent_tile_pin_mapping[eq_tile_index][pin_index] = equivalent_pin_index
+ *                              This is necessary to maintain consistency between two equivalent tiles that have the same pins
+ *                              defined with different indeces.
+ * equivalent_tile_inverse_pin_mapping: Multi-dimensional array that works as the previous one, but the mapping is inverse in this case.
+ *                                      Example: equivalent_tile_pin_mapping[eq_tile_index][equivalent_pin_index] = pin_index
+ *
  * area: Describes how much area this logic block takes, if undefined, use default
  * type_timing_inf: timing information unique to this type
  * num_drivers: Total number of output drivers supplied
@@ -587,6 +600,7 @@ struct t_type_descriptor /* TODO rename this.  maybe physical type descriptor or
 	t_pb_type *pb_type = nullptr;
 	t_pb_graph_node *pb_graph_head = nullptr;
 
+	/* Equivalent tiles information */
 	int num_equivalent_tiles = 0;
 	t_type_descriptor **equivalent_tiles = nullptr;
 	int **equivalent_tile_pin_mapping = nullptr; /* [0..num_equivalent_tiles-1][0..num_pins-1] */

libs/libarchfpga/src/read_xml_arch_file.cpp

@@ -302,7 +302,7 @@ void XmlReadArch(const char *ArchFile, const bool timing_enabled,
         Next = get_single_child(architecture, "tiles", loc_data);
         ProcessTilesTags(Next, Types, *NumTypes, *arch, arch_def_fc, loc_data);
 
-		/* Process directs */
+        /* Process directs */
         Next = get_single_child(architecture, "directlist", loc_data, OPTIONAL);
         if (Next) {
             ProcessDirects(Next, &(arch->Directs), &(arch->num_directs),
@@ -2816,7 +2816,24 @@ static void ProcessTilesTags(pugi::xml_node Node,
 	}
 }
 
-/* TODO Add documentation */
+/* Processes the equivalent tiles defined in the XML arch definition
+ * <tiles>
+ *   <tile name="LAB">
+ *     <mode name="MLAB">
+ *       <map .../>
+ *       <map .../>
+ *       <map .../>
+ *     </mode>
+ *   </tile>
+ * </tiles>
+ *
+ * In particular this function parses the `modes` (if they exist) of each tile
+ * and adds the equivalent tile information to the t_type_descriptor relative to
+ * the current tile.
+ * It populates the following t_type_descriptor members:
+ *     - num_equivalent_tiles;
+ *     - equivalent_tiles.
+ */
 static void ProcessTileExtraModes(pugi::xml_node Node,
 		t_type_descriptor *Type,
 		t_type_descriptor **Types,
@@ -2848,7 +2865,11 @@ static void ProcessTileExtraModes(pugi::xml_node Node,
 	}
 }
 
-/* TODO: Add documentation */
+/* Processes the pin_mapping of each equivalent tile.
+ * It goes through each mode and populates the following t_type_descriptor memebrs:
+ *     - equivalent_tile_pin_mapping;
+ *     - equivalent_tile_inverse_pin_mapping.
+ */
 static void ProcessTileExtraModePinMapping(pugi::xml_node Node,
 		t_type_descriptor *Type,
 		t_type_descriptor *EquivalentType,

vpr/src/base/clustered_netlist.h

@@ -126,13 +126,21 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
         //Returns the physical block
         t_pb* block_pb(const ClusterBlockId id) const;
 
-        //Returns the type of CLB (Logic block, RAM, DSP, etc.). Calls block_type with boolean set to true.
+        /*
+         * Returns the type of CLB (Logic block, RAM, DSP, etc.). There are two different overloaded block_type functions
+         * 1) The first one (without the boolean) is used to retrieve the actual physical type corresponding to the placed
+         *    block. This function will call the one with the boolean, setting `get_equivalent_if_set` to true.
+         * 2) The second one (with the boolean) is used to retrieve the physical or logical type relative to a block.
+         *    Depending on the value of `get_equivalent_if_set` we will get a different block_type:
+         *        - True: the function returns the physical placed tile (can be an equivalent tile) of the block;
+         *        - False: the function returns the logical tile of the block (even if it was placed in an equivalent tile).
+         */
         t_type_ptr block_type(const ClusterBlockId id) const;
-
-        //Returns the type of CLB. If get_equivalent_if_set is true, if the equivalent tile has been chosen it returns it.
         t_type_ptr block_type(const ClusterBlockId id, bool get_equivalent_if_set) const;
 
         //Returns the equivalent type index (if any) of a CLB
+        //The index is used to retrieve the equivalent type from the t_type_descriptor structure
+        //Example: type->equivalent_tiles[index]
         int block_eq_type_index(const ClusterBlockId id) const;
 
         //Returns the net of the block attached to the specific pin index
@@ -182,7 +190,8 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
         //  t_type_ptr  : The type of the CLB
         ClusterBlockId create_block(const char *name, t_pb* pb, t_type_ptr type);
 
-        //Add the equivalent block type for a CLB
+        //Add the equivalent block type for a CLB. This mutator adds both the equivalent type index and
+        //the equivalent type to the corresponding vector_maps
         //  blk_id      : The block placed in an equivalent tile location
         //  i_eq_type   : The index used to retrieve the equivalent tile from the t_type_ptr structure
         //  eq_type     : The equivalent type associated with this block