Runtime API deprecation warnings (#761)

Add runtime warnings for use of deprecated Chisel methods. This is done using a macro that takes the message from a `@deprecated` annotation, and adds a call to `Builder.deprecated`.

Reasoning is that by default, Scala doesn't print all deprecations, and that it's somewhat tricky to notice them - yet some support questions revolve around the use of deprecated and terribad API. This now prints warnings for uses of deprecated functions at runtime, and aggregates them by error and line to avoid spam. Also included is convenient information on enabling scalac deprecations.

This also changes how line numbers for Chisel's error facility is determined, using prefix string comparison of the stack trace element classnames, instead of checking if the class is a subtype of UserModule. The previous one (specifically, calls to Class.forName) seems to interact badly with reflection-based cloneType when called at scale. This should also give more accurate reporting of errors that are in user code but outside of a UserModule.

It turns out that `@deprecated` on macro functions don't do anything, so this changes the tags to the functions that the macros point to, which seems to work properly. It also turns out that there's a bunch of uses of deprecated functions in chiselTests which needs to be fixed.

Not all `@deprecated` functions are also annotated with `@chiselRuntimeDeprecation`, because they're still used in Chisel internals, and we can't track whether they're called by the user or by Chisel and it will give a misleading error. These are a small amount of functions.

5 files changed, 40 insertions, 21 deletions

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala b/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
index 14011cd9..e45f6d72 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala
@@ -231,14 +231,6 @@ sealed class Vec[T <: Data] private[core] (gen: => T, val length: Int)
     */
   def apply(idx: Int): T = self(idx)
 
-  @deprecated("Use Vec.apply instead", "chisel3")
-  def read(idx: UInt)(implicit compileOptions: CompileOptions): T = do_apply(idx)(compileOptions)
-
-  @deprecated("Use Vec.apply instead", "chisel3")
-  def write(idx: UInt, data: T)(implicit compileOptions: CompileOptions): Unit = {
-    do_apply(idx)(compileOptions).:=(data)(DeprecatedSourceInfo, compileOptions)
-  }
-
   override def cloneType: this.type = {
     new Vec(gen.cloneType, length).asInstanceOf[this.type]
   }
@@ -341,11 +333,15 @@ trait VecLike[T <: Data] extends collection.IndexedSeq[T] with HasId {
   override def hashCode: Int = super[HasId].hashCode
   override def equals(that: Any): Boolean = super[HasId].equals(that)
 
+  @chiselRuntimeDeprecated
   @deprecated("Use Vec.apply instead", "chisel3")
-  def read(idx: UInt)(implicit compileOptions: CompileOptions): T
+  def read(idx: UInt)(implicit compileOptions: CompileOptions): T = do_apply(idx)(compileOptions)
 
+  @chiselRuntimeDeprecated
   @deprecated("Use Vec.apply instead", "chisel3")
-  def write(idx: UInt, data: T)(implicit compileOptions: CompileOptions): Unit
+  def write(idx: UInt, data: T)(implicit compileOptions: CompileOptions): Unit = {
+    do_apply(idx)(compileOptions).:=(data)(DeprecatedSourceInfo, compileOptions)
+  }
 
   /** Outputs true if p outputs true for every element.
     */
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 61617775..51f5f5ec 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -277,15 +277,26 @@ sealed abstract class Bits(width: Width, override val litArg: Option[LitArg])
   }
 
   /** Reinterpret cast to Bits. */
+  @chiselRuntimeDeprecated
   @deprecated("Use asUInt, which does the same thing but returns a more concrete type", "chisel3")
-  final def asBits(): Bits = macro SourceInfoTransform.noArg
-
-  def do_asBits(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bits = asUInt()
+  final def asBits(implicit compileOptions: CompileOptions): Bits = {
+    implicit val sourceInfo = DeprecatedSourceInfo
+    do_asUInt
+  }
 
+  @chiselRuntimeDeprecated
   @deprecated("Use asSInt, which makes the reinterpret cast more explicit", "chisel3")
-  final def toSInt(implicit compileOptions: CompileOptions): SInt = do_asSInt(DeprecatedSourceInfo, compileOptions)
+  final def toSInt(implicit compileOptions: CompileOptions): SInt = {
+    implicit val sourceInfo = DeprecatedSourceInfo
+    do_asSInt
+  }
+  
+  @chiselRuntimeDeprecated
   @deprecated("Use asUInt, which makes the reinterpret cast more explicit", "chisel3")
-  final def toUInt(implicit compileOptions: CompileOptions): UInt = do_asUInt(DeprecatedSourceInfo, compileOptions)
+  final def toUInt(implicit compileOptions: CompileOptions): UInt = {
+    implicit val sourceInfo = DeprecatedSourceInfo
+    do_asUInt
+  }
 
   final def do_toBool(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = {
     width match {
@@ -477,7 +488,7 @@ sealed class UInt private[core] (width: Width, lit: Option[ULit] = None)
   final def andR(): Bool = macro SourceInfoTransform.noArg
   final def xorR(): Bool = macro SourceInfoTransform.noArg
 
-  def do_orR(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this != 0.U
+  def do_orR(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this =/= 0.U
   def do_andR(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = ~this === 0.U
   def do_xorR(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = redop(sourceInfo, XorReduceOp)
 
@@ -486,12 +497,12 @@ sealed class UInt private[core] (width: Width, lit: Option[ULit] = None)
   override def do_<= (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, LessEqOp, that)
   override def do_>= (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, GreaterEqOp, that)
 
+  @chiselRuntimeDeprecated
   @deprecated("Use '=/=', which avoids potential precedence problems", "chisel3")
-  final def != (that: UInt): Bool = macro SourceInfoTransform.thatArg
+  final def != (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this =/= that
   final def =/= (that: UInt): Bool = macro SourceInfoTransform.thatArg
   final def === (that: UInt): Bool = macro SourceInfoTransform.thatArg
 
-  def do_!= (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, NotEqualOp, that)
   def do_=/= (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, NotEqualOp, that)
   def do_=== (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, EqualOp, that)
 
@@ -652,12 +663,12 @@ sealed class SInt private[core] (width: Width, lit: Option[SLit] = None)
   override def do_<= (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, LessEqOp, that)
   override def do_>= (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, GreaterEqOp, that)
 
+  @chiselRuntimeDeprecated
   @deprecated("Use '=/=', which avoids potential precedence problems", "chisel3")
-  final def != (that: SInt): Bool = macro SourceInfoTransform.thatArg
+  final def != (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = this =/= that
   final def =/= (that: SInt): Bool = macro SourceInfoTransform.thatArg
   final def === (that: SInt): Bool = macro SourceInfoTransform.thatArg
 
-  def do_!= (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, NotEqualOp, that)
   def do_=/= (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, NotEqualOp, that)
   def do_=== (that: SInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = compop(sourceInfo, EqualOp, that)
 
@@ -979,6 +990,7 @@ object FixedPoint {
   def apply(): FixedPoint = apply(Width(), BinaryPoint())
 
   /** Create an FixedPoint type or port with fixed width. */
+  @chiselRuntimeDeprecated
   @deprecated("Use FixedPoint(width: Width, binaryPoint: BinaryPoint) example FixedPoint(16.W, 8.BP)", "chisel3")
   def apply(width: Int, binaryPoint: Int): FixedPoint = apply(Width(width), BinaryPoint(binaryPoint))
 
@@ -1010,6 +1022,7 @@ object FixedPoint {
   /** Create an FixedPoint literal with inferred width from Double.
     * Use PrivateObject to force users to specify width and binaryPoint by name
     */
+  @chiselRuntimeDeprecated
   @deprecated("use fromDouble(value: Double, width: Width, binaryPoint: BinaryPoint)", "chisel3")
   def fromDouble(value: Double, dummy: PrivateType = PrivateObject,
                  width: Int = -1, binaryPoint: Int = 0): FixedPoint = {
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Data.scala b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
index 1cf50e9f..40781490 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Data.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
@@ -70,8 +70,9 @@ object ActualDirection {
   case class Bidirectional(dir: BidirectionalDirection) extends ActualDirection
 }
 
-@deprecated("debug doesn't do anything in Chisel3 as no pruning happens in the frontend", "chisel3")
 object debug {  // scalastyle:ignore object.name
+  @chiselRuntimeDeprecated
+  @deprecated("debug doesn't do anything in Chisel3 as no pruning happens in the frontend", "chisel3")
   def apply (arg: Data): Data = arg
 }
 
@@ -379,6 +380,7 @@ abstract class Data extends HasId {
     *
     * This performs the inverse operation of fromBits(Bits).
     */
+  @chiselRuntimeDeprecated
   @deprecated("Best alternative, .asUInt()", "chisel3")
   def toBits(implicit compileOptions: CompileOptions): UInt = do_asUInt(DeprecatedSourceInfo, compileOptions)
 
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Mem.scala b/chiselFrontend/src/main/scala/chisel3/core/Mem.scala
index 2c8e1a1e..c9208030 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Mem.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Mem.scala
@@ -10,6 +10,7 @@ import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo.{SourceInfo, SourceInfoTransform, UnlocatableSourceInfo, MemTransform}
 
 object Mem {
+  @chiselRuntimeDeprecated
   @deprecated("Mem argument order should be size, t; this will be removed by the official release", "chisel3")
   def apply[T <: Data](t: T, size: Int)(implicit compileOptions: CompileOptions): Mem[T] = do_apply(size, t)(UnlocatableSourceInfo, compileOptions)
 
@@ -118,6 +119,7 @@ sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId {
 sealed class Mem[T <: Data](t: T, length: Int) extends MemBase(t, length)
 
 object SyncReadMem {
+  @chiselRuntimeDeprecated
   @deprecated("SeqMem/SyncReadMem argument order should be size, t; this will be removed by the official release", "chisel3")
   def apply[T <: Data](t: T, size: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SyncReadMem[T] = do_apply(size, t)
 
diff --git a/chiselFrontend/src/main/scala/chisel3/core/UserModule.scala b/chiselFrontend/src/main/scala/chisel3/core/UserModule.scala
index 9c923037..1411fa80 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/UserModule.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/UserModule.scala
@@ -131,6 +131,7 @@ abstract class LegacyModule(implicit moduleCompileOptions: CompileOptions)
 
   // _clock and _reset can be clock and reset in these 2ary constructors
   // once chisel2 compatibility issues are resolved
+  @chiselRuntimeDeprecated
   @deprecated("Module constructor with override_clock and override_reset deprecated, use withClockAndReset", "chisel3")
   def this(override_clock: Option[Clock]=None, override_reset: Option[Bool]=None)
       (implicit moduleCompileOptions: CompileOptions) = {
@@ -139,10 +140,15 @@ abstract class LegacyModule(implicit moduleCompileOptions: CompileOptions)
     this.override_reset = override_reset
   }
 
+  @chiselRuntimeDeprecated
   @deprecated("Module constructor with override _clock deprecated, use withClock", "chisel3")
   def this(_clock: Clock)(implicit moduleCompileOptions: CompileOptions) = this(Option(_clock), None)(moduleCompileOptions)
+  
+  @chiselRuntimeDeprecated
   @deprecated("Module constructor with override _reset deprecated, use withReset", "chisel3")
   def this(_reset: Bool)(implicit moduleCompileOptions: CompileOptions)  = this(None, Option(_reset))(moduleCompileOptions)
+  
+  @chiselRuntimeDeprecated
   @deprecated("Module constructor with override _clock, _reset deprecated, use withClockAndReset", "chisel3")
   def this(_clock: Clock, _reset: Bool)(implicit moduleCompileOptions: CompileOptions) = this(Option(_clock), Option(_reset))(moduleCompileOptions)