Add Simlog.flush (#4895)

Add SimLog.flush, an API to flush prints to their files/file descriptors.

Author: jackkoenig

core/src/main/scala/chisel3/SimLog.scala

@@ -3,7 +3,7 @@
 package chisel3
 
 import chisel3._
-import chisel3.internal.firrtl.ir.Printf
+import chisel3.internal.firrtl.ir.{Flush, Printf}
 import chisel3.internal.Builder
 import chisel3.experimental.SourceInfo
 
@@ -43,6 +43,18 @@ sealed trait SimLog extends SimLogIntf {
     this.printfWithReset(pable)(sourceInfo)
   }
 
+  /** Flush any buffered output immediately */
+  def flush()(implicit sourceInfo: SourceInfo): Unit = {
+    val clock = Builder.forcedClock
+    _filename.foreach(Printable.checkScope(_, "SimLog filename "))
+
+    when(!Module.reset.asBool) {
+      layer.block(layers.Verification, skipIfAlreadyInBlock = true, skipIfLayersEnabled = true) {
+        Builder.pushCommand(Flush(sourceInfo, _filename, clock.ref))
+      }
+    }
+  }
+
   // Eventually this might be a richer type but for now Some[Printable] is filename, None is Stderr
   protected def _filename: Option[Printable]
 

core/src/main/scala/chisel3/internal/MonoConnect.scala

@@ -53,7 +53,7 @@ private[chisel3] object MonoConnect {
       s"""${formatName(sink)} cannot be written from module ${source.parentNameOpt.getOrElse("(unknown)")}."""
     )
   def escapedScopeErrorMsg(data: Data, blockInfo: SourceInfo) = {
-    s"'$data' has escaped the scope of the block (${blockInfo.makeMessage()}) in which it was constructed."
+    s"operand '$data' has escaped the scope of the block (${blockInfo.makeMessage()}) in which it was constructed."
   }
   def UnknownRelationException =
     MonoConnectException("Sink or source unavailable to current module.")

core/src/main/scala/chisel3/internal/firrtl/Converter.scala

@@ -201,6 +201,10 @@ private[chisel3] object Converter {
         firrtl.Utils.one,
         e.name
       )
+    case e @ Flush(info, filename, clock) =>
+      val (fmt, args) = filename.map(unpack(_, ctx, info)).getOrElse(("", Seq.empty))
+      val fn = Option.when(fmt.nonEmpty)(fir.StringLit(fmt))
+      fir.Flush(convert(info), fn, args.map(a => convert(a, ctx, info)), convert(clock, ctx, info))
     case e @ ProbeDefine(sourceInfo, sink, probeExpr) =>
       fir.ProbeDefine(convert(sourceInfo), convert(sink, ctx, sourceInfo), convert(probeExpr, ctx, sourceInfo))
     case e @ ProbeForceInitial(sourceInfo, probe, value) =>

core/src/main/scala/chisel3/internal/firrtl/IR.scala

@@ -500,6 +500,12 @@ private[chisel3] object ir {
     pable:      Printable
   ) extends Definition
 
+  case class Flush(
+    sourceInfo: SourceInfo,
+    filename:   Option[Printable],
+    clock:      Arg
+  ) extends Command
+
   case class ProbeDefine(sourceInfo: SourceInfo, sink: Arg, probe: Arg) extends Command
   case class ProbeForceInitial(sourceInfo: SourceInfo, probe: Arg, value: Arg) extends Command
   case class ProbeReleaseInitial(sourceInfo: SourceInfo, probe: Arg) extends Command

core/src/main/scala/chisel3/internal/firrtl/Serializer.scala

@@ -265,6 +265,14 @@ private[chisel3] object Serializer {
       val lbl = e.name
       if (lbl.nonEmpty) { b ++= " : "; b ++= legalize(lbl) }
       serialize(e.sourceInfo)
+    case e @ Flush(info, filename, clock) =>
+      b ++= "fflush("; serialize(clock, ctx, info); b ++= ", UInt<1>(0h1)";
+      filename.foreach { fable =>
+        val (ffmt, fargs) = unpack(fable, ctx, info)
+        b ++= ", "; b ++= fir.StringLit(ffmt).escape
+        fargs.foreach { a => b ++= ", "; serialize(a, ctx, info) }
+      }
+      b += ')'; serialize(info)
     case e @ ProbeDefine(sourceInfo, sink, probeExpr) =>
       b ++= "define "; serialize(sink, ctx, sourceInfo); b ++= " = "; serialize(probeExpr, ctx, sourceInfo);
       serialize(sourceInfo)

docs/src/explanations/printing.md

@@ -264,4 +264,22 @@ val withFile = Module(new MyLogger(SimLog.file("data.log")))
 
 // Use with stderr
 val withStderr = Module(new MyLogger(SimLog.StdErr))
+```
+
+### Flush
+
+`SimLog` objects can be flushed to ensure that all buffered output is written.
+This is useful in simulations using the logged output as input to a co-simulated components like a checker or golden model.
+
+```scala mdoc:compile-only
+val log = SimLog.file("logfile.log")
+val in = IO(Input(UInt(8.W)))
+log.printf(cf"in = $in%d\n")
+log.flush() // Flush buffered output right away.
+```
+
+You can also flush standard error:
+
+```scala mdoc:compile-only
+SimLog.StdErr.flush() // This will flush all standard printfs.
 ```

firrtl/src/main/scala/firrtl/ir/IR.scala

@@ -450,6 +450,12 @@ case class Fprint(
     with IsDeclaration
     with UseSerializer
 
+@deprecated("All APIs in package firrtl are deprecated.", "Chisel 7.0.0")
+case class Flush(val info: Info, val filename: Option[StringLit], args: Seq[Expression], val clk: Expression)
+    extends Statement
+    with HasInfo
+    with UseSerializer
+
 @deprecated("All APIs in package firrtl are deprecated.", "Chisel 7.0.0")
 case class ProbeDefine(info: Info, sink: Expression, probeExpr: Expression) extends Statement with UseSerializer
 @deprecated("All APIs in package firrtl are deprecated.", "Chisel 7.0.0")

firrtl/src/main/scala/firrtl/ir/Serializer.scala

@@ -290,6 +290,10 @@ object Serializer {
       b ++= string.escape
       if (args.nonEmpty) b ++= ", "; s(args, ", "); b += ')'
       sStmtName(print.name); s(info)
+    case flush @ Flush(info, filename, args, clk) =>
+      b ++= "fflush("; s(clk); b ++= ", UInt<1>(0h1)";
+      filename.foreach { f => b ++= ", "; b ++= f.escape; b ++= ", "; s(args, ", ") }
+      b += ')'; s(info)
     case IsInvalid(info, expr)    => b ++= "invalidate "; s(expr); s(info)
     case DefWire(info, name, tpe) => b ++= "wire "; b ++= legalize(name); b ++= " : "; s(tpe); s(info)
     case DefRegister(info, name, tpe, clock) =>

firrtl/src/test/scala/firrtlTests/SerializerSpec.scala

@@ -421,5 +421,12 @@ class SerializerSpec extends AnyFlatSpec with Matchers {
         "label"
       )
     ) should include("""fprintf(clock, enable, "filename_%0d", x, "hello %x", arg) : label""")
+    info("flush okay!")
+    Serializer.serialize(
+      Flush(NoInfo, Some(StringLit("filename_%0d")), Seq(Reference("x")), Reference("clock"))
+    ) should include("""fflush(clock, UInt<1>(0h1), "filename_%0d", x)""")
+    Serializer.serialize(
+      Flush(NoInfo, None, Seq.empty, Reference("clock"))
+    ) should include("""fflush(clock, UInt<1>(0h1))""")
   }
 }

src/test/scala-2/chiselTests/SimLogSpec.scala

@@ -19,11 +19,13 @@ class SimLogSpec extends AnyFlatSpec with Matchers with FileCheck with ChiselSim
     class MyModule extends Module {
       val fd = SimLog.file("logfile.log")
       fd.printf(cf"An exact string")
+      fd.flush()
     }
     ChiselStage
       .emitCHIRRTL(new MyModule)
       .fileCheck()(
-        """CHECK: fprintf(clock, UInt<1>(0h1), "logfile.log", "An exact string")"""
+        """|CHECK: fprintf(clock, UInt<1>(0h1), "logfile.log", "An exact string")
+           |CHECK: fflush(clock, UInt<1>(0h1), "logfile.log")""".stripMargin
       )
   }
 
@@ -44,16 +46,19 @@ class SimLogSpec extends AnyFlatSpec with Matchers with FileCheck with ChiselSim
     class MyModule(fd: SimLog) extends Module {
       val in = IO(Input(UInt(8.W)))
       fd.printf(cf"in = $in%0d\n")
+      fd.flush()
     }
     ChiselStage
       .emitCHIRRTL(new MyModule(SimLog.file("logfile.log")))
       .fileCheck()(
-        """CHECK: fprintf(clock, UInt<1>(0h1), "logfile.log", "in = %0d\n", in)"""
+        """|CHECK: fprintf(clock, UInt<1>(0h1), "logfile.log", "in = %0d\n", in)
+           |CHECK: fflush(clock, UInt<1>(0h1), "logfile.log")""".stripMargin
       )
     ChiselStage
       .emitCHIRRTL(new MyModule(SimLog.StdErr))
       .fileCheck()(
-        """CHECK: printf(clock, UInt<1>(0h1), "in = %0d\n", in)"""
+        """|CHECK: printf(clock, UInt<1>(0h1), "in = %0d\n", in)
+           |CHECK: fflush(clock, UInt<1>(0h1))""".stripMargin
       )
   }
 
@@ -62,15 +67,17 @@ class SimLogSpec extends AnyFlatSpec with Matchers with FileCheck with ChiselSim
       val idx = IO(Input(UInt(8.W)))
       val fd = SimLog.file(cf"logfile_$idx%0d.log")
       fd.printf(cf"An exact string")
+      fd.flush()
     }
     ChiselStage
       .emitCHIRRTL(new MyModule)
       .fileCheck()(
-        """CHECK: fprintf(clock, UInt<1>(0h1), "logfile_%0d.log", idx, "An exact string")"""
+        """|CHECK: fprintf(clock, UInt<1>(0h1), "logfile_%0d.log", idx, "An exact string")
+           |CHECK: fflush(clock, UInt<1>(0h1), "logfile_%0d.log", idx)""".stripMargin
       )
   }
 
-  it should "check scope for Printable filenames" in {
+  it should "check scope for Printable filenames on printf" in {
     class Child(log: SimLog) extends Module {
       val bar = IO(Input(UInt(8.W)))
       log.printf(cf"bar = $bar%0d\n")
@@ -85,6 +92,19 @@ class SimLogSpec extends AnyFlatSpec with Matchers with FileCheck with ChiselSim
     (e.getMessage should include).regex("SimLog filename operand '.*' is not visible from the current module Child")
   }
 
+  it should "check scope for Printable filenames on flush" in {
+    class MyModule extends Module {
+      var log: SimLog = null
+      when(true.B) {
+        val foo = Wire(UInt(8.W))
+        log = SimLog.file(cf"logfile_$foo%0d.log")
+      }
+      log.flush()
+    }
+    val e = the[ChiselException] thrownBy ChiselStage.emitCHIRRTL(new MyModule, Array("--throw-on-first-error"))
+    (e.getMessage should include).regex("SimLog filename operand '.*' has escaped the scope of the block")
+  }
+
   it should "support writing to a file in simulation" in {
     val testdir = implicitly[HasTestingDirectory].getDirectory
     val logfile = testdir.resolve("workdir-verilator").resolve("logfile.log").toFile