FIRRTLInstanceInfo.cpp

Go to the documentation of this file.

//===- FIRRTLInstanceInfo.cpp - Instance info analysis ----------*- C++ -*-===//
//
// 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
//
//===----------------------------------------------------------------------===//
//
// This file defines the InstanceInfo analysis.  This is an analysis that
// depends on the InstanceGraph analysis, but provides additional information
// about FIRRTL operations.  This is useful if you find yourself needing to
// selectively iterate over parts of the design.
//
//===----------------------------------------------------------------------===//
 
#include "circt/Analysis/FIRRTLInstanceInfo.h"
#include "circt/Dialect/FIRRTL/AnnotationDetails.h"
#include "circt/Dialect/FIRRTL/FIRRTLInstanceGraph.h"
#include "circt/Dialect/SV/SVOps.h"
#include "circt/Support/Debug.h"
#include "circt/Support/InstanceGraph.h"
#include "llvm/ADT/PostOrderIterator.h"
#include "llvm/Support/Debug.h"
 
#ifndef NDEBUG
#include "llvm/ADT/DepthFirstIterator.h"
#endif
 
#define DEBUG_TYPE "firrtl-analysis-instanceinfo"
 
using namespace circt;
using namespace firrtl;
 
bool InstanceInfo::isInstanceUnderLayer(InstanceOp inst) {
  return inst.getLowerToBind() || inst.getDoNotPrint() ||
         inst->getParentOfType<LayerBlockOp>() ||
         inst->getParentOfType<sv::IfDefOp>();
}
 
bool InstanceInfo::isInstanceUnderLayer(InstanceChoiceOp inst) {
  return inst->getParentOfType<LayerBlockOp>() ||
         inst->getParentOfType<sv::IfDefOp>();
}
 
bool InstanceInfo::LatticeValue::isUnknown() const { return kind == Unknown; }
 
bool InstanceInfo::LatticeValue::isConstant() const { return kind == Constant; }
 
bool InstanceInfo::LatticeValue::isMixed() const { return kind == Mixed; }
 
bool InstanceInfo::LatticeValue::getConstant() const {
  assert(isConstant());
  return value;
}
 
void InstanceInfo::LatticeValue::markConstant(bool constant) {
  kind = Constant;
  value = constant;
}
 
void InstanceInfo::LatticeValue::markMixed() { kind = Mixed; }
 
void InstanceInfo::LatticeValue::mergeIn(LatticeValue that) {
  if (kind > that.kind)
    return;
 
  if (kind < that.kind) {
    kind = that.kind;
    value = that.value;
    return;
  }
 
  if (isConstant() && getConstant() != that.value)
    kind = Mixed;
}
 
void InstanceInfo::LatticeValue::mergeIn(bool value) {
  LatticeValue latticeValue;
  latticeValue.markConstant(value);
  mergeIn(latticeValue);
}
 
InstanceInfo::LatticeValue InstanceInfo::LatticeValue::operator!() {
  if (isUnknown() || isMixed())
    return *this;
 
  auto invert = LatticeValue();
  invert.markConstant(!getConstant());
  return invert;
}
 
InstanceInfo::InstanceInfo(Operation *op, mlir::AnalysisManager &am) {
  auto &iGraph = am.getAnalysis<InstanceGraph>();
 
  // Setup circuit attributes based on presence of annotations.
  circuitAttributes.effectiveDut = iGraph.getTopLevelNode()->getModule();
  for (auto *node : iGraph) {
    auto moduleOp = node->getModule();
    AnnotationSet annotations(moduleOp);
    if (annotations.hasAnnotation(markDUTAnnoClass)) {
      circuitAttributes.dut = moduleOp;
      circuitAttributes.effectiveDut = moduleOp;
    }
  }
 
  // Setup boundary conditions for any modules without users.
  for (auto *node : iGraph) {
    if (!node->noUses())
      continue;
 
    auto moduleOp = node->getModule();
    ModuleAttributes &attributes = moduleAttributes[moduleOp];
 
    attributes.underDut.mergeIn(isDut(moduleOp));
    attributes.inDesign.mergeIn(isDut(moduleOp));
    attributes.inEffectiveDesign.mergeIn(isEffectiveDut(moduleOp) || !hasDut());
    attributes.underLayer.mergeIn(false);
    attributes.inInstanceChoice.mergeIn(false);
  }
 
  // Visit modules in reverse post-order (visit parents before children) to
  // merge parent attributes and per-instance attributes into children.
  iGraph.walkInversePostOrder([&](igraph::InstanceGraphNode &modIt) {
    auto moduleOp = modIt.getModule();
    ModuleAttributes &attributes = moduleAttributes[moduleOp];
 
    AnnotationSet annotations(moduleOp);
    auto isDut = annotations.hasAnnotation(markDUTAnnoClass);
    auto isGCCompanion = annotations.hasAnnotation(companionAnnoClass);
 
    if (isDut) {
      attributes.underDut.markConstant(true);
      attributes.inDesign.markConstant(true);
      attributes.inEffectiveDesign.markConstant(true);
    }
 
    if (isGCCompanion) {
      attributes.inDesign.mergeIn(false);
      attributes.inEffectiveDesign.mergeIn(false);
      attributes.underLayer.mergeIn(true);
    }
 
    // Merge in values based on the instantiations of this module.
    for (auto *useIt : modIt.uses()) {
      auto parentOp = useIt->getParent()->getModule();
      auto parentAttrs = moduleAttributes.find(parentOp)->getSecond();
 
      // Update underDut.
      if (!isDut)
        attributes.underDut.mergeIn(parentAttrs.underDut);
 
      // Update underLayer.
      bool underLayer = false;
      if (auto instanceOp = useIt->getInstance<InstanceOp>())
        underLayer = InstanceInfo::isInstanceUnderLayer(instanceOp);
 
      // Update inInstanceChoice.
      if (auto instanceChoiceOp = useIt->getInstance<InstanceChoiceOp>()) {
        attributes.inInstanceChoice.mergeIn(true);
        underLayer = isInstanceUnderLayer(instanceChoiceOp);
      } else {
        attributes.inInstanceChoice.mergeIn(parentAttrs.inInstanceChoice);
      }
 
      if (!isGCCompanion) {
        if (underLayer)
          attributes.underLayer.mergeIn(true);
        else
          attributes.underLayer.mergeIn(parentAttrs.underLayer);
      }
 
      // Update inDesign and inEffectiveDesign.
      if (underLayer) {
        attributes.inDesign.mergeIn(false);
        attributes.inEffectiveDesign.mergeIn(false);
      } else if (!isDut && !isGCCompanion) {
        attributes.inDesign.mergeIn(parentAttrs.inDesign);
        attributes.inEffectiveDesign.mergeIn(parentAttrs.inEffectiveDesign);
      }
    }
  });
 
  // Visit modules in post-order (visit children before parents) to aggregate
  // information into parents about themselves and their children.
  //
  // This walk is _more expensive_ than the earlier walk as this, at worst,
  // needs to do a full IR walk.  Mitigate this via short circuiting when we
  // have enough information to interrupt the walk or to skip it entirely.
  iGraph.walkPostOrder([&](igraph::InstanceGraphNode &modIt) {
    auto moduleOp = modIt.getModule();
    ModuleAttributes &attributes = moduleAttributes[moduleOp];
 
    // Merge in attributes of instances within the module.
    for (auto *instIt : modIt) {
      attributes.hasProperties |=
          moduleAttributes[instIt->getTarget()->getModule()].hasProperties;
      if (attributes.postOrderSaturated())
        break;
    }
 
    // Early exit if there is no body to examine or if the module cannot be
    // public.
    auto moduleLike = modIt.getModule<FModuleLike>();
    if (!moduleLike)
      return;
 
    // Merge in attributes of the module.
    attributes.hasProperties |= moduleLike.isPublic();
 
    // If the module is classlike, it is a property.  Walk the ports and update
    // attributes for each.
    attributes.hasProperties |= isa<ClassLike>(moduleLike.getOperation());
    for (auto port : moduleLike.getPorts()) {
      attributes.hasProperties |= isa<PropertyType>(port.type);
      if (attributes.postOrderSaturated())
        break;
    }
 
    // Early exit if the attributes can no longer change.  This avoids needing
    // to do a walk of the module body.
    if (attributes.postOrderSaturated())
      return;
 
    // Walk the ops to populate information, short circuiting as soon as
    // we've gathered enough information to stop the walk.  Only FModuleOp has
    // a body to walk; external/intrinsic modules are fully characterized by
    // their ports, already checked above.
    if (auto fmodule = dyn_cast<FModuleOp>(moduleLike.getOperation())) {
      auto isPropertyType = [](Type t) { return isa<PropertyType>(t); };
      fmodule.walk([&](Operation *op) {
        if (attributes.hasProperties)
          return WalkResult::interrupt();
        attributes.hasProperties |=
            llvm::any_of(op->getOperandTypes(), isPropertyType) ||
            llvm::any_of(op->getResultTypes(), isPropertyType);
        return WalkResult::advance();
      });
    }
  });
 
  LLVM_DEBUG({
    mlir::OpPrintingFlags flags;
    flags.skipRegions();
    debugHeader("FIRRTL InstanceInfo Analysis")
        << "\n"
        << llvm::indent(2) << "circuit attributes:\n"
        << llvm::indent(4) << "hasDut: " << (hasDut() ? "true" : "false")
        << "\n"
        << llvm::indent(4) << "dut: ";
    if (auto dut = circuitAttributes.dut)
      dut->print(llvm::dbgs(), flags);
    else
      llvm::dbgs() << "null";
    llvm::dbgs() << "\n" << llvm::indent(4) << "effectiveDut: ";
    circuitAttributes.effectiveDut->print(llvm::dbgs(), flags);
    llvm::dbgs() << "\n" << llvm::indent(2) << "module attributes:\n";
    iGraph.walkInversePostOrder([&](auto &modIt) {
      auto moduleOp = modIt.getModule();
      auto attributes = moduleAttributes[moduleOp];
      llvm::dbgs().indent(4)
          << "- module: " << moduleOp.getModuleName() << "\n"
          << llvm::indent(6)
          << "isDut: " << (isDut(moduleOp) ? "true" : "false") << "\n"
          << llvm::indent(6)
          << "isEffectiveDut: " << (isEffectiveDut(moduleOp) ? "true" : "false")
          << "\n"
          << llvm::indent(6) << "underDut: " << attributes.underDut << "\n"
          << llvm::indent(6) << "underLayer: " << attributes.underLayer << "\n"
          << llvm::indent(6) << "inDesign: " << attributes.inDesign << "\n"
          << llvm::indent(6)
          << "inEffectiveDesign: " << attributes.inEffectiveDesign << "\n"
          << llvm::indent(6)
          << "inInstanceChoice: " << attributes.inInstanceChoice << "\n"
          << llvm::indent(6)
          << "hasProperties: " << (attributes.hasProperties ? "true" : "false")
          << "\n";
    });
  });
}
 
const InstanceInfo::ModuleAttributes &
InstanceInfo::getModuleAttributes(igraph::ModuleOpInterface op) {
  return moduleAttributes.find(op)->getSecond();
}
 
bool InstanceInfo::hasDut() { return circuitAttributes.dut; }
 
bool InstanceInfo::isDut(igraph::ModuleOpInterface op) {
  if (hasDut())
    return op == circuitAttributes.dut;
  return false;
}
 
bool InstanceInfo::isEffectiveDut(igraph::ModuleOpInterface op) {
  if (hasDut())
    return isDut(op);
  return op == circuitAttributes.effectiveDut;
}
 
igraph::ModuleOpInterface InstanceInfo::getDut() {
  return circuitAttributes.dut;
}
 
igraph::ModuleOpInterface InstanceInfo::getEffectiveDut() {
  return circuitAttributes.effectiveDut;
}
 
bool InstanceInfo::anyInstanceUnderDut(igraph::ModuleOpInterface op) {
  auto underDut = getModuleAttributes(op).underDut;
  return underDut.isMixed() || allInstancesUnderDut(op);
}
 
bool InstanceInfo::allInstancesUnderDut(igraph::ModuleOpInterface op) {
  auto underDut = getModuleAttributes(op).underDut;
  return underDut.isConstant() && underDut.getConstant();
}
 
bool InstanceInfo::anyInstanceUnderEffectiveDut(igraph::ModuleOpInterface op) {
  return !hasDut() || anyInstanceUnderDut(op);
}
 
bool InstanceInfo::allInstancesUnderEffectiveDut(igraph::ModuleOpInterface op) {
  return !hasDut() || allInstancesUnderDut(op);
}
 
bool InstanceInfo::anyInstanceUnderLayer(igraph::ModuleOpInterface op) {
  auto underLayer = getModuleAttributes(op).underLayer;
  return underLayer.isMixed() || allInstancesUnderLayer(op);
}
 
bool InstanceInfo::allInstancesUnderLayer(igraph::ModuleOpInterface op) {
  auto underLayer = getModuleAttributes(op).underLayer;
  return underLayer.isConstant() && underLayer.getConstant();
}
 
bool InstanceInfo::anyInstanceInDesign(igraph::ModuleOpInterface op) {
  auto inDesign = getModuleAttributes(op).inDesign;
  return inDesign.isMixed() || allInstancesInDesign(op);
}
 
bool InstanceInfo::allInstancesInDesign(igraph::ModuleOpInterface op) {
  auto inDesign = getModuleAttributes(op).inDesign;
  return inDesign.isConstant() && inDesign.getConstant();
}
 
bool InstanceInfo::anyInstanceInEffectiveDesign(igraph::ModuleOpInterface op) {
  auto inEffectiveDesign = getModuleAttributes(op).inEffectiveDesign;
  return inEffectiveDesign.isMixed() || allInstancesInEffectiveDesign(op);
}
 
bool InstanceInfo::allInstancesInEffectiveDesign(igraph::ModuleOpInterface op) {
  auto inEffectiveDesign = getModuleAttributes(op).inEffectiveDesign;
  return inEffectiveDesign.isConstant() && inEffectiveDesign.getConstant();
}
 
bool InstanceInfo::anyInstanceInInstanceChoice(igraph::ModuleOpInterface op) {
  auto inInstanceChoice = getModuleAttributes(op).inInstanceChoice;
  return inInstanceChoice.isMixed() ||
         (inInstanceChoice.isConstant() && inInstanceChoice.getConstant());
}
 
bool InstanceInfo::moduleContainsProperties(igraph::ModuleOpInterface op) {
  return getModuleAttributes(op).hasProperties;
}