From fc3fedaa9c16d7861b452388a70ec2f6e2a3dc30 Mon Sep 17 00:00:00 2001 From: mergify[bot] Date: Tue, 20 Sep 2022 18:54:01 +0000 Subject: Cleanup Cookbook and printing docs (#2727) (#2742) * Cleanup Cookbook and printing docs * Format specifiers are actually concise now Co-authored-by: Megan Wachs (cherry picked from commit df2a71833ffc8ee8a053a1e8ea41c482e46be132) Co-authored-by: Aditya Naik <91489422+adkian-sifive@users.noreply.github.com>--- docs/src/cookbooks/cookbook.md | 8 ++++---- docs/src/explanations/printing.md | 34 ++++++++++++++++------------------ 2 files changed, 20 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md index ab8e76d3..14bf9706 100644 --- a/docs/src/cookbooks/cookbook.md +++ b/docs/src/cookbooks/cookbook.md @@ -55,7 +55,7 @@ class Foo extends RawModule { bundle.foo := 0xc.U bundle.bar := 0x3.U val uint = bundle.asUInt - printf(p"$uint") // 195 + printf(cf"$uint") // 195 // Test assert(uint === 0xc3.U) @@ -78,7 +78,7 @@ class Foo extends RawModule { val uint = 0xb4.U val bundle = uint.asTypeOf(new MyBundle) - printf(p"$bundle") // Bundle(foo -> 11, bar -> 4) + printf(cf"$bundle") // Bundle(foo -> 11, bar -> 4) // Test assert(bundle.foo === 0xb.U) @@ -126,7 +126,7 @@ class Foo extends RawModule { val uint = 0xc.U val vec = VecInit(uint.asBools) - printf(p"$vec") // Vec(0, 0, 1, 1) + printf(cf"$vec") // Vec(0, 0, 1, 1) // Test assert(vec(0) === false.B) @@ -147,7 +147,7 @@ class Foo extends RawModule { val vec = VecInit(true.B, false.B, true.B, true.B) val uint = vec.asUInt - printf(p"$uint") // 13 + printf(cf"$uint") // 13 // Test // (remember leftmost Bool in Vec is low order bit) diff --git a/docs/src/explanations/printing.md b/docs/src/explanations/printing.md index abd1a427..71a6f5cf 100644 --- a/docs/src/explanations/printing.md +++ b/docs/src/explanations/printing.md @@ -13,22 +13,22 @@ Chisel provides the `printf` function for debugging purposes. It comes in two fl ### Scala-style -Chisel also supports printf in a style similar to [Scala's String Interpolation](http://docs.scala-lang.org/overviews/core/string-interpolation.html). Chisel provides a custom string interpolator `p` which can be used as follows: +Chisel also supports printf in a style similar to [Scala's String Interpolation](http://docs.scala-lang.org/overviews/core/string-interpolation.html). Chisel provides a custom string interpolator `cf` which follows C-style format specifiers (see section [C-style](#c-style) below). Here's a few examples of using the `cf` interpolator: ```scala mdoc:invisible import chisel3._ ``` ```scala mdoc:compile-only val myUInt = 33.U -printf(p"myUInt = $myUInt") // myUInt = 33 +printf(cf"myUInt = $myUInt") // myUInt = 33 ``` -Note that when concatenating `p"..."` strings, you need to start with a `p"..."` string: +Note that when concatenating `cf"..."` strings, you need to start with a `cf"..."` string: ```scala mdoc:compile-only // Does not interpolate the second string val myUInt = 33.U -printf("my normal string" + p"myUInt = $myUInt") +printf("my normal string" + cf"myUInt = $myUInt") ``` #### Simple formatting @@ -38,22 +38,20 @@ Other formats are available as follows: ```scala mdoc:compile-only val myUInt = 33.U // Hexadecimal -printf(p"myUInt = 0x${Hexadecimal(myUInt)}") // myUInt = 0x21 +printf(cf"myUInt = 0x$myUInt%x") // myUInt = 0x21 // Binary -printf(p"myUInt = ${Binary(myUInt)}") // myUInt = 100001 +printf(cf"myUInt = $myUInt%b") // myUInt = 100001 // Character -printf(p"myUInt = ${Character(myUInt)}") // myUInt = ! +printf(cf"myUInt = $myUInt%c") // myUInt = ! ``` -We recognize that the format specifiers are verbose, so we are working on a more concise syntax. - #### 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. ```scala mdoc:compile-only val myVec = VecInit(5.U, 10.U, 13.U) -printf(p"myVec = $myVec") // myVec = Vec(5, 10, 13) +printf(cf"myVec = $myVec") // myVec = Vec(5, 10, 13) val myBundle = Wire(new Bundle { val foo = UInt() @@ -61,7 +59,7 @@ val myBundle = Wire(new Bundle { }) myBundle.foo := 3.U myBundle.bar := 11.U -printf(p"myBundle = $myBundle") // myBundle = Bundle(a -> 3, b -> 11) +printf(cf"myBundle = $myBundle") // myBundle = Bundle(a -> 3, b -> 11) ``` #### Custom Printing @@ -76,11 +74,11 @@ class Message extends Bundle { val data = UInt(64.W) override def toPrintable: Printable = { val char = Mux(valid, 'v'.U, '-'.U) - p"Message:\n" + - p" valid : ${Character(char)}\n" + - p" addr : 0x${Hexadecimal(addr)}\n" + - p" length : $length\n" + - p" data : 0x${Hexadecimal(data)}\n" + cf"Message:\n" + + cf" valid : $char%c\n" + + cf" addr : $addr%x\n" + + cf" length : $length\n" + + cf" data : $data%x\n" } } @@ -90,7 +88,7 @@ myMessage.addr := "h1234".U myMessage.length := 10.U myMessage.data := "hdeadbeef".U -printf(p"$myMessage") +printf(cf"$myMessage") ``` Which prints the following: @@ -103,7 +101,7 @@ Message: data : 0x00000000deadbeef ``` -Notice the use of `+` between `p` interpolated "strings". The results of `p` interpolation can be concatenated by using the `+` operator. For more information, please see the documentation +Notice the use of `+` between `cf` interpolated "strings". The results of `cf` interpolation can be concatenated by using the `+` operator. ### C-Style -- cgit v1.2.3