Merge branch '1.3.x' into 1.3-release

# Conflicts:
#	build.sbt

build.sbt

@@ -33,8 +33,8 @@ lazy val commonSettings = Seq(
   organization := "edu.berkeley.cs",
   name := "firrtl",
   version := "1.3.0-RC1",
-  scalaVersion := "2.12.10",
-  crossScalaVersions := Seq("2.12.10", "2.11.12"),
+  scalaVersion := "2.12.11",
+  crossScalaVersions := Seq("2.12.11", "2.11.12"),
   addCompilerPlugin(scalafixSemanticdb),
   scalacOptions := scalacOptionsVersion(scalaVersion.value) ++ Seq(
     "-deprecation",

build.sc

@@ -4,16 +4,16 @@ import mill.scalalib._
 import mill.scalalib.publish._
 import mill.modules.Util
 
-object firrtl extends mill.Cross[firrtlCrossModule]("2.11.12", "2.12.10")
+object firrtl extends mill.Cross[firrtlCrossModule]("2.11.12", "2.12.11")
 
 class firrtlCrossModule(crossVersion: String) extends ScalaModule with SbtModule with PublishModule {
   // different scala version shares same sources
-  // mill use foo/2.11.12 foo/2.12.10 as millSourcePath by default
+  // mill use foo/2.11.12 foo/2.12.11 as millSourcePath by default
   override def millSourcePath = super.millSourcePath / os.up / os.up
 
   def scalaVersion = crossVersion
 
-  // 2.12.10 -> Array("2", "12", "10") -> "12" -> 12
+  // 2.12.11 -> Array("2", "12", "10") -> "12" -> 12
   private def majorVersion = crossVersion.split('.')(1).toInt
 
   def publishVersion = "1.3.0-RC1"
@@ -66,7 +66,7 @@ class firrtlCrossModule(crossVersion: String) extends ScalaModule with SbtModule
     def testFrameworks = Seq("org.scalatest.tools.Framework")
 
     // a sbt-like testOnly command.
-    // for example, mill -i "firrtl[2.12.10].test.testOnly" "firrtlTests.AsyncResetSpec"
+    // for example, mill -i "firrtl[2.12.11].test.testOnly" "firrtlTests.AsyncResetSpec"
     def testOnly(args: String*) = T.command {
       super.runMain("org.scalatest.run", args: _*)
     }

project/plugins.sbt

@@ -20,6 +20,6 @@ addSbtPlugin("com.simplytyped" % "sbt-antlr4" % "0.8.2")
 
 addSbtPlugin("com.github.gseitz" % "sbt-protobuf" % "0.6.5")
 
-addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.9.11")
+addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.9.12")
 
 libraryDependencies += "com.github.os72" % "protoc-jar" % "3.11.1"

spec/spec.tex

@@ -1014,7 +1014,7 @@ \subsection{Signed Integers from Literal Bits}
 
 The bit representation contains a binary, octal or hex indicator, followed by an optional sign, followed by the value.
 
-If a bit width is not given, the number of bits in the bit representation is the minimal bitwidth to represent the value represented by the string. The following examples create a 8-bit integer representing the number -13.
+If a bit width is not given, the number of bits in the bit representation is the minimal bitwidth to represent the value represented by the string. The following examples create a 8-bit integer representing the number -13. For all bases, a negative sign acts as if it were a unary negation; in other words, a negative literal produces the additive inverse of the unsigned interpretation of the digit pattern.
 \begin{lstlisting}
 SInt("b-1101")
 SInt("h-d")
@@ -1728,9 +1728,9 @@ \section{Details about Syntax}
 
 An integer literal in FIRRTL begins with one of the following, where `\#' represents a digit between 0 and 9.
 \begin{itemize}
-\item `0x' : For indicating a hexadecimal number. The rest of the literal must consist of either digits or a letter between `A' and `F', or the separator `\_'.
-\item `0o' : For indicating an octal number. The rest of the literal must consist of digits between 0 and 7, or the separator `\_'.
-\item `0b' : For indicating a binary number. The rest of the literal must consist of either 0 or 1, or the separator `\_'.
+\item `h' : For indicating a hexadecimal number, followed by an optional sign. The rest of the literal must consist of either digits or a letter between `A' and `F'.
+\item `o' : For indicating an octal number, followed by an optional sign. The rest of the literal must consist of digits between 0 and 7.
+\item `b' : For indicating a binary number, followed by an optional sign. The rest of the literal must consist of digits that are either 0 or 1.
 \item `-\#' : For indicating a negative decimal number. The rest of the literal must consist of digits between 0 and 9.
 \item `\#' : For indicating a positive decimal number. The rest of the literal must consist of digits between 0 and 9.
 \end{itemize}

src/main/antlr4/FIRRTL.g4

@@ -186,6 +186,8 @@ intLit
   : UnsignedInt
   | SignedInt
   | HexLit
+  | OctalLit
+  | BinaryLit
   ;
 
 lowerBound
@@ -320,6 +322,14 @@ HexLit
   : '"' 'h' ( '+' | '-' )? ( HexDigit )+ '"'
   ;
 
+OctalLit
+  : '"' 'o' ( '+' | '-' )? ( OctalDigit )+ '"'
+  ;
+
+BinaryLit
+  : '"' 'b' ( '+' | '-' )? ( BinaryDigit )+ '"'
+  ;
+
 DoubleLit
   : ( '+' | '-' )? Digit+ '.' Digit+ ( 'E' ( '+' | '-' )? Digit+ )?
   ;
@@ -334,6 +344,16 @@ HexDigit
   : [a-fA-F0-9]
   ;
 
+fragment
+OctalDigit
+  : [0-7]
+  ;
+
+fragment
+BinaryDigit
+  : [01]
+  ;
+
 StringLit
   : '"' UnquotedString? '"'
   ;

src/main/scala/firrtl/Emitter.scala

@@ -465,8 +465,7 @@ class VerilogEmitter extends SeqTransform with Emitter {
     } 
   }
 
-  /** 
-    * Provide API to retrieve EmissionOptions based on the provided AnnotationSeq 
+  /** Provide API to retrieve EmissionOptions based on the provided [[AnnotationSeq]]
     * 
     * @param annotations : AnnotationSeq to be searched for EmissionOptions
     *
@@ -494,7 +493,9 @@ class VerilogEmitter extends SeqTransform with Emitter {
     def getConnectEmissionOption(target: ReferenceTarget): ConnectEmissionOption =
       connectEmissionOption(target)
 
-    private val emissionAnnos = annotations.collect{ case m : SingleTargetAnnotation[ReferenceTarget] with EmissionOption => m }
+    private val emissionAnnos = annotations.collect{
+      case m : SingleTargetAnnotation[ReferenceTarget] @unchecked with EmissionOption => m
+    }
     // using multiple foreach instead of a single partial function as an Annotation can gather multiple EmissionOptions for simplicity
     emissionAnnos.foreach { case a :RegisterEmissionOption => registerEmissionOption += ((a.target,a)) case _ => }
     emissionAnnos.foreach { case a :WireEmissionOption     => wireEmissionOption += ((a.target,a))     case _ => }

src/main/scala/firrtl/RenameMap.scala

@@ -97,9 +97,9 @@ final class RenameMap private (val underlying: mutable.HashMap[CompleteTarget, S
     */
   def recordAll(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): Unit =
     map.foreach{
-      case (from: IsComponent, tos: Seq[IsMember]) => completeRename(from, tos)
-      case (from: IsModule, tos: Seq[IsMember]) => completeRename(from, tos)
-      case (from: CircuitTarget, tos: Seq[CircuitTarget]) => completeRename(from, tos)
+      case (from: IsComponent, tos: Seq[_]) => completeRename(from, tos)
+      case (from: IsModule, tos: Seq[_]) => completeRename(from, tos)
+      case (from: CircuitTarget, tos: Seq[_]) => completeRename(from, tos)
       case other => Utils.throwInternalError(s"Illegal rename: ${other._1} -> ${other._2}")
     }
 

src/main/scala/firrtl/Visitor.scala

@@ -28,6 +28,8 @@ class Visitor(infoMode: InfoMode) extends AbstractParseTreeVisitor[FirrtlNode] w
 
   //  These regex have to change if grammar changes
   private val HexPattern = """\"*h([+\-]?[a-zA-Z0-9]+)\"*""".r
+  private val OctalPattern = """\"*o([+\-]?[0-7]+)\"*""".r
+  private val BinaryPattern = """\"*b([+\-]?[01]+)\"*""".r
   private val DecPattern = """([+\-]?[1-9]\d*)""".r
   private val ZeroPattern = "0".r
   private val DecimalPattern = """([+\-]?[0-9]\d*\.[0-9]\d*)""".r
@@ -37,6 +39,8 @@ class Visitor(infoMode: InfoMode) extends AbstractParseTreeVisitor[FirrtlNode] w
     s match {
       case ZeroPattern(_*) => BigInt(0)
       case HexPattern(hexdigits) => BigInt(hexdigits, 16)
+      case OctalPattern(octaldigits) => BigInt(octaldigits, 8)
+      case BinaryPattern(binarydigits) => BigInt(binarydigits, 2)
       case DecPattern(num) => BigInt(num, 10)
       case _ => throw new Exception("Invalid String for conversion to BigInt " + s)
     }

src/main/scala/firrtl/annotations/Annotation.scala

@@ -80,7 +80,7 @@ trait SingleTargetAnnotation[T <: Named] extends Annotation {
 /** [[MultiTargetAnnotation]] keeps the renamed targets grouped within a single annotation. */
 trait MultiTargetAnnotation extends Annotation {
   /** Contains a sequence of [[Target]].
-    * When creating in [[toFirrtl]], [[targets]] should be assigned by `Seq(Seq(TargetA), Seq(TargetB), Seq(TargetC))`
+    * When created, [[targets]] should be assigned by `Seq(Seq(TargetA), Seq(TargetB), Seq(TargetC))`
     * */
   val targets: Seq[Seq[Target]]
 

src/main/scala/firrtl/constraint/ConstraintSolver.scala

@@ -10,7 +10,7 @@ import scala.collection.mutable
 
 /** Forwards-Backwards Constraint Solver
   *
-  * Used for computing [[Width]] and [[Bound]] constraints
+  * Used for computing [[firrtl.ir.Width Width]] and [[firrtl.ir.Bound Bound]] constraints
   *
   * Note - this is an O(N) algorithm, but requires exponential memory. We rely on aggressive early optimization
   *   of constraint expressions to (usually) get around this.

src/main/scala/firrtl/graph/DiGraph.scala

@@ -336,7 +336,7 @@ class DiGraph[T] private[graph] (private[graph] val edges: LinkedHashMap[T, Link
     * Any edge including a deleted node will be deleted
     *
     * @param vprime the Set[T] of desired vertices
-    * @throws IllegalArgumentException if vprime is not a subset of V
+    * @throws scala.IllegalArgumentException if vprime is not a subset of V
     * @return the subgraph
     */
   def subgraph(vprime: Set[T]): DiGraph[T] = {
@@ -350,7 +350,7 @@ class DiGraph[T] private[graph] (private[graph] val edges: LinkedHashMap[T, Link
     * transformed into an edge (u,v).
     *
     * @param vprime the Set[T] of desired vertices
-    * @throws IllegalArgumentException if vprime is not a subset of V
+    * @throws scala.IllegalArgumentException if vprime is not a subset of V
     * @return the simplified graph
     */
   def simplify(vprime: Set[T]): DiGraph[T] = {
@@ -394,7 +394,7 @@ class MutableDiGraph[T] extends DiGraph[T](new LinkedHashMap[T, LinkedHashSet[T]
   }
 
   /** Add edge (u,v) to the graph.
-    * @throws IllegalArgumentException if u and/or v is not in the graph
+    * @throws scala.IllegalArgumentException if u and/or v is not in the graph
     */
   def addEdge(u: T, v: T): Unit = {
     require(contains(u))

src/main/scala/firrtl/graph/EdgeData.scala

@@ -34,7 +34,7 @@ trait EdgeData[V, E] {
     * @param u the source of the edge
     * @param v the destination of the edge
     * @throws EdgeNotFoundException if the edge does not exist
-    * @throws NoSuchElementException if the edge has no data
+    * @throws scala.NoSuchElementException if the edge has no data
     */
   def edgeData(u: V, v: V): E = {
     assertEdgeExists(u, v)
@@ -76,25 +76,23 @@ trait MutableEdgeData[V, E] extends EdgeData[V, E] {
     edgeDataMap((u, v)) = data
   }
 
-  /**
-    * Add an edge (u,v) to the graph with associated edge data.
+  /** Add an edge (u,v) to the graph with associated edge data.
     *
-    * @see [[DiGraph.addEdge]]
+    * @see [[MutableDiGraph.addEdge]]
     * @param u the source of the edge
     * @param v the destination of the edge
     * @param data the edge data to associate with the edge
-    * @throws IllegalArgumentException if u or v is not part of the graph
+    * @throws scala.IllegalArgumentException if u or v is not part of the graph
     */
   def addEdge(u: V, v: V, data: E): Unit = {
     addEdge(u, v)
     setEdgeData(u, v, data)
   }
 
-  /**
-    * Safely add an edge (u,v) to the graph with associated edge data. If on or more of the two
+  /** Safely add an edge (u,v) to the graph with associated edge data. If on or more of the two
     * vertices is not present in the graph, add them before creating the edge.
     *
-    * @see [[DiGraph.addPairWithEdge]]
+    * @see [[MutableDiGraph.addPairWithEdge]]
     * @param u the source of the edge
     * @param v the destination of the edge
     * @param data the edge data to associate with the edge
@@ -109,7 +107,7 @@ trait MutableEdgeData[V, E] extends EdgeData[V, E] {
     * are present in the graph. This is useful for preventing spurious edge creating when examining
     * a subset of possible nodes.
     *
-    * @see [[DiGraph.addEdgeIfValid]]
+    * @see [[MutableDiGraph.addEdgeIfValid]]
     * @return a Boolean indicating whether the edge was added
     * @param u the source of the edge
     * @param v the destination of the edge

src/main/scala/firrtl/graph/RenderDiGraph.scala

@@ -19,10 +19,9 @@ class RenderDiGraph[T <: Any](diGraph: DiGraph[T], graphName: String = "", rankD
 
   /**
     * override this to change the default way a node is displayed. Default is toString surrounded by double quotes
+    * This example changes the double quotes to brackets
     * {{{
-    * val rend = new RenderDiGraph(graph, "alice") {
-    *   override def renderNode(node: Symbol): String = s"\"${symbol.name}\""
-    *   }
+    *   override def renderNode(node: String): String = { "[" + node + "]" }
     * }}}
     */
   def renderNode(node: T): String = {

src/main/scala/firrtl/passes/InferWidths.scala

@@ -3,16 +3,14 @@
 package firrtl.passes
 
 // Datastructures
-import firrtl._
-import firrtl.annotations.{Annotation, ReferenceTarget}
-import firrtl.ir._
-import firrtl.Utils._
-import firrtl.Mappers._
 import firrtl.Implicits.width2constraint
-import firrtl.annotations.{CircuitTarget, ModuleTarget, ReferenceTarget, Target}
+import firrtl.Mappers._
+import firrtl.Utils._
+import firrtl._
+import firrtl.annotations._
 import firrtl.constraint.{ConstraintSolver, IsMax}
+import firrtl.ir._
 import firrtl.options.{Dependency, PreservesAll}
-import firrtl.traversals.Foreachers._
 
 object InferWidths {
   def apply(): InferWidths = new InferWidths()

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

@@ -26,9 +26,9 @@ class WrapWithRemainder(info: Info, mname: String, wrap: DoPrim)
   * 1) Align binary points
   *    - adds shift operators to primop args and connections
   *    - does not affect declaration- or inferred-types
-  * 2) Replace Interval [[DefNode]] with [[DefWire]] + [[Connect]]
+  * 2) Replace Interval [[firrtl.ir.DefNode DefNode]] with [[firrtl.ir.DefWire DefWire]] + [[firrtl.ir.Connect Connect]]
   *    - You have to do this to capture the smaller bitwidths of nodes that intervals give you. Otherwise, any future
-  *    InferTypes would reinfer the larger widths on these nodes from SInt width inference rules
+  *    InferTypes would re-infer the larger widths on these nodes from SInt width inference rules
   * 3) Replace declaration IntervalType's with SIntType's
   *    - for each declaration:
   *      a. remove non-zero binary points

src/main/scala/firrtl/stage/phases/CatchExceptions.scala

@@ -2,10 +2,11 @@
 
 package firrtl.stage.phases
 
-import firrtl.{AnnotationSeq, CustomTransformException, FIRRTLException, FirrtlInternalException, FirrtlUserException,
-  Utils}
-import firrtl.options.{DependencyManagerException, Phase, PhaseException, OptionsException}
-import firrtl.passes.{PassException, PassExceptions}
+import firrtl.options.{DependencyManagerException, OptionsException, Phase, PhaseException}
+import firrtl.{
+  AnnotationSeq, CustomTransformException, FIRRTLException,
+  FirrtlInternalException, FirrtlUserException, Utils
+}
 
 import scala.util.control.ControlThrowable
 

src/main/scala/firrtl/stage/transforms/Compiler.scala

@@ -2,9 +2,9 @@
 
 package firrtl.stage.transforms
 
-import firrtl.{CircuitState, Transform, VerilogEmitter}
 import firrtl.options.DependencyManagerUtils.CharSet
 import firrtl.stage.TransformManager
+import firrtl.{Transform, VerilogEmitter}
 
 class Compiler(
   targets: Seq[TransformManager.TransformDependency],

src/main/scala/firrtl/transforms/InferResets.scala

@@ -96,7 +96,7 @@ object InferResets {
   }
 }
 
-/** Infers the concrete type of [[ResetType]]s by their connections
+/** Infers the concrete type of [[firrtl.ir.ResetType ResetType]]s by their connections
   *
   * There are 3 cases
   * 1. An abstract reset driven by and/or driving only asynchronous resets will be inferred as
@@ -105,7 +105,7 @@ object InferResets {
   *    error
   * 1. Otherwise, the reset is inferred as synchronous (i.e. the abstract reset is only invalidated
   *    or is driven by or drives only synchronous resets)
-  * @note This is a global inference because ports can be of type [[ResetType]]
+  * @note This is a global inference because ports can be of type [[firrtl.ir.ResetType ResetType]]
   * @note This transform should be run before [[DedupModules]] so that similar Modules from
   *   generator languages like Chisel can infer differently
   */

src/main/scala/firrtl/transforms/InlineBitExtractions.scala

@@ -1,3 +1,5 @@
+// See LICENSE for license details.
+
 package firrtl
 package transforms
 
@@ -38,10 +40,10 @@ object InlineBitExtractionsTransform {
   /** Mapping from references to the [[firrtl.ir.Expression Expression]]s that drive them */
   type Netlist = mutable.HashMap[WrappedExpression, Expression]
 
-  /** Recursively replace [[WRef]]s with new [[Expression]]s
+  /** Recursively replace [[WRef]]s with new [[firrtl.ir.Expression Expression]]s
     *
     * @param netlist a '''mutable''' HashMap mapping references to [[firrtl.ir.DefNode DefNode]]s to their connected
-    * [[firrtl.ir.Expression Expression]]s. It is '''not''' mutated in this function
+    * [[firrtl.ir.Expression Expression Expression]]s. It is '''not''' mutated in this function
     * @param expr the Expression being transformed
     * @return Returns expr with Bits inlined
     */
@@ -74,8 +76,8 @@ object InlineBitExtractionsTransform {
   /** Inline bits in a Statement
     *
     * @param netlist a '''mutable''' HashMap mapping references to [[firrtl.ir.DefNode DefNode]]s to their connected
-    * [[firrtl.ir.Expression Expression]]s. This function '''will''' mutate it if stmt is a [[firrtl.ir.DefNode
-    * DefNode]] with a Temporary name and a value that is a [[PrimOp]] Bits
+    * [[firrtl.ir.Expression Expression]]s. This function '''will''' mutate it if stmt is
+    * a [[firrtl.ir.DefNode DefNode]] with a Temporary name and a value that is a [[firrtl.ir.PrimOp PrimOp]] Bits
     * @param stmt the Statement being searched for nodes and transformed
     * @return Returns stmt with Bits inlined
     */