Added more code comments, formatted the code

Signed-off-by: Maciej Kurc <mkurc@antmicro.com>

6 files changed, 124 insertions, 123 deletions

diff --git a/fpga_interchange/arch.cc b/fpga_interchange/arch.cc
index 33720e98..64eef2ad 100644
--- a/fpga_interchange/arch.cc
+++ b/fpga_interchange/arch.cc
@@ -814,8 +814,10 @@ bool Arch::place()
     archInfoToAttributes();
 
     // Print site LUT mapping caching stats
-    log_info("Site LUT mapping cache miss ratio: %.1f%%\n", 
-        getCtx()->site_lut_mapping_cache.getMissRatio() * 100.0f);
+    log_info("Site LUT mapping cache stats:\n");
+    log_info("    miss ratio: %.1f%%\n", getCtx()->site_lut_mapping_cache.getMissRatio() * 100.0f);
+    log_info("    peak size : %zuMB (%zu items)\n", getCtx()->site_lut_mapping_cache.getSizeMB(),
+             getCtx()->site_lut_mapping_cache.getCount());
 
     getCtx()->check();
 
diff --git a/fpga_interchange/luts.cc b/fpga_interchange/luts.cc
index 9c68739e..d9e17ca9 100644
--- a/fpga_interchange/luts.cc
+++ b/fpga_interchange/luts.cc
@@ -255,7 +255,8 @@ uint32_t LutMapper::check_wires(const std::vector<std::vector<int32_t>> &bel_to_
     return vcc_mask;
 }
 
-bool LutMapper::remap_luts(const Context *ctx, SiteLutMappingResult* lut_mapping, pool<const LutBel *, hash_ptr_ops> *blocked_luts)
+bool LutMapper::remap_luts(const Context *ctx, SiteLutMappingResult *lut_mapping,
+                           pool<const LutBel *, hash_ptr_ops> *blocked_luts)
 {
     dict<NetInfo *, LutPin, hash_ptr_ops> lut_pin_map;
     std::vector<const LutBel *> lut_bels;
@@ -417,7 +418,7 @@ bool LutMapper::remap_luts(const Context *ctx, SiteLutMappingResult* lut_mapping
         // Cell to BEL pin map
         for (size_t pin_idx = 0; pin_idx < cellInfo->lut_cell.pins.size(); ++pin_idx) {
             IdString cellPin = cellInfo->lut_cell.pins[pin_idx];
-            IdString belPin  = lutBel.pins[cell_to_bel_pin_remaps[cell_idx][pin_idx]];
+            IdString belPin = lutBel.pins[cell_to_bel_pin_remaps[cell_idx][pin_idx]];
             cell.belPins[cellPin] = belPin;
         }
 
diff --git a/fpga_interchange/luts.h b/fpga_interchange/luts.h
index 7b6ce758..8f33507a 100644
--- a/fpga_interchange/luts.h
+++ b/fpga_interchange/luts.h
@@ -70,12 +70,12 @@ struct LutBel
 
 struct SiteLutMapping
 {
-    struct LutCellMapping {
+    struct LutCellMapping
+    {
         LutCell lut_cell;
     };
 };
 
-
 // Work forward from cell definition and cell -> bel pin map and check that
 // equation is valid.
 void check_equation(const LutCell &lut_cell, const dict<IdString, IdString> &cell_to_bel_map, const LutBel &lut_bel,
@@ -99,7 +99,8 @@ struct LutMapper
 
     std::vector<CellInfo *> cells;
 
-    bool remap_luts(const Context *ctx, SiteLutMappingResult* lut_mapping, pool<const LutBel *, hash_ptr_ops> *blocked_luts);
+    bool remap_luts(const Context *ctx, SiteLutMappingResult *lut_mapping,
+                    pool<const LutBel *, hash_ptr_ops> *blocked_luts);
 
     // Determine which wires given the current mapping must be tied to the
     // default constant.
diff --git a/fpga_interchange/site_lut_mapping_cache.cc b/fpga_interchange/site_lut_mapping_cache.cc
index 7edb0818..0cf741f2 100644
--- a/fpga_interchange/site_lut_mapping_cache.cc
+++ b/fpga_interchange/site_lut_mapping_cache.cc
@@ -17,23 +17,22 @@
  *
  */
 
-#include "nextpnr.h"
-#include "archdefs.h"
-#include "site_arch.h"
 #include "site_lut_mapping_cache.h"
+#include "nextpnr.h"
 
 NEXTPNR_NAMESPACE_BEGIN
 
 // ============================================================================
 
-SiteLutMappingKey SiteLutMappingKey::create (const SiteInformation& siteInfo) {
+SiteLutMappingKey SiteLutMappingKey::create(const SiteInformation &siteInfo)
+{
     const Context *ctx = siteInfo.ctx;
 
     // Look for LUT cells in the site
-    std::vector<CellInfo*> lutCells;
+    std::vector<CellInfo *> lutCells;
     lutCells.reserve(siteInfo.cells_in_site.size());
 
-    for (CellInfo* cellInfo : siteInfo.cells_in_site) {
+    for (CellInfo *cellInfo : siteInfo.cells_in_site) {
 
         // Not a LUT cell
         if (cellInfo->lut_cell.pins.empty()) {
@@ -52,10 +51,7 @@ SiteLutMappingKey SiteLutMappingKey::create (const SiteInformation& siteInfo) {
 
     // Sort cells by BEL indices to maintain always the same order
     std::sort(lutCells.begin(), lutCells.end(),
-              [](const CellInfo* a, const CellInfo* b)
-    {
-        return a->bel.index > b->bel.index;
-    });
+              [](const CellInfo *a, const CellInfo *b) { return a->bel.index > b->bel.index; });
 
     // Initialize the key
     SiteLutMappingKey key;
@@ -67,19 +63,19 @@ SiteLutMappingKey SiteLutMappingKey::create (const SiteInformation& siteInfo) {
     // to get always the same key for the same LUT port configuration even
     // when the actual global net names are different.
     dict<IdString, int32_t> netMap;
-    for (CellInfo* cellInfo : lutCells) {
+    for (CellInfo *cellInfo : lutCells) {
 
         NPNR_ASSERT(key.numCells < SiteLutMappingKey::MAX_LUT_CELLS);
-        auto& cell = key.cells[key.numCells++];
+        auto &cell = key.cells[key.numCells++];
 
-        cell.type       = cellInfo->type;
-        cell.belIndex   = cellInfo->bel.index;
+        cell.type = cellInfo->type;
+        cell.belIndex = cellInfo->bel.index;
 
         cell.conns.fill(0);
 
         size_t portId = 0;
-        for (const auto& port : cellInfo->ports) {
-            const auto& portInfo = port.second;
+        for (const auto &port : cellInfo->ports) {
+            const auto &portInfo = port.second;
 
             // Consider only LUT inputs
             if (portInfo.type != PORT_IN) {
@@ -89,13 +85,12 @@ SiteLutMappingKey SiteLutMappingKey::create (const SiteInformation& siteInfo) {
             // Assign net id if any
             int32_t netId = 0;
             if (portInfo.net != nullptr) {
-                auto    netInfo = portInfo.net;
+                auto netInfo = portInfo.net;
 
                 auto it = netMap.find(netInfo->name);
                 if (it != netMap.end()) {
                     netId = it->second;
-                }
-                else {
+                } else {
                     netId = (int32_t)netMap.size() + 1;
                     netMap[netInfo->name] = netId;
                 }
@@ -114,27 +109,27 @@ SiteLutMappingKey SiteLutMappingKey::create (const SiteInformation& siteInfo) {
 
 // ============================================================================
 
+bool SiteLutMappingResult::apply(const SiteInformation &siteInfo)
+{
 
-bool SiteLutMappingResult::apply (const SiteInformation& siteInfo) {
-
-    Context *ctx = const_cast<Context*>(siteInfo.ctx);
+    Context *ctx = const_cast<Context *>(siteInfo.ctx);
     TileStatus &tileStatus = ctx->get_tile_status(siteInfo.tile);
 
-    for (auto& cell : cells) {
+    for (auto &cell : cells) {
 
         // Get the bound cell
-        CellInfo* cellInfo = tileStatus.boundcells[cell.belIndex];
+        CellInfo *cellInfo = tileStatus.boundcells[cell.belIndex];
         NPNR_ASSERT(cellInfo);
 
         // Double check BEL binding
-        NPNR_ASSERT(cellInfo->bel.tile  == siteInfo.tile);
+        NPNR_ASSERT(cellInfo->bel.tile == siteInfo.tile);
         NPNR_ASSERT(cellInfo->bel.index == cell.belIndex);
 
         // Cell <-> BEL pin map
         size_t numPins = cellInfo->lut_cell.pins.size();
         for (size_t pinIdx = 0; pinIdx < numPins; ++pinIdx) {
-            const IdString& cellPin = cellInfo->lut_cell.pins[pinIdx];
-            auto &belPins           = cellInfo->cell_bel_pins[cellPin];
+            const IdString &cellPin = cellInfo->lut_cell.pins[pinIdx];
+            auto &belPins = cellInfo->cell_bel_pins[cellPin];
 
             // There is only one pin
             belPins.resize(1);
@@ -149,14 +144,15 @@ bool SiteLutMappingResult::apply (const SiteInformation& siteInfo) {
     return true;
 }
 
-size_t SiteLutMappingResult::getSizeInBytes () const {
+size_t SiteLutMappingResult::getSizeInBytes() const
+{
 
     size_t size = 0;
 
     size += sizeof(SiteLutMappingResult);
     size += blockedWires.size() * sizeof(std::pair<IdString, IdString>);
 
-    for (const auto& cell : cells) {
+    for (const auto &cell : cells) {
         size += sizeof(Cell);
         size += cell.belPins.size() * sizeof(decltype(cell.belPins)::value_type);
     }
@@ -166,14 +162,12 @@ size_t SiteLutMappingResult::getSizeInBytes () const {
 
 // ============================================================================
 
-void SiteLutMappingCache::add (const SiteLutMappingKey& key,
-                               const SiteLutMappingResult& result)
+void SiteLutMappingCache::add(const SiteLutMappingKey &key, const SiteLutMappingResult &result)
 {
     cache_[key] = result;
 }
 
-bool SiteLutMappingCache::get (const SiteLutMappingKey& key,
-                               SiteLutMappingResult* result)
+bool SiteLutMappingCache::get(const SiteLutMappingKey &key, SiteLutMappingResult *result)
 {
     if (cache_.count(key) == 0) {
         numMisses++;
@@ -185,17 +179,18 @@ bool SiteLutMappingCache::get (const SiteLutMappingKey& key,
     return true;
 }
 
-void SiteLutMappingCache::clear () {
+void SiteLutMappingCache::clear()
+{
     cache_.clear();
     clearStats();
 }
 
-void SiteLutMappingCache::clearStats () {
-    numHits   = 0;
+void SiteLutMappingCache::clearStats()
+{
+    numHits = 0;
     numMisses = 0;
 }
 
 // ============================================================================
 
 NEXTPNR_NAMESPACE_END
-
diff --git a/fpga_interchange/site_lut_mapping_cache.h b/fpga_interchange/site_lut_mapping_cache.h
index b4c074c7..0025b889 100644
--- a/fpga_interchange/site_lut_mapping_cache.h
+++ b/fpga_interchange/site_lut_mapping_cache.h
@@ -20,75 +20,80 @@
 #ifndef SITE_LUT_MAPPING_CACHE_H
 #define SITE_LUT_MAPPING_CACHE_H
 
-#include "idstring.h"
 #include "nextpnr_namespaces.h"
+#include "idstring.h"
+#include "site_arch.h"
 
 NEXTPNR_NAMESPACE_BEGIN
 
 // Key structure used in site LUT mapping cache
-struct SiteLutMappingKey {
+struct SiteLutMappingKey
+{
 
     // Maximum number of LUT cells per site
-    static constexpr size_t MAX_LUT_CELLS  = 8;
+    static constexpr size_t MAX_LUT_CELLS = 8;
     // Maximum number of LUT inputs per cell
     static constexpr size_t MAX_LUT_INPUTS = 6;
 
     // LUT Cell data
-    struct Cell {
-        IdString    type;       // Cell type
-        int32_t     belIndex;   // Bound BEL index
-  
+    struct Cell
+    {
+        IdString type;    // Cell type
+        int32_t belIndex; // Bound BEL index
+
         // Port to net assignments. These are local net ids generated during
         // key creation. This is to abstract connections from actual design
         // net names. the Id 0 means unconnected.
         std::array<int32_t, MAX_LUT_INPUTS> conns;
 
-        bool operator == (const Cell& other) const {
-            return (type == other.type) &&
-                   (belIndex == other.belIndex) &&
-                   (conns == other.conns);
+        bool operator==(const Cell &other) const
+        {
+            return (type == other.type) && (belIndex == other.belIndex) && (conns == other.conns);
         }
 
-        bool operator != (const Cell& other) const {
-            return (type != other.type) ||
-                   (belIndex != other.belIndex) ||
-                   (conns != other.conns);
+        bool operator!=(const Cell &other) const
+        {
+            return (type != other.type) || (belIndex != other.belIndex) || (conns != other.conns);
         }
     };
 
-    int32_t    tileType; // Tile type
-    int32_t    siteType; // Site type in that tile type
-    size_t     numCells; // LUT cell count
+    int32_t tileType;                      // Tile type
+    int32_t siteType;                      // Site type in that tile type
+    size_t numCells;                       // LUT cell count
     std::array<Cell, MAX_LUT_CELLS> cells; // LUT cell data
 
-    unsigned int    hash_; // Precomputed hash
+    unsigned int hash_; // Precomputed hash
 
-    static SiteLutMappingKey create (const SiteInformation& siteInfo);
+    // Creates a key from the given site state
+    static SiteLutMappingKey create(const SiteInformation &siteInfo);
 
-    size_t getSizeInBytes () const {
-        return sizeof(SiteLutMappingKey);
-    }
+    // Returns size in bytes of the key
+    size_t getSizeInBytes() const { return sizeof(SiteLutMappingKey); }
 
-    void computeHash () {
+    // Precomputes hash of the key and stores it within
+    void computeHash()
+    {
         hash_ = mkhash(0, tileType);
         hash_ = mkhash(hash_, siteType);
         hash_ = mkhash(hash_, numCells);
-        for (size_t j=0; j<numCells; ++j) {
-            const auto& cell = cells[j];
+        for (size_t j = 0; j < numCells; ++j) {
+            const auto &cell = cells[j];
             hash_ = mkhash(hash_, cell.type.index);
             hash_ = mkhash(hash_, cell.belIndex);
-            for (size_t i=0; i<MAX_LUT_INPUTS; ++i) {
+            for (size_t i = 0; i < MAX_LUT_INPUTS; ++i) {
                 hash_ = mkhash(hash_, cell.conns[i]);
             }
         }
     }
 
-    bool compareCells (const SiteLutMappingKey &other) const {
+    // Compares cell data of this and other key
+    bool compareCells(const SiteLutMappingKey &other) const
+    {
         if (numCells != other.numCells) {
             return false;
         }
 
-        for (size_t i=0; i<numCells; ++i) {
+        for (size_t i = 0; i < numCells; ++i) {
             if (cells[i] != other.cells[i]) {
                 return false;
             }
@@ -96,68 +101,70 @@ struct SiteLutMappingKey {
         return true;
     }
 
-    bool operator == (const SiteLutMappingKey &other) const {
-        return (hash_ == other.hash_) &&
-               (tileType == other.tileType) &&
-               (siteType == other.siteType) &&
+    bool operator==(const SiteLutMappingKey &other) const
+    {
+        return (hash_ == other.hash_) && (tileType == other.tileType) && (siteType == other.siteType) &&
                compareCells(other);
     }
 
-    bool operator != (const SiteLutMappingKey &other) const {
-        return (hash_ != other.hash_) ||
-               (tileType != other.tileType) ||
-               (siteType != other.siteType) ||
+    bool operator!=(const SiteLutMappingKey &other) const
+    {
+        return (hash_ != other.hash_) || (tileType != other.tileType) || (siteType != other.siteType) ||
                !compareCells(other);
     }
 
-    unsigned int hash () const {
-        return hash_;
-    }
+    unsigned int hash() const { return hash_; }
 };
 
 // Site LUT mapping result data
-struct SiteLutMappingResult {
+struct SiteLutMappingResult
+{
 
     // LUT cell data
-    struct Cell {
-        int32_t                     belIndex; // BEL in tile index
-        LutCell                     lutCell;  // LUT mapping data
-        dict<IdString, IdString>    belPins;  // Cell to BEL pin mapping
+    struct Cell
+    {
+        int32_t belIndex;                 // BEL in tile index
+        LutCell lutCell;                  // LUT mapping data
+        dict<IdString, IdString> belPins; // Cell to BEL pin mapping
     };
 
-    bool                isValid; // Validity flag
-    std::vector<Cell>   cells;   // Cell data
+    bool isValid;            // Validity flag
+    std::vector<Cell> cells; // Cell data
 
-    pool<std::pair<IdString, IdString>>  blockedWires;
+    pool<std::pair<IdString, IdString>> blockedWires; // Set of blocked wires
 
     // Applies the mapping result to the site
-    bool apply  (const SiteInformation& siteInfo);
+    bool apply(const SiteInformation &siteInfo);
 
     // Returns size in bytes
-    size_t getSizeInBytes () const;
+    size_t getSizeInBytes() const;
 };
 
 // Site LUT mapping cache object
-class SiteLutMappingCache {
-public:
-
-    void add    (const SiteLutMappingKey& key, const SiteLutMappingResult& result);
-    bool get    (const SiteLutMappingKey& key, SiteLutMappingResult* result);
-
-    void clear      ();
-    void clearStats ();
-
-    float getMissRatio () const {
-        return (float)numMisses / (float)(numHits + numMisses);
-    }
-
-    size_t getCount () const {
-        return cache_.size();
-    }
-
-    size_t getSizeMB () const {
+class SiteLutMappingCache
+{
+  public:
+    // Adds an entry to the cache
+    void add(const SiteLutMappingKey &key, const SiteLutMappingResult &result);
+    // Retrieves an entry from the cache. Returns false if not found
+    bool get(const SiteLutMappingKey &key, SiteLutMappingResult *result);
+
+    // Clears the cache
+    void clear();
+    // Clears statistics counters of the cache
+    void clearStats();
+
+    // Return get() miss ratio
+    float getMissRatio() const { return (float)numMisses / (float)(numHits + numMisses); }
+
+    // Returns count of entries in the cache
+    size_t getCount() const { return cache_.size(); }
+
+    // Returns size of the cache rounded upwards to full MBs.
+    size_t getSizeMB() const
+    {
         size_t size = 0;
-        for (const auto& it : cache_) {
+        for (const auto &it : cache_) {
             size += it.first.getSizeInBytes();
             size += it.second.getSizeInBytes();
         }
@@ -166,15 +173,13 @@ public:
         return (size + MB - 1) / MB; // Round up to megabytes
     }
 
-private:
-
-    dict<SiteLutMappingKey, SiteLutMappingResult> cache_;
+  private:
+    dict<SiteLutMappingKey, SiteLutMappingResult> cache_; // The cache
 
-    size_t numHits   = 0;
-    size_t numMisses = 0;
+    size_t numHits = 0;   // Hit count
+    size_t numMisses = 0; // Miss count
 };
 
-
 NEXTPNR_NAMESPACE_END
 
 #endif /* SITE_LUT_MAPPING_CACHE_H */
diff --git a/fpga_interchange/site_router.cc b/fpga_interchange/site_router.cc
index bcfe4539..4094b331 100644
--- a/fpga_interchange/site_router.cc
+++ b/fpga_interchange/site_router.cc
@@ -1099,10 +1099,7 @@ static bool map_luts_in_site(const SiteInformation &site_info, pool<std::pair<Id
         lutMapping.apply(site_info);
 
         blocked_wires->clear();
-        blocked_wires->insert(
-            lutMapping.blockedWires.begin(),
-            lutMapping.blockedWires.end()
-        );
+        blocked_wires->insert(lutMapping.blockedWires.begin(), lutMapping.blockedWires.end());
     }
 
     return lutMapping.isValid;