Add SimulationTime (%T) format specifier (#4875)

Author: jackkoenig

core/src/main/scala/chisel3/Printable.scala

@@ -72,7 +72,7 @@ sealed abstract class Printable {
 
 object Printable {
 
-  private[chisel3] def isNoArgSpecifier(c: Char): Boolean = c == '%' || c == 'm'
+  private[chisel3] def isNoArgSpecifier(c: Char): Boolean = c == '%' || c == 'm' || c == 'T'
 
   /** Pack standard printf fmt, args* style into Printable
     */
@@ -102,7 +102,7 @@ object Printable {
     while (iter < fmt.size) {
       // Encountered % which is either
       // 1. Describing a format specifier.
-      // 2. %% or %m
+      // 2. %%, %m, or %T
       // 3. Dangling percent - most likely due to a typo - intended literal percent or forgot the specifier.
       // Try to give meaningful error reports
       if (fmt(iter) == '%') {
@@ -193,10 +193,10 @@ object Printable {
   /** Resolve Printables that are resolved at Chisel-time */
   private[chisel3] def resolve(pable: Printable, ctx: Component)(implicit info: SourceInfo): Printable =
     pable.map {
-      case Name(data)             => PString(data.ref.name)
-      case FullName(data)         => PString(data.ref.fullName(ctx))
-      case HierarchicalModuleName => PString("{{HierarchicalModuleName}}")
-      case other                  => other
+      case Name(data)     => PString(data.ref.name)
+      case FullName(data) => PString(data.ref.fullName(ctx))
+      case s: SpecialFirrtlSubstitution => PString(s.substitutionString)
+      case other => other
     }
 }
 
@@ -377,11 +377,28 @@ case object Percent extends Printable {
   final def unpack:     (String, Seq[Data]) = ("%%", List.empty)
 }
 
+/** Printable with special representation in FIRRTL
+  *
+  * @note The name of the singleton object exactly matches the FIRRTL value.
+  */
+sealed trait SpecialFirrtlSubstitution { self: Singleton with Printable =>
+  private[chisel3] final def substitutionString: String = "{{" + this.getClass.getSimpleName.dropRight(1) + "}}"
+}
+
 /** Represents the hierarchical name in the Verilog (`%m`) */
-case object HierarchicalModuleName extends Printable {
+case object HierarchicalModuleName extends Printable with SpecialFirrtlSubstitution {
   @deprecated("Use unpack with no arguments instead.", "Chisel 7.0.0")
   final def unpack(ctx: Component)(implicit info: SourceInfo): (String, Iterable[String]) = ("%m", List.empty)
   @deprecated("Use unpack with no arguments instead.", "Chisel 7.0.0")
   final def unpackArgs: Seq[Bits] = List.empty
   final def unpack:     (String, Seq[Data]) = ("%m", List.empty)
 }
+
+/** Represents the simulation time in the Verilog, similar to `%t` + `$time` */
+case object SimulationTime extends Printable with SpecialFirrtlSubstitution {
+  @deprecated("Use unpack with no arguments instead.", "Chisel 7.0.0")
+  final def unpack(ctx: Component)(implicit info: SourceInfo): (String, Iterable[String]) = ("%T", List.empty)
+  @deprecated("Use unpack with no arguments instead.", "Chisel 7.0.0")
+  final def unpackArgs: Seq[Bits] = List.empty
+  final def unpack:     (String, Seq[Data]) = ("%T", List.empty)
+}

core/src/main/scala/chisel3/package.scala

@@ -248,6 +248,8 @@ package object chisel3 {
                 Percent
               } else if (s(end + 1) == 'm') {
                 HierarchicalModuleName
+              } else if (s(end + 1) == 'T') {
+                SimulationTime
               } else {
                 throw new UnknownFormatConversionException("Un-escaped %")
               }

docs/src/explanations/printing.md

@@ -62,12 +62,16 @@ printf(cf"myUInt = $myUInt%c") // myUInt = !
 There are special values you can include in your `cf` interpolated string:
 
 * `HierarchicalModuleName` (`%m`): The hierarchical name of the current module
+* `SimulationTime` (`%T`): The current simulation time (unlike Verilog's `%t`, this does not take an argument)
 * `Percent` (`%%`): A literal `%`
 
 ```scala mdoc:compile-only
 printf(cf"hierarchical path = $HierarchicalModuleName\n") // hierarchical path = <verilog.module.path>
 printf(cf"hierarchical path = %m\n") // equivalent to the above
 
+printf(cf"simulation time = $SimulationTime\n") // simulation time = <simulation.time>
+printf(cf"simulation time = %T\n") // equivalent to the above
+
 printf(cf"100$Percent\n") // 100%
 printf(cf"100%%\n") // equivalent to the above
 ```
@@ -167,6 +171,7 @@ Chisel provides `printf` in a similar style to its C namesake. It accepts a doub
 | `%c` | 8-bit ASCII character |
 | `%%` | literal percent |
 | `%m` | hierarchical name |
+| `%T` | simulation time |
 
 `%d`, `%x`, and `%b` support the modifiers described in the [Format modifiers](#format-modifiers) section above.
 

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

@@ -318,18 +318,18 @@ class PrintableSpec extends AnyFlatSpec with Matchers with FileCheck {
   it should "support all legal format specifiers" in {
     class MyModule extends Module {
       val in = IO(Input(UInt(8.W)))
-      printf(cf"$HierarchicalModuleName $in%d $in%x $in%b $in%c %%\n")
+      printf(cf"$SimulationTime $HierarchicalModuleName $in%d $in%x $in%b $in%c %%\n")
     }
     ChiselStage
       .emitCHIRRTL(new MyModule)
       .fileCheck()(
-        """CHECK{LITERAL}: printf(clock, UInt<1>(0h1), "{{HierarchicalModuleName}} %d %x %b %c %%\n", in, in, in, in)"""
+        """CHECK{LITERAL}: printf(clock, UInt<1>(0h1), "{{SimulationTime}} {{HierarchicalModuleName}} %d %x %b %c %%\n", in, in, in, in)"""
       )
     // Also check Verilog
     ChiselStage
       .emitSystemVerilog(new MyModule)
       .fileCheck()(
-        """CHECK: $fwrite(`PRINTF_FD_, "%m %d %x %b %c %%\n", in, in, in, in);"""
+        """CHECK: $fwrite(`PRINTF_FD_, "%0t %m %d %x %b %c %%\n", $time, in, in, in, in);"""
       )
 
   }
@@ -391,6 +391,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers with FileCheck {
       (PString("foo"), ("foo", Seq())),
       (Percent, ("%%", Seq())),
       (HierarchicalModuleName, ("%m", Seq())),
+      (SimulationTime, ("%T", Seq())),
       (Name(x), ("%n", Seq(x))),
       (FullName(x), ("%N", Seq(x)))
     )

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

@@ -76,18 +76,18 @@ class PrintfSpec extends AnyFlatSpec with Matchers with FileCheck {
   "printf" should "support all legal format specifiers" in {
     class MyModule extends Module {
       val in = IO(Input(UInt(8.W)))
-      printf("%m %d %x %b %c %%\n", in, in, in, in)
+      printf("%T %m %d %x %b %c %%\n", in, in, in, in)
     }
     ChiselStage
       .emitCHIRRTL(new MyModule)
       .fileCheck()(
-        """CHECK{LITERAL}: printf(clock, UInt<1>(0h1), "{{HierarchicalModuleName}} %d %x %b %c %%\n", in, in, in, in)"""
+        """CHECK{LITERAL}: printf(clock, UInt<1>(0h1), "{{SimulationTime}} {{HierarchicalModuleName}} %d %x %b %c %%\n", in, in, in, in)"""
       )
     // Also check Verilog
     ChiselStage
       .emitSystemVerilog(new MyModule)
       .fileCheck()(
-        """CHECK: $fwrite(`PRINTF_FD_, "%m %d %x %b %c %%\n", in, in, in, in);"""
+        """CHECK: $fwrite(`PRINTF_FD_, "%0t %m %d %x %b %c %%\n", $time, in, in, in, in);"""
       )
   }