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.

1 files changed, 50 insertions, 0 deletions

diff --git a/src/test/scala/chiselTests/Math.scala b/src/test/scala/chiselTests/Math.scala
new file mode 100644
index 00000000..aa32a828
--- /dev/null
+++ b/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)
+        }
+      }
+    }
+  }
+}