Add width utility functions to avoid incorrect usage of bare log2Ceil…

…(). (#819)

* Add width utility functions to avoid incorrect usage of bare log2Ceil().

* Respond to comments:
Remove apply(Data) method.
Change name(s) to signedBitLength, unsignedBitLength.

* Respond to comments - don't be lazy.
Independently calculate the bit length to verify correct operation.

* Respond to comments - return in.bitLength - 0 (not 1) for 0

* Respond to comments - update wdith for signed 0; add explicit tests.

* Add comment expressing zero width wire assumption.

src/main/scala/chisel3/util/Math.scala

@@ -5,8 +5,7 @@
 
 package chisel3.util
 
-import chisel3._
-import chisel3.internal.chiselRuntimeDeprecated
+import chisel3.internal
 
 /** Compute the log2 of a Scala integer, rounded up, with min value of 1.
   * Useful for getting the number of bits needed to represent some number of states (in - 1),
@@ -99,3 +98,36 @@ object isPow2 {
   def apply(in: BigInt): Boolean = in > 0 && ((in & (in-1)) == 0)
   def apply(in: Int): Boolean = apply(BigInt(in))
 }
+
+
+object unsignedBitLength {
+  /** Return the number of bits required to encode a specific value, assuming no sign bit is required.
+    *
+    * Basically, `n.bitLength`. NOTE: This will return 0 for a value of 0.
+    * This reflects the Chisel assumption that a zero width wire has a value of 0.
+    * @param in - the number to be encoded.
+    * @return - an Int representing the number of bits to encode.
+    */
+  def apply(in: BigInt): Int = {
+    require(in >= 0)
+    in.bitLength
+  }
+}
+
+object signedBitLength {
+  /** Return the number of bits required to encode a specific value, assuming a sign bit is required.
+    *
+    * Basically, 0 for 0, 1 for -1, and `n.bitLength` + 1 for everything else.
+    * This reflects the Chisel assumption that a zero width wire has a value of 0.
+    * @param in - the number to be encoded.
+    * @return - an Int representing the number of bits to encode.
+    */
+  def apply(in: BigInt): Int = {
+    in.toInt match {
+      case 0 => 0
+      case -1 => 1
+      case _ => in.bitLength + 1
+    }
+
+  }
+}

src/test/scala/chiselTests/Math.scala

@@ -0,0 +1,50 @@
+// See LICENSE for license details.
+
+package chiselTests
+
+import org.scalacheck.Shrink
+
+class Math extends ChiselPropSpec {
+  import chisel3.util._
+  // Disable shrinking on error.
+  implicit val noShrinkListVal = Shrink[List[Int]](_ => Stream.empty)
+  implicit val noShrinkInt = Shrink[Int](_ => Stream.empty)
+
+  property ("unsignedBitLength is computed correctly") {
+    forAll(safeUIntWidth) { case (width: Int) =>
+      for ( offset <- List(-1, 0, 1)) {
+        val n = (1 << width) + offset
+        if (n >= 0) {
+          val d = unsignedBitLength(n)
+          val t = if (n == 0) 0 else if (offset < 0) width else width + 1
+          d shouldEqual (t)
+        }
+      }
+    }
+  }
+
+  property ("signedBitLength is computed correctly") {
+    forAll(safeUIntWidth) { case (width: Int) =>
+      for ( offset <- List(-1, 0, 1)) {
+        for ( mult <- List(-1, +1)) {
+          val n = ((1 << (width - 1)) + offset) * mult
+          val d = signedBitLength(n)
+          val t = n match {
+            case -2 => 2
+            case -1 => 1
+            case 0 => 0
+            case 1 => 2
+            case 2 => 3
+            case _ =>
+              if (n > 0) {
+                if (offset < 0) width else width + 1
+              } else {
+                if (offset > 0) width + 1 else width
+              }
+          }
+          d shouldEqual (t)
+        }
+      }
+    }
+  }
+}