Bundle Literals Framework

chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala

@@ -62,6 +62,12 @@ sealed abstract class Aggregate extends Data {
     }
   }
 
+  override def litOption = ???  // TODO implement me
+
+  // Returns the LitArg of a Bits object.
+  // Internal API for Bundle literals, to copy the LitArg of argument literals into the top map.
+  protected def litArgOfBits(elt: Bits): LitArg = elt.litArgOption.get
+
   /** Returns a Seq of the immediate contents of this Aggregate, in order.
     */
   def getElements: Seq[Data]
@@ -736,7 +742,7 @@ abstract class Bundle(implicit compileOptions: CompileOptions) extends Record {
     // (which could lead to data conflicts, since it's likely the user didn't know to re-bind them).
     // This is not guaranteed to catch all cases (for example, Data in Tuples or Iterables).
     val boundDataParamNames = ctorParamsNameVals.collect {
-      case (paramName, paramVal: Data) if paramVal.hasBinding => paramName
+      case (paramName, paramVal: Data) if paramVal.topBindingOpt.isDefined => paramName
     }
     if (boundDataParamNames.nonEmpty) {
       autoClonetypeError(s"constructor parameters (${boundDataParamNames.sorted.mkString(", ")}) have values that are hardware types, which is likely to cause subtle errors." +

chiselFrontend/src/main/scala/chisel3/core/Assert.scala

@@ -60,7 +60,7 @@ object assert { // scalastyle:ignore object.name
         case None => s"Assertion failed\n    at $escLine\n"
       }
       printf.printfWithoutReset(fmt, data:_*)
-      pushCommand(Stop(sourceInfo, Node(Builder.forcedClock), 1))
+      pushCommand(Stop(sourceInfo, Builder.forcedClock.ref, 1))
     }
   }
 
@@ -81,7 +81,7 @@ object stop { // scalastyle:ignore object.name
   /** Terminate execution with a failure code. */
   def apply(code: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Unit = {
     when (!Module.reset.toBool) {
-      pushCommand(Stop(sourceInfo, Node(Builder.forcedClock), code))
+      pushCommand(Stop(sourceInfo, Builder.forcedClock.ref, code))
     }
   }
 

chiselFrontend/src/main/scala/chisel3/core/BiConnect.scala

@@ -186,7 +186,7 @@ object BiConnect {
     // Source and sink are ambiguous in the case of a Bi/Bulk Connect (<>).
     // If either is a DontCareBinding, just issue a DefInvalid for the other,
     //  otherwise, issue a Connect.
-    (left.binding, right.binding) match {
+    (left.topBinding, right.topBinding) match {
       case (lb: DontCareBinding, _) => pushCommand(DefInvalid(sourceInfo, right.lref))
       case (_, rb: DontCareBinding) => pushCommand(DefInvalid(sourceInfo, left.lref))
       case (_, _) => pushCommand(Connect(sourceInfo, right.lref, left.ref))
@@ -197,7 +197,7 @@ object BiConnect {
     // Source and sink are ambiguous in the case of a Bi/Bulk Connect (<>).
     // If either is a DontCareBinding, just issue a DefInvalid for the other,
     //  otherwise, issue a Connect.
-    (left.binding, right.binding) match {
+    (left.topBinding, right.topBinding) match {
       case (lb: DontCareBinding, _) => pushCommand(DefInvalid(sourceInfo, right.lref))
       case (_, rb: DontCareBinding) => pushCommand(DefInvalid(sourceInfo, left.lref))
       case (_, _) => pushCommand(Connect(sourceInfo, left.lref, right.ref))

chiselFrontend/src/main/scala/chisel3/core/Binding.scala

@@ -1,6 +1,7 @@
 package chisel3.core
 
 import chisel3.internal.Builder.{forcedModule}
+import chisel3.internal.firrtl.LitArg
 
 object Binding {
   class BindingException(message: String) extends Exception(message)
@@ -26,7 +27,7 @@ object requireIsHardware {
       case Some(x: BaseModule) => x._compatAutoWrapPorts
       case _ =>
     }
-    if (!node.hasBinding) {
+    if (!node.topBindingOpt.isDefined) {
       val prefix = if (msg.nonEmpty) s"$msg " else ""
       throw Binding.ExpectedHardwareException(s"$prefix'$node' must be hardware, " +
         "not a bare Chisel type. Perhaps you forgot to wrap it in Wire(_) or IO(_)?")
@@ -37,7 +38,7 @@ object requireIsHardware {
 /** Requires that a node is a chisel type (not hardware, "unbound")
   */
 object requireIsChiselType {
-  def apply(node: Data, msg: String = "") = if (node.hasBinding) {
+  def apply(node: Data, msg: String = "") = if (node.topBindingOpt.isDefined) {
     val prefix = if (msg.nonEmpty) s"$msg " else ""
     throw Binding.ExpectedChiselTypeException(s"$prefix'$node' must be a Chisel type, not hardware")
   }
@@ -92,8 +93,6 @@ sealed trait ConstrainedBinding extends TopBinding {
 // A binding representing a data that cannot be (re)assigned to.
 sealed trait ReadOnlyBinding extends TopBinding
 
-// TODO literal info here
-case class LitBinding() extends UnconstrainedBinding with ReadOnlyBinding
 // TODO(twigg): Ops between unenclosed nodes can also be unenclosed
 // However, Chisel currently binds all op results to a module
 case class OpBinding(enclosure: UserModule) extends ConstrainedBinding with ReadOnlyBinding
@@ -103,8 +102,14 @@ case class RegBinding(enclosure: UserModule) extends ConstrainedBinding
 case class WireBinding(enclosure: UserModule) extends ConstrainedBinding
 
 case class ChildBinding(parent: Data) extends Binding {
-  def location = parent.binding.location
+  def location = parent.topBinding.location
 }
 // A DontCare element has a specific Binding, somewhat like a literal.
 // It is a source (RHS). It may only be connected/applied to sinks.
 case class DontCareBinding() extends UnconstrainedBinding
+
+sealed trait LitBinding extends UnconstrainedBinding with ReadOnlyBinding
+// Literal binding attached to a element that is not part of a Bundle.
+case class ElementLitBinding(litArg: LitArg) extends LitBinding
+// Literal binding attached to the root of a Bundle, containing literal values of its children.
+case class BundleLitBinding(litMap: Map[Data, LitArg]) extends LitBinding

chiselFrontend/src/main/scala/chisel3/core/Bits.scala

@@ -61,20 +61,44 @@ private[chisel3] sealed trait ToBoolable extends Element {
   * bitwise operations.
   */
 //scalastyle:off number.of.methods
-sealed abstract class Bits(width: Width, override val litArg: Option[LitArg])
+sealed abstract class Bits(width: Width)
     extends Element(width) with ToBoolable {
   // TODO: perhaps make this concrete?
   // Arguments for: self-checking code (can't do arithmetic on bits)
   // Arguments against: generates down to a FIRRTL UInt anyways
 
-  // If this is a literal, setRef so that we don't allocate a name
-  litArg.foreach(setRef)
-
   // Only used for in a few cases, hopefully to be removed
   private[core] def cloneTypeWidth(width: Width): this.type
 
   def cloneType: this.type = cloneTypeWidth(width)
 
+  private[core] override def topBindingOpt: Option[TopBinding] = super.topBindingOpt match {
+    // Translate Bundle lit bindings to Element lit bindings
+    case Some(BundleLitBinding(litMap)) => litMap.get(this) match {
+      case Some(litArg) => Some(ElementLitBinding(litArg))
+      case _ => Some(DontCareBinding())
+    }
+    case topBindingOpt => topBindingOpt
+  }
+
+  private[core] def litArgOption: Option[LitArg] = topBindingOpt match {
+    case Some(ElementLitBinding(litArg)) => Some(litArg)
+    case _ => None
+  }
+
+  override def litOption: Option[BigInt] = litArgOption.map(_.num)
+  private[core] def litIsForcedWidth: Option[Boolean] = litArgOption.map(_.forcedWidth)
+
+  // provide bits-specific literal handling functionality here
+  override private[chisel3] def ref: Arg = topBindingOpt match {
+    case Some(ElementLitBinding(litArg)) => litArg
+    case Some(BundleLitBinding(litMap)) => litMap.get(this) match {
+      case Some(litArg) => litArg
+      case _ => throwException(s"internal error: DontCare should be caught before getting ref")
+    }
+    case _ => super.ref
+  }
+
   final def tail(n: Int): UInt = macro SourceInfoTransform.nArg
   final def head(n: Int): UInt = macro SourceInfoTransform.nArg
 
@@ -106,13 +130,8 @@ sealed abstract class Bits(width: Width, override val litArg: Option[LitArg])
     if (x < 0) {
       Builder.error(s"Negative bit indices are illegal (got $x)")
     }
-    if (isLit()) {
-      (((litValue() >> x.toInt) & 1) == 1).asBool
-    } else {
-
-      requireIsHardware(this, "bits to be indexed")
-      pushOp(DefPrim(sourceInfo, Bool(), BitsExtractOp, this.ref, ILit(x), ILit(x)))
-    }
+    requireIsHardware(this, "bits to be indexed")
+    pushOp(DefPrim(sourceInfo, Bool(), BitsExtractOp, this.ref, ILit(x), ILit(x)))
   }
 
   /** Returns the specified bit on this wire as a [[Bool]], statically
@@ -150,12 +169,8 @@ sealed abstract class Bits(width: Width, override val litArg: Option[LitArg])
       Builder.error(s"Invalid bit range ($x,$y)")
     }
     val w = x - y + 1
-    if (isLit()) {
-      ((litValue >> y) & ((BigInt(1) << w) - 1)).asUInt(w.W)
-    } else {
-      requireIsHardware(this, "bits to be sliced")
-      pushOp(DefPrim(sourceInfo, UInt(Width(w)), BitsExtractOp, this.ref, ILit(x), ILit(y)))
-    }
+    requireIsHardware(this, "bits to be sliced")
+    pushOp(DefPrim(sourceInfo, UInt(Width(w)), BitsExtractOp, this.ref, ILit(x), ILit(y)))
   }
 
   // REVIEW TODO: again, is this necessary? Or just have this and use implicits?
@@ -295,7 +310,7 @@ sealed abstract class Bits(width: Width, override val litArg: Option[LitArg])
     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 = {
@@ -428,8 +443,7 @@ abstract trait Num[T <: Data] {
 /** A data type for unsigned integers, represented as a binary bitvector.
   * Defines arithmetic operations between other integer types.
   */
-sealed class UInt private[core] (width: Width, lit: Option[ULit] = None)
-    extends Bits(width, lit) with Num[UInt] {
+sealed class UInt private[core] (width: Width) extends Bits(width) with Num[UInt] {
 
   private[core] override def typeEquivalent(that: Data): Boolean =
     that.isInstanceOf[UInt] && this.width == that.width
@@ -576,9 +590,9 @@ trait UIntFactory {
    /** Create a UInt literal with specified width. */
   protected[chisel3] def Lit(value: BigInt, width: Width): UInt = {
     val lit = ULit(value, width)
-    val result = new UInt(lit.width, Some(lit))
+    val result = new UInt(lit.width)
     // Bind result to being an Literal
-    result.bind(LitBinding())
+    result.bind(ElementLitBinding(lit))
     result
   }
 
@@ -595,8 +609,7 @@ trait UIntFactory {
 object UInt extends UIntFactory
 object Bits extends UIntFactory
 
-sealed class SInt private[core] (width: Width, lit: Option[SLit] = None)
-    extends Bits(width, lit) with Num[SInt] {
+sealed class SInt private[core] (width: Width) extends Bits(width) with Num[SInt] {
 
   private[core] override def typeEquivalent(that: Data): Boolean =
     this.getClass == that.getClass && this.width == that.width  // TODO: should this be true for unspecified widths?
@@ -731,9 +744,8 @@ trait SIntFactory {
    /** Create an SInt literal with specified width. */
   protected[chisel3] def Lit(value: BigInt, width: Width): SInt = {
     val lit = SLit(value, width)
-    val result = new SInt(lit.width, Some(lit))
-    // Bind result to being an Literal
-    result.bind(LitBinding())
+    val result = new SInt(lit.width)
+    result.bind(ElementLitBinding(lit))
     result
   }
 }
@@ -746,12 +758,20 @@ sealed trait Reset extends Element with ToBoolable
 // operations on a Bool make sense?
 /** A data type for booleans, defined as a single bit indicating true or false.
   */
-sealed class Bool(lit: Option[ULit] = None) extends UInt(1.W, lit) with Reset {
+sealed class Bool() extends UInt(1.W) with Reset {
   private[core] override def cloneTypeWidth(w: Width): this.type = {
     require(!w.known || w.get == 1)
     new Bool().asInstanceOf[this.type]
   }
 
+  def litToBooleanOption: Option[Boolean] = litOption.map {
+    case intVal if intVal == 1 => true
+    case intVal if intVal == 0 => false
+    case intVal => throwException(s"Boolean with unexpected literal value $intVal")
+  }
+
+  def litToBoolean: Boolean = litToBooleanOption.get
+
   // REVIEW TODO: Why does this need to exist and have different conventions
   // than Bits?
   final def & (that: Bool): Bool = macro SourceInfoTransform.thatArg
@@ -795,9 +815,8 @@ trait BoolFactory {
   /** Creates Bool literal.
    */
   protected[chisel3] def Lit(x: Boolean): Bool = {
-    val result = new Bool(Some(ULit(if (x) 1 else 0, Width(1))))
-    // Bind result to being an Literal
-    result.bind(LitBinding())
+    val result = new Bool()
+    result.bind(ElementLitBinding(ULit(if (x) 1 else 0, Width(1))))
     result
   }
 }
@@ -817,8 +836,8 @@ object Bool extends BoolFactory
   *                    and thus use this field as a simple exponent
   * @param lit
   */
-sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint, lit: Option[FPLit] = None)
-    extends Bits(width, lit) with Num[FixedPoint] {
+sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint)
+    extends Bits(width) with Num[FixedPoint] {
   private[core] override def typeEquivalent(that: Data): Boolean = that match {
     case that: FixedPoint => this.width == that.width && this.binaryPoint == that.binaryPoint  // TODO: should this be true for unspecified widths?
     case _ => false
@@ -832,6 +851,13 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint, lit
     case _ => this badConnect that
   }
 
+  def litToDoubleOption: Option[Double] = litOption.map { intVal =>
+    val multiplier = math.pow(2, binaryPoint.get)
+    intVal.toDouble / multiplier
+  }
+
+  def litToDouble: Double = litToDoubleOption.get
+
   final def unary_- (): FixedPoint = macro SourceInfoTransform.noArg
   final def unary_-% (): FixedPoint = macro SourceInfoTransform.noArg
 
@@ -1047,8 +1073,8 @@ object FixedPoint {
   /** Create an FixedPoint port with specified width and binary position. */
   def apply(value: BigInt, width: Width, binaryPoint: BinaryPoint): FixedPoint = {
     val lit = FPLit(value, width, binaryPoint)
-    val newLiteral = new FixedPoint(lit.width, lit.binaryPoint, Some(lit))
-    newLiteral.bind(LitBinding())
+    val newLiteral = new FixedPoint(lit.width, lit.binaryPoint)
+    newLiteral.bind(ElementLitBinding(lit))
     newLiteral
   }
 
@@ -1099,6 +1125,8 @@ final class Analog private (width: Width) extends Element(width) {
   private[core] override def typeEquivalent(that: Data): Boolean =
     that.isInstanceOf[Analog] && this.width == that.width
 
+  override def litOption = None
+
   def cloneType: this.type = new Analog(width).asInstanceOf[this.type]
 
   // Used to enforce single bulk connect of Analog types, multi-attach is still okay

chiselFrontend/src/main/scala/chisel3/core/BlackBox.scala

@@ -70,7 +70,6 @@ abstract class ExtModule(val params: Map[String, Param] = Map.empty[String, Para
     // While BlackBoxes are not supposed to have an implementation, we still need to call
     // _onModuleClose on all nodes (for example, Aggregates use it for recursive naming).
     for (id <- getIds) {
-      id.forceName(default="_T", _namespace)
       id._onModuleClose
     }
 
@@ -155,7 +154,6 @@ abstract class BlackBox(val params: Map[String, Param] = Map.empty[String, Param
     // Doing so would cause the wrong names to be assigned, since their parent
     // is now the module itself instead of the io bundle.
     for (id <- getIds; if id ne io) {
-      id.forceName(default="_T", _namespace)
       id._onModuleClose
     }
 

chiselFrontend/src/main/scala/chisel3/core/Clock.scala

@@ -23,6 +23,8 @@ sealed class Clock extends Element(Width(1)) {
     case _ => super.badConnect(that)(sourceInfo)
   }
 
+  override def litOption = None
+
   /** Not really supported */
   def toPrintable: Printable = PString("CLOCK")