Add support for printing hierarchical names in Verilog (%m) (chipsalliance#4820)

Co-authored-by: Megan Wachs <[email protected]>

Author: 2 people

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

@@ -64,16 +64,21 @@ sealed abstract class Printable {
 }
 object Printable {
 
+  private[chisel3] def isNoArgSpecifier(c: Char): Boolean = c == '%' || c == 'm'
+
   /** Pack standard printf fmt, args* style into Printable
     */
   def pack(fmt: String, data: Data*): Printable = {
     val args = data.iterator
     // Error handling
     def carrotAt(index: Int) = (" " * index) + "^"
-    def errorMsg(index: Int) =
-      s"""|    fmt = "$fmt"
+    def errorMsg(index: Int) = {
+      // Escape newlines because they mess up the error message
+      val fmtEsc = fmt.replaceAll("\n", "\\\\n")
+      s"""|    fmt = "$fmtEsc"
           |           ${carrotAt(index)}
           |    data = ${data.mkString(", ")}""".stripMargin
+    }
 
     def checkArg(i: Int): Unit = {
       if (!args.hasNext) {
@@ -89,11 +94,11 @@ object Printable {
     while (iter < fmt.size) {
       // Encountered % which is either
       // 1. Describing a format specifier.
-      // 2. Literal Percent
+      // 2. %% or %m
       // 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) == '%') {
-        if (iter != fmt.size - 1 && (fmt(iter + 1) != '%' && !fmt(iter + 1).isWhitespace)) {
+        if (iter != fmt.size - 1 && (!isNoArgSpecifier(fmt(iter + 1)) && !fmt(iter + 1).isWhitespace)) {
           checkArg(iter)
           buf += fmt.substring(curr_start, iter)
           curr_start = iter
@@ -112,7 +117,7 @@ object Printable {
           throw new UnknownFormatConversionException(msg)
         }
 
-        // A literal percent - hence increment by 2.
+        // %% or %m - hence increment by 2.
         else {
           iter += 2
         }
@@ -235,3 +240,9 @@ case object Percent extends Printable {
   final def unpack(ctx: Component)(implicit info: SourceInfo): (String, Iterable[String]) = ("%%", List.empty)
   final def unpackArgs:                                        Seq[Bits] = List.empty
 }
+
+/** Represents the hierarchical name in the Verilog (`%m`) */
+case object HierarchicalName extends Printable {
+  final def unpack(ctx: Component)(implicit info: SourceInfo): (String, Iterable[String]) = ("%m", List.empty)
+  final def unpackArgs:                                        Seq[Bits] = List.empty
+}

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

@@ -24,9 +24,10 @@ private[chisel3] object Converter {
       case PString(str) => (str.replaceAll("%", "%%"), List.empty)
       case format: FirrtlFormat =>
         ("%" + format.specifier, List(format.bits.ref))
-      case Name(data)     => (data.ref.name, List.empty)
-      case FullName(data) => (data.ref.fullName(ctx), List.empty)
-      case Percent        => ("%%", List.empty)
+      case Name(data)       => (data.ref.name, List.empty)
+      case FullName(data)   => (data.ref.fullName(ctx), List.empty)
+      case Percent          => ("%%", List.empty)
+      case HierarchicalName => ("%m", List.empty)
     }
   }
 

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

@@ -84,9 +84,10 @@ private[chisel3] object Serializer {
       case PString(str) => (str.replaceAll("%", "%%"), List.empty)
       case format: FirrtlFormat =>
         ("%" + format.specifier, List(format.bits.ref))
-      case Name(data)     => (data.ref.name, List.empty)
-      case FullName(data) => (data.ref.fullName(ctx), List.empty)
-      case Percent        => ("%%", List.empty)
+      case Name(data)       => (data.ref.name, List.empty)
+      case FullName(data)   => (data.ref.fullName(ctx), List.empty)
+      case Percent          => ("%%", List.empty)
+      case HierarchicalName => ("%m", List.empty)
     }
   }
 

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

@@ -229,31 +229,41 @@ package object chisel3 {
     @nowarn("msg=checkLengths in class StringContext is deprecated")
     def cf(args: Any*): Printable = {
 
-      // Handle literal %
-      // Takes the part string -
-      // - this is assumed to not have any format specifiers - already handled / removed before calling this function.
-      // Only thing present is literal % if any which should ideally be with %%.
-      // If not - then flag an error.
-      // Return seq of Printables (either PString or Percent or both - nothing else
-      def percentSplitter(s: String): Seq[Printable] = {
-        if (s.isEmpty) Seq(PString(""))
-        else {
-          val pieces = s.split("%%").toList.flatMap { p =>
-            if (p.contains('%')) throw new UnknownFormatConversionException("Un-escaped % found")
-            // Wrap in PString and intersperse the escaped percentages
-            Seq(Percent, PString(p))
+      // Handle special escapes like %% and %m
+      def escapeHandler(s: String): Seq[Printable] = {
+        val pieces = mutable.ListBuffer.empty[Printable]
+        var start = 0
+        var end = 0
+        while (end < s.length) {
+          if (s(end) == '%') {
+            val piece =
+              if (end == s.length - 1) {
+                throw new UnknownFormatConversionException("Trailing %")
+              } else if (s(end + 1) == '%') {
+                Percent
+              } else if (s(end + 1) == 'm') {
+                HierarchicalName
+              } else {
+                throw new UnknownFormatConversionException("Un-escaped %")
+              }
+            pieces += PString(s.substring(start, end))
+            pieces += piece
+            start = end + 2
+            end = start
+          } else {
+            end += 1
           }
-          if (pieces.isEmpty) Seq(Percent)
-          else pieces.tail // Don't forget to drop the extra percent we put at the beginning
         }
+        pieces += PString(s.substring(start, end))
+        pieces.toList
       }
 
       def extractFormatSpecifier(part: String): (Option[String], String) = {
         // Check if part starts with a format specifier (with % - disambiguate with literal % checking the next character if needed to be %)
         // In the case of %f specifier there is a chance that we need more information - so capture till the 1st letter (a-zA-Z).
         // Example cf"This is $val%2.2f here" - parts - Seq("This is ","%2.2f here") - the format specifier here is %2.2f.
         val endFmtIdx =
-          if (part.length > 1 && part(0) == '%' && part(1) != '%') part.indexWhere(_.isLetter)
+          if (part.length > 1 && part(0) == '%' && !Printable.isNoArgSpecifier(part(1))) part.indexWhere(_.isLetter)
           else -1
         val (fmt, rest) = part.splitAt(endFmtIdx + 1)
 
@@ -301,10 +311,10 @@ package object chisel3 {
             case t => PString(fmt.getOrElse("%s").format(t))
 
           }
-          Seq(fmtArg) ++ percentSplitter(modP)
+          Seq(fmtArg) ++ escapeHandler(modP)
         }
       }
-      Printables(percentSplitter(parts.head) ++ pables)
+      Printables(escapeHandler(parts.head) ++ pables)
     }
   }
 

docs/src/explanations/printing.md

@@ -57,6 +57,22 @@ printf(cf"myUInt = $myUInt%b") // myUInt = 100001
 printf(cf"myUInt = $myUInt%c") // myUInt = !
 ```
 
+#### Special values
+
+There are special values you can include in your `cf` interpolated string:
+
+* `HierarchicalName` (`%m`): The hierarchical name of the signal
+* `Percent` (`%%`): A literal `%`
+
+```scala mdoc:compile-only
+printf(cf"hierarchical path = $HierarchicalName\n") // hierarchical path = <verilog.module.path>
+printf(cf"hierarchical path = %m\n") // equivalent to the above
+
+printf(cf"100$Percent\n") // 100%
+printf(cf"100%%\n") // equivalent to the above
+```
+
+
 #### Aggregate data-types
 
 Chisel provides default custom "pretty-printing" for Vecs and Bundles. The default printing of a Vec is similar to printing a Seq or List in Scala while printing a Bundle is similar to printing a Scala Map.
@@ -126,6 +142,7 @@ Chisel provides `printf` in a similar style to its C namesake. It accepts a doub
 | `%b` | binary number |
 | `%c` | 8-bit ASCII character |
 | `%%` | literal percent |
+| `%m` | hierarchical name |
 
 It also supports a small set of escape characters:
 

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

@@ -4,12 +4,13 @@ package chiselTests
 
 import chisel3._
 import circt.stage.ChiselStage
+import chisel3.testing.scalatest.FileCheck
 import org.scalactic.source.Position
 import org.scalatest.flatspec.AnyFlatSpec
 import org.scalatest.matchers.should.Matchers
 
 /* Printable Tests */
-class PrintableSpec extends AnyFlatSpec with Matchers {
+class PrintableSpec extends AnyFlatSpec with Matchers with FileCheck {
   // This regex is brittle, it specifically finds the clock and enable signals followed by commas
   private val PrintfRegex = """\s*printf\(\w+, [^,]+,(.*)\).*""".r
   private val StringRegex = """([^"]*)"(.*?)"(.*)""".r
@@ -310,4 +311,16 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
     generateAndCheck(new MyModule) { case Seq(Printf("\\\\ \\\\]", Seq())) =>
     }
   }
+
+  it should "support all legal format specifiers" in {
+    class MyModule extends Module {
+      val in = IO(Input(UInt(8.W)))
+      printf(cf"$HierarchicalName $in%d $in%x $in%b $in%c %%\n")
+    }
+    ChiselStage
+      .emitCHIRRTL(new MyModule)
+      .fileCheck()(
+        """CHECK: printf(clock, UInt<1>(0h1), "%m %d %x %b %c %%\n", in, in, in, in)"""
+      )
+  }
 }

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

@@ -4,6 +4,7 @@ package chiselTests
 
 import chisel3._
 import circt.stage.ChiselStage
+import chisel3.testing.scalatest.FileCheck
 import org.scalatest.flatspec.AnyFlatSpec
 import org.scalatest.matchers.should.Matchers
 
@@ -38,7 +39,7 @@ class ScopeTesterModule extends Module {
   val wp = cf"$w"
 }
 
-class PrintfSpec extends AnyFlatSpec with Matchers {
+class PrintfSpec extends AnyFlatSpec with Matchers with FileCheck {
   "A printf with a single argument" should "elaborate" in {
     val chirrtl = ChiselStage.emitCHIRRTL(new SinglePrintfTester)
 
@@ -72,4 +73,15 @@ class PrintfSpec extends AnyFlatSpec with Matchers {
       }
     }
   }
+  "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)
+    }
+    ChiselStage
+      .emitCHIRRTL(new MyModule)
+      .fileCheck()(
+        """CHECK: printf(clock, UInt<1>(0h1), "%m %d %x %b %c %%\n", in, in, in, in)"""
+      )
+  }
 }