Support to force routing tap multiplexers in clock network

docs/source/manual/file_formats/bitstream_setting.rst

@@ -14,6 +14,7 @@ This can define a hard-coded bitstream for a reconfigurable resource in FPGA fab
     <pb_type name="<string>" source="eblif" content=".param LUT" is_mode_select_bistream="true" bitstream_offset="1"/>
     <default_mode_bits name="<string>" mode_bits="<string>"/>
     <interconnect name="<string>" default_path="<string>"/>
+    <clock_routing network="<string>" pin="<string>"/>
     <non_fabric name="<string>" file="<string>">
       <pb name="<string>" type="<string>" content="<string>"/>
     </non_fabric>
@@ -104,6 +105,35 @@ The following syntax are applicable to the XML definition tagged by ``interconne
 
   The default path can be either ``iopad.inpad`` or ``ff.Q`` which corresponds to the first input and the second input respectively.
 
+Clock Routing-related Settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following syntax are applicable to the XML definition tagged by ``clock_routing`` in bitstream setting files.
+This is to force the routing for clock tap multiplexers (green line in :numref:`fig_prog_clock_network_example_2x2`) even when they are not used/mapped. If no specified, only the used clock tap multiplexers will be configured to propagate clock signals.
+
+.. note:: This requires the benchmark has at least 1 global signal. Otherwise, the clock routing will be skipped, and there is no impact from this setting.
+
+.. option:: network="<string>"
+
+  The ``network`` name to be constrained, which should be a valid name defined in the clock network file (See details in :ref:`file_formats_clock_network`). For example, 
+
+.. code-block:: xml
+
+  <clock_routing network="clk_tree_2lvl" pin="clk[0:0]"/>
+  <clock_routing network="rst_tree_2lvl" pin="rst[1:1]"/>
+
+The network and pin correspond to the clock network name and a valid pin of ``global_port`` in the clock network description.
+
+.. code-block:: xml
+
+  <clock_network name="clk_tree_2lvl" global_port="clk[0:7]"/>
+  <clock_network name="rst_tree_2lvl" global_port="rst[0:7]"/>  
+
+.. option:: pin="<string>"
+
+  The pin should be a valid pin of the ``global_port`` that is defined in the clock network description under the selected clock network.
+
+
 non_fabric-related Settings
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

libs/libarchopenfpga/src/bitstream_setting.cpp

@@ -24,6 +24,12 @@ BitstreamSetting::default_mode_settings() const {
                          default_mode_setting_ids_.end());
 }
 
+BitstreamSetting::bitstream_clock_routing_setting_range
+BitstreamSetting::clock_routing_settings() const {
+  return vtr::make_range(clock_routing_setting_ids_.begin(),
+                         clock_routing_setting_ids_.end());
+}
+
 BitstreamSetting::bitstream_interconnect_setting_range
 BitstreamSetting::interconnect_settings() const {
   return vtr::make_range(interconnect_setting_ids_.begin(),
@@ -126,6 +132,20 @@ std::string BitstreamSetting::default_mode_bits_to_string(
   return mode_bits_str;
 }
 
+std::string BitstreamSetting::clock_routing_network(
+  const BitstreamClockRoutingSettingId& clock_routing_setting_id) const {
+  VTR_ASSERT(
+    true == valid_bitstream_clock_routing_setting_id(clock_routing_setting_id));
+  return clock_routing_network_names_[clock_routing_setting_id];
+}
+
+BasicPort BitstreamSetting::clock_routing_pin(
+  const BitstreamClockRoutingSettingId& clock_routing_setting_id) const {
+  VTR_ASSERT(
+    true == valid_bitstream_clock_routing_setting_id(clock_routing_setting_id));
+  return clock_routing_pins_[clock_routing_setting_id];
+}
+
 std::string BitstreamSetting::interconnect_name(
   const BitstreamInterconnectSettingId& interconnect_setting_id) const {
   VTR_ASSERT(true ==
@@ -222,6 +242,18 @@ BitstreamSetting::add_bitstream_default_mode_setting(
   return default_mode_setting_id;
 }
 
+BitstreamClockRoutingSettingId
+BitstreamSetting::add_bitstream_clock_routing_setting(
+  const std::string& ntwk_name, const BasicPort& pin) {
+  BitstreamClockRoutingSettingId clock_routing_setting_id =
+    BitstreamClockRoutingSettingId(clock_routing_setting_ids_.size());
+  clock_routing_setting_ids_.push_back(clock_routing_setting_id);
+  clock_routing_network_names_.push_back(ntwk_name);
+  clock_routing_pins_.push_back(pin);
+
+  return clock_routing_setting_id;
+}
+
 BitstreamInterconnectSettingId
 BitstreamSetting::add_bitstream_interconnect_setting(
   const std::string& interconnect_name,
@@ -290,6 +322,14 @@ bool BitstreamSetting::valid_bitstream_default_mode_setting_id(
           default_mode_setting_ids_[default_mode_setting_id]);
 }
 
+bool BitstreamSetting::valid_bitstream_clock_routing_setting_id(
+  const BitstreamClockRoutingSettingId& clock_routing_setting_id) const {
+  return (size_t(clock_routing_setting_id) <
+          clock_routing_setting_ids_.size()) &&
+         (clock_routing_setting_id ==
+          clock_routing_setting_ids_[clock_routing_setting_id]);
+}
+
 bool BitstreamSetting::valid_bitstream_interconnect_setting_id(
   const BitstreamInterconnectSettingId& interconnect_setting_id) const {
   return (size_t(interconnect_setting_id) < interconnect_setting_ids_.size()) &&

libs/libarchopenfpga/src/bitstream_setting.h

@@ -9,6 +9,7 @@
 #include <vector>
 
 #include "bitstream_setting_fwd.h"
+#include "openfpga_port.h"
 #include "vtr_geometry.h"
 #include "vtr_vector.h"
 
@@ -62,6 +63,9 @@ class BitstreamSetting {
   typedef vtr::vector<BitstreamDefaultModeSettingId,
                       BitstreamDefaultModeSettingId>::const_iterator
     bitstream_default_mode_setting_iterator;
+  typedef vtr::vector<BitstreamClockRoutingSettingId,
+                      BitstreamClockRoutingSettingId>::const_iterator
+    bitstream_clock_routing_setting_iterator;
   typedef vtr::vector<BitstreamInterconnectSettingId,
                       BitstreamInterconnectSettingId>::const_iterator
     bitstream_interconnect_setting_iterator;
@@ -73,6 +77,8 @@ class BitstreamSetting {
     bitstream_pb_type_setting_range;
   typedef vtr::Range<bitstream_default_mode_setting_iterator>
     bitstream_default_mode_setting_range;
+  typedef vtr::Range<bitstream_clock_routing_setting_iterator>
+    bitstream_clock_routing_setting_range;
   typedef vtr::Range<bitstream_interconnect_setting_iterator>
     bitstream_interconnect_setting_range;
   typedef vtr::Range<overwrite_bitstream_iterator> overwrite_bitstream_range;
@@ -83,10 +89,12 @@ class BitstreamSetting {
  public: /* Accessors: aggregates */
   bitstream_pb_type_setting_range pb_type_settings() const;
   bitstream_default_mode_setting_range default_mode_settings() const;
+  bitstream_clock_routing_setting_range clock_routing_settings() const;
   bitstream_interconnect_setting_range interconnect_settings() const;
   overwrite_bitstream_range overwrite_bitstreams() const;
 
  public: /* Public Accessors */
+  /* pb_type settings */
   std::string pb_type_name(
     const BitstreamPbTypeSettingId& pb_type_setting_id) const;
   std::vector<std::string> parent_pb_type_names(
@@ -114,6 +122,13 @@ class BitstreamSetting {
   std::string default_mode_bits_to_string(
     const BitstreamDefaultModeSettingId& default_mode_setting_id) const;
 
+  /* Clock routing settings */
+  std::string clock_routing_network(
+    const BitstreamClockRoutingSettingId& clock_routing_setting_id) const;
+  BasicPort clock_routing_pin(
+    const BitstreamClockRoutingSettingId& clock_routing_setting_id) const;
+
+  /* Interconnect settings */
   std::string interconnect_name(
     const BitstreamInterconnectSettingId& interconnect_setting_id) const;
   std::vector<std::string> parent_pb_type_names(
@@ -122,11 +137,16 @@ class BitstreamSetting {
     const BitstreamInterconnectSettingId& interconnect_setting_id) const;
   std::string default_path(
     const BitstreamInterconnectSettingId& interconnect_setting_id) const;
+
+  /* Non-fabric bitstream setting */
   std::vector<NonFabricBitstreamSetting> non_fabric() const;
+
+  /* Bitstream overwriting setting */
   std::string overwrite_bitstream_path(const OverwriteBitstreamId& id) const;
   bool overwrite_bitstream_value(const OverwriteBitstreamId& id) const;
 
  public: /* Public Mutators */
+  /* pb_type settings */
   BitstreamPbTypeSettingId add_bitstream_pb_type_setting(
     const std::string& pb_type_name,
     const std::vector<std::string>& parent_pb_type_names,
@@ -138,21 +158,29 @@ class BitstreamSetting {
   void set_bitstream_offset(const BitstreamPbTypeSettingId& pb_type_setting_id,
                             const size_t& offset);
 
+  /* Default Mode Bit settings */
   BitstreamDefaultModeSettingId add_bitstream_default_mode_setting(
     const std::string& pb_type_name,
     const std::vector<std::string>& parent_pb_type_names,
     const std::vector<std::string>& parent_mode_names,
     const std::vector<size_t>& mode_bits);
 
+  /* Clock routing settings */
+  BitstreamClockRoutingSettingId add_bitstream_clock_routing_setting(
+    const std::string& ntwk_name, const BasicPort& pin);
+
+  /* Interconnect settings */
   BitstreamInterconnectSettingId add_bitstream_interconnect_setting(
     const std::string& interconnect_name,
     const std::vector<std::string>& parent_pb_type_names,
     const std::vector<std::string>& parent_mode_names,
     const std::string& default_path);
 
+  /* Non-fabric bitstream setting */
   void add_non_fabric(const std::string& name, const std::string& file);
   void add_non_fabric_pb(const std::string& pb, const std::string& content);
 
+  /* Bitstream overwriting setting */
   OverwriteBitstreamId add_overwrite_bitstream(const std::string& path,
                                                const bool& value);
 
@@ -161,6 +189,8 @@ class BitstreamSetting {
     const BitstreamPbTypeSettingId& pb_type_setting_id) const;
   bool valid_bitstream_default_mode_setting_id(
     const BitstreamDefaultModeSettingId& default_mode_setting_id) const;
+  bool valid_bitstream_clock_routing_setting_id(
+    const BitstreamClockRoutingSettingId& clock_routing_setting_id) const;
   bool valid_bitstream_interconnect_setting_id(
     const BitstreamInterconnectSettingId& interconnect_setting_id) const;
   bool valid_overwrite_bitstream_id(const OverwriteBitstreamId& id) const;
@@ -198,6 +228,13 @@ class BitstreamSetting {
   vtr::vector<BitstreamDefaultModeSettingId, std::vector<size_t>>
     pb_type_default_mode_bits_;
 
+  /* Clock routing */
+  vtr::vector<BitstreamClockRoutingSettingId, BitstreamClockRoutingSettingId>
+    clock_routing_setting_ids_;
+  vtr::vector<BitstreamClockRoutingSettingId, std::string>
+    clock_routing_network_names_;
+  vtr::vector<BitstreamClockRoutingSettingId, BasicPort> clock_routing_pins_;
+
   /* Interconnect-related settings:
    * - Name of interconnect under a given pb_type
    * - The default path to be considered for a given interconnect during

libs/libarchopenfpga/src/bitstream_setting_fwd.h

@@ -15,13 +15,16 @@
 
 struct bitstream_pb_type_setting_id_tag;
 struct bitstream_default_mode_setting_id_tag;
+struct bitstream_clock_routing_setting_id_tag;
 struct bitstream_interconnect_setting_id_tag;
 struct overwrite_bitstream_id_tag;
 
 typedef vtr::StrongId<bitstream_pb_type_setting_id_tag>
   BitstreamPbTypeSettingId;
 typedef vtr::StrongId<bitstream_default_mode_setting_id_tag>
   BitstreamDefaultModeSettingId;
+typedef vtr::StrongId<bitstream_clock_routing_setting_id_tag>
+  BitstreamClockRoutingSettingId;
 typedef vtr::StrongId<bitstream_interconnect_setting_id_tag>
   BitstreamInterconnectSettingId;
 typedef vtr::StrongId<overwrite_bitstream_id_tag> OverwriteBitstreamId;

libs/libarchopenfpga/src/bitstream_setting_xml_constants.h

@@ -0,0 +1,53 @@
+#ifndef BITSTREAM_SETTING_XML_CONSTANTS_H
+#define BITSTREAM_SETTING_XML_CONSTANTS_H
+
+/* Constants required by XML parser */
+
+constexpr const char* XML_BITSTREAM_SETTING_ROOT_NAME =
+  "openfpga_bitstream_setting";
+/* Pb-type XML syntax */
+constexpr const char* XML_PB_TYPE_NODE_NAME = "pb_type";
+constexpr const char* XML_PB_TYPE_ATTRIBUTE_NAME = "name";
+constexpr const char* XML_PB_TYPE_ATTRIBUTE_SOURCE = "source";
+constexpr const char* XML_PB_TYPE_ATTRIBUTE_CONTENT = "content";
+constexpr const char* XML_PB_TYPE_ATTRIBUTE_IS_MODE_SELECT_BITSTREAM =
+  "is_mode_select_bitstream";
+constexpr const char* XML_PB_TYPE_ATTRIBUTE_BITSTREAM_OFFSET =
+  "bitstream_offset";
+
+/* Default mode bits XML syntax */
+constexpr const char* XML_DEFAULT_MODE_BITS_NODE_NAME = "default_mode_bits";
+constexpr const char* XML_DEFAULT_MODE_BITS_ATTRIBUTE_NAME = "name";
+constexpr const char* XML_DEFAULT_MODE_BITS_ATTRIBUTE_MODE_BITS = "mode_bits";
+
+/* Clock routing XML syntax */
+constexpr const char* XML_CLOCK_ROUTING_NODE_NAME = "clock_routing";
+constexpr const char* XML_CLOCK_ROUTING_ATTRIBUTE_NETWORK = "network";
+constexpr const char* XML_CLOCK_ROUTING_ATTRIBUTE_PIN = "pin";
+
+/* Interconnect XML syntax */
+constexpr const char* XML_INTERCONNECT_NODE_NAME = "interconnect";
+constexpr const char* XML_INTERCONNECT_ATTRIBUTE_NAME = "name";
+constexpr const char* XML_INTERCONNECT_ATTRIBUTE_DEFAULT_PATH = "default_path";
+
+/* Non fabric XML syntax */
+constexpr const char* XML_NON_FABRIC_NODE_NAME = "non_fabric";
+constexpr const char* XML_NON_FABRIC_ATTRIBUTE_NAME = "name";
+constexpr const char* XML_NON_FABRIC_ATTRIBUTE_FILE = "file";
+constexpr const char* XML_NON_FABRIC_PB_NODE_NAME = "pb";
+constexpr const char* XML_NON_FABRIC_PB_ATTRIBUTE_NAME = "name";
+constexpr const char* XML_NON_FABRIC_PB_ATTRIBUTE_CONTENT = "content";
+
+/* Overwrite bitstream XML syntax */
+constexpr const char* XML_OVERWRITE_BITSTREAM_NODE_NAME = "overwrite_bitstream";
+constexpr const char* XML_OVERWRITE_BITSTREAM_ATTRIBUTE_BIT = "bit";
+constexpr const char* XML_OVERWRITE_BITSTREAM_ATTRIBUTE_PATH = "path";
+constexpr const char* XML_OVERWRITE_BITSTREAM_ATTRIBUTE_VALUE = "value";
+
+/* Sanity check constants */
+constexpr const char* XML_VALID_NODE_NAMES[] = {
+  XML_PB_TYPE_NODE_NAME,      XML_DEFAULT_MODE_BITS_NODE_NAME,
+  XML_INTERCONNECT_NODE_NAME, XML_CLOCK_ROUTING_NODE_NAME,
+  XML_NON_FABRIC_NODE_NAME,   XML_OVERWRITE_BITSTREAM_NODE_NAME};
+
+#endif