Merge branch 'master' into 3.6-release

Author: jackkoenig

.github/workflows/install-circt/action.yml

@@ -4,7 +4,7 @@ inputs:
   version:
     description: 'version to install'
     required: false
-    default: 'firtool-1.30.0'
+    default: 'firtool-1.31.0'
 
 runs:
   using: composite

.github/workflows/test.yml

@@ -19,7 +19,7 @@ jobs:
         jvm: ["8"]
         scala: ["2.13.10", "2.12.17"]
         espresso: ["2.4"]
-        circt: ["firtool-1.30.0"]
+        circt: ["firtool-1.31.0"]
     runs-on: ${{ matrix.system }}
 
     steps:
@@ -131,6 +131,9 @@ jobs:
           gem install jekyll-redirect-from
       - name: Install CIRCT
         uses: ./.github/workflows/install-circt
+        #TODO: make the microsite building include building ScalaDoc
+      - name: Build the docs
+        run: sbt doc
       - name: Build the microsite
         run: make -C website
         env:
@@ -200,7 +203,7 @@ jobs:
       - name: Setup GPG (for Publish)
         uses: olafurpg/setup-gpg@v3
       - name: Publish
-        run: sbt ci-release
+        run: sbt -DdisableFatalWarnings ci-release
         env:
           PGP_PASSPHRASE: ${{ secrets.PGP_PASSPHRASE }}
           PGP_SECRET: ${{ secrets.PGP_SECRET }}

build.sbt

@@ -36,13 +36,29 @@ lazy val commonSettings = Seq(
   }
 )
 
+lazy val fatalWarningsSettings = Seq(
+  scalacOptions ++= {
+    CrossVersion.partialVersion(scalaVersion.value) match {
+      case Some((2, n)) if n >= 13 =>
+          if (sys.props.contains("disableFatalWarnings")) {
+            Nil
+          } else {
+            "-Werror" :: Nil
+          }
+
+      case _                       => Nil
+    }
+  }
+)
+
 lazy val warningSuppression = Seq(
   scalacOptions += "-Wconf:" + Seq(
     "msg=APIs in chisel3.internal:s",
     "msg=Importing from firrtl:s",
     "msg=migration to the MLIR:s",
     "msg=method hasDefiniteSize in trait IterableOnceOps is deprecated:s",  // replacement `knownSize` is not in 2.12
-    "msg=object JavaConverters in package collection is deprecated:s"
+    "msg=object JavaConverters in package collection is deprecated:s",
+    "msg=undefined in comment for method cf in class PrintableHelper:s"
   ).mkString(",")
 )
 
@@ -96,6 +112,7 @@ lazy val chiselSettings = Seq(
 )
 
 autoCompilerPlugins := true
+autoAPIMappings := true
 
 // Plugin must be fully cross-versioned (published for Scala minor version)
 // The plugin only works in Scala 2.12+
@@ -136,7 +153,6 @@ lazy val plugin = (project in file("plugin"))
   .settings(publishSettings: _*)
   .settings(
     libraryDependencies += "org.scala-lang" % "scala-compiler" % scalaVersion.value,
-    scalacOptions += "-Xfatal-warnings",
     crossScalaVersions := pluginScalaVersions,
     // Must be published for Scala minor version
     crossVersion := CrossVersion.full,
@@ -145,6 +161,7 @@ lazy val plugin = (project in file("plugin"))
       target.value / s"scala-${scalaVersion.value}"
     }
   )
+  .settings(fatalWarningsSettings: _*)
   .settings(
     mimaPreviousArtifacts := {
       Set()
@@ -182,6 +199,7 @@ lazy val core = (project in file("core"))
   .settings(publishSettings: _*)
   .settings(mimaPreviousArtifacts := Set())
   .settings(warningSuppression: _*)
+  .settings(fatalWarningsSettings: _*)
   .settings(
     name := "chisel3-core",
     libraryDependencies ++= Seq(
@@ -213,6 +231,7 @@ lazy val chisel = (project in file("."))
   .dependsOn(core)
   .aggregate(macros, core, plugin)
   .settings(warningSuppression: _*)
+  .settings(fatalWarningsSettings: _*)
   .settings(
     mimaPreviousArtifacts := Set(),
     Test / scalacOptions ++= Seq("-language:reflectiveCalls"),
@@ -264,6 +283,8 @@ lazy val integrationTests = (project in file("integration-tests"))
   .dependsOn(chisel)
   .dependsOn(standardLibrary)
   .settings(commonSettings: _*)
+  .settings(warningSuppression: _*)
+  .settings(fatalWarningsSettings: _*)
   .settings(chiselSettings: _*)
   .settings(usePluginSettings: _*)
   .settings(
@@ -287,7 +308,6 @@ lazy val docs = project // new documentation project
   .settings(commonSettings)
   .settings(
     scalacOptions ++= Seq(
-      "-Xfatal-warnings",
       "-language:reflectiveCalls",
       "-language:implicitConversions",
       "-Wconf:msg=firrtl:s"
@@ -300,7 +320,4 @@ lazy val docs = project // new documentation project
       "BUILD_DIR" -> "docs-target" // build dir for mdoc programs to dump temp files
     )
   )
-
-addCommandAlias("com", "all compile")
-addCommandAlias("lint", "; compile:scalafix --check ; test:scalafix --check")
-addCommandAlias("fix", "all compile:scalafix test:scalafix")
+  .settings(fatalWarningsSettings: _*)

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

@@ -227,7 +227,7 @@ sealed class Vec[T <: Data] private[chisel3] (gen: => T, val length: Int) extend
 
   /** The "bulk connect operator", assigning elements in this Vec from elements in a Seq.
     *
-    * For chisel3._, uses the [[BiConnect]] algorithm; sub-elements of `that` may end up driving sub-elements of `this`
+    * For chisel3._, uses the `chisel3.internal.BiConnect` algorithm; sub-elements of `that` may end up driving sub-elements of `this`
     *  - Complicated semantics, will likely be deprecated in the future
     *
     * For Chisel._, emits the FIRRTL.<- operator
@@ -249,7 +249,7 @@ sealed class Vec[T <: Data] private[chisel3] (gen: => T, val length: Int) extend
 
   /** The "bulk connect operator", assigning elements in this Vec from elements in a Vec.
     *
-    * For chisel3._, uses the [[BiConnect]] algorithm; sub-elements of `that` may end up driving sub-elements of `this`
+    * For chisel3._, uses the `chisel3.internal.BiConnect` algorithm; sub-elements of `that` may end up driving sub-elements of `this`
     *  - See docs/src/explanations/connection-operators.md for details
     *
     * For Chisel._, emits the FIRRTL.<- operator
@@ -1159,11 +1159,11 @@ abstract class Record(private[chisel3] implicit val compileOptions: CompileOptio
     clone
   }
 
-  /** The collection of [[Data]]
+  /** The collection of [[chisel3.Data]]
     *
     * This underlying datastructure is a ListMap because the elements must
     * remain ordered for serialization/deserialization. Elements added later
-    * are higher order when serialized (this is similar to [[Vec]]). For example:
+    * are higher order when serialized (this is similar to `Vec`). For example:
     * {{{
     *   // Assume we have some type MyRecord that creates a Record from the ListMap
     *   val record = MyRecord(ListMap("fizz" -> UInt(16.W), "buzz" -> UInt(16.W)))

core/src/main/scala/chisel3/Annotation.scala

@@ -28,11 +28,7 @@ trait ChiselMultiAnnotation {
   def toFirrtl: Seq[Annotation]
 }
 
-/** Mixin for [[ChiselAnnotation]] that instantiates an associated FIRRTL Transform when this Annotation is present
-  * during a run of
-  * [[Driver$.execute(args:Array[String],dut:()=>chisel3\.RawModule)* Driver.execute]].
-  * Automatic Transform instantiation is *not* supported when the Circuit and Annotations are serialized before invoking
-  * FIRRTL.
+/** Mixin for [[ChiselAnnotation]] that instantiates an associated Transform when this Annotation is present
   */
 trait RunFirrtlTransform extends ChiselAnnotation {
   def transformClass: Class[_ <: Transform]
@@ -78,12 +74,7 @@ object annotate {
   *  io.out(1) := fullAdder(io.a, io.b, "mod2")
   * }
   * }}}
-  *
-  * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations
-  * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods
-  * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically.
   */
-
 object doNotDedup {
 
   /** Marks a module to be ignored in Dedup Transform in Firrtl

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

@@ -148,8 +148,22 @@ sealed abstract class Bits(private[chisel3] val width: Width) extends Element wi
 
   /** @group SourceInfoTransformMacro */
   final def do_extract(x: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = {
+    this.widthOption.foreach { thisWidth =>
+      if (thisWidth == 0) {
+        Builder.error(s"Cannot extract from zero-width")
+      } else {
+        x.widthOption.foreach { xWidth =>
+          if (xWidth >= 31 || (1 << (xWidth - 1)) >= thisWidth) {
+            Builder.warning(s"Dynamic index with width $xWidth is too large for extractee of width $thisWidth")
+          } else if ((1 << xWidth) < thisWidth) {
+            Builder.warning(s"Dynamic index with width $xWidth is too small for extractee of width $thisWidth")
+          }
+        }
+      }
+    }
     val theBits = this >> x
-    theBits(0)
+    val noExtract = theBits.widthOption.exists(_ <= 1)
+    if (noExtract) theBits.asBool else theBits(0)
   }
 
   /** Returns the specified bit on this wire as a [[Bool]], dynamically addressed.
@@ -360,10 +374,10 @@ sealed abstract class Bits(private[chisel3] val width: Width) extends Element wi
   /** @group SourceInfoTransformMacro */
   def do_asSInt(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt
 
-  /** Reinterpret this $coll as a [[FixedPoint]].
+  /** Reinterpret this $coll as a `FixedPoint`.
     *
     * @note The value is not guaranteed to be preserved. For example, a [[UInt]] of width 3 and value 7 (0b111) would
-    * become a [[FixedPoint]] with value -1. The interpretation of the number is also affected by the specified binary
+    * become a `FixedPoint` with value -1. The interpretation of the number is also affected by the specified binary
     * point. '''Caution is advised!'''
     */
   @deprecated(deprecatedMFCMessage, "Chisel 3.6")
@@ -1317,7 +1331,7 @@ package experimental {
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
     def binaryPoint: BinaryPoint
 
-    /** Return the [[Double]] value of this instance if it is a Literal
+    /** Return the `Double` value of this instance if it is a Literal
       * @note this method may throw an exception if the literal value won't fit in a Double
       */
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
@@ -1334,7 +1348,7 @@ package experimental {
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
     def litToDouble: Double = litToDoubleOption.get
 
-    /** Return the [[BigDecimal]] value of this instance if it is a Literal
+    /** Return the [[scala.math.BigDecimal]] value of this instance if it is a Literal
       * @note this method may throw an exception if the literal value won't fit in a BigDecimal
       */
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
@@ -1346,7 +1360,7 @@ package experimental {
       }
     }
 
-    /** Return the [[BigDecimal]] value of this instance assuming it is a literal (convenience method)
+    /** Return the [[scala.math.BigDecimal]] value of this instance assuming it is a literal (convenience method)
       * @return
       */
     @deprecated(deprecatedMFCMessage, "Chisel 3.6")
@@ -1846,7 +1860,7 @@ package experimental {
     *   val one = 1.I
     *   val six = Seq.fill(6)(one).reduce(_ + _)
     * }}}
-    * A UInt computed in this way would require a [[Width]]
+    * A UInt computed in this way would require a `Width`
     * binary point
     * The width and binary point may be inferred.
     *

core/src/main/scala/chisel3/Data.scala

@@ -723,7 +723,7 @@ abstract class Data extends HasId with NamedComponent with SourceInfoDoc {
 
   /** The "bulk connect operator", assigning elements in this Vec from elements in a Vec.
     *
-    * For chisel3._, uses the [[BiConnect]] algorithm; sub-elements of `that` may end up driving sub-elements of `this`
+    * For chisel3._, uses the `chisel3.internal.BiConnect` algorithm; sub-elements of that` may end up driving sub-elements of `this`
     *  - Complicated semantics, hard to write quickly, will likely be deprecated in the future
     *
     * For Chisel._, emits the FIRRTL.<- operator

core/src/main/scala/chisel3/Module.scala

@@ -401,8 +401,8 @@ package experimental {
 
     /** The desired name of this module (which will be used in generated FIRRTL IR or Verilog).
       *
-      * The name of a module approximates the behavior of the Java Reflection [[`getSimpleName` method
-      * https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#getSimpleName--]] with some modifications:
+      * The name of a module approximates the behavior of the Java Reflection `getSimpleName` method
+      * https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#getSimpleName-- with some modifications:
       *
       * - Anonymous modules will get an `"_Anon"` tag
       * - Modules defined in functions will use their class name and not a numeric name

core/src/main/scala/chisel3/VerificationStatement.scala

@@ -64,7 +64,7 @@ object assert extends VerifPrintMacrosDoc {
     * @param cond condition, assertion fires (simulation fails) on a rising clock edge when false and reset is not asserted
     * @param message optional chisel Printable type message
     *
-    * @note See [[printf.apply(fmt:Printable)]] for documentation on printf using Printables
+    * @note See [[printf.apply(pable:chisel3\.Printable)*]] for documentation on printf using Printables
     * @note currently cannot be used in core Chisel / libraries because macro
     * defs need to be compiled first and the SBT project is not set up to do
     * that
@@ -239,7 +239,7 @@ object assume extends VerifPrintMacrosDoc {
     * @param cond condition, assertion fires (simulation fails) when false
     * @param message optional Printable type message when the assertion fires
     *
-    * @note See [[printf.apply(fmt:Printable]] for documentation on printf using Printables
+    * @note See [[printf.apply(pable:chisel3\.Printable)*]] for documentation on printf using Printables
     */
   def apply(
     cond:    Bool,

core/src/main/scala/chisel3/connectable/Connectable.scala

@@ -125,7 +125,7 @@ object Connectable {
     * $chiselTypeRestrictions
     *
     * Additional notes:
-    * - Connecting two [[util.DecoupledIO]]'s would connect `bits`, `valid`, AND `ready` from producer to consumer (despite `ready` being flipped)
+    * - Connecting two `util.DecoupledIO`'s would connect `bits`, `valid`, AND `ready` from producer to consumer (despite `ready` being flipped)
     * - Functionally equivalent to chisel3.:=, but different than Chisel.:=
     *
     * @group connection
@@ -143,7 +143,7 @@ object Connectable {
     * $chiselTypeRestrictions
     *
     * Additional notes:
-    *  - Connecting two [[util.DecoupledIO]]'s would connect `bits` and `valid` from producer to consumer, but leave `ready` unconnected
+    *  - Connecting two `util.DecoupledIO`'s would connect `bits` and `valid` from producer to consumer, but leave `ready` unconnected
     *
     * @group connection
     *
@@ -160,7 +160,7 @@ object Connectable {
     * $chiselTypeRestrictions
     *
     * Additional notes:
-    *  - Connecting two [[util.DecoupledIO]]'s would connect `ready` from consumer to producer, but leave `bits` and `valid` unconnected
+    *  - Connecting two `util.DecoupledIO`'s would connect `ready` from consumer to producer, but leave `bits` and `valid` unconnected
     *
     * @group connection
     *
@@ -182,7 +182,7 @@ object Connectable {
     * - An additional type restriction is that all relative orientations of `consumer` and `producer` must match exactly.
     *
     * Additional notes:
-    *  - Connecting two wires of [[util.DecoupledIO]] chisel type would connect `bits` and `valid` from producer to consumer, and `ready` from consumer to producer.
+    *  - Connecting two wires of `util.DecoupledIO` chisel type would connect `bits` and `valid` from producer to consumer, and `ready` from consumer to producer.
     *  - If the types of consumer and producer also have identical relative flips, then we can emit FIRRTL.<= as it is a stricter version of chisel3.:<>=
     *  - "turk-duck-en" is a dish where a turkey is stuffed with a duck, which is stuffed with a chicken; `:<>=` is a `:=` stuffed with a `<>`
     *

core/src/main/scala/chisel3/dontTouch.scala

@@ -19,9 +19,6 @@ import firrtl.transforms.DontTouchAnnotation
   *   dontTouch(dead) // Marking it as such will preserve it
   * }
   * }}}
-  * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations
-  * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods
-  * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically.
   * @note Because this is an optimization barrier, constants will not be propagated through a signal marked as
   * dontTouch.
   */

core/src/main/scala/chisel3/experimental/Trace.scala

@@ -59,7 +59,7 @@ object Trace {
     def duplicate(n: T): Annotation = this.copy(target = n)
   }
 
-  /** Get [[CompleteTarget]] of the target `x` for `annos`.
+  /** Get `CompleteTarget` of the target `x` for `annos`.
     * This API can be used to find the final reference to a signal or module which is marked by `traceName`
     */
   def finalTarget(annos: AnnotationSeq)(x: HasId): Seq[CompleteTarget] = finalTargetMap(annos)