Loading [MathJax]/extensions/tex2jax.js
CIRCT 21.0.0git
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
LowerXMR.cpp
Go to the documentation of this file.
1//===- LowerXMR.cpp - FIRRTL Lower to XMR -----------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file implements FIRRTL XMR Lowering.
10//
11//===----------------------------------------------------------------------===//
12
22#include "mlir/IR/ImplicitLocOpBuilder.h"
23#include "mlir/Pass/Pass.h"
24#include "llvm/ADT/BitVector.h"
25#include "llvm/ADT/DenseMap.h"
26#include "llvm/ADT/EquivalenceClasses.h"
27#include "llvm/ADT/PostOrderIterator.h"
28#include "llvm/Support/Debug.h"
29
30#define DEBUG_TYPE "firrtl-lower-xmr"
31
32namespace circt {
33namespace firrtl {
34#define GEN_PASS_DEF_LOWERXMR
35#include "circt/Dialect/FIRRTL/Passes.h.inc"
36} // namespace firrtl
37} // namespace circt
38
39using namespace circt;
40using namespace firrtl;
41using hw::InnerRefAttr;
42
43/// The LowerXMRPass will replace every RefResolveOp with an XMR encoded within
44/// a verbatim expr op. This also removes every RefType port from the modules
45/// and corresponding instances. This is a dataflow analysis over a very
46/// constrained RefType. Domain of the dataflow analysis is the set of all
47/// RefSendOps. It computes an interprocedural reaching definitions (of
48/// RefSendOp) analysis. Essentially every RefType value must be mapped to one
49/// and only one RefSendOp. The analysis propagates the dataflow from every
50/// RefSendOp to every value of RefType across modules. The RefResolveOp is the
51/// final leaf into which the dataflow must reach.
52///
53/// Since there can be multiple readers, multiple RefResolveOps can be reachable
54/// from a single RefSendOp. To support multiply instantiated modules and
55/// multiple readers, it is essential to track the path to the RefSendOp, other
56/// than just the RefSendOp. For example, if there exists a wire `xmr_wire` in
57/// module `Foo`, the algorithm needs to support generating Top.Bar.Foo.xmr_wire
58/// and Top.Foo.xmr_wire and Top.Zoo.Foo.xmr_wire for different instance paths
59/// that exist in the circuit.
60
61namespace {
62struct XMRNode {
63 using NextNodeOnPath = std::optional<size_t>;
64 using SymOrIndexOp = PointerUnion<Attribute, Operation *>;
65 SymOrIndexOp info;
66 NextNodeOnPath next;
67};
68[[maybe_unused]] llvm::raw_ostream &operator<<(llvm::raw_ostream &os,
69 const XMRNode &node) {
70 os << "node(";
71 if (auto attr = dyn_cast<Attribute>(node.info))
72 os << "path=" << attr;
73 else {
74 auto subOp = cast<RefSubOp>(cast<Operation *>(node.info));
75 os << "index=" << subOp.getIndex() << " (-> " << subOp.getType() << ")";
76 }
77 os << ", next=" << node.next << ")";
78 return os;
79}
80
81/// Track information about operations being created in a module. This is used
82/// to generate more compact code and reuse operations where possible.
83class ModuleState {
84
85public:
86 ModuleState(FModuleOp &moduleOp) : body(moduleOp.getBodyBlock()) {}
87
88 /// Return the existing XMRRefOp for this type, symbol, and suffix for this
89 /// module. Otherwise, create a new one. The first XMRRefOp will be created
90 /// at the beginning of the module. Subsequent XMRRefOps will be created
91 /// immediately following the first one.
92 Value getOrCreateXMRRefOp(Type type, FlatSymbolRefAttr symbol,
93 StringAttr suffix, ImplicitLocOpBuilder &builder) {
94 // Return the saved XMRRefOp.
95 auto it = xmrRefCache.find({type, symbol, suffix});
96 if (it != xmrRefCache.end())
97 return it->getSecond();
98
99 // Create a new XMRRefOp.
100 OpBuilder::InsertionGuard guard(builder);
101 if (xmrRefPoint.isSet())
102 builder.restoreInsertionPoint(xmrRefPoint);
103 else
104 builder.setInsertionPointToStart(body);
105
106 Value xmr = builder.create<XMRRefOp>(type, symbol, suffix);
107 xmrRefCache.insert({{type, symbol, suffix}, xmr});
108
109 xmrRefPoint = builder.saveInsertionPoint();
110 return xmr;
111 };
112
113private:
114 /// The module's body. This is used to set the insertion point for the first
115 /// created operation.
116 Block *body;
117
118 /// Map used to know if we created this XMRRefOp before.
119 DenseMap<std::tuple<Type, SymbolRefAttr, StringAttr>, Value> xmrRefCache;
120
121 /// The saved insertion point for XMRRefOps.
122 OpBuilder::InsertPoint xmrRefPoint;
123};
124} // end anonymous namespace
125
127
128 void runOnOperation() override {
129 // Populate a CircuitNamespace that can be used to generate unique
130 // circuit-level symbols.
131 CircuitNamespace ns(getOperation());
132 circuitNamespace = &ns;
133
135 &ns, OpBuilder::InsertPoint(getOperation().getBodyBlock(),
136 getOperation().getBodyBlock()->begin()));
137 hierPathCache = &pc;
138
139 llvm::EquivalenceClasses<Value> eq;
140 dataFlowClasses = &eq;
141
142 InstanceGraph &instanceGraph = getAnalysis<InstanceGraph>();
143 SmallVector<RefResolveOp> resolveOps;
144 SmallVector<RefSubOp> indexingOps;
145 SmallVector<Operation *> forceAndReleaseOps;
146 // The dataflow function, that propagates the reachable RefSendOp across
147 // RefType Ops.
148 auto transferFunc = [&](Operation *op) -> LogicalResult {
149 return TypeSwitch<Operation *, LogicalResult>(op)
150 .Case<RefSendOp>([&](RefSendOp send) {
151 // Get a reference to the actual signal to which the XMR will be
152 // generated.
153 Value xmrDef = send.getBase();
154 if (isZeroWidth(send.getType().getType())) {
155 markForRemoval(send);
156 return success();
157 }
158
159 if (auto verbExpr = xmrDef.getDefiningOp<VerbatimExprOp>())
160 if (verbExpr.getSymbolsAttr().empty() && verbExpr->hasOneUse()) {
161 // This represents the internal path into a module. For
162 // generating the correct XMR, no node can be created in this
163 // module. Create a null InnerRef and ensure the hierarchical
164 // path ends at the parent that instantiates this module.
165 auto inRef = InnerRefAttr();
166 auto ind = addReachingSendsEntry(send.getResult(), inRef);
167 xmrPathSuffix[ind] = verbExpr.getText();
168 markForRemoval(verbExpr);
169 markForRemoval(send);
170 return success();
171 }
172 // Get an InnerRefAttr to the value being sent.
173
174 // Add a node, don't need to have symbol on defining operation,
175 // just a way to send out the value.
176 ImplicitLocOpBuilder b(xmrDef.getLoc(), &getContext());
177 b.setInsertionPointAfterValue(xmrDef);
178 SmallString<32> opName;
179 auto nameKind = NameKindEnum::DroppableName;
180
181 if (auto [name, rootKnown] = getFieldName(
182 getFieldRefFromValue(xmrDef, /*lookThroughCasts=*/true),
183 /*nameSafe=*/true);
184 rootKnown) {
185 opName = name + "_probe";
186 nameKind = NameKindEnum::InterestingName;
187 } else if (auto *xmrDefOp = xmrDef.getDefiningOp()) {
188 // Inspect "name" directly for ops that aren't named by above.
189 // (e.g., firrtl.constant)
190 if (auto name = xmrDefOp->getAttrOfType<StringAttr>("name")) {
191 (Twine(name.strref()) + "_probe").toVector(opName);
192 nameKind = NameKindEnum::InterestingName;
193 }
194 }
195 xmrDef = b.create<NodeOp>(xmrDef, opName, nameKind).getResult();
196
197 // Create a new entry for this RefSendOp. The path is currently
198 // local.
199 addReachingSendsEntry(send.getResult(), getInnerRefTo(xmrDef));
200 markForRemoval(send);
201 return success();
202 })
203 .Case<RWProbeOp>([&](RWProbeOp rwprobe) {
204 if (!isZeroWidth(rwprobe.getType().getType()))
205 addReachingSendsEntry(rwprobe.getResult(), rwprobe.getTarget());
206 markForRemoval(rwprobe);
207 return success();
208 })
209 .Case<MemOp>([&](MemOp mem) {
210 // MemOp can produce debug ports of RefType. Each debug port
211 // represents the RefType for the corresponding register of the
212 // memory. Since the memory is not yet generated the register name
213 // is assumed to be "Memory". Note that MemOp creates RefType
214 // without a RefSend.
215 for (const auto &res : llvm::enumerate(mem.getResults()))
216 if (isa<RefType>(mem.getResult(res.index()).getType())) {
217 auto inRef = getInnerRefTo(mem);
218 auto ind = addReachingSendsEntry(res.value(), inRef);
219 xmrPathSuffix[ind] = "Memory";
220 // Just node that all the debug ports of memory must be removed.
221 // So this does not record the port index.
222 refPortsToRemoveMap[mem].resize(1);
223 }
224 return success();
225 })
226 .Case<InstanceOp>(
227 [&](auto inst) { return handleInstanceOp(inst, instanceGraph); })
228 .Case<FConnectLike>([&](FConnectLike connect) {
229 // Ignore BaseType.
230 if (!isa<RefType>(connect.getSrc().getType()))
231 return success();
232 markForRemoval(connect);
233 if (isZeroWidth(
234 type_cast<RefType>(connect.getSrc().getType()).getType()))
235 return success();
236 // Merge the dataflow classes of destination into the source of the
237 // Connect. This handles two cases:
238 // 1. If the dataflow at the source is known, then the
239 // destination is also inferred. By merging the dataflow class of
240 // destination with source, every value reachable from the
241 // destination automatically infers a reaching RefSend.
242 // 2. If dataflow at source is unkown, then just record that both
243 // source and destination will have the same dataflow information.
244 // Later in the pass when the reaching RefSend is inferred at the
245 // leader of the dataflowClass, then we automatically infer the
246 // dataflow at this connect and every value reachable from the
247 // destination.
248 dataFlowClasses->unionSets(connect.getSrc(), connect.getDest());
249 return success();
250 })
251 .Case<RefSubOp>([&](RefSubOp op) -> LogicalResult {
252 markForRemoval(op);
253 if (isZeroWidth(op.getType().getType()))
254 return success();
255
256 // Enqueue for processing after visiting other operations.
257 indexingOps.push_back(op);
258 return success();
259 })
260 .Case<RefResolveOp>([&](RefResolveOp resolve) {
261 // Merge dataflow, under the same conditions as above for Connect.
262 // 1. If dataflow at the resolve.getRef is known, propagate that to
263 // the result. This is true for downward scoped XMRs, that is,
264 // RefSendOp must be visited before the corresponding RefResolveOp
265 // is visited.
266 // 2. Else, just record that both result and ref should have the
267 // same reaching RefSend. This condition is true for upward scoped
268 // XMRs. That is, RefResolveOp can be visited before the
269 // corresponding RefSendOp is recorded.
270
271 markForRemoval(resolve);
272 if (!isZeroWidth(resolve.getType()))
273 dataFlowClasses->unionSets(resolve.getRef(), resolve.getResult());
274 resolveOps.push_back(resolve);
275 return success();
276 })
277 .Case<RefCastOp>([&](RefCastOp op) {
278 markForRemoval(op);
279 if (!isZeroWidth(op.getType().getType()))
280 dataFlowClasses->unionSets(op.getInput(), op.getResult());
281 return success();
282 })
283 .Case<Forceable>([&](Forceable op) {
284 // Handle declarations containing refs as "data".
285 if (type_isa<RefType>(op.getDataRaw().getType())) {
286 markForRemoval(op);
287 return success();
288 }
289
290 // Otherwise, if forceable track the rwprobe result.
291 if (!op.isForceable() || op.getDataRef().use_empty() ||
292 isZeroWidth(op.getDataType()))
293 return success();
294
295 addReachingSendsEntry(op.getDataRef(), getInnerRefTo(op));
296 return success();
297 })
298 .Case<RefForceOp, RefForceInitialOp, RefReleaseOp,
299 RefReleaseInitialOp>([&](auto op) {
300 forceAndReleaseOps.push_back(op);
301 return success();
302 })
303 .Default([&](auto) { return success(); });
304 };
305
306 SmallVector<FModuleOp> publicModules;
307
308 // Traverse the modules in post order.
309
310 DenseSet<InstanceGraphNode *> visited;
311 for (auto *root : instanceGraph) {
312 for (auto *node : llvm::post_order_ext(root, visited)) {
313 auto module = dyn_cast<FModuleOp>(*node->getModule());
314 if (!module)
315 continue;
316 LLVM_DEBUG(llvm::dbgs() << "Traversing module:"
317 << module.getModuleNameAttr() << "\n");
318
319 moduleStates.insert({module, ModuleState(module)});
320
321 if (module.isPublic())
322 publicModules.push_back(module);
323
324 auto result = module.walk([&](Operation *op) {
325 if (transferFunc(op).failed())
326 return WalkResult::interrupt();
327 return WalkResult::advance();
328 });
329
330 if (result.wasInterrupted())
331 return signalPassFailure();
332
333 // Since we walk operations pre-order and not along dataflow edges,
334 // ref.sub may not be resolvable when we encounter them (they're not
335 // just unification). This can happen when refs go through an output
336 // port or input instance result and back into the design. Handle these
337 // by walking them, resolving what we can, until all are handled or
338 // nothing can be resolved.
339 while (!indexingOps.empty()) {
340 // Grab the set of unresolved ref.sub's.
341 decltype(indexingOps) worklist;
342 worklist.swap(indexingOps);
343
344 for (auto op : worklist) {
345 auto inputEntry =
346 getRemoteRefSend(op.getInput(), /*errorIfNotFound=*/false);
347 // If we can't resolve, add back and move on.
348 if (!inputEntry)
349 indexingOps.push_back(op);
350 else
351 addReachingSendsEntry(op.getResult(), op.getOperation(),
352 inputEntry);
353 }
354 // If nothing was resolved, give up.
355 if (worklist.size() == indexingOps.size()) {
356 auto op = worklist.front();
357 getRemoteRefSend(op.getInput());
358 op.emitError(
359 "indexing through probe of unknown origin (input probe?)")
360 .attachNote(op.getInput().getLoc())
361 .append("indexing through this reference");
362 return signalPassFailure();
363 }
364 }
365
366 // Record all the RefType ports to be removed later.
367 size_t numPorts = module.getNumPorts();
368 for (size_t portNum = 0; portNum < numPorts; ++portNum)
369 if (isa<RefType>(module.getPortType(portNum))) {
370 setPortToRemove(module, portNum, numPorts);
371 }
372 }
373 }
374
375 LLVM_DEBUG({
376 for (const auto &I :
377 *dataFlowClasses) { // Iterate over all of the equivalence sets.
378 if (!I->isLeader())
379 continue; // Ignore non-leader sets.
380 // Print members in this set.
381 llvm::interleave(dataFlowClasses->members(*I), llvm::dbgs(), "\n");
382 llvm::dbgs() << "\n dataflow at leader::" << I->getData() << "\n =>";
383 auto iter = dataflowAt.find(I->getData());
384 if (iter != dataflowAt.end()) {
385 for (auto init = refSendPathList[iter->getSecond()]; init.next;
386 init = refSendPathList[*init.next])
387 llvm::dbgs() << "\n " << init;
388 }
389 llvm::dbgs() << "\n Done\n"; // Finish set.
390 }
391 });
392 for (auto refResolve : resolveOps)
393 if (handleRefResolve(refResolve).failed())
394 return signalPassFailure();
395 for (auto *op : forceAndReleaseOps)
396 if (failed(handleForceReleaseOp(op)))
397 return signalPassFailure();
398 for (auto module : publicModules) {
399 if (failed(handlePublicModuleRefPorts(module)))
400 return signalPassFailure();
401 }
403
404 // Clean up
405 moduleNamespaces.clear();
406 visitedModules.clear();
407 dataflowAt.clear();
408 refSendPathList.clear();
409 dataFlowClasses = nullptr;
410 refPortsToRemoveMap.clear();
411 opsToRemove.clear();
412 xmrPathSuffix.clear();
413 circuitNamespace = nullptr;
414 hierPathCache = nullptr;
415 }
416
417 /// Generate the ABI ref_<module> prefix string into `prefix`.
418 void getRefABIPrefix(FModuleLike mod, SmallVectorImpl<char> &prefix) {
419 auto modName = mod.getModuleName();
420 if (auto ext = dyn_cast<FExtModuleOp>(*mod)) {
421 // Use defName for module portion, if set.
422 if (auto defname = ext.getDefname(); defname && !defname->empty())
423 modName = *defname;
424 }
425 (Twine("ref_") + modName).toVector(prefix);
426 }
427
428 /// Get full macro name as StringAttr for the specified ref port.
429 /// Uses existing 'prefix', optionally preprends the backtick character.
430 StringAttr getRefABIMacroForPort(FModuleLike mod, size_t portIndex,
431 const Twine &prefix, bool backTick = false) {
432 return StringAttr::get(&getContext(), Twine(backTick ? "`" : "") + prefix +
433 "_" + mod.getPortName(portIndex));
434 }
435
436 LogicalResult resolveReferencePath(mlir::TypedValue<RefType> refVal,
437 ImplicitLocOpBuilder builder,
438 mlir::FlatSymbolRefAttr &ref,
439 SmallString<128> &stringLeaf) {
440 assert(stringLeaf.empty());
441
442 auto remoteOpPath = getRemoteRefSend(refVal);
443 if (!remoteOpPath)
444 return failure();
445 SmallVector<Attribute> refSendPath;
446 SmallVector<RefSubOp> indexing;
447 size_t lastIndex;
448 while (remoteOpPath) {
449 lastIndex = *remoteOpPath;
450 auto entr = refSendPathList[*remoteOpPath];
451 if (entr.info)
452 TypeSwitch<XMRNode::SymOrIndexOp>(entr.info)
453 .Case<Attribute>([&](auto attr) {
454 // If the path is a singular verbatim expression, the attribute of
455 // the send path list entry will be null.
456 if (attr)
457 refSendPath.push_back(attr);
458 })
459 .Case<Operation *>(
460 [&](auto *op) { indexing.push_back(cast<RefSubOp>(op)); });
461 remoteOpPath = entr.next;
462 }
463 auto iter = xmrPathSuffix.find(lastIndex);
464
465 // If this xmr has a suffix string (internal path into a module, that is not
466 // yet generated).
467 if (iter != xmrPathSuffix.end()) {
468 if (!refSendPath.empty())
469 stringLeaf.append(".");
470 stringLeaf.append(iter->getSecond());
471 }
472
473 assert(!(refSendPath.empty() && stringLeaf.empty()) &&
474 "nothing to index through");
475
476 // All indexing done as the ref is plumbed around indexes through
477 // the target/referent, not the current point of the path which
478 // describes how to access the referent we're indexing through.
479 // Above we gathered all indexing operations, so now append them
480 // to the path (after any relevant `xmrPathSuffix`) to reach
481 // the target element.
482 // Generating these strings here (especially if ref is sent
483 // out from a different design) is fragile but should get this
484 // working well enough while sorting out how to do this better.
485 // Some discussion of this can be found here:
486 // https://github.com/llvm/circt/pull/5551#discussion_r1258908834
487 for (auto subOp : llvm::reverse(indexing)) {
488 TypeSwitch<FIRRTLBaseType>(subOp.getInput().getType().getType())
489 .Case<FVectorType, OpenVectorType>([&](auto vecType) {
490 (Twine("[") + Twine(subOp.getIndex()) + "]").toVector(stringLeaf);
491 })
492 .Case<BundleType, OpenBundleType>([&](auto bundleType) {
493 auto fieldName = bundleType.getElementName(subOp.getIndex());
494 stringLeaf.append({".", fieldName});
495 });
496 }
497
498 if (!refSendPath.empty())
499 // Compute the HierPathOp that stores the path.
500 ref = FlatSymbolRefAttr::get(
501 hierPathCache
502 ->getOrCreatePath(builder.getArrayAttr(refSendPath),
503 builder.getLoc())
504 .getSymNameAttr());
505
506 return success();
507 }
508
509 LogicalResult resolveReference(mlir::TypedValue<RefType> refVal,
510 ImplicitLocOpBuilder &builder,
511 FlatSymbolRefAttr &ref, StringAttr &xmrAttr) {
512 auto remoteOpPath = getRemoteRefSend(refVal);
513 if (!remoteOpPath)
514 return failure();
515
516 SmallString<128> xmrString;
517 if (failed(resolveReferencePath(refVal, builder, ref, xmrString)))
518 return failure();
519 xmrAttr =
520 xmrString.empty() ? StringAttr{} : builder.getStringAttr(xmrString);
521
522 return success();
523 }
524
525 // Replace the Force/Release's ref argument with a resolved XMRRef.
526 LogicalResult handleForceReleaseOp(Operation *op) {
527 return TypeSwitch<Operation *, LogicalResult>(op)
528 .Case<RefForceOp, RefForceInitialOp, RefReleaseOp, RefReleaseInitialOp>(
529 [&](auto op) {
530 // Drop if zero-width target.
531 auto destType = op.getDest().getType();
532 if (isZeroWidth(destType.getType())) {
533 op.erase();
534 return success();
535 }
536
537 ImplicitLocOpBuilder builder(op.getLoc(), op);
538 FlatSymbolRefAttr ref;
539 StringAttr str;
540 if (failed(resolveReference(op.getDest(), builder, ref, str)))
541 return failure();
542
543 Value xmr =
544 moduleStates.find(op->template getParentOfType<FModuleOp>())
545 ->getSecond()
546 .getOrCreateXMRRefOp(destType, ref, str, builder);
547 op.getDestMutable().assign(xmr);
548 return success();
549 })
550 .Default([](auto *op) {
551 return op->emitError("unexpected operation kind");
552 });
553 }
554
555 // Replace the RefResolveOp with verbatim op representing the XMR.
556 LogicalResult handleRefResolve(RefResolveOp resolve) {
557 auto resWidth = getBitWidth(resolve.getType());
558 if (resWidth.has_value() && *resWidth == 0) {
559 // Donot emit 0 width XMRs, replace it with constant 0.
560 ImplicitLocOpBuilder builder(resolve.getLoc(), resolve);
561 auto zeroUintType = UIntType::get(builder.getContext(), 0);
562 auto zeroC = builder.createOrFold<BitCastOp>(
563 resolve.getType(), builder.create<ConstantOp>(
564 zeroUintType, getIntZerosAttr(zeroUintType)));
565 resolve.getResult().replaceAllUsesWith(zeroC);
566 return success();
567 }
568
569 FlatSymbolRefAttr ref;
570 StringAttr str;
571 ImplicitLocOpBuilder builder(resolve.getLoc(), resolve);
572 if (failed(resolveReference(resolve.getRef(), builder, ref, str)))
573 return failure();
574
575 Value result = builder.create<XMRDerefOp>(resolve.getType(), ref, str);
576 resolve.getResult().replaceAllUsesWith(result);
577 return success();
578 }
579
580 void setPortToRemove(Operation *op, size_t index, size_t numPorts) {
581 if (refPortsToRemoveMap[op].size() < numPorts)
582 refPortsToRemoveMap[op].resize(numPorts);
583 refPortsToRemoveMap[op].set(index);
584 }
585
586 // Propagate the reachable RefSendOp across modules.
587 LogicalResult handleInstanceOp(InstanceOp inst,
588 InstanceGraph &instanceGraph) {
589 Operation *mod = inst.getReferencedModule(instanceGraph);
590 if (auto extRefMod = dyn_cast<FExtModuleOp>(mod)) {
591 // Extern modules can generate RefType ports, they have an attached
592 // attribute which specifies the internal path into the extern module.
593 // This string attribute will be used to generate the final xmr.
594 auto internalPaths = extRefMod.getInternalPaths();
595 auto numPorts = inst.getNumResults();
596 SmallString<128> circuitRefPrefix;
597
598 /// Get the resolution string for this ref-type port.
599 auto getPath = [&](size_t portNo) {
600 // If there's an internal path specified (with path), use that.
601 if (internalPaths)
602 if (auto path =
603 cast<InternalPathAttr>(internalPaths->getValue()[portNo])
604 .getPath())
605 return path;
606
607 // Otherwise, we're using the ref ABI. Generate the prefix string
608 // and return the macro for the specified port.
609 if (circuitRefPrefix.empty())
610 getRefABIPrefix(extRefMod, circuitRefPrefix);
611
612 return getRefABIMacroForPort(extRefMod, portNo, circuitRefPrefix, true);
613 };
614
615 for (const auto &res : llvm::enumerate(inst.getResults())) {
616 if (!isa<RefType>(inst.getResult(res.index()).getType()))
617 continue;
618
619 auto inRef = getInnerRefTo(inst);
620 auto ind = addReachingSendsEntry(res.value(), inRef);
621
622 xmrPathSuffix[ind] = getPath(res.index());
623 // The instance result and module port must be marked for removal.
624 setPortToRemove(inst, res.index(), numPorts);
625 setPortToRemove(extRefMod, res.index(), numPorts);
626 }
627 return success();
628 }
629 auto refMod = dyn_cast<FModuleOp>(mod);
630 bool multiplyInstantiated = !visitedModules.insert(refMod).second;
631 for (size_t portNum = 0, numPorts = inst.getNumResults();
632 portNum < numPorts; ++portNum) {
633 auto instanceResult = inst.getResult(portNum);
634 if (!isa<RefType>(instanceResult.getType()))
635 continue;
636 if (!refMod)
637 return inst.emitOpError("cannot lower ext modules with RefType ports");
638 // Reference ports must be removed.
639 setPortToRemove(inst, portNum, numPorts);
640 // Drop the dead-instance-ports.
641 if (instanceResult.use_empty() ||
642 isZeroWidth(type_cast<RefType>(instanceResult.getType()).getType()))
643 continue;
644 auto refModuleArg = refMod.getArgument(portNum);
645 if (inst.getPortDirection(portNum) == Direction::Out) {
646 // For output instance ports, the dataflow is into this module.
647 // Get the remote RefSendOp, that flows through the module ports.
648 // If dataflow at remote module argument does not exist, error out.
649 auto remoteOpPath = getRemoteRefSend(refModuleArg);
650 if (!remoteOpPath)
651 return failure();
652 // Get the path to reaching refSend at the referenced module argument.
653 // Now append this instance to the path to the reaching refSend.
654 addReachingSendsEntry(instanceResult, getInnerRefTo(inst),
655 remoteOpPath);
656 } else {
657 // For input instance ports, the dataflow is into the referenced module.
658 // Input RefType port implies, generating an upward scoped XMR.
659 // No need to add the instance context, since downward reference must be
660 // through single instantiated modules.
661 if (multiplyInstantiated)
662 return refMod.emitOpError(
663 "multiply instantiated module with input RefType port '")
664 << refMod.getPortName(portNum) << "'";
665 dataFlowClasses->unionSets(
666 dataFlowClasses->getOrInsertLeaderValue(refModuleArg),
667 dataFlowClasses->getOrInsertLeaderValue(instanceResult));
668 }
669 }
670 return success();
671 }
672
673 LogicalResult handlePublicModuleRefPorts(FModuleOp module) {
674 auto *body = getOperation().getBodyBlock();
675
676 // Find all the output reference ports.
677 SmallString<128> circuitRefPrefix;
678 SmallVector<std::tuple<StringAttr, StringAttr, ArrayAttr>> ports;
679 auto declBuilder =
680 ImplicitLocOpBuilder::atBlockBegin(module.getLoc(), body);
681 for (size_t portIndex = 0, numPorts = module.getNumPorts();
682 portIndex != numPorts; ++portIndex) {
683 auto refType = type_dyn_cast<RefType>(module.getPortType(portIndex));
684 if (!refType || isZeroWidth(refType.getType()) ||
685 module.getPortDirection(portIndex) != Direction::Out)
686 continue;
687 auto portValue =
688 cast<mlir::TypedValue<RefType>>(module.getArgument(portIndex));
689 mlir::FlatSymbolRefAttr ref;
690 SmallString<128> stringLeaf;
691 if (failed(resolveReferencePath(portValue, declBuilder, ref, stringLeaf)))
692 return failure();
693
694 SmallString<128> formatString;
695 if (ref)
696 formatString += "{{0}}";
697 formatString += stringLeaf;
698
699 // Insert a macro with the format:
700 // ref_<module-name>_<ref-name> <path>
701 if (circuitRefPrefix.empty())
702 getRefABIPrefix(module, circuitRefPrefix);
703 auto macroName =
704 getRefABIMacroForPort(module, portIndex, circuitRefPrefix);
705 declBuilder.create<sv::MacroDeclOp>(macroName, ArrayAttr(), StringAttr());
706 ports.emplace_back(macroName, declBuilder.getStringAttr(formatString),
707 ref ? declBuilder.getArrayAttr({ref}) : ArrayAttr{});
708 }
709
710 // Create a file only if the module has at least one ref port.
711 if (ports.empty())
712 return success();
713
714 // The macros will be exported to a `ref_<module-name>.sv` file.
715 // In the IR, the file is inserted before the module.
716 auto fileBuilder = ImplicitLocOpBuilder(module.getLoc(), module);
717 fileBuilder.create<emit::FileOp>(circuitRefPrefix + ".sv", [&] {
718 for (auto [macroName, formatString, symbols] : ports) {
719 fileBuilder.create<sv::MacroDefOp>(FlatSymbolRefAttr::get(macroName),
720 formatString, symbols);
721 }
722 });
723
724 return success();
725 }
726
727 /// Get the cached namespace for a module.
729 return moduleNamespaces.try_emplace(module, module).first->second;
730 }
731
732 InnerRefAttr getInnerRefTo(Value val) {
733 if (auto arg = dyn_cast<BlockArgument>(val))
734 return ::getInnerRefTo(
735 cast<FModuleLike>(arg.getParentBlock()->getParentOp()),
736 arg.getArgNumber(),
737 [&](FModuleLike mod) -> hw::InnerSymbolNamespace & {
738 return getModuleNamespace(mod);
739 });
740 return getInnerRefTo(val.getDefiningOp());
741 }
742
743 InnerRefAttr getInnerRefTo(Operation *op) {
744 return ::getInnerRefTo(op,
745 [&](FModuleLike mod) -> hw::InnerSymbolNamespace & {
746 return getModuleNamespace(mod);
747 });
748 }
749
750 void markForRemoval(Operation *op) { opsToRemove.push_back(op); }
751
752 std::optional<size_t> getRemoteRefSend(Value val,
753 bool errorIfNotFound = true) {
754 auto iter = dataflowAt.find(dataFlowClasses->getOrInsertLeaderValue(val));
755 if (iter != dataflowAt.end())
756 return iter->getSecond();
757 if (!errorIfNotFound)
758 return std::nullopt;
759 // The referenced module must have already been analyzed, error out if the
760 // dataflow at the child module is not resolved.
761 if (BlockArgument arg = dyn_cast<BlockArgument>(val))
762 arg.getOwner()->getParentOp()->emitError(
763 "reference dataflow cannot be traced back to the remote read op "
764 "for module port '")
765 << dyn_cast<FModuleOp>(arg.getOwner()->getParentOp())
766 .getPortName(arg.getArgNumber())
767 << "'";
768 else
769 val.getDefiningOp()->emitOpError(
770 "reference dataflow cannot be traced back to the remote read op");
771 signalPassFailure();
772 return std::nullopt;
773 }
774
775 size_t
776 addReachingSendsEntry(Value atRefVal, XMRNode::SymOrIndexOp info,
777 std::optional<size_t> continueFrom = std::nullopt) {
778 auto leader = dataFlowClasses->getOrInsertLeaderValue(atRefVal);
779 auto indx = refSendPathList.size();
780 dataflowAt[leader] = indx;
781 refSendPathList.push_back({info, continueFrom});
782 return indx;
783 }
784
786 // Now erase all the Ops and ports of RefType.
787 // This needs to be done as the last step to ensure uses are erased before
788 // the def is erased.
789 for (Operation *op : llvm::reverse(opsToRemove))
790 op->erase();
791 for (auto iter : refPortsToRemoveMap)
792 if (auto mod = dyn_cast<FModuleOp>(iter.getFirst()))
793 mod.erasePorts(iter.getSecond());
794 else if (auto mod = dyn_cast<FExtModuleOp>(iter.getFirst()))
795 mod.erasePorts(iter.getSecond());
796 else if (auto inst = dyn_cast<InstanceOp>(iter.getFirst())) {
797 ImplicitLocOpBuilder b(inst.getLoc(), inst);
798 inst.erasePorts(b, iter.getSecond());
799 inst.erase();
800 } else if (auto mem = dyn_cast<MemOp>(iter.getFirst())) {
801 // Remove all debug ports of the memory.
802 ImplicitLocOpBuilder builder(mem.getLoc(), mem);
803 SmallVector<Attribute, 4> resultNames;
804 SmallVector<Type, 4> resultTypes;
805 SmallVector<Attribute, 4> portAnnotations;
806 SmallVector<Value, 4> oldResults;
807 for (const auto &res : llvm::enumerate(mem.getResults())) {
808 if (isa<RefType>(mem.getResult(res.index()).getType()))
809 continue;
810 resultNames.push_back(mem.getPortName(res.index()));
811 resultTypes.push_back(res.value().getType());
812 portAnnotations.push_back(mem.getPortAnnotation(res.index()));
813 oldResults.push_back(res.value());
814 }
815 auto newMem = builder.create<MemOp>(
816 resultTypes, mem.getReadLatency(), mem.getWriteLatency(),
817 mem.getDepth(), RUWAttr::Undefined,
818 builder.getArrayAttr(resultNames), mem.getNameAttr(),
819 mem.getNameKind(), mem.getAnnotations(),
820 builder.getArrayAttr(portAnnotations), mem.getInnerSymAttr(),
821 mem.getInitAttr(), mem.getPrefixAttr());
822 for (const auto &res : llvm::enumerate(oldResults))
823 res.value().replaceAllUsesWith(newMem.getResult(res.index()));
824 mem.erase();
825 }
826 opsToRemove.clear();
827 refPortsToRemoveMap.clear();
828 dataflowAt.clear();
829 refSendPathList.clear();
830 moduleStates.clear();
831 }
832
834
835private:
836 /// Cached module namespaces.
837 DenseMap<Operation *, hw::InnerSymbolNamespace> moduleNamespaces;
838
839 DenseSet<Operation *> visitedModules;
840 /// Map of a reference value to an entry into refSendPathList. Each entry in
841 /// refSendPathList represents the path to RefSend.
842 /// The path is required since there can be multiple paths to the RefSend and
843 /// we need to identify a unique path.
844 DenseMap<Value, size_t> dataflowAt;
845
846 /// refSendPathList is used to construct a path to the RefSendOp. Each entry
847 /// is an XMRNode, with an InnerRefAttr or indexing op, and a pointer to the
848 /// next node in the path. The InnerRefAttr can be to an InstanceOp or to the
849 /// XMR defining op, the index op records narrowing along path. All the nodes
850 /// representing an InstanceOp or indexing operation must have a valid
851 /// NextNodeOnPath. Only the node representing the final XMR defining op has
852 /// no NextNodeOnPath, which denotes a leaf node on the path.
853 SmallVector<XMRNode> refSendPathList;
854
855 llvm::EquivalenceClasses<Value> *dataFlowClasses;
856 // Instance and module ref ports that needs to be removed.
857 DenseMap<Operation *, llvm::BitVector> refPortsToRemoveMap;
858
859 /// RefResolve, RefSend, and Connects involving them that will be removed.
860 SmallVector<Operation *> opsToRemove;
861
862 /// Record the internal path to an external module or a memory.
863 DenseMap<size_t, SmallString<128>> xmrPathSuffix;
864
866
867 /// Utility to create HerPathOps at a predefined location in the circuit.
868 /// This handles caching and keeps the order consistent.
870
871 /// Per-module helpers for creating operations within modules.
872 DenseMap<FModuleOp, ModuleState> moduleStates;
873};
874
875std::unique_ptr<mlir::Pass> circt::firrtl::createLowerXMRPass() {
876 return std::make_unique<LowerXMRPass>();
877}
assert(baseType &&"element must be base type")
static std::vector< mlir::Value > toVector(mlir::ValueRange range)
static Block * getBodyBlock(FModuleLike mod)
LogicalResult resolveReference(mlir::TypedValue< RefType > refVal, ImplicitLocOpBuilder &builder, FlatSymbolRefAttr &ref, StringAttr &xmrAttr)
Definition LowerXMR.cpp:509
DenseMap< Operation *, hw::InnerSymbolNamespace > moduleNamespaces
Cached module namespaces.
Definition LowerXMR.cpp:837
llvm::EquivalenceClasses< Value > * dataFlowClasses
Definition LowerXMR.cpp:855
DenseMap< size_t, SmallString< 128 > > xmrPathSuffix
Record the internal path to an external module or a memory.
Definition LowerXMR.cpp:863
InnerRefAttr getInnerRefTo(Value val)
Definition LowerXMR.cpp:732
size_t addReachingSendsEntry(Value atRefVal, XMRNode::SymOrIndexOp info, std::optional< size_t > continueFrom=std::nullopt)
Definition LowerXMR.cpp:776
DenseMap< FModuleOp, ModuleState > moduleStates
Per-module helpers for creating operations within modules.
Definition LowerXMR.cpp:872
LogicalResult resolveReferencePath(mlir::TypedValue< RefType > refVal, ImplicitLocOpBuilder builder, mlir::FlatSymbolRefAttr &ref, SmallString< 128 > &stringLeaf)
Definition LowerXMR.cpp:436
DenseMap< Value, size_t > dataflowAt
Map of a reference value to an entry into refSendPathList.
Definition LowerXMR.cpp:844
void setPortToRemove(Operation *op, size_t index, size_t numPorts)
Definition LowerXMR.cpp:580
hw::InnerSymbolNamespace & getModuleNamespace(FModuleLike module)
Get the cached namespace for a module.
Definition LowerXMR.cpp:728
void markForRemoval(Operation *op)
Definition LowerXMR.cpp:750
hw::HierPathCache * hierPathCache
Utility to create HerPathOps at a predefined location in the circuit.
Definition LowerXMR.cpp:869
void garbageCollect()
Definition LowerXMR.cpp:785
LogicalResult handlePublicModuleRefPorts(FModuleOp module)
Definition LowerXMR.cpp:673
void getRefABIPrefix(FModuleLike mod, SmallVectorImpl< char > &prefix)
Generate the ABI ref_<module> prefix string into prefix.
Definition LowerXMR.cpp:418
void runOnOperation() override
Definition LowerXMR.cpp:128
LogicalResult handleRefResolve(RefResolveOp resolve)
Definition LowerXMR.cpp:556
DenseMap< Operation *, llvm::BitVector > refPortsToRemoveMap
Definition LowerXMR.cpp:857
SmallVector< XMRNode > refSendPathList
refSendPathList is used to construct a path to the RefSendOp.
Definition LowerXMR.cpp:853
LogicalResult handleInstanceOp(InstanceOp inst, InstanceGraph &instanceGraph)
Definition LowerXMR.cpp:587
LogicalResult handleForceReleaseOp(Operation *op)
Definition LowerXMR.cpp:526
std::optional< size_t > getRemoteRefSend(Value val, bool errorIfNotFound=true)
Definition LowerXMR.cpp:752
DenseSet< Operation * > visitedModules
Definition LowerXMR.cpp:839
InnerRefAttr getInnerRefTo(Operation *op)
Definition LowerXMR.cpp:743
StringAttr getRefABIMacroForPort(FModuleLike mod, size_t portIndex, const Twine &prefix, bool backTick=false)
Get full macro name as StringAttr for the specified ref port.
Definition LowerXMR.cpp:430
CircuitNamespace * circuitNamespace
Definition LowerXMR.cpp:865
bool isZeroWidth(FIRRTLBaseType t)
Definition LowerXMR.cpp:833
SmallVector< Operation * > opsToRemove
RefResolve, RefSend, and Connects involving them that will be removed.
Definition LowerXMR.cpp:860
int32_t getBitWidthOrSentinel()
If this is an IntType, AnalogType, or sugar type for a single bit (Clock, Reset, etc) then return the...
This graph tracks modules and where they are instantiated.
FieldRef getFieldRefFromValue(Value value, bool lookThroughCasts=false)
Get the FieldRef from a value.
hw::InnerRefAttr getInnerRefTo(const hw::InnerSymTarget &target, GetNamespaceCallback getNamespace)
Obtain an inner reference to the target (operation or port), adding an inner symbol as necessary.
llvm::raw_ostream & operator<<(llvm::raw_ostream &os, const InstanceInfo::LatticeValue &value)
std::pair< std::string, bool > getFieldName(const FieldRef &fieldRef, bool nameSafe=false)
Get a string identifier representing the FieldRef.
std::unique_ptr< mlir::Pass > createLowerXMRPass()
Definition LowerXMR.cpp:875
std::optional< int64_t > getBitWidth(FIRRTLBaseType type, bool ignoreFlip=false)
IntegerAttr getIntZerosAttr(Type type)
Utility for generating a constant zero attribute.
void info(Twine message)
Definition LSPUtils.cpp:20
The InstanceGraph op interface, see InstanceGraphInterface.td for more details.
The namespace of a CircuitOp, generally inhabited by modules.
Definition Namespace.h:24