Add Analog type

Used for stitching Verilog inout through Chisel Modules (from BlackBox
to BlackBox)

4 files changed, 126 insertions, 1 deletions

diff --git a/chiselFrontend/src/main/scala/chisel3/core/Attach.scala b/chiselFrontend/src/main/scala/chisel3/core/Attach.scala
new file mode 100644
index 00000000..5e767b84
--- /dev/null
+++ b/chiselFrontend/src/main/scala/chisel3/core/Attach.scala
@@ -0,0 +1,45 @@
+// See LICENSE for license details.
+
+package chisel3.core
+
+import chisel3.internal._
+import chisel3.internal.Builder.pushCommand
+import chisel3.internal.firrtl._
+import chisel3.internal.sourceinfo.{SourceInfo}
+
+object attach {  // scalastyle:ignore object.name
+  // Exceptions that can be generated by attach
+  case class AttachException(message: String) extends Exception(message)
+  def ConditionalAttachException =
+    AttachException(": Conditional attach is not allowed!")
+
+  // Actual implementation
+  private[core] def impl(elts: Seq[Analog], contextModule: Module)(implicit sourceInfo: SourceInfo): Unit = {
+    if (Builder.whenDepth != 0) throw ConditionalAttachException
+
+    // TODO Check that references are valid and can be attached
+
+    pushCommand(Attach(sourceInfo, elts.map(_.lref)))
+  }
+
+  /** Create an electrical connection between [[Analog]] components
+    *
+    * @param elts The components to attach
+    *
+    * @example
+    * {{{
+    * val a1 = Wire(Analog(32.W))
+    * val a2 = Wire(Analog(32.W))
+    * attach(a1, a2)
+    * }}}
+    */
+  def apply(elts: Analog*)(implicit sourceInfo: SourceInfo): Unit = {
+    try {
+      impl(elts, Builder.forcedModule)
+    } catch {
+      case AttachException(message) =>
+        throwException(elts.mkString("Attaching (", ", ", s") failed @$message"))
+    }
+  }
+}
+
diff --git a/chiselFrontend/src/main/scala/chisel3/core/BiConnect.scala b/chiselFrontend/src/main/scala/chisel3/core/BiConnect.scala
index b17239e7..825dbad7 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/BiConnect.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/BiConnect.scala
@@ -2,8 +2,10 @@
 
 package chisel3.core
 
+import chisel3.internal.Builder
 import chisel3.internal.Builder.pushCommand
-import chisel3.internal.firrtl.Connect
+import chisel3.internal.firrtl.{Attach, Connect}
+import chisel3.internal.throwException
 import scala.language.experimental.macros
 import chisel3.internal.sourceinfo._
 
@@ -42,6 +44,9 @@ object BiConnect {
     BiConnectException(s": Right Record missing field ($field).")
   def MismatchedException(left: String, right: String) =
     BiConnectException(s": Left ($left) and Right ($right) have different types.")
+  def AttachAlreadyBulkConnectedException(sourceInfo: SourceInfo) =
+    BiConnectException(sourceInfo.makeMessage(": Analog previously bulk connected at " + _))
+
 
   /** This function is what recursively tries to connect a left and right together
   *
@@ -52,6 +57,13 @@ object BiConnect {
   def connect(sourceInfo: SourceInfo, connectCompileOptions: CompileOptions, left: Data, right: Data, context_mod: Module): Unit =
     (left, right) match {
       // Handle element case (root case)
+      case (left_a: Analog, right_a: Analog) =>
+        try {
+          analogAttach(sourceInfo, left_a, right_a, context_mod)
+        } catch {
+          // If attach fails, convert to BiConnectException
+          case attach.AttachException(message) => throw BiConnectException(message)
+        }
       case (left_e: Element, right_e: Element) => {
         elemConnect(sourceInfo, connectCompileOptions, left_e, right_e, context_mod)
         // TODO(twigg): Verify the element-level classes are connectable
@@ -235,4 +247,22 @@ object BiConnect {
     // so just error out
     else throw UnknownRelationException
   }
+
+  // This function checks if analog element-level attaching is allowed
+  // Then it either issues it or throws the appropriate exception.
+  def analogAttach(implicit sourceInfo: SourceInfo, left: Analog, right: Analog, contextModule: Module): Unit = {
+    // Error if left or right is BICONNECTED in the current module already
+    for (elt <- left :: right :: Nil) {
+      elt.biConnectLocs.get(contextModule) match {
+        case Some(sl) => throw AttachAlreadyBulkConnectedException(sl)
+        case None => // Do nothing
+      }
+    }
+
+    // Do the attachment
+    attach.impl(Seq(left, right), contextModule)
+    // Mark bulk connected
+    left.biConnectLocs(contextModule) = sourceInfo
+    right.biConnectLocs(contextModule) = sourceInfo
+  }
 }
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
index 96ea137f..bf134771 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Bits.scala
@@ -3,6 +3,7 @@
 package chisel3.core
 
 import scala.language.experimental.macros
+import collection.mutable
 
 import chisel3.internal._
 import chisel3.internal.Builder.{pushCommand, pushOp}
@@ -1020,3 +1021,51 @@ object FixedPoint {
   }
 
 }
+
+/** Data type for representing bidirectional bitvectors of a given width
+  *
+  * Analog support is limited to allowing wiring up of Verilog BlackBoxes with bidirectional (inout)
+  * pins. There is currently no support for reading or writing of Analog types within Chisel code.
+  *
+  * Given that Analog is bidirectional, it is illegal to assign a direction to any Analog type. It
+  * is legal to "flip" the direction (since Analog can be a member of aggregate types) which has no
+  * effect.
+  *
+  * Analog types are generally connected using the bidirectional [[attach]] mechanism, but also
+  * support limited bulkconnect `<>`. Analog types are only allowed to be bulk connected *once* in a
+  * given module. This is to prevent any surprising consequences of last connect semantics.
+  *
+  * @note This API is experimental and subject to change
+  */
+final class Analog private (width: Width) extends Element(width) {
+  require(width.known, "Since Analog is only for use in BlackBoxes, width must be known")
+
+  // Used to enforce single bulk connect of Analog types, multi-attach is still okay
+  // Note that this really means 1 bulk connect per Module because a port can
+  //   be connected in the parent module as well
+  private[core] val biConnectLocs = mutable.Map.empty[Module, SourceInfo]
+
+  // Define setter/getter pairing
+  // Analog can only be bound to Ports and Wires (and Unbound)
+  private[core] override def binding_=(target: Binding): Unit = target match {
+    case (_: UnboundBinding | _: WireBinding | PortBinding(_, None)) => super.binding_=(target)
+    case _ => throwException("Only Wires and Ports can be of type Analog")
+  }
+  private[core] override def cloneTypeWidth(w: Width): this.type =
+    new Analog(w).asInstanceOf[this.type]
+  private[chisel3] def toType = s"Analog$width"
+  def cloneType: this.type = cloneTypeWidth(width)
+  // What do flatten and fromBits mean?
+  private[chisel3] def flatten: IndexedSeq[Bits] =
+    throwException("Chisel Internal Error: Analog cannot be flattened into Bits")
+  def do_fromBits(that: Bits)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): this.type =
+    throwException("Analog does not support fromBits")
+  final def toPrintable: Printable = PString("Analog")
+}
+/** Object that provides factory methods for [[Analog]] objects
+  *
+  * @note This API is experimental and subject to change
+  */
+object Analog {
+  def apply(width: Width): Analog = new Analog(width)
+}
diff --git a/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala b/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
index 50400034..bee72817 100644
--- a/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
+++ b/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
@@ -263,6 +263,7 @@ case class WhenBegin(sourceInfo: SourceInfo, pred: Arg) extends Command
 case class WhenEnd(sourceInfo: SourceInfo) extends Command
 case class Connect(sourceInfo: SourceInfo, loc: Node, exp: Arg) extends Command
 case class BulkConnect(sourceInfo: SourceInfo, loc1: Node, loc2: Node) extends Command
+case class Attach(sourceInfo: SourceInfo, locs: Seq[Node]) extends Command
 case class ConnectInit(sourceInfo: SourceInfo, loc: Node, exp: Arg) extends Command
 case class Stop(sourceInfo: SourceInfo, clock: Arg, ret: Int) extends Command
 case class Port(id: Data, dir: Direction)