[Seq] Add clock gate operation

include/circt/Dialect/Seq/SeqOps.td

@@ -220,3 +220,37 @@ def WritePortOp : SeqOp<"write", [
   let results = (outs);
   let hasCustomAssemblyFormat = 1;
 }
+
+//===----------------------------------------------------------------------===//
+// Clock Gate
+//===----------------------------------------------------------------------===//
+
+def ClockGateOp : SeqOp<"clock_gate", [Pure]> {
+  let summary = "Safely gates a clock with an enable signal";
+  let description = [{
+    The `seq.clock_gate` enables and disables a clock safely, without glitches,
+    based on a boolean enable value. If the enable operand is 1, the output
+    clock produced by the clock gate is identical to the input clock. If the
+    enable operand is 0, the output clock is a constant zero.
+
+    The `enable` operand is sampled at the rising edge of the input clock; any
+    changes on the enable before or after that edge are ignored and do not
+    affect the output clock.
+
+    The `test_enable` operand is optional and if present is OR'd together with
+    the `enable` operand to determine whether the output clock is gated or not.
+
+    ```
+    %gatedClock = seq.clock_gate %clock, %enable : i1
+    %gatedClock = seq.clock_gate %clock, %enable, %test_enable : i1, i1
+    ```
+  }];
+
+  let arguments = (ins I1:$input, I1:$enable, Optional<I1>:$test_enable);
+  let results = (outs I1:$output);
+  let hasFolder = 1;
+  let hasCanonicalizeMethod = 1;
+  let assemblyFormat = [{
+    $input `,` $enable (`,` $test_enable^)? attr-dict
+  }];
+}

lib/Dialect/Seq/SeqOps.cpp

@@ -24,6 +24,29 @@ using namespace mlir;
 using namespace circt;
 using namespace seq;
 
+/// Determine the integer value of a constant operand.
+static std::optional<APInt> getConstantInt(Attribute operand) {
+  if (!operand)
+    return {};
+  if (auto attr = dyn_cast<IntegerAttr>(operand))
+    return attr.getValue();
+  return {};
+}
+
+/// Determine whether a constant operand is a zero value.
+static bool isConstantZero(Attribute operand) {
+  if (auto cst = getConstantInt(operand))
+    return cst->isZero();
+  return false;
+}
+
+/// Determine whether a constant operand is a one value.
+static bool isConstantOne(Attribute operand) {
+  if (auto cst = getConstantInt(operand))
+    return cst->isOne();
+  return false;
+}
+
 bool circt::seq::isValidIndexValues(Value hlmemHandle, ValueRange addresses) {
   auto memType = hlmemHandle.getType().cast<seq::HLMemType>();
   auto shape = memType.getShape();
@@ -597,6 +620,44 @@ OpFoldResult FirRegOp::fold(FoldAdaptor adaptor) {
   return IntegerAttr::get(intType, 0);
 }
 
+//===----------------------------------------------------------------------===//
+// ClockGateOp
+//===----------------------------------------------------------------------===//
+
+OpFoldResult ClockGateOp::fold(FoldAdaptor adaptor) {
+  // Forward the clock if one of the enables is always true.
+  if (isConstantOne(adaptor.getEnable()) ||
+      isConstantOne(adaptor.getTestEnable()))
+    return getInput();
+
+  // Fold to a constant zero clock if the enables are always false.
+  if (isConstantZero(adaptor.getEnable()) &&
+      (!getTestEnable() || isConstantZero(adaptor.getTestEnable())))
+    return IntegerAttr::get(IntegerType::get(getContext(), 1), 0);
+
+  // Forward constant zero clocks.
+  if (isConstantZero(adaptor.getInput()))
+    return IntegerAttr::get(IntegerType::get(getContext(), 1), 0);
+
+  return {};
+}
+
+LogicalResult ClockGateOp::canonicalize(ClockGateOp op,
+                                        PatternRewriter &rewriter) {
+  // Remove constant false test enable.
+  if (auto testEnable = op.getTestEnable()) {
+    if (auto constOp = testEnable.getDefiningOp<hw::ConstantOp>()) {
+      if (constOp.getValue().isZero()) {
+        rewriter.updateRootInPlace(op,
+                                   [&] { op.getTestEnableMutable().clear(); });
+        return success();
+      }
+    }
+  }
+
+  return failure();
+}
+
 //===----------------------------------------------------------------------===//
 // TableGen generated logic.
 //===----------------------------------------------------------------------===//

test/Dialect/Seq/canonicalization.mlir

@@ -87,3 +87,36 @@ hw.module @UninitializedArrayElement(%a: i1, %clock: i1) -> (b: !hw.array<2xi1>)
   %1 = hw.array_create %0, %a : i1
   hw.output %r : !hw.array<2xi1>
 }
+
+// CHECK-LABEL: hw.module @ClockGate
+hw.module @ClockGate(%clock: i1, %enable: i1, %testEnable: i1) {
+  // CHECK-NEXT: hw.constant false
+  %false = hw.constant false
+  %true = hw.constant true
+
+  // CHECK-NEXT: %zeroClock = hw.wire %false sym @zeroClock
+  %0 = seq.clock_gate %false, %enable
+  %zeroClock = hw.wire %0 sym @zeroClock : i1
+
+  // CHECK-NEXT: %alwaysOff1 = hw.wire %false sym @alwaysOff1
+  // CHECK-NEXT: %alwaysOff2 = hw.wire %false sym @alwaysOff2
+  %1 = seq.clock_gate %clock, %false
+  %2 = seq.clock_gate %clock, %false, %false
+  %alwaysOff1 = hw.wire %1 sym @alwaysOff1 : i1
+  %alwaysOff2 = hw.wire %2 sym @alwaysOff2 : i1
+
+  // CHECK-NEXT: %alwaysOn1 = hw.wire %clock sym @alwaysOn1
+  // CHECK-NEXT: %alwaysOn2 = hw.wire %clock sym @alwaysOn2
+  // CHECK-NEXT: %alwaysOn3 = hw.wire %clock sym @alwaysOn3
+  %3 = seq.clock_gate %clock, %true
+  %4 = seq.clock_gate %clock, %true, %testEnable
+  %5 = seq.clock_gate %clock, %enable, %true
+  %alwaysOn1 = hw.wire %3 sym @alwaysOn1 : i1
+  %alwaysOn2 = hw.wire %4 sym @alwaysOn2 : i1
+  %alwaysOn3 = hw.wire %5 sym @alwaysOn3 : i1
+
+  // CHECK-NEXT: [[TMP:%.+]] = seq.clock_gate %clock, %enable
+  // CHECK-NEXT: %dropTestEnable = hw.wire [[TMP]] sym @dropTestEnable
+  %6 = seq.clock_gate %clock, %enable, %false
+  %dropTestEnable = hw.wire %6 sym @dropTestEnable : i1
+}

test/Dialect/Seq/round-trip.mlir

@@ -46,3 +46,11 @@ hw.module @d0(%clk : i1, %rst : i1) -> () {
   %myMemory_rdata = seq.read %myMemory[%c0_i0] rden %c1_i1 { latency = 0} : !seq.hlmem<1xi32>
   hw.output
 }
+
+// CHECK-LABEL: hw.module @ClockGate
+hw.module @ClockGate(%clock: i1, %enable: i1, %test_enable: i1) {
+  // CHECK-NEXT: seq.clock_gate %clock, %enable
+  // CHECK-NEXT: seq.clock_gate %clock, %enable, %test_enable
+  %cg0 = seq.clock_gate %clock, %enable
+  %cg1 = seq.clock_gate %clock, %enable, %test_enable
+}