FSMOps.cpp

Go to the documentation of this file.

//===- FSMOps.cpp - Implementation of FSM dialect operations --------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
 
#include "circt/Dialect/FSM/FSMOps.h"
#include "mlir/Dialect/Arith/IR/Arith.h"
#include "mlir/Dialect/Func/IR/FuncOps.h"
#include "mlir/IR/BuiltinOps.h"
#include "mlir/IR/DialectImplementation.h"
#include "mlir/IR/PatternMatch.h"
#include "mlir/Interfaces/FunctionImplementation.h"
#include "llvm/Support/FormatVariadic.h"
 
using namespace mlir;
using namespace circt;
using namespace fsm;
 
//===----------------------------------------------------------------------===//
// MachineOp
//===----------------------------------------------------------------------===//
 
void MachineOp::build(OpBuilder &builder, OperationState &state, StringRef name,
                      StringRef initialStateName, FunctionType type,
                      ArrayRef<NamedAttribute> attrs,
                      ArrayRef<DictionaryAttr> argAttrs) {
  state.addAttribute(MachineOp::getSymNameAttrName(state.name),
                     builder.getStringAttr(name));
  state.addAttribute(MachineOp::getFunctionTypeAttrName(state.name),
                     TypeAttr::get(type));
  state.addAttribute("initialState",
                     StringAttr::get(state.getContext(), initialStateName));
  state.attributes.append(attrs.begin(), attrs.end());
  Region *region = state.addRegion();
  Block *body = new Block();
  region->push_back(body);
  body->addArguments(
      type.getInputs(),
      SmallVector<Location, 4>(type.getNumInputs(), builder.getUnknownLoc()));
 
  if (argAttrs.empty())
    return;
  assert(type.getNumInputs() == argAttrs.size());
  call_interface_impl::addArgAndResultAttrs(
      builder, state, argAttrs,
      /*resultAttrs=*/{}, MachineOp::getArgAttrsAttrName(state.name),
      MachineOp::getResAttrsAttrName(state.name));
}
 
/// Get the initial state of the machine.
StateOp MachineOp::getInitialStateOp() {
  return dyn_cast_or_null<StateOp>(lookupSymbol(getInitialState()));
}
 
size_t MachineOp::getNumStates() {
  auto stateOps = getBody().getOps<StateOp>();
  return std::distance(stateOps.begin(), stateOps.end());
}
 
StringAttr MachineOp::getArgName(size_t i) {
  if (auto args = getArgNames())
    return cast<StringAttr>((*args)[i]);
 
  return StringAttr::get(getContext(), "in" + std::to_string(i));
}
 
StringAttr MachineOp::getResName(size_t i) {
  if (auto resNameAttrs = getResNames())
    return cast<StringAttr>((*resNameAttrs)[i]);
 
  return StringAttr::get(getContext(), "out" + std::to_string(i));
}
 
/// Get the port information of the machine.
void MachineOp::getHWPortInfo(SmallVectorImpl<hw::PortInfo> &ports) {
  ports.clear();
  auto machineType = getFunctionType();
  for (unsigned i = 0, e = machineType.getNumInputs(); i < e; ++i) {
    hw::PortInfo port;
    port.name = getArgName(i);
    if (!port.name)
      port.name = StringAttr::get(getContext(), "in" + std::to_string(i));
    port.dir = circt::hw::ModulePort::Direction::Input;
    port.type = machineType.getInput(i);
    port.argNum = i;
    ports.push_back(port);
  }
 
  for (unsigned i = 0, e = machineType.getNumResults(); i < e; ++i) {
    hw::PortInfo port;
    port.name = getResName(i);
    if (!port.name)
      port.name = StringAttr::get(getContext(), "out" + std::to_string(i));
    port.dir = circt::hw::ModulePort::Direction::Output;
    port.type = machineType.getResult(i);
    port.argNum = i;
    ports.push_back(port);
  }
}
 
ParseResult MachineOp::parse(OpAsmParser &parser, OperationState &result) {
  auto buildFuncType =
      [&](Builder &builder, ArrayRef<Type> argTypes, ArrayRef<Type> results,
          function_interface_impl::VariadicFlag,
          std::string &) { return builder.getFunctionType(argTypes, results); };
 
  return function_interface_impl::parseFunctionOp(
      parser, result, /*allowVariadic=*/false,
      MachineOp::getFunctionTypeAttrName(result.name), buildFuncType,
      MachineOp::getArgAttrsAttrName(result.name),
      MachineOp::getResAttrsAttrName(result.name));
}
 
void MachineOp::print(OpAsmPrinter &p) {
  function_interface_impl::printFunctionOp(
      p, *this, /*isVariadic=*/false, getFunctionTypeAttrName(),
      getArgAttrsAttrName(), getResAttrsAttrName());
}
 
static LogicalResult compareTypes(Location loc, TypeRange rangeA,
                                  TypeRange rangeB) {
  if (rangeA.size() != rangeB.size())
    return emitError(loc) << "mismatch in number of types compared ("
                          << rangeA.size() << " != " << rangeB.size() << ")";
 
  size_t index = 0;
  for (auto zip : llvm::zip(rangeA, rangeB)) {
    auto typeA = std::get<0>(zip);
    auto typeB = std::get<1>(zip);
    if (typeA != typeB)
      return emitError(loc) << "type mismatch at index " << index << " ("
                            << typeA << " != " << typeB << ")";
    ++index;
  }
 
  return success();
}
 
LogicalResult MachineOp::verify() {
  // If this function is external there is nothing to do.
  if (isExternal())
    return success();
 
  // Verify that the argument list of the function and the arg list of the entry
  // block line up.  The trait already verified that the number of arguments is
  // the same between the signature and the block.
  if (failed(compareTypes(getLoc(), getArgumentTypes(),
                          front().getArgumentTypes())))
    return emitOpError(
        "entry block argument types must match the machine input types");
 
  // Verify that the machine only has one block terminated with OutputOp.
  if (!llvm::hasSingleElement(*this))
    return emitOpError("must only have a single block");
 
  // Verify that the initial state exists
  if (!getInitialStateOp())
    return emitOpError("initial state '" + getInitialState() +
                       "' was not defined in the machine");
 
  if (getArgNames() && getArgNames()->size() != getArgumentTypes().size())
    return emitOpError() << "number of machine arguments ("
                         << getArgumentTypes().size()
                         << ") does "
                            "not match the provided number "
                            "of argument names ("
                         << getArgNames()->size() << ")";
 
  if (getResNames() && getResNames()->size() != getResultTypes().size())
    return emitOpError() << "number of machine results ("
                         << getResultTypes().size()
                         << ") does "
                            "not match the provided number "
                            "of result names ("
                         << getResNames()->size() << ")";
 
  return success();
}
 
SmallVector<hw::PortInfo> MachineOp::getPortList() {
  SmallVector<hw::PortInfo> ports;
  auto fnType = getFunctionType();
  auto addPorts = [&](TypeRange types, std::optional<ArrayAttr> names,
                      hw::ModulePort::Direction dir, StringRef prefix) {
    for (auto [i, type] : llvm::enumerate(types)) {
      StringAttr name = (names && i < names->size())
                            ? cast<StringAttr>((*names)[i])
                            : StringAttr::get(getContext(), prefix + Twine(i));
      ports.push_back({{name, type, dir}, static_cast<size_t>(i), {}, {}});
    }
  };
 
  addPorts(fnType.getInputs(), getArgNames(), hw::ModulePort::Direction::Input,
           "input");
  addPorts(fnType.getResults(), getResNames(),
           hw::ModulePort::Direction::Output, "output");
 
  return ports;
}
 
//===----------------------------------------------------------------------===//
// InstanceOp
//===----------------------------------------------------------------------===//
 
/// Lookup the machine for the symbol.  This returns null on invalid IR.
MachineOp InstanceOp::getMachineOp() {
  auto module = (*this)->getParentOfType<ModuleOp>();
  return module.lookupSymbol<MachineOp>(getMachine());
}
 
LogicalResult InstanceOp::verify() {
  auto m = getMachineOp();
  if (!m)
    return emitError("cannot find machine definition '") << getMachine() << "'";
 
  return success();
}
 
void InstanceOp::getAsmResultNames(
    function_ref<void(Value, StringRef)> setNameFn) {
  setNameFn(getInstance(), getName());
}
 
//===----------------------------------------------------------------------===//
// TriggerOp
//===----------------------------------------------------------------------===//
 
template <typename OpType>
static LogicalResult verifyCallerTypes(OpType op) {
  auto machine = op.getMachineOp();
  if (!machine)
    return op.emitError("cannot find machine definition");
 
  // Check operand types first.
  if (failed(compareTypes(op.getLoc(), machine.getArgumentTypes(),
                          op.getInputs().getTypes()))) {
    auto diag =
        op.emitOpError("operand types must match the machine input types");
    diag.attachNote(machine->getLoc()) << "original machine declared here";
    return failure();
  }
 
  // Check result types.
  if (failed(compareTypes(op.getLoc(), machine.getResultTypes(),
                          op.getOutputs().getTypes()))) {
    auto diag =
        op.emitOpError("result types must match the machine output types");
    diag.attachNote(machine->getLoc()) << "original machine declared here";
    return failure();
  }
 
  return success();
}
 
/// Lookup the machine for the symbol.  This returns null on invalid IR.
MachineOp TriggerOp::getMachineOp() {
  auto instanceOp = getInstance().getDefiningOp<InstanceOp>();
  if (!instanceOp)
    return nullptr;
 
  return instanceOp.getMachineOp();
}
 
LogicalResult TriggerOp::verify() { return verifyCallerTypes(*this); }
 
//===----------------------------------------------------------------------===//
// HWInstanceOp
//===----------------------------------------------------------------------===//
 
// InstanceOpInterface interface
 
/// Lookup the machine for the symbol.  This returns null on invalid IR.
MachineOp HWInstanceOp::getMachineOp() {
  auto module = (*this)->getParentOfType<ModuleOp>();
  return module.lookupSymbol<MachineOp>(getMachine());
}
 
LogicalResult HWInstanceOp::verify() { return verifyCallerTypes(*this); }
 
SmallVector<hw::PortInfo> HWInstanceOp::getPortList() {
  return getMachineOp().getPortList();
}
 
/// Module name is the same as the machine name.
StringRef HWInstanceOp::getModuleName() { return getMachine(); }
FlatSymbolRefAttr HWInstanceOp::getModuleNameAttr() { return getMachineAttr(); }
 
mlir::StringAttr HWInstanceOp::getInstanceNameAttr() { return getNameAttr(); }
 
llvm::StringRef HWInstanceOp::getInstanceName() { return getName(); }
 
//===----------------------------------------------------------------------===//
// StateOp
//===----------------------------------------------------------------------===//
 
void StateOp::build(OpBuilder &builder, OperationState &state,
                    StringRef stateName) {
  OpBuilder::InsertionGuard guard(builder);
  Region *output = state.addRegion();
  output->push_back(new Block());
  builder.setInsertionPointToEnd(&output->back());
  fsm::OutputOp::create(builder, state.location);
  Region *transitions = state.addRegion();
  transitions->push_back(new Block());
  state.addAttribute(StateOp::getSymNameAttrName(state.name),
                     builder.getStringAttr(stateName));
}
 
void StateOp::build(OpBuilder &builder, OperationState &state,
                    StringRef stateName, ValueRange outputs) {
  OpBuilder::InsertionGuard guard(builder);
  Region *output = state.addRegion();
  output->push_back(new Block());
  builder.setInsertionPointToEnd(&output->back());
  fsm::OutputOp::create(builder, state.location, outputs);
  Region *transitions = state.addRegion();
  transitions->push_back(new Block());
  state.addAttribute(StateOp::getSymNameAttrName(state.name),
                     builder.getStringAttr(stateName));
}
 
SetVector<StateOp> StateOp::getNextStates() {
  SmallVector<StateOp> nextStates;
  llvm::transform(
      getTransitions().getOps<TransitionOp>(),
      std::inserter(nextStates, nextStates.begin()),
      [](TransitionOp transition) { return transition.getNextStateOp(); });
  return SetVector<StateOp>(nextStates.begin(), nextStates.end());
}
 
LogicalResult StateOp::canonicalize(StateOp op, PatternRewriter &rewriter) {
  bool hasAlwaysTakenTransition = false;
  SmallVector<TransitionOp, 4> transitionsToErase;
  // Remove all transitions after an "always-taken" transition.
  for (auto transition : op.getTransitions().getOps<TransitionOp>()) {
    if (!hasAlwaysTakenTransition)
      hasAlwaysTakenTransition = transition.isAlwaysTaken();
    else
      transitionsToErase.push_back(transition);
  }
 
  for (auto transition : transitionsToErase)
    rewriter.eraseOp(transition);
 
  return failure(transitionsToErase.empty());
}
 
LogicalResult StateOp::verify() {
  MachineOp parent = getOperation()->getParentOfType<MachineOp>();
 
  if (parent.getNumResults() != 0 && (getOutput().empty()))
    return emitOpError("state must have a non-empty output region when the "
                       "machine has results.");
 
  if (!getOutput().empty()) {
    // Ensure that the output block has a single OutputOp terminator.
    Block *outputBlock = &getOutput().front();
    if (outputBlock->empty() || !isa<fsm::OutputOp>(outputBlock->back()))
      return emitOpError("output block must have a single OutputOp terminator");
  }
 
  return success();
}
 
Block *StateOp::ensureOutput(OpBuilder &builder) {
  if (getOutput().empty()) {
    OpBuilder::InsertionGuard g(builder);
    auto *block = new Block();
    getOutput().push_back(block);
    builder.setInsertionPointToStart(block);
    fsm::OutputOp::create(builder, getLoc());
  }
  return &getOutput().front();
}
 
//===----------------------------------------------------------------------===//
// OutputOp
//===----------------------------------------------------------------------===//
 
LogicalResult OutputOp::verify() {
  if ((*this)->getParentRegion() ==
      &(*this)->getParentOfType<StateOp>().getTransitions()) {
    if (getNumOperands() != 0)
      emitOpError("transitions region must not output any value");
    return success();
  }
 
  // Verify that the result list of the machine and the operand list of the
  // OutputOp line up.
  auto machine = (*this)->getParentOfType<MachineOp>();
  if (failed(
          compareTypes(getLoc(), machine.getResultTypes(), getOperandTypes())))
    return emitOpError("operand types must match the machine output types");
 
  return success();
}
 
//===----------------------------------------------------------------------===//
// TransitionOp
//===----------------------------------------------------------------------===//
 
void TransitionOp::build(OpBuilder &builder, OperationState &state,
                         StateOp nextState) {
  build(builder, state, nextState.getName());
}
 
void TransitionOp::build(OpBuilder &builder, OperationState &state,
                         StringRef nextState,
                         llvm::function_ref<void()> guardCtor,
                         llvm::function_ref<void()> actionCtor) {
  state.addAttribute("nextState",
                     FlatSymbolRefAttr::get(builder.getStringAttr(nextState)));
  OpBuilder::InsertionGuard guard(builder);
 
  Region *guardRegion = state.addRegion(); // guard
  if (guardCtor) {
    builder.createBlock(guardRegion);
    guardCtor();
  }
 
  Region *actionRegion = state.addRegion(); // action
  if (actionCtor) {
    builder.createBlock(actionRegion);
    actionCtor();
  }
}
 
Block *TransitionOp::ensureGuard(OpBuilder &builder) {
  if (getGuard().empty()) {
    OpBuilder::InsertionGuard g(builder);
    auto *block = new Block();
    getGuard().push_back(block);
    builder.setInsertionPointToStart(block);
    fsm::ReturnOp::create(builder, getLoc());
  }
  return &getGuard().front();
}
 
Block *TransitionOp::ensureAction(OpBuilder &builder) {
  if (getAction().empty())
    getAction().push_back(new Block());
  return &getAction().front();
}
 
/// Lookup the next state for the symbol. This returns null on invalid IR.
StateOp TransitionOp::getNextStateOp() {
  auto machineOp = (*this)->getParentOfType<MachineOp>();
  if (!machineOp)
    return nullptr;
 
  return machineOp.lookupSymbol<StateOp>(getNextState());
}
 
bool TransitionOp::isAlwaysTaken() {
  if (!hasGuard())
    return true;
 
  auto guardReturn = getGuardReturn();
  if (guardReturn.getNumOperands() == 0)
    return true;
 
  if (auto constantOp =
          guardReturn.getOperand().getDefiningOp<mlir::arith::ConstantOp>())
    return cast<BoolAttr>(constantOp.getValue()).getValue();
 
  return false;
}
 
LogicalResult TransitionOp::canonicalize(TransitionOp op,
                                         PatternRewriter &rewriter) {
  if (op.hasGuard()) {
    auto guardReturn = op.getGuardReturn();
    if (guardReturn.getNumOperands() == 1)
      if (auto constantOp = guardReturn.getOperand()
                                .getDefiningOp<mlir::arith::ConstantOp>()) {
        // Simplify when the guard region returns a constant value.
        if (cast<BoolAttr>(constantOp.getValue()).getValue()) {
          // Replace the original return op with a new one without any operands
          // if the constant is TRUE.
          rewriter.setInsertionPoint(guardReturn);
          fsm::ReturnOp::create(rewriter, guardReturn.getLoc());
          rewriter.eraseOp(guardReturn);
        } else {
          // Erase the whole transition op if the constant is FALSE, because the
          // transition will never be taken.
          rewriter.eraseOp(op);
        }
        return success();
      }
  }
 
  return failure();
}
 
LogicalResult TransitionOp::verify() {
  if (!getNextStateOp())
    return emitOpError("cannot find the definition of the next state `")
           << getNextState() << "`";
 
  // Verify the action region, if present.
  if (hasGuard()) {
    if (getGuard().front().empty() ||
        !isa_and_nonnull<fsm::ReturnOp>(&getGuard().front().back()))
      return emitOpError("guard region must terminate with a ReturnOp");
  }
 
  // Verify the transition is located in the correct region.
  if ((*this)->getParentRegion() != &getCurrentState().getTransitions())
    return emitOpError("must only be located in the transitions region");
 
  return success();
}
 
//===----------------------------------------------------------------------===//
// VariableOp
//===----------------------------------------------------------------------===//
 
void VariableOp::getAsmResultNames(
    function_ref<void(Value, StringRef)> setNameFn) {
  setNameFn(getResult(), getName());
}
 
//===----------------------------------------------------------------------===//
// ReturnOp
//===----------------------------------------------------------------------===//
 
void ReturnOp::setOperand(Value value) {
  if (getOperand())
    getOperation()->setOperand(0, value);
  else
    getOperation()->insertOperands(0, {value});
}
 
//===----------------------------------------------------------------------===//
// UpdateOp
//===----------------------------------------------------------------------===//
 
/// Get the targeted variable operation. This returns null on invalid IR.
VariableOp UpdateOp::getVariableOp() {
  return getVariable().getDefiningOp<VariableOp>();
}
 
LogicalResult UpdateOp::canonicalize(UpdateOp op, PatternRewriter &rewriter) {
  // Remove no-op updates that update a variable to itself
  if (op.getVariable() == op.getValue()) {
    rewriter.eraseOp(op);
    return success();
  }
  return failure();
}
 
LogicalResult UpdateOp::verify() {
  if (!getVariable())
    return emitOpError("destination is not a variable operation");
 
  if (!(*this)->getParentOfType<TransitionOp>().getAction().isAncestor(
          (*this)->getParentRegion()))
    return emitOpError("must only be located in the action region");
 
  auto transition = (*this)->getParentOfType<TransitionOp>();
  for (auto otherUpdateOp : transition.getAction().getOps<UpdateOp>()) {
    if (otherUpdateOp == *this)
      continue;
    if (otherUpdateOp.getVariable() == getVariable())
      return otherUpdateOp.emitOpError(
          "multiple updates to the same variable within a single action region "
          "is disallowed");
  }
 
  return success();
}
 
//===----------------------------------------------------------------------===//
// TableGen generated logic
//===----------------------------------------------------------------------===//
 
// Provide the autogenerated implementation guts for the Op classes.
#define GET_OP_CLASSES
#include "circt/Dialect/FSM/FSM.cpp.inc"
#undef GET_OP_CLASSES
 
#include "circt/Dialect/FSM/FSMDialect.cpp.inc"