[hw] Rename HierPathBuilder -> HierPathCache

Rename the `hw::HierPathBuilder` utility to `hw::HierPathCache`.  This
more accurately represents what it is, i.e., it is a cache of hierarchical
path ops.

h/t @rwy7 for the offline suggestion for the name change.

Signed-off-by: Schuyler Eldridge <[email protected]>

Author: seldridge

include/circt/Dialect/HW/HierPathBuilder.h renamed to include/circt/Dialect/HW/HierPathCache.h

@@ -1,24 +1,24 @@
-//===- HierPathBuilder.h - HierPathOp Builder Utility ---------------------===//
+//===- HierPathCache.h - HierPathOp Caching Utility -----------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
-// The HierPathBuilder is a utility for creating hierarchical paths at some
-// location in a circuit.  This exists to help with a common pattern where you
-// are running a transform and you need to build HierPathOps, but you don't know
-// when you are going to do it.  You also don't want to create the same
-// HierPathOp multiple times.  This utility will maintain a cache of existing
-// ops and only create new ones when necessary.  Additionally, this creates the
-// ops in nice, predictable order.  I.e., all the ops are inserted into the IR
-// in the order they are created, not in reverse order.
+// The HierPathCache is a utility for creating hierarchical paths at a
+// pre-defined location in a circuit.  This exists to help with a common pattern
+// where you are running a transform and you need to build HierPathOps, but you
+// don't know when you are going to do it.  You also don't want to create the
+// same HierPathOp multiple times.  This utility will maintain a cache of
+// existing ops and only create new ones when necessary.  Additionally, this
+// creates the ops in nice, predictable order.  I.e., all the ops are inserted
+// into the IR in the order they are created, not in reverse order.
 //
 //===----------------------------------------------------------------------===//
 
-#ifndef CIRCT_DIALECT_HW_HIERPATHBUILDER_H
-#define CIRCT_DIALECT_HW_HIERPATHBUILDER_H
+#ifndef CIRCT_DIALECT_HW_HIERPATHCACHE_H
+#define CIRCT_DIALECT_HW_HIERPATHCACHE_H
 
 #include "circt/Dialect/HW/HWOps.h"
 #include "circt/Support/Namespace.h"
@@ -27,14 +27,18 @@
 namespace circt {
 namespace hw {
 
-class HierPathBuilder {
+class HierPathCache {
 public:
-  HierPathBuilder(Namespace *ns, OpBuilder::InsertPoint insertionPoint)
+  HierPathCache(Namespace *ns, OpBuilder::InsertPoint insertionPoint)
       : ns(ns), pathInsertPoint(insertionPoint) {}
 
+  /// Get an existing `hw::HierPathOp` at the default location in the circuit.
   HierPathOp getOrCreatePath(ArrayAttr pathArray, Location loc,
                              StringRef nameHint = "xmrPath");
 
+  /// Get an existing `hw::HierPathOp` at a specific location in the circuit.
+  /// The insertion point will be updated to allow for this method to be used
+  /// repeatedly to create the ops predictably, one after the other.
   HierPathOp getOrCreatePath(ArrayAttr pathArray, Location loc,
                              OpBuilder::InsertPoint &insertPoint,
                              StringRef nameHint = "xmrPath");
@@ -54,4 +58,4 @@ class HierPathBuilder {
 } // namespace hw
 } // namespace circt
 
-#endif // CIRCT_DIALECT_HW_HIERPATHBUILDER_H
+#endif // CIRCT_DIALECT_HW_HIERPATHCACHE_H

lib/Dialect/FIRRTL/Transforms/LowerXMR.cpp

@@ -16,7 +16,7 @@
 #include "circt/Dialect/FIRRTL/FIRRTLUtils.h"
 #include "circt/Dialect/FIRRTL/Namespace.h"
 #include "circt/Dialect/FIRRTL/Passes.h"
-#include "circt/Dialect/HW/HierPathBuilder.h"
+#include "circt/Dialect/HW/HierPathCache.h"
 #include "circt/Dialect/HW/InnerSymbolNamespace.h"
 #include "circt/Dialect/SV/SVOps.h"
 #include "mlir/IR/ImplicitLocOpBuilder.h"
@@ -131,10 +131,10 @@ class LowerXMRPass : public circt::firrtl::impl::LowerXMRBase<LowerXMRPass> {
     CircuitNamespace ns(getOperation());
     circuitNamespace = &ns;
 
-    hw::HierPathBuilder pb(
+    hw::HierPathCache pc(
         &ns, OpBuilder::InsertPoint(getOperation().getBodyBlock(),
                                     getOperation().getBodyBlock()->begin()));
-    hierPathBuilder = &pb;
+    hierPathCache = &pc;
 
     llvm::EquivalenceClasses<Value> eq;
     dataFlowClasses = &eq;
@@ -414,7 +414,7 @@ class LowerXMRPass : public circt::firrtl::impl::LowerXMRBase<LowerXMRPass> {
     opsToRemove.clear();
     xmrPathSuffix.clear();
     circuitNamespace = nullptr;
-    hierPathBuilder = nullptr;
+    hierPathCache = nullptr;
   }
 
   /// Generate the ABI ref_<module> prefix string into `prefix`.
@@ -501,7 +501,7 @@ class LowerXMRPass : public circt::firrtl::impl::LowerXMRBase<LowerXMRPass> {
     if (!refSendPath.empty())
       // Compute the HierPathOp that stores the path.
       ref = FlatSymbolRefAttr::get(
-          hierPathBuilder
+          hierPathCache
               ->getOrCreatePath(builder.getArrayAttr(refSendPath),
                                 builder.getLoc())
               .getSymNameAttr());
@@ -869,7 +869,7 @@ class LowerXMRPass : public circt::firrtl::impl::LowerXMRBase<LowerXMRPass> {
 
   /// Utility to create HerPathOps at a predefined location in the circuit.
   /// This handles caching and keeps the order consistent.
-  hw::HierPathBuilder *hierPathBuilder;
+  hw::HierPathCache *hierPathCache;
 
   /// Per-module helpers for creating operations within modules.
   DenseMap<FModuleOp, ModuleState> moduleStates;

lib/Dialect/HW/CMakeLists.txt

@@ -1,7 +1,7 @@
 set(CIRCT_HW_Sources
   ConversionPatterns.cpp
   CustomDirectiveImpl.cpp
-  HierPathBuilder.cpp
+  HierPathCache.cpp
   HWAttributes.cpp
   HWEnums.cpp
   HWDialect.cpp

lib/Dialect/HW/HierPathBuilder.cpp renamed to lib/Dialect/HW/HierPathCache.cpp

@@ -1,29 +1,29 @@
-//===- HierPathBuilder.cpp - HierPathOp Builder Utility -------------------===//
+//===- HierPathCache.h - HierPathOp Caching Utility -----------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
-// Implementation of a utility for creating Hierarchical Path operation.s
+// Implementation of a utility for creating Hierarchical Path operations.
 //
 //===----------------------------------------------------------------------===//
 
-#include "circt/Dialect/HW/HierPathBuilder.h"
+#include "circt/Dialect/HW/HierPathCache.h"
 #include "circt/Dialect/HW/HWOps.h"
 
 namespace circt {
 namespace hw {
 
-HierPathOp HierPathBuilder::getOrCreatePath(ArrayAttr pathArray, Location loc,
-                                            StringRef nameHint) {
+HierPathOp HierPathCache::getOrCreatePath(ArrayAttr pathArray, Location loc,
+                                          StringRef nameHint) {
   return getOrCreatePath(pathArray, loc, pathInsertPoint, nameHint);
 }
 
-HierPathOp HierPathBuilder::getOrCreatePath(ArrayAttr pathArray, Location loc,
-                                            OpBuilder::InsertPoint &insertPoint,
-                                            StringRef nameHint) {
+HierPathOp HierPathCache::getOrCreatePath(ArrayAttr pathArray, Location loc,
+                                          OpBuilder::InsertPoint &insertPoint,
+                                          StringRef nameHint) {
 
   assert(pathArray && !pathArray.empty());
   // Return an existing HierPathOp if one exists with the same path.  Add