Merge branch '1.3.x' into 1.3-release

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,14 +1,16 @@
 ### Contributor Checklist
 
 - [ ] Did you add Scaladoc to every public function/method?
+- [ ] Did you update the FIRRTL spec to include every new feature/behavior?
 - [ ] Did you add at least one test demonstrating the PR?
 - [ ] Did you delete any extraneous printlns/debugging code?
 - [ ] Did you specify the type of improvement?
 - [ ] Did you state the API impact?
 - [ ] Did you specify the code generation impact?
 - [ ] Did you request a desired merge strategy?
+- [ ] Did you add text to be included in the Release Notes for this change?
 
-### Type of Improvement
+#### Type of Improvement
 
 <!-- Choose one or more from the following: -->
 <!--   - bug fix                            -->
@@ -19,24 +21,30 @@
 <!--   - backend code generation            -->
 <!--   - new feature/API                    -->
 
-### API Impact
+#### API Impact
 
 <!-- How would this affect the current API? Does this add, extend, deprecate, remove, or break any existing API? -->
 
-### Backend Code Generation Impact
+#### Backend Code Generation Impact
 
 <!-- Does this change any generated Verilog?  -->
 <!-- How does it change it or in what circumstances would it?  -->
 
-### Desired Merge Strategy
+#### Desired Merge Strategy
 
 <!-- If approved, how should this PR be merged? -->
 <!-- Options are: -->
 <!--   - Squash: The PR will be squashed and merged (choose this if you have no preference. -->
 <!--   - Rebase: You will rebase the PR onto master and it will be merged with a merge commit. -->
 
+#### Release Notes
+<!--
+Text from here to the end of the body will be considered for inclusion in the release notes for the version containing this pull request.
+-->
+
 ### Reviewer Checklist (only modified by reviewer)
 - [ ] Did you add the appropriate labels?
 - [ ] Did you mark the proper milestone (1.2.x, 1.3.0, 1.4.0) ?
 - [ ] Did you review?
+- [ ] Did you check whether all relevant Contributor checkboxes have been checked?
 - [ ] Did you mark as `Please Merge`?

.travis.yml

@@ -42,6 +42,10 @@ jobs:
         - verilator --version
         - bash .install_yosys.sh
         - yosys -V
+    - stage: test
+      name: "Unidoc builds (no warnings)"
+      script:
+        - sbt $SBT_ARGS unidoc
     - stage: test
       name: "Tests: FIRRTL (2.12)"
       script:

build.sbt

@@ -39,6 +39,9 @@ lazy val commonSettings = Seq(
   scalacOptions := scalacOptionsVersion(scalaVersion.value) ++ Seq(
     "-deprecation",
     "-unchecked",
+    "-language:reflectiveCalls",
+    "-language:existentials",
+    "-language:implicitConversions",
     "-Yrangepos",          // required by SemanticDB compiler plugin
     "-Ywarn-unused-import" // required by `RemoveUnused` rule
   ),
@@ -129,22 +132,24 @@ lazy val publishSettings = Seq(
   }
 )
 
+
+def scalacDocOptionsVersion(scalaVersion: String): Seq[String] = {
+  Seq() ++ {
+    // If we're building with Scala > 2.11, enable the compile option
+    //  to flag warnings as errors. This must be disabled for 2.11 since
+    //  references to the Java class library from Java 9 on generate warnings.
+    //  https://github.com/scala/bug/issues/10675
+    CrossVersion.partialVersion(scalaVersion) match {
+      case Some((2, scalaMajor: Long)) if scalaMajor < 12 => Seq()
+      case _ => Seq("-Xfatal-warnings")
+    }
+  }
+}
 lazy val docSettings = Seq(
   doc in Compile := (doc in ScalaUnidoc).value,
   autoAPIMappings := true,
-  apiMappings ++= {
-    Option(System.getProperty("sun.boot.class.path")).flatMap { classPath =>
-      classPath.split(java.io.File.pathSeparator).find(_.endsWith(java.io.File.separator + "rt.jar"))
-    }.map { jarPath =>
-      Map(
-        file(jarPath) -> url("https://docs.oracle.com/javase/8/docs/api")
-      )
-    }.getOrElse {
-      streams.value.log.warn("Failed to add bootstrap class path of Java to apiMappings")
-      Map.empty[File,URL]
-    }
-  },
   scalacOptions in Compile in doc ++= Seq(
+    "-feature",
     "-diagrams",
     "-diagrams-max-classes", "25",
     "-doc-version", version.value,
@@ -161,7 +166,7 @@ lazy val docSettings = Seq(
         }
       s"https://github.com/freechipsproject/firrtl/tree/$branch€{FILE_PATH}.scala"
     }
-  ) ++ scalacOptionsVersion(scalaVersion.value)
+  ) ++ scalacOptionsVersion(scalaVersion.value) ++ scalacDocOptionsVersion(scalaVersion.value)
 )
 
 lazy val firrtl = (project in file("."))

project/plugins.sbt

@@ -22,4 +22,6 @@ addSbtPlugin("com.github.gseitz" % "sbt-protobuf" % "0.6.5")
 
 addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.9.12")
 
+addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "3.0.0")
+
 libraryDependencies += "com.github.os72" % "protoc-jar" % "3.11.1"

src/main/scala/firrtl/Utils.scala

@@ -522,11 +522,6 @@ object Utils extends LazyLogging {
     case SourceFlow => Input
     case SinkFlow => Output
   }
-  @deprecated("Migrate from 'Gender' to 'Flow. This method will be removed in 1.3", "1.2")
-  def to_gender(d: Direction): Gender = d match {
-    case Input => MALE
-    case Output => FEMALE
-  }
   def to_flow(d: Direction): Flow = d match {
     case Input => SourceFlow
     case Output => SinkFlow
@@ -583,38 +578,6 @@ object Utils extends LazyLogging {
     case ex: WSubAccess => kind(ex.expr)
     case ex => ExpKind
   }
-  @deprecated("Migrate from 'Gender' to 'Flow'. This method will be removed in 1.3", "1.2")
-  def gender(e: Expression): Gender = e match {
-    case ex: WRef => ex.gender
-    case ex: WSubField => ex.gender
-    case ex: WSubIndex => ex.gender
-    case ex: WSubAccess => ex.gender
-    case ex: DoPrim => MALE
-    case ex: UIntLiteral => MALE
-    case ex: SIntLiteral => MALE
-    case ex: Mux => MALE
-    case ex: ValidIf => MALE
-    case WInvalid => MALE
-    case ex => throwInternalError(s"gender: shouldn't be here - $e")
-  }
-  @deprecated("Migrate from 'Gender' to 'Flow'. This method will be removed in 1.3", "1.2")
-  def get_gender(s: Statement): Gender = s match {
-    case sx: DefWire => BIGENDER
-    case sx: DefRegister => BIGENDER
-    case sx: WDefInstance => MALE
-    case sx: DefNode => MALE
-    case sx: DefInstance => MALE
-    case sx: DefMemory => MALE
-    case sx: Block => UNKNOWNGENDER
-    case sx: Connect => UNKNOWNGENDER
-    case sx: PartialConnect => UNKNOWNGENDER
-    case sx: Stop => UNKNOWNGENDER
-    case sx: Print => UNKNOWNGENDER
-    case sx: IsInvalid => UNKNOWNGENDER
-    case EmptyStmt => UNKNOWNGENDER
-  }
-  @deprecated("Migrate from 'Gender' to 'Flow'. This method will be removed in 1.3", "1.2")
-  def get_gender(p: Port): Gender = if (p.direction == Input) MALE else FEMALE
   def flow(e: Expression): Flow = e match {
     case ex: WRef => ex.flow
     case ex: WSubField => ex.flow

src/main/scala/firrtl/WIR.scala

@@ -26,18 +26,7 @@ case object SinkFlow extends Flow
 case object DuplexFlow extends Flow
 case object UnknownFlow extends Flow
 
-private[firrtl] trait GenderFromFlow { this: Expression =>
-  val flow: Flow
-  @deprecated("Migrate from 'Gender' to 'Flow'. This method will be removed in 1.3.", "1.2")
-  def gender: Gender = flow match {
-    case SourceFlow  => MALE
-    case SinkFlow    => FEMALE
-    case DuplexFlow  => BIGENDER
-    case UnknownFlow => UNKNOWNGENDER
-  }
-}
-
-case class WRef(name: String, tpe: Type, kind: Kind, flow: Flow) extends Expression with GenderFromFlow {
+case class WRef(name: String, tpe: Type, kind: Kind, flow: Flow) extends Expression {
   def serialize: String = name
   def mapExpr(f: Expression => Expression): Expression = this
   def mapType(f: Type => Type): Expression = this.copy(tpe = f(tpe))
@@ -62,7 +51,7 @@ object WRef {
   /** Creates a WRef from an arbitrary string name */
   def apply(n: String, t: Type = UnknownType, k: Kind = ExpKind): WRef = new WRef(n, t, k, UnknownFlow)
 }
-case class WSubField(expr: Expression, name: String, tpe: Type, flow: Flow) extends Expression with GenderFromFlow {
+case class WSubField(expr: Expression, name: String, tpe: Type, flow: Flow) extends Expression {
   def serialize: String = s"${expr.serialize}.$name"
   def mapExpr(f: Expression => Expression): Expression = this.copy(expr = f(expr))
   def mapType(f: Type => Type): Expression = this.copy(tpe = f(tpe))
@@ -75,7 +64,7 @@ object WSubField {
   def apply(expr: Expression, n: String): WSubField = new WSubField(expr, n, field_type(expr.tpe, n), UnknownFlow)
   def apply(expr: Expression, name: String, tpe: Type): WSubField = new WSubField(expr, name, tpe, UnknownFlow)
 }
-case class WSubIndex(expr: Expression, value: Int, tpe: Type, flow: Flow) extends Expression with GenderFromFlow {
+case class WSubIndex(expr: Expression, value: Int, tpe: Type, flow: Flow) extends Expression {
   def serialize: String = s"${expr.serialize}[$value]"
   def mapExpr(f: Expression => Expression): Expression = this.copy(expr = f(expr))
   def mapType(f: Type => Type): Expression = this.copy(tpe = f(tpe))
@@ -84,7 +73,7 @@ case class WSubIndex(expr: Expression, value: Int, tpe: Type, flow: Flow) extend
   def foreachType(f: Type => Unit): Unit = f(tpe)
   def foreachWidth(f: Width => Unit): Unit = Unit
 }
-case class WSubAccess(expr: Expression, index: Expression, tpe: Type, flow: Flow) extends Expression with GenderFromFlow {
+case class WSubAccess(expr: Expression, index: Expression, tpe: Type, flow: Flow) extends Expression {
   def serialize: String = s"${expr.serialize}[${index.serialize}]"
   def mapExpr(f: Expression => Expression): Expression = this.copy(expr = f(expr), index = f(index))
   def mapType(f: Type => Type): Expression = this.copy(tpe = f(tpe))

src/main/scala/firrtl/package.scala

@@ -15,27 +15,4 @@ package object firrtl {
 
   @deprecated("Use firrtl.stage.TargetDirAnnotation", "1.2")
   val TargetDirAnnotation = firrtl.options.TargetDirAnnotation
-
-  @deprecated("Use Flow instead of Gender. This trait will be removed in 1.3", "1.2")
-  trait Gender
-
-  @deprecated("Use SourceFlow instead of MALE. This case object will be removed in 1.3", "1.2")
-  case object MALE extends Gender
-
-  @deprecated("Use SinkFlow instead of FEMALE. This case object will be removed in 1.3", "1.2")
-  case object FEMALE extends Gender
-
-  @deprecated("Use DuplexFlow instead of BIGENDER. This case object will be removed in 1.3", "1.2")
-  case object BIGENDER extends Gender
-
-  @deprecated("Use UnknownFlow instead of UNKNOWNGENDER. This case object will be removed in 1.3", "1.2")
-  case object UNKNOWNGENDER extends Gender
-
-  @deprecated("Please migrate from 'Gender' to 'Flow'. This implicit conversion will be removed in 1.3", "1.2")
-  implicit def genderToFlow(gender: Gender): Flow = gender match {
-    case MALE          => SourceFlow
-    case FEMALE        => SinkFlow
-    case BIGENDER      => DuplexFlow
-    case UNKNOWNGENDER => UnknownFlow
-  }
 }

src/main/scala/firrtl/passes/Checks.scala

@@ -731,19 +731,3 @@ object CheckFlows extends Pass with PreservesAll[Transform] {
   }
 }
 
-@deprecated("Use 'CheckFlows'. This object will be removed in 1.3", "1.2")
-object CheckGenders {
-
-  implicit def toStr(g: Gender): String = g match {
-    case MALE => "source"
-    case FEMALE => "sink"
-    case UNKNOWNGENDER => "unknown"
-    case BIGENDER => "sourceOrSink"
-  }
-
-  def run(c: Circuit): Circuit = CheckFlows.run(c)
-
-  @deprecated("Use 'CheckFlows.WrongFlow'. This class will be removed in 1.3", "1.2")
-  class WrongGender(info:Info, mname: String, expr: String, wrong: Flow, right: Flow) extends PassException(
-    s"$info: [module $mname]  Expression $expr is used as a $wrong but can only be used as a $right.")
-}

src/main/scala/firrtl/passes/RemoveAccesses.scala

@@ -18,6 +18,7 @@ object RemoveAccesses extends Pass {
 
   override val prerequisites =
     Seq( Dependency(PullMuxes),
+         Dependency(ZeroLengthVecs),
          Dependency(ReplaceAccesses),
          Dependency(ExpandConnects) ) ++ firrtl.stage.Forms.Deduped
 

src/main/scala/firrtl/passes/RemoveIntervals.scala

@@ -173,7 +173,7 @@ class RemoveIntervals extends Pass with PreservesAll[Transform] {
     case DefNode(info, name, value) => value.tpe match {
       case IntervalType(l, u, p) =>
         val newType = IntervalType(l, u, p)
-        Block(Seq(DefWire(info, name, newType), Connect(info, WRef(name, newType, WireKind, FEMALE), value)))
+        Block(Seq(DefWire(info, name, newType), Connect(info, WRef(name, newType, WireKind, SinkFlow), value)))
       case other => s
     }
     case other => other map makeWireStmt

src/main/scala/firrtl/passes/Resolves.scala

@@ -88,17 +88,6 @@ object ResolveFlows extends Pass with PreservesAll[Transform] {
     c copy (modules = c.modules map resolve_flow)
 }
 
-@deprecated("Use 'ResolveFlows'. This will be removed in 1.3", "1.2")
-object ResolveGenders extends Pass {
-
-  def run(c: Circuit): Circuit = ResolveFlows.run(c)
-
-  def resolve_e(g: Gender)(e: Expression): Expression = ResolveFlows.resolve_e(g)(e)
-
-  def resolve_s(s: Statement): Statement = ResolveFlows.resolve_s(s)
-
-}
-
 object CInferMDir extends Pass with PreservesAll[Transform] {
 
   override val prerequisites = firrtl.stage.Forms.ChirrtlForm :+ Dependency(CInferTypes)

src/main/scala/firrtl/passes/ZeroLengthVecs.scala

@@ -0,0 +1,69 @@
+// See LICENSE for license details.
+
+package firrtl.passes
+
+import firrtl._
+import firrtl.ir._
+import firrtl.Mappers._
+import firrtl.PrimOps._
+import firrtl.options.{Dependency, PreservesAll}
+
+/** Handles dynamic accesses to zero-length vectors.
+  *
+  * @note Removes assignments that use a zero-length vector as a sink
+  * @note Removes signals resulting from accesses to a zero-length vector from attach groups
+  * @note Removes attaches that become degenerate after zero-length-accessor removal
+  * @note Replaces "source" references to elements of zero-length vectors with always-invalid validif
+  */
+object ZeroLengthVecs extends Pass with PreservesAll[Transform] {
+  override val prerequisites =
+    Seq( Dependency(PullMuxes),
+         Dependency(ResolveKinds),
+         Dependency(InferTypes),
+         Dependency(ExpandConnects) )
+
+  // Pass in an expression, not just a type, since it's not possible to generate an expression of
+  // interval type with the type alone unless you declare a component
+  private def replaceWithDontCare(toReplace: Expression): Expression = {
+    val default = toReplace.tpe match {
+      case UIntType(w) => UIntLiteral(0, w)
+      case SIntType(w) => SIntLiteral(0, w)
+      case FixedType(w, p) => FixedLiteral(0, w, p)
+      case it: IntervalType =>
+        val zeroType = IntervalType(Closed(0), Closed(0), IntWidth(0))
+        val zeroLit = DoPrim(AsInterval, Seq(SIntLiteral(0)), Seq(0, 0, 0), zeroType)
+        DoPrim(Clip, Seq(zeroLit, toReplace), Nil, it)
+    }
+    ValidIf(UIntLiteral(0), default, toReplace.tpe)
+  }
+
+  private def zeroLenDerivedRefLike(expr: Expression): Boolean = (expr, expr.tpe) match {
+    case (_, VectorType(_, 0)) => true
+    case (WSubIndex(e, _, _, _), _) => zeroLenDerivedRefLike(e)
+    case (WSubAccess(e, _, _, _), _) => zeroLenDerivedRefLike(e)
+    case (WSubField(e, _, _, _), _) => zeroLenDerivedRefLike(e)
+    case _ => false
+  }
+
+  // The connects have all been lowered, so all aggregate-typed expressions are "grounded" by WSubField/WSubAccess/WSubIndex
+  // Map before matching because we want don't-cares to propagate UP expression trees
+  private def dropZeroLenSubAccesses(expr: Expression): Expression = expr match {
+    case _: WSubIndex | _: WSubAccess | _: WSubField =>
+      if (zeroLenDerivedRefLike(expr)) replaceWithDontCare(expr) else expr
+    case e => e map dropZeroLenSubAccesses
+  }
+
+  // Attach semantics: drop all zero-length-derived members of attach group, drop stmt if trivial
+  private def onStmt(stmt: Statement): Statement = stmt match {
+    case Connect(_, sink, _) if zeroLenDerivedRefLike(sink) => EmptyStmt
+    case IsInvalid(_, sink) if zeroLenDerivedRefLike(sink) => EmptyStmt
+    case Attach(info, sinks) =>
+      val filtered = Attach(info, sinks.filterNot(zeroLenDerivedRefLike))
+      if (filtered.exprs.length < 2) EmptyStmt else filtered
+    case s => s.map(onStmt).map(dropZeroLenSubAccesses)
+  }
+
+  override def run(c: Circuit): Circuit = {
+    c.copy(modules = c.modules.map(m => m.map(onStmt)))
+  }
+}

src/main/scala/firrtl/stage/Forms.scala

@@ -51,6 +51,7 @@ object Forms {
          Dependency(passes.ReplaceAccesses),
          Dependency(passes.ExpandConnects),
          Dependency(passes.RemoveAccesses),
+         Dependency(passes.ZeroLengthVecs),
          Dependency[passes.ExpandWhensAndCheck],
          Dependency[passes.RemoveIntervals],
          Dependency(passes.ConvertFixedToSInt),

src/main/scala/firrtl/transforms/Flatten.scala

@@ -47,7 +47,7 @@ class Flatten extends Transform {
     *  @return modified circuit and ModuleNames to inline
     */
    def duplicateSubCircuitsFromAnno(c: Circuit, mods: Set[ModuleName], insts: Set[ComponentName]): (Circuit, Set[ModuleName]) = {
-     val modMap = c.modules.map(m => m.name->m) toMap
+     val modMap = c.modules.map(m => m.name->m).toMap
      val seedMods = mutable.Map.empty[String, String]
      val newModDefs = mutable.Set.empty[DefModule]
      val nsp = Namespace(c)