Invalidateapi (#645)

* Require explicit connection to DontCare to generate "is invalid".

* Add tests for RefNotInitializedException.
Currently, we fail the when ... otherwise ...

* Disable ScalaTest shrinking on error in ComplexAssignSpec.

* fix broken merge; still some binding issues

* cleanup DontCare connection checks; add missing directions to test module IOs

* Have library code inherit compileOptions from the enclosing Module (if it exists).

* work around current firrtl uninitialized references with Strict compile options and explicitInvalidate

* more CompileOptions cleanup; move test-specific defines to package object

* minimize differences with master

* set default CompileOptions.explicitInvalidate to false until we fix the FIRRTL when issue

* ignore the StrictCompiler property checks (until  CompileOptions.explicitInvalidate is defaulted to true)

* Revert "more CompileOptions cleanup; move test-specific defines to package object"

This reverts commit e4486edcba990d150e76e08a2fc6abca033556e0.

* Revert "work around current firrtl uninitialized references with Strict compile options and explicitInvalidate"

This reverts commit 426faa430a62c3dac2dbdf33044d3386d4243157.

* remove unused code

* Convert to binding-based DontCare implementation

* comment cleanup to minimize differences with master

* Tentatively remove possibly redundant DefInvalid on module ports.

* Respond to code review change request.
- backout build.sbt change
- correct indentation
- handle bulk of DontCare semantics in elemConnect()
- have DontCare extend Element, not Data (eliminate most Object specific methods
- add comments indicating reason for explicit DontCare connections

* Initialize test elements without requiring a DontCare.

* Respond to review change requests.
- DontCare should work on left or right side in BiDirectional connections
- call bind() to set DontCare binding instead of messing with internal variables
- DontCares are only equivalent with DontCares
- clean up processWhens() definition

* Eliminate DontCare connection to inputs in MonoConnect().

* Pull aggregates apart for the purpose of DontCare connections.

* Restore the explicit (conditionally executed) ports DefInvalidin ImplicitModule()

* Don't add DontCare's to the module list of _ids.

* Add missing DefInvalid() to LegacyModule().

* Respond to review requests: add DontCare BiConnect Vec, remove null parent hack to avoid addId(), initialize singletons early in Builder

* Move DontCare out of chisel3.experimental.

1 files changed, 33 insertions, 4 deletions

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Data.scala b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
index aa286e0d..db99d6b3 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Data.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Data.scala
@@ -8,6 +8,7 @@ import chisel3.internal._
 import chisel3.internal.Builder.{pushCommand, pushOp}
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo._
+import chisel3.core.BiConnect.DontCareCantBeSink
 
 /** User-specified directions.
   */
@@ -33,8 +34,8 @@ object SpecifiedDirection {
     case Input => Output
   }
 
-  /** Returns the effective UserDirection of this node given the parent's effective UserDirection
-    * and the user-specified UserDirection of this node.
+  /** Returns the effective SpecifiedDirection of this node given the parent's effective SpecifiedDirection
+    * and the user-specified SpecifiedDirection of this node.
     */
   def fromParent(parentDirection: SpecifiedDirection, thisDirection: SpecifiedDirection) =
     (parentDirection, thisDirection) match {
@@ -222,7 +223,7 @@ abstract class Data extends HasId {
     _specifiedDirection = direction
   }
 
-  /** This overwrites a relative UserDirection with an explicit one, and is used to implement
+  /** This overwrites a relative SpecifiedDirection with an explicit one, and is used to implement
     * the compatibility layer where, at the elements, Flip is Input and unspecified is Output.
     * DO NOT USE OUTSIDE THIS PURPOSE. THIS OPERATION IS DANGEROUS!
     */
@@ -311,6 +312,8 @@ abstract class Data extends HasId {
       requireIsHardware(that, s"data to be bulk-connected")
       (this.topBinding, that.topBinding) match {
         case (_: ReadOnlyBinding, _: ReadOnlyBinding) => throwException(s"Both $this and $that are read-only")
+        // DontCare cannot be a sink (LHS)
+        case (_: DontCareBinding, _) => throw DontCareCantBeSink
         case _ =>  // fine
       }
       try {
@@ -425,7 +428,9 @@ trait WireFactory {
     x.bind(WireBinding(Builder.forcedUserModule))
 
     pushCommand(DefWire(sourceInfo, x))
-    pushCommand(DefInvalid(sourceInfo, x.ref))
+    if (!compileOptions.explicitInvalidate) {
+      pushCommand(DefInvalid(sourceInfo, x.ref))
+    }
 
     x
   }
@@ -454,3 +459,27 @@ object WireInit {
     x
   }
 }
+
+/** RHS (source) for Invalidate API.
+  * Causes connection logic to emit a DefInvalid when connected to an output port (or wire).
+  */
+object DontCare extends Element(width = UnknownWidth()) {
+  // This object should be initialized before we execute any user code that refers to it,
+  //  otherwise this "Chisel" object will end up on the UserModule's id list.
+
+  bind(DontCareBinding(), SpecifiedDirection.Output)
+  override def cloneType = DontCare
+
+  def toPrintable: Printable = PString("DONTCARE")
+
+  private[core] def connectFromBits(that: chisel3.core.Bits)(implicit sourceInfo:  SourceInfo, compileOptions: CompileOptions): Unit = {
+    Builder.error("connectFromBits: DontCare cannot be a connection sink (LHS)")
+  }
+
+  def do_asUInt(implicit sourceInfo: chisel3.internal.sourceinfo.SourceInfo, compileOptions: CompileOptions): chisel3.core.UInt = {
+    Builder.error("DontCare does not have a UInt representation")
+    0.U
+  }
+  // DontCare's only match themselves.
+  private[core] def typeEquivalent(that: chisel3.core.Data): Boolean = that == DontCare
+}