ESILowerToHW.cpp

Go to the documentation of this file.

//===- ESILowerToHW.cpp - Lower ESI to HW -----------------------*- 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
//
//===----------------------------------------------------------------------===//
//
// Lower to HW/SV conversions and pass.
//
//===----------------------------------------------------------------------===//
 
#include "../PassDetails.h"
 
#include "circt/Dialect/Comb/CombOps.h"
#include "circt/Dialect/ESI/APIUtilities.h"
#include "circt/Dialect/ESI/ESIOps.h"
#include "circt/Dialect/HW/HWOps.h"
#include "circt/Dialect/SV/SVOps.h"
#include "circt/Support/BackedgeBuilder.h"
#include "circt/Support/LLVM.h"
#include "circt/Support/SymCache.h"
 
#include "mlir/Transforms/DialectConversion.h"
 
#include "llvm/ADT/StringExtras.h"
#include "llvm/ADT/TypeSwitch.h"
#include "llvm/Support/JSON.h"
 
using namespace circt;
using namespace circt::esi;
using namespace circt::esi::detail;
using namespace circt::hw;
using namespace circt::sv;
 
namespace {
/// Lower PipelineStageOp ops to an HW implementation. Unwrap and re-wrap
/// appropriately. Another conversion will take care merging the resulting
/// adjacent wrap/unwrap ops.
struct PipelineStageLowering : public OpConversionPattern<PipelineStageOp> {
public:
  PipelineStageLowering(ESIHWBuilder &builder, MLIRContext *ctxt)
      : OpConversionPattern(ctxt), builder(builder) {}
  using OpConversionPattern::OpConversionPattern;
 
  LogicalResult
  matchAndRewrite(PipelineStageOp stage, OpAdaptor adaptor,
                  ConversionPatternRewriter &rewriter) const final;
 
private:
  ESIHWBuilder &builder;
};
} // anonymous namespace
 
LogicalResult PipelineStageLowering::matchAndRewrite(
    PipelineStageOp stage, OpAdaptor adaptor,
    ConversionPatternRewriter &rewriter) const {
  auto loc = stage.getLoc();
  auto chPort = stage.getInput().getType().dyn_cast<ChannelType>();
  if (!chPort)
    return rewriter.notifyMatchFailure(stage, "stage had wrong type");
  Operation *symTable = stage->getParentWithTrait<OpTrait::SymbolTable>();
  auto stageModule = builder.declareStage(symTable, stage);
 
  size_t width = circt::hw::getBitWidth(chPort.getInner());
 
  ArrayAttr stageParams =
      builder.getStageParameterList(rewriter.getUI32IntegerAttr(width));
 
  // Unwrap the channel. The ready signal is a Value we haven't created yet,
  // so create a temp value and replace it later. Give this constant an
  // odd-looking type to make debugging easier.
  circt::BackedgeBuilder back(rewriter, loc);
  circt::Backedge wrapReady = back.get(rewriter.getI1Type());
  auto unwrap =
      rewriter.create<UnwrapValidReadyOp>(loc, stage.getInput(), wrapReady);
 
  StringRef pipeStageName = "pipelineStage";
  if (auto name = stage->getAttrOfType<StringAttr>("name"))
    pipeStageName = name.getValue();
 
  // Instantiate the "ESI_PipelineStage" external module.
  circt::Backedge stageReady = back.get(rewriter.getI1Type());
  llvm::SmallVector<Value> operands = {stage.getClk(), stage.getRst()};
  operands.push_back(unwrap.getRawOutput());
  operands.push_back(unwrap.getValid());
  operands.push_back(stageReady);
  auto stageInst = rewriter.create<InstanceOp>(loc, stageModule, pipeStageName,
                                               operands, stageParams);
  auto stageInstResults = stageInst.getResults();
 
  // Set a_ready (from the unwrap) back edge correctly to its output from
  // stage.
  wrapReady.setValue(stageInstResults[0]);
  Value x, xValid;
  x = stageInstResults[1];
  xValid = stageInstResults[2];
 
  // Wrap up the output of the HW stage module.
  auto wrap = rewriter.create<WrapValidReadyOp>(
      loc, chPort, rewriter.getI1Type(), x, xValid);
  // Set the stages x_ready backedge correctly.
  stageReady.setValue(wrap.getReady());
 
  rewriter.replaceOp(stage, wrap.getChanOutput());
  return success();
}
 
namespace {
struct NullSourceOpLowering : public OpConversionPattern<NullSourceOp> {
public:
  NullSourceOpLowering(MLIRContext *ctxt) : OpConversionPattern(ctxt) {}
  using OpConversionPattern::OpConversionPattern;
 
  LogicalResult
  matchAndRewrite(NullSourceOp nullop, OpAdaptor adaptor,
                  ConversionPatternRewriter &rewriter) const final;
};
} // anonymous namespace
 
LogicalResult NullSourceOpLowering::matchAndRewrite(
    NullSourceOp nullop, OpAdaptor adaptor,
    ConversionPatternRewriter &rewriter) const {
  auto innerType = nullop.getOut().getType().cast<ChannelType>().getInner();
  Location loc = nullop.getLoc();
  int64_t width = hw::getBitWidth(innerType);
  if (width == -1)
    return rewriter.notifyMatchFailure(
        nullop, "NullOp lowering only supports hw types");
  auto valid =
      rewriter.create<hw::ConstantOp>(nullop.getLoc(), rewriter.getI1Type(), 0);
  auto zero =
      rewriter.create<hw::ConstantOp>(loc, rewriter.getIntegerType(width), 0);
  auto typedZero = rewriter.create<hw::BitcastOp>(loc, innerType, zero);
  auto wrap = rewriter.create<WrapValidReadyOp>(loc, typedZero, valid);
  wrap->setAttr("name", rewriter.getStringAttr("nullsource"));
  rewriter.replaceOp(nullop, {wrap.getChanOutput()});
  return success();
}
 
namespace {
/// Eliminate back-to-back wrap-unwraps to reduce the number of ESI channels.
struct RemoveWrapUnwrap : public ConversionPattern {
public:
  RemoveWrapUnwrap(MLIRContext *context)
      : ConversionPattern(MatchAnyOpTypeTag(), /*benefit=*/1, context) {}
 
  LogicalResult
  matchAndRewrite(Operation *op, ArrayRef<Value> operands,
                  ConversionPatternRewriter &rewriter) const override {
    Value valid, ready, data;
    WrapValidReadyOp wrap = dyn_cast<WrapValidReadyOp>(op);
    UnwrapValidReadyOp unwrap = dyn_cast<UnwrapValidReadyOp>(op);
    if (wrap) {
      if (!wrap.getChanOutput().hasOneUse() ||
          !(unwrap = dyn_cast<UnwrapValidReadyOp>(
                wrap.getChanOutput().use_begin()->getOwner())))
        return rewriter.notifyMatchFailure(
            wrap, "This conversion only supports wrap-unwrap back-to-back. "
                  "Could not find 'unwrap'.");
 
      data = operands[0];
      valid = operands[1];
      ready = unwrap.getReady();
    } else if (unwrap) {
      wrap = dyn_cast<WrapValidReadyOp>(operands[0].getDefiningOp());
      if (!wrap)
        return rewriter.notifyMatchFailure(
            operands[0].getDefiningOp(),
            "This conversion only supports wrap-unwrap back-to-back. "
            "Could not find 'wrap'.");
      valid = wrap.getValid();
      data = wrap.getRawInput();
      ready = operands[1];
    } else {
      return failure();
    }
 
    if (!wrap.getChanOutput().hasOneUse())
      return rewriter.notifyMatchFailure(wrap, [](Diagnostic &d) {
        d << "This conversion only supports wrap-unwrap back-to-back. "
             "Wrap didn't have exactly one use.";
      });
    rewriter.replaceOp(wrap, {nullptr, ready});
    rewriter.replaceOp(unwrap, {data, valid});
    return success();
  }
};
} // anonymous namespace
 
namespace {
/// Use the op canonicalizer to lower away the op. Assumes the canonicalizer
/// deletes the op.
template <typename Op>
struct CanonicalizerOpLowering : public OpConversionPattern<Op> {
public:
  CanonicalizerOpLowering(MLIRContext *ctxt) : OpConversionPattern<Op>(ctxt) {}
 
  LogicalResult
  matchAndRewrite(Op op, typename Op::Adaptor adaptor,
                  ConversionPatternRewriter &rewriter) const final {
    if (failed(Op::canonicalize(op, rewriter)))
      return rewriter.notifyMatchFailure(op->getLoc(), "canonicalizer failed");
    return success();
  }
};
} // anonymous namespace
 
namespace {
struct ESItoHWPass : public LowerESItoHWBase<ESItoHWPass> {
  void runOnOperation() override;
};
} // anonymous namespace
 
namespace {
/// Lower a `wrap.iface` to `wrap.vr` by extracting the wires then feeding the
/// new `wrap.vr`.
struct WrapInterfaceLower : public OpConversionPattern<WrapSVInterfaceOp> {
public:
  using OpConversionPattern::OpConversionPattern;
 
  LogicalResult
  matchAndRewrite(WrapSVInterfaceOp wrap, OpAdaptor adaptor,
                  ConversionPatternRewriter &rewriter) const final;
};
} // anonymous namespace
 
LogicalResult
WrapInterfaceLower::matchAndRewrite(WrapSVInterfaceOp wrap, OpAdaptor adaptor,
                                    ConversionPatternRewriter &rewriter) const {
  auto operands = adaptor.getOperands();
  if (operands.size() != 1)
    return rewriter.notifyMatchFailure(wrap, [&operands](Diagnostic &d) {
      d << "wrap.iface has 1 argument. Got " << operands.size() << "operands";
    });
  auto sinkModport = dyn_cast<GetModportOp>(operands[0].getDefiningOp());
  if (!sinkModport)
    return failure();
  auto ifaceInstance =
      dyn_cast<InterfaceInstanceOp>(sinkModport.getIface().getDefiningOp());
  if (!ifaceInstance)
    return failure();
 
  auto loc = wrap.getLoc();
  auto validSignal = rewriter.create<ReadInterfaceSignalOp>(
      loc, ifaceInstance, ESIHWBuilder::validStr);
  Value dataSignal;
  dataSignal = rewriter.create<ReadInterfaceSignalOp>(loc, ifaceInstance,
                                                      ESIHWBuilder::dataStr);
  auto wrapVR = rewriter.create<WrapValidReadyOp>(loc, dataSignal, validSignal);
  rewriter.create<AssignInterfaceSignalOp>(
      loc, ifaceInstance, ESIHWBuilder::readyStr, wrapVR.getReady());
  rewriter.replaceOp(wrap, {wrapVR.getChanOutput()});
  return success();
}
 
namespace {
/// Lower an unwrap interface to just extract the wires and feed them into an
/// `unwrap.vr`.
struct UnwrapInterfaceLower : public OpConversionPattern<UnwrapSVInterfaceOp> {
public:
  UnwrapInterfaceLower(MLIRContext *ctxt) : OpConversionPattern(ctxt) {}
  using OpConversionPattern::OpConversionPattern;
 
  LogicalResult
  matchAndRewrite(UnwrapSVInterfaceOp wrap, OpAdaptor adaptor,
                  ConversionPatternRewriter &rewriter) const final;
};
} // anonymous namespace
 
LogicalResult UnwrapInterfaceLower::matchAndRewrite(
    UnwrapSVInterfaceOp unwrap, OpAdaptor adaptor,
    ConversionPatternRewriter &rewriter) const {
  auto operands = adaptor.getOperands();
  if (operands.size() != 2)
    return rewriter.notifyMatchFailure(unwrap, [&operands](Diagnostic &d) {
      d << "Unwrap.iface has 2 arguments. Got " << operands.size()
        << "operands";
    });
 
  auto sourceModport = dyn_cast<GetModportOp>(operands[1].getDefiningOp());
  if (!sourceModport)
    return failure();
  auto ifaceInstance =
      dyn_cast<InterfaceInstanceOp>(sourceModport.getIface().getDefiningOp());
  if (!ifaceInstance)
    return failure();
 
  auto loc = unwrap.getLoc();
  auto readySignal = rewriter.create<ReadInterfaceSignalOp>(
      loc, ifaceInstance, ESIHWBuilder::readyStr);
  auto unwrapVR =
      rewriter.create<UnwrapValidReadyOp>(loc, operands[0], readySignal);
  rewriter.create<AssignInterfaceSignalOp>(
      loc, ifaceInstance, ESIHWBuilder::validStr, unwrapVR.getValid());
 
  rewriter.create<AssignInterfaceSignalOp>(
      loc, ifaceInstance, ESIHWBuilder::dataStr, unwrapVR.getRawOutput());
  rewriter.eraseOp(unwrap);
  return success();
}
 
namespace {
/// Lower `CosimEndpointOp` ops to a SystemVerilog extern module and a Capnp
/// gasket op.
struct CosimToHostLowering : public OpConversionPattern<CosimToHostEndpointOp> {
public:
  CosimToHostLowering(ESIHWBuilder &b)
      : OpConversionPattern(b.getContext(), 1), builder(b) {}
 
  using OpConversionPattern::OpConversionPattern;
 
  LogicalResult
  matchAndRewrite(CosimToHostEndpointOp, OpAdaptor adaptor,
                  ConversionPatternRewriter &rewriter) const final;
 
private:
  ESIHWBuilder &builder;
};
} // anonymous namespace
 
LogicalResult CosimToHostLowering::matchAndRewrite(
    CosimToHostEndpointOp ep, OpAdaptor adaptor,
    ConversionPatternRewriter &rewriter) const {
  auto loc = ep.getLoc();
  auto *ctxt = rewriter.getContext();
  circt::BackedgeBuilder bb(rewriter, loc);
 
  Value toHost = adaptor.getToHost();
  Type type = toHost.getType();
  uint64_t width = getWidth(type);
 
  // Set all the parameters.
  SmallVector<Attribute, 8> params;
  params.push_back(ParamDeclAttr::get("TO_HOST_TYPE_ID", getTypeID(type)));
  params.push_back(ParamDeclAttr::get("TO_HOST_SIZE_BITS",
                                      rewriter.getI32IntegerAttr(width)));
 
  // Set up the egest route to drive the EP's toHost ports.
  auto sendReady = bb.get(rewriter.getI1Type());
  UnwrapValidReadyOp unwrapSend =
      rewriter.create<UnwrapValidReadyOp>(loc, toHost, sendReady);
  auto castedSendData = rewriter.create<hw::BitcastOp>(
      loc, rewriter.getIntegerType(width), unwrapSend.getRawOutput());
 
  // Build or get the cached Cosim Endpoint module parameterization.
  Operation *symTable = ep->getParentWithTrait<OpTrait::SymbolTable>();
  HWModuleExternOp endpoint =
      builder.declareCosimEndpointToHostModule(symTable);
 
  // Create replacement Cosim_Endpoint instance.
  Value operands[] = {
      adaptor.getClk(),
      adaptor.getRst(),
      unwrapSend.getValid(),
      castedSendData.getResult(),
  };
  auto cosimEpModule = rewriter.create<InstanceOp>(
      loc, endpoint, ep.getNameAttr(), operands, ArrayAttr::get(ctxt, params));
  sendReady.setValue(cosimEpModule.getResult(0));
 
  // Replace the CosimEndpointOp op.
  rewriter.eraseOp(ep);
 
  return success();
}
 
namespace {
/// Lower `CosimEndpointOp` ops to a SystemVerilog extern module and a Capnp
/// gasket op.
struct CosimFromHostLowering
    : public OpConversionPattern<CosimFromHostEndpointOp> {
public:
  CosimFromHostLowering(ESIHWBuilder &b)
      : OpConversionPattern(b.getContext(), 1), builder(b) {}
 
  using OpConversionPattern::OpConversionPattern;
 
  LogicalResult
  matchAndRewrite(CosimFromHostEndpointOp, OpAdaptor adaptor,
                  ConversionPatternRewriter &rewriter) const final;
 
private:
  ESIHWBuilder &builder;
};
} // anonymous namespace
 
LogicalResult CosimFromHostLowering::matchAndRewrite(
    CosimFromHostEndpointOp ep, OpAdaptor adaptor,
    ConversionPatternRewriter &rewriter) const {
  auto loc = ep.getLoc();
  auto *ctxt = rewriter.getContext();
  circt::BackedgeBuilder bb(rewriter, loc);
 
  ChannelType type = ep.getFromHost().getType();
  uint64_t width = getWidth(type);
 
  // Set all the parameters.
  SmallVector<Attribute, 8> params;
  params.push_back(ParamDeclAttr::get("FROM_HOST_TYPE_ID", getTypeID(type)));
  params.push_back(ParamDeclAttr::get("FROM_HOST_SIZE_BITS",
                                      rewriter.getI32IntegerAttr(width)));
 
  // Get information necessary for injest path.
  auto recvReady = bb.get(rewriter.getI1Type());
 
  // Build or get the cached Cosim Endpoint module parameterization.
  Operation *symTable = ep->getParentWithTrait<OpTrait::SymbolTable>();
  HWModuleExternOp endpoint =
      builder.declareCosimEndpointFromHostModule(symTable);
 
  // Create replacement Cosim_Endpoint instance.
  StringAttr nameAttr = ep->getAttr("name").dyn_cast_or_null<StringAttr>();
  StringRef name = nameAttr ? nameAttr.getValue() : "CosimEndpointOp";
  Value operands[] = {adaptor.getClk(), adaptor.getRst(), recvReady};
 
  auto cosimEpModule = rewriter.create<InstanceOp>(
      loc, endpoint, name, operands, ArrayAttr::get(ctxt, params));
 
  // Set up the injest path.
  Value recvDataFromCosim = cosimEpModule.getResult(1);
  Value recvValidFromCosim = cosimEpModule.getResult(0);
  auto castedRecvData =
      rewriter.create<hw::BitcastOp>(loc, type.getInner(), recvDataFromCosim);
  WrapValidReadyOp wrapRecv = rewriter.create<WrapValidReadyOp>(
      loc, castedRecvData.getResult(), recvValidFromCosim);
  recvReady.setValue(wrapRecv.getReady());
 
  // Replace the CosimEndpointOp op.
  rewriter.replaceOp(ep, wrapRecv.getChanOutput());
 
  return success();
}
 
namespace {
/// Lower `CompressedManifestOps` ops to a SystemVerilog extern module.
struct CosimManifestLowering
    : public OpConversionPattern<CompressedManifestOp> {
public:
  using OpConversionPattern::OpConversionPattern;
 
  LogicalResult
  matchAndRewrite(CompressedManifestOp, OpAdaptor adaptor,
                  ConversionPatternRewriter &rewriter) const final;
};
} // anonymous namespace
 
LogicalResult CosimManifestLowering::matchAndRewrite(
    CompressedManifestOp op, OpAdaptor adaptor,
    ConversionPatternRewriter &rewriter) const {
  MLIRContext *ctxt = rewriter.getContext();
  Location loc = op.getLoc();
 
  // Declare external module.
  Attribute params[] = {
      ParamDeclAttr::get("COMPRESSED_MANIFEST_SIZE", rewriter.getI32Type())};
  PortInfo ports[] = {
      {{rewriter.getStringAttr("compressed_manifest"),
        rewriter.getType<hw::UnpackedArrayType>(
            rewriter.getI8Type(),
            ParamDeclRefAttr::get(
                rewriter.getStringAttr("COMPRESSED_MANIFEST_SIZE"),
                rewriter.getI32Type())),
        ModulePort::Direction::Input},
       0},
  };
  rewriter.setInsertionPointToEnd(
      op->getParentOfType<mlir::ModuleOp>().getBody());
  auto manifestModule = rewriter.create<HWModuleExternOp>(
      loc, rewriter.getStringAttr("Cosim_Manifest"), ports, "Cosim_Manifest",
      ArrayAttr::get(ctxt, params));
 
  rewriter.setInsertionPoint(op);
 
  // Assemble the manifest data into a constant.
  SmallVector<Attribute> bytes;
  for (char b : op.getCompressedManifest().getData())
    bytes.push_back(rewriter.getI8IntegerAttr(b));
  auto manifestConstant = rewriter.create<hw::AggregateConstantOp>(
      loc, hw::UnpackedArrayType::get(rewriter.getI8Type(), bytes.size()),
      rewriter.getArrayAttr(bytes));
  auto manifestLogic =
      rewriter.create<sv::LogicOp>(loc, manifestConstant.getType());
  rewriter.create<sv::AssignOp>(loc, manifestLogic, manifestConstant);
  auto manifest = rewriter.create<sv::ReadInOutOp>(loc, manifestLogic);
 
  // Then instantiate the external module.
  rewriter.create<hw::InstanceOp>(
      loc, manifestModule, "__manifest", ArrayRef<Value>({manifest}),
      rewriter.getArrayAttr(
          {ParamDeclAttr::get("COMPRESSED_MANIFEST_SIZE",
                              rewriter.getI32IntegerAttr(bytes.size()))}));
  rewriter.eraseOp(op);
  return success();
}
 
void ESItoHWPass::runOnOperation() {
  auto top = getOperation();
  auto *ctxt = &getContext();
 
  ConversionTarget noBundlesTarget(*ctxt);
  noBundlesTarget.markUnknownOpDynamicallyLegal(
      [](Operation *) { return true; });
  noBundlesTarget.addIllegalOp<PackBundleOp>();
  noBundlesTarget.addIllegalOp<UnpackBundleOp>();
  RewritePatternSet bundlePatterns(&getContext());
  bundlePatterns.add<CanonicalizerOpLowering<PackBundleOp>>(&getContext());
  bundlePatterns.add<CanonicalizerOpLowering<UnpackBundleOp>>(&getContext());
  if (failed(applyPartialConversion(getOperation(), noBundlesTarget,
                                    std::move(bundlePatterns))))
    signalPassFailure();
 
  // Set up a conversion and give it a set of laws.
  ConversionTarget pass1Target(*ctxt);
  pass1Target.addLegalDialect<comb::CombDialect>();
  pass1Target.addLegalDialect<HWDialect>();
  pass1Target.addLegalDialect<SVDialect>();
  pass1Target.addLegalOp<WrapValidReadyOp, UnwrapValidReadyOp>();
 
  pass1Target.addIllegalOp<WrapSVInterfaceOp, UnwrapSVInterfaceOp>();
  pass1Target.addIllegalOp<PipelineStageOp>();
  pass1Target.addIllegalOp<CompressedManifestOp>();
 
  // Add all the conversion patterns.
  ESIHWBuilder esiBuilder(top);
  RewritePatternSet pass1Patterns(ctxt);
  pass1Patterns.insert<PipelineStageLowering>(esiBuilder, ctxt);
  pass1Patterns.insert<WrapInterfaceLower>(ctxt);
  pass1Patterns.insert<UnwrapInterfaceLower>(ctxt);
  pass1Patterns.insert<CosimToHostLowering>(esiBuilder);
  pass1Patterns.insert<CosimFromHostLowering>(esiBuilder);
  pass1Patterns.insert<NullSourceOpLowering>(ctxt);
 
  if (platform == Platform::cosim) {
    pass1Patterns.insert<CosimManifestLowering>(ctxt);
  }
 
  // Run the conversion.
  if (failed(
          applyPartialConversion(top, pass1Target, std::move(pass1Patterns))))
    signalPassFailure();
 
  ConversionTarget pass2Target(*ctxt);
  pass2Target.addLegalDialect<comb::CombDialect>();
  pass2Target.addLegalDialect<HWDialect>();
  pass2Target.addLegalDialect<SVDialect>();
  pass2Target.addIllegalDialect<ESIDialect>();
 
  RewritePatternSet pass2Patterns(ctxt);
  pass2Patterns.insert<CanonicalizerOpLowering<UnwrapFIFOOp>>(ctxt);
  pass2Patterns.insert<CanonicalizerOpLowering<WrapFIFOOp>>(ctxt);
  pass2Patterns.insert<RemoveWrapUnwrap>(ctxt);
  if (failed(
          applyPartialConversion(top, pass2Target, std::move(pass2Patterns))))
    signalPassFailure();
}
 
std::unique_ptr<OperationPass<ModuleOp>> circt::esi::createESItoHWPass() {
  return std::make_unique<ESItoHWPass>();
}