[FIRRTL] Add {{HierarchicalModuleName}} support (#8380)

Add support for the FIRRTL 5.0.0 printf substitution
`{{HierarchicalModuleName}}`.  Support this in the FIRRTL Dialect with a
new operation.  Add FIRRTL parsing, FIRRTL emission, and FIRRTL-to-HW
lowering.

Signed-off-by: Schuyler Eldridge <[email protected]>

Author: seldridge

include/circt/Dialect/FIRRTL/FIRRTLExpressions.td

@@ -1705,4 +1705,27 @@ def TimeOp : FIRRTLOp<"fstring.time", [HasCustomSSAName, Pure]> {
 
 }
 
+def HierarchicalModuleNameOp :
+  FIRRTLOp<"fstring.hierarchicalmodulename", [HasCustomSSAName, Pure]> {
+
+  let summary = "an operation that represents the module name with its full path";
+  let description = [{
+
+    This operation represents the name of the current module with a
+    fully-qualified path in front of it.  It returns a format string type which
+    can only be used as a substitution inside a printf.  This operation is not
+    represented in the FIRRTL spec.
+
+    This operation is the FIRRTL Dialect representation of the special
+    substitution `{{HierarchicalModuleName}}`.
+  }];
+
+  let arguments = (ins);
+  let results = (outs FStringType:$result);
+  let assemblyFormat = [{
+    attr-dict `:` type($result)
+  }];
+
+}
+
 #endif // CIRCT_DIALECT_FIRRTL_FIRRTLEXPRESSIONS_TD

include/circt/Dialect/FIRRTL/FIRRTLVisitors.h

@@ -68,7 +68,7 @@ class ExprVisitor {
             DoubleConstantOp, ListCreateOp, ListConcatOp, UnresolvedPathOp,
             PathOp, IntegerAddOp, IntegerMulOp, IntegerShrOp,
             // Format String expressions
-            TimeOp>([&](auto expr) -> ResultType {
+            TimeOp, HierarchicalModuleNameOp>([&](auto expr) -> ResultType {
           return thisCast->visitExpr(expr, args...);
         })
         .Default([&](auto expr) -> ResultType {
@@ -229,6 +229,7 @@ class ExprVisitor {
 
   // Format string expressions
   HANDLE(TimeOp, Unhandled);
+  HANDLE(HierarchicalModuleNameOp, Unhandled);
 #undef HANDLE
 };
 

lib/Conversion/FIRRTLToHW/LowerToHW.cpp

@@ -1520,7 +1520,7 @@ struct FIRRTLLowering : public FIRRTLVisitor<FIRRTLLowering, LogicalResult> {
   Value getLoweredNonClockValue(Value value);
   Value getLoweredAndExtendedValue(Value value, Type destType);
   Value getLoweredAndExtOrTruncValue(Value value, Type destType);
-  Value getLoweredFmtOperand(Value operand);
+  std::optional<Value> getLoweredFmtOperand(Value operand);
   LogicalResult setLowering(Value orig, Value result);
   LogicalResult setPossiblyFoldedLowering(Value orig, Value result);
   template <typename ResultOpType, typename... CtorArgTypes>
@@ -1771,6 +1771,7 @@ struct FIRRTLLowering : public FIRRTLVisitor<FIRRTLLowering, LogicalResult> {
 
   // Format String Operations
   LogicalResult visitExpr(TimeOp op);
+  LogicalResult visitExpr(HierarchicalModuleNameOp op);
 
   // Statements
   LogicalResult lowerVerificationStatement(
@@ -2442,20 +2443,29 @@ Value FIRRTLLowering::getLoweredAndExtOrTruncValue(Value value, Type destType) {
 }
 
 /// Return a lowered version of 'operand' suitable for use with substitution /
-/// format strings. Zero bit operands are rewritten as one bit zeros and signed
-/// integers are wrapped in $signed().
-Value FIRRTLLowering::getLoweredFmtOperand(Value operand) {
+/// format strings. There are three possible results:
+///
+///   1. Does not contain a value if no lowering is set.  This is an error.
+///   2. The lowering contains an empty value.  This means that the operand
+///      should be dropped.
+///   3. The lowering contains a value.  This means the operand should be used.
+///
+/// Zero bit operands are rewritten as one bit zeros and signed integers are
+/// wrapped in $signed().
+std::optional<Value> FIRRTLLowering::getLoweredFmtOperand(Value operand) {
   // Handle special substitutions.
   if (type_isa<FStringType>(operand.getType())) {
     if (isa<TimeOp>(operand.getDefiningOp()))
       return builder.create<sv::TimeOp>();
+    if (isa<HierarchicalModuleNameOp>(operand.getDefiningOp()))
+      return {nullptr};
   }
 
   auto loweredValue = getLoweredValue(operand);
   if (!loweredValue) {
     // If this is a zero bit operand, just pass a one bit zero.
     if (!isZeroBitFIRRTLType(operand.getType()))
-      return nullptr;
+      return {};
     loweredValue = getOrCreateIntConstant(1, 0);
   }
 
@@ -4331,10 +4341,12 @@ LogicalResult FIRRTLLowering::visitExpr(XMRDerefOp op) {
   return setLoweringTo<seq::ToClockOp>(op, readXmr);
 }
 
-// Do nothing when lowering this operation.  We need to handle this at its usage
-// sites to guarantee creation of `sv::TimeOp` that is colocated with the
-// `sv::FWriteOp`.
+// Do nothing when lowering fstring operations.  These need to be handled at
+// their usage sites (at the PrintfOps).
 LogicalResult FIRRTLLowering::visitExpr(TimeOp op) { return success(); }
+LogicalResult FIRRTLLowering::visitExpr(HierarchicalModuleNameOp op) {
+  return success();
+}
 
 //===----------------------------------------------------------------------===//
 // Statements
@@ -4594,14 +4606,25 @@ LogicalResult FIRRTLLowering::visitStmt(PrintFOp op) {
       auto substitution = op.getSubstitutions()[subIdx++];
       assert(type_isa<FStringType>(substitution.getType()) &&
              "the operand for a '{{}}' substitution must be an 'fstring' type");
-      if (auto timeOp = dyn_cast<TimeOp>(substitution.getDefiningOp())) {
-        formatString.append("%0t");
-      } else {
-        op.emitError("has a substitution with an unimplemented lowering")
-                .attachNote(substitution.getLoc())
-            << "op with an unimplemented lowering is here";
+      auto result =
+          TypeSwitch<Operation *, LogicalResult>(substitution.getDefiningOp())
+              .Case<TimeOp>([&](auto) {
+                formatString.append("%0t");
+                return success();
+              })
+              .Case<HierarchicalModuleNameOp>([&](auto) {
+                formatString.append("%m");
+                return success();
+              })
+              .Default([&](auto) {
+                op.emitError("has a substitution with an unimplemented "
+                             "lowering")
+                        .attachNote(substitution.getLoc())
+                    << "op with an unimplemented lowering is here";
+                return failure();
+              });
+      if (failed(result))
         return failure();
-      }
       i += 3;
       break;
     }
@@ -4633,10 +4656,11 @@ LogicalResult FIRRTLLowering::visitStmt(PrintFOp op) {
         // Lower the operands handling any special substitutions that need to be
         // lowered on a per-use basis.
         for (auto operand : op.getSubstitutions()) {
-          Value loweredValue = getLoweredFmtOperand(operand);
+          std::optional<Value> loweredValue = getLoweredFmtOperand(operand);
           if (!loweredValue)
             failed = true;
-          operands.push_back(loweredValue);
+          if (*loweredValue)
+            operands.push_back(*loweredValue);
         }
         if (failed)
           return;
@@ -4780,13 +4804,15 @@ LogicalResult FIRRTLLowering::lowerVerificationStatement(
       if (!loweredValue)
         return failure();
 
+      if (!*loweredValue)
+        break;
       // For SVA assert/assume statements, wrap any message ops in $sampled() to
       // guarantee that these will print with the same value as when the
       // assertion triggers.  (See SystemVerilog 2017 spec section 16.9.3 for
       // more information.)
       if (flavor == VerificationFlavor::SVA)
-        loweredValue = builder.create<sv::SampledOp>(loweredValue);
-      messageOps.push_back(loweredValue);
+        loweredValue = builder.create<sv::SampledOp>(*loweredValue);
+      messageOps.push_back(*loweredValue);
     }
   }
 

lib/Dialect/FIRRTL/Export/FIREmitter.cpp

@@ -897,10 +897,15 @@ void Emitter::emitStatement(PrintFOp op) {
       case '{':
         if (origFormatString.slice(i, i + 4) == "{{}}") {
           formatString.append("{{");
-          if (isa<TimeOp>(op.getSubstitutions()[opIdx++].getDefiningOp()))
-            formatString.append("SimulationTime");
-          else
-            emitError(op, "unsupported fstring substitution type");
+          TypeSwitch<Operation *>(
+              op.getSubstitutions()[opIdx++].getDefiningOp())
+              .Case<TimeOp>(
+                  [&](auto) { formatString.append("SimulationTime"); })
+              .Case<HierarchicalModuleNameOp>(
+                  [&](auto) { formatString.append("HierarchicalModuleName"); })
+              .Default([&](auto) {
+                emitError(op, "unsupported fstring substitution type");
+              });
           formatString.append("}}");
         }
         i += 3;

lib/Dialect/FIRRTL/FIRRTLOps.cpp

@@ -6378,6 +6378,11 @@ void TimeOp::getAsmResultNames(OpAsmSetValueNameFn setNameFn) {
   setNameFn(getResult(), "time");
 }
 
+void HierarchicalModuleNameOp::getAsmResultNames(
+    OpAsmSetValueNameFn setNameFn) {
+  setNameFn(getResult(), "hierarchicalmodulename");
+}
+
 //===----------------------------------------------------------------------===//
 // TblGen Generated Logic.
 //===----------------------------------------------------------------------===//

lib/Dialect/FIRRTL/Import/FIRParser.cpp

@@ -3038,6 +3038,8 @@ ParseResult FIRStmtParser::parsePrintf() {
         auto specialString = formatString.slice(start, i);
         if (specialString == "SimulationTime") {
           operands.push_back(builder.create<TimeOp>());
+        } else if (specialString == "HierarchicalModuleName") {
+          operands.push_back(builder.create<HierarchicalModuleNameOp>());
         } else {
           emitError(formatStringLoc)
               << "unknown printf substitution '" << specialString

test/Conversion/FIRRTLToHW/lower-to-hw.mlir

@@ -385,7 +385,7 @@ firrtl.circuit "Simple"   attributes {annotations = [{class =
     // CHECK-NEXT:     sv.if [[AND]] {
     // CHECK-NEXT:       %PRINTF_FD_ = sv.macro.ref.expr @PRINTF_FD_() : () -> i32
     // CHECK-NEXT:       [[TIME:%.+]] = sv.system.time : i64
-    // CHECK-NEXT:       sv.fwrite %PRINTF_FD_, "[%0t]: %0d"([[TIME]], %a) : i64, i4
+    // CHECK-NEXT:       sv.fwrite %PRINTF_FD_, "[%0t]: %0d %m"([[TIME]], %a) : i64, i4
     // CHECK-NEXT:     }
     // CHECK-NEXT:   }
     // CHECK-NEXT: }
@@ -406,7 +406,8 @@ firrtl.circuit "Simple"   attributes {annotations = [{class =
     firrtl.printf %clock, %reset, "Hi signed %d %d\0A"(%1, %d) : !firrtl.clock, !firrtl.uint<1>, !firrtl.sint<5>, !firrtl.sint<4>
 
     %time = firrtl.fstring.time : !firrtl.fstring
-    firrtl.printf %clock, %reset, "[{{}}]: %d" (%time, %a) : !firrtl.clock, !firrtl.uint<1>, !firrtl.fstring, !firrtl.uint<4>
+    %hierarchicalmodulename = firrtl.fstring.hierarchicalmodulename : !firrtl.fstring
+    firrtl.printf %clock, %reset, "[{{}}]: %d {{}}" (%time, %a, %hierarchicalmodulename) : !firrtl.clock, !firrtl.uint<1>, !firrtl.fstring, !firrtl.uint<4>, !firrtl.fstring
 
     firrtl.skip
 

test/Dialect/FIRRTL/parse-basic.fir

@@ -2061,8 +2061,8 @@ circuit Foo:
   public module Foo:
     input clock: Clock
     ; In FIRRTL versions < 4.2.0, the following is not a "special substitution".
-    ; CHECK{{LITERAL}}: firrtl.printf %clock, %c1_ui1, "[{{SimulationTime}}]: hello world "
-    printf(clock, UInt<1>(1), "[{{SimulationTime}}]: hello world")
+    ; CHECK{{LITERAL}}: firrtl.printf %clock, %c1_ui1, "[{{SimulationTime}}]: hello from {{HierarchicalModuleName}}"
+    printf(clock, UInt<1>(1), "[{{SimulationTime}}]: hello from {{HierarchicalModuleName}}")
 
 ;// -----
 FIRRTL version 5.0.0
@@ -2071,5 +2071,6 @@ circuit Foo:
     input clock: Clock
     ; In FIRRTL versions >= 4.2.0, the following is not a "special substitution".
     ; CHECK:            %time = firrtl.fstring.time : !firrtl.fstring
-    ; CHECK{{LITERAL}}: firrtl.printf %clock, %c1_ui1, "[{{}}]: hello world "(%time)
-    printf(clock, UInt<1>(1), "[{{SimulationTime}}]: hello world")
+    ; CHECK:            %hierarchicalmodulename = firrtl.fstring.hierarchicalmodulename : !firrtl.fstring
+    ; CHECK{{LITERAL}}: firrtl.printf %clock, %c1_ui1, "[{{}}]: hello world {{}}"(%time, %hierarchicalmodulename)
+    printf(clock, UInt<1>(1), "[{{SimulationTime}}]: hello from {{HierarchicalModuleName}}")

test/firtool/print.fir

@@ -1,6 +1,6 @@
 ; RUN: firtool %s | FileCheck %s
 
-FIRRTL version 5.1.0
+FIRRTL version 5.0.0
 circuit PrintTest:
   ; CHECK-LABEL: module PrintTest
   public module PrintTest :
@@ -23,3 +23,6 @@ circuit PrintTest:
 
     ; CHECK-NEXT: $fwrite(`PRINTF_FD_, "literals: %%\n");
     printf(clock, cond, "literals: %%\n")
+
+    ; CHECK-NEXT: $fwrite(`PRINTF_FD_, "[%0t]: %m\n", $time);
+    printf(clock, cond, "[{{SimulationTime}}]: {{HierarchicalModuleName}}\n")