Merge branch 'master' into 2.5-release

.github/workflows/test.yml

@@ -22,8 +22,10 @@ jobs:
           verilator --version
       - name: Setup Scala
         uses: olafurpg/setup-scala@v10
-      - name: Cache
-        uses: coursier/cache-action@v5
+      # Commented out because cached dependency SNAPSHOTs were stale
+      # This can be uncommented in the future
+      #- name: Cache
+      #  uses: coursier/cache-action@v5
       - name: Setup Mill
         uses: jodersky/[email protected]
       - name: Mill sanity check
@@ -50,4 +52,4 @@ jobs:
           PGP_PASSPHRASE: ${{ secrets.PGP_PASSPHRASE }}
           PGP_SECRET: ${{ secrets.PGP_SECRET }}
           SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
-          SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
+          SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}

build.sbt

@@ -41,6 +41,8 @@ libraryDependencies ++= Seq("chisel3","firrtl","firrtl-interpreter", "treadle").
     "edu.berkeley.cs" %% dep % sys.props.getOrElse(dep + "Version", defaultVersions(dep))
 }
 
+addCompilerPlugin("edu.berkeley.cs" %% "chisel3-plugin" % defaultVersions("chisel3") cross CrossVersion.full)
+
 // sbt 1.2.6 fails with `Symbol 'term org.junit' is missing from the classpath`
 // when compiling tests under 2.11.12
 // An explicit dependency on junit seems to alleviate this.

src/main/scala/chisel3/ChiselExecutionOptions.scala

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3
+
+import chisel3.stage.{NoRunFirrtlCompilerAnnotation, PrintFullStackTraceAnnotation}
+
+import firrtl.{AnnotationSeq, ExecutionOptionsManager, ComposableOptions}
+
+//TODO: provide support for running firrtl as separate process, could alternatively be controlled by external driver
+//TODO: provide option for not saving chirrtl file, instead calling firrtl with in memory chirrtl
+/**
+  * Options that are specific to chisel.
+  *
+  * @param runFirrtlCompiler when true just run chisel, when false run chisel then compile its output with firrtl
+  * @note this extends FirrtlExecutionOptions which extends CommonOptions providing easy access to down chain options
+  */
+case class ChiselExecutionOptions(
+                                   runFirrtlCompiler: Boolean = true,
+                                   printFullStackTrace: Boolean = false
+                                   // var runFirrtlAsProcess: Boolean = false
+                                 ) extends ComposableOptions {
+
+  def toAnnotations: AnnotationSeq =
+    (if (!runFirrtlCompiler) { Seq(NoRunFirrtlCompilerAnnotation) } else { Seq() }) ++
+      (if (printFullStackTrace) { Some(PrintFullStackTraceAnnotation) } else { None })
+
+}
+
+trait HasChiselExecutionOptions {
+  self: ExecutionOptionsManager =>
+
+  var chiselOptions = ChiselExecutionOptions()
+
+  parser.note("chisel3 options")
+
+  parser.opt[Unit]("no-run-firrtl")
+    .abbr("chnrf")
+    .foreach { _ =>
+      chiselOptions = chiselOptions.copy(runFirrtlCompiler = false)
+    }
+    .text("Stop after chisel emits chirrtl file")
+
+  parser.opt[Unit]("full-stacktrace")
+    .foreach { _ =>
+      chiselOptions = chiselOptions.copy(printFullStackTrace = true)
+    }
+    .text("Do not trim stack trace")
+}
+

src/main/scala/chisel3/Driver.scala

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3
+
+import chisel3.internal.ErrorLog
+import internal.firrtl._
+import firrtl._
+import firrtl.options.{Dependency, Phase, PhaseManager, StageError}
+import firrtl.options.phases.DeletedWrapper
+import firrtl.options.Viewer.view
+import firrtl.annotations.JsonProtocol
+import firrtl.util.{BackendCompilationUtilities => FirrtlBackendCompilationUtilities}
+import chisel3.stage.{ChiselExecutionResultView, ChiselGeneratorAnnotation, ChiselStage}
+import chisel3.stage.phases.DriverCompatibility
+import java.io._
+
+
+/**
+  * This family provides return values from the chisel3 and possibly firrtl compile steps
+  */
+@deprecated("This will be removed in Chisel 3.5", "Chisel3 3.4")
+trait ChiselExecutionResult
+
+/**
+  *
+  * @param circuitOption  Optional circuit, has information like circuit name
+  * @param emitted            The emitted Chirrrl text
+  * @param firrtlResultOption Optional Firrtl result, @see freechipsproject/firrtl for details
+  */
+@deprecated("This will be removed in Chisel 3.5", "Chisel 3.4")
+case class ChiselExecutionSuccess(
+                                  circuitOption: Option[Circuit],
+                                  emitted: String,
+                                  firrtlResultOption: Option[FirrtlExecutionResult]
+                                  ) extends ChiselExecutionResult
+
+/**
+  * Getting one of these indicates failure of some sort.
+  *
+  * @param message A clue might be provided here.
+  */
+@deprecated("This will be removed in Chisel 3.5", "Chisel 3.4")
+case class ChiselExecutionFailure(message: String) extends ChiselExecutionResult

src/main/scala/chisel3/iotesters/AdvTester.scala

@@ -9,6 +9,8 @@ import chisel3.util._
 import scala.collection.mutable.ArrayBuffer
 import java.io.{PrintWriter, StringWriter}
 // Provides a template to define advanced tester transactions
+//
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 trait AdvTests extends PeekPokeTests {
   def cycles: Long
   def wire_poke[T <: Element: Pokeable](port: T, target: BigInt):  Unit
@@ -20,6 +22,7 @@ trait AdvTests extends PeekPokeTests {
   def do_until(work: =>Unit)(pred: =>Boolean, maxCycles: Long = 0L): Boolean
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 abstract class AdvTester[+T <: Module](dut: T,
                                        base: Int = 16,
                                        logFile: Option[java.io.File] = chiselMain.context.logFile)

src/main/scala/chisel3/iotesters/ChiselMain.scala

@@ -25,6 +25,7 @@ private[iotesters] class TesterContext {
   var waveform: Option[File] = None
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 object chiselMain {
   private val contextVar = new DynamicVariable[Option[TesterContext]](None)
   private[iotesters] def context = contextVar.value.getOrElse(new TesterContext)
@@ -206,6 +207,7 @@ object chiselMain {
   }
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 object chiselMainTest {
   def apply[T <: Module](args: Array[String], dutGen: () => T)(testerGen: T => PeekPokeTester[T]): Unit = {
     chiselMain(args, dutGen, testerGen)

src/main/scala/chisel3/iotesters/ChiselPokeSpec.scala

@@ -7,35 +7,42 @@ import org.scalatest._
 import chisel3._
 import chisel3.iotesters._
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 sealed trait TesterBackend {
   def create[T <: Module](dutGen: () => T, options: TesterOptionsManager): (T, Backend)
 }
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 case object FirrtlInterpreterBackend extends TesterBackend {
   override def create[T <: Module](dutGen: () => T, options: TesterOptionsManager): (T, Backend) = {
     setupFirrtlTerpBackend(dutGen, options)
   }
 }
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 case object VerilatorBackend extends TesterBackend {
   override def create[T <: Module](dutGen: () => T, options: TesterOptionsManager): (T, Backend) = {
     setupVerilatorBackend(dutGen, options)
   }
 }
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 case object IvlBackend extends TesterBackend {
   override def create[T <: Module](dutGen: () => T, options: TesterOptionsManager): (T, Backend) = {
     setupIVLBackend(dutGen, options)
   }
 }
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 case object VcsBackend extends TesterBackend {
   override def create[T <: Module](dutGen: () => T, options: TesterOptionsManager): (T, Backend) = {
     setupVCSBackend(dutGen, options)
   }
 }
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 case object VsimBackend extends TesterBackend {
   override def create[T <: Module](dutGen: () => T, options: TesterOptionsManager): (T, Backend) = {
     setupVSIMBackend(dutGen, options)
   }
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 trait ChiselPokeTesterUtils extends Assertions {
   class InnerTester(val backend: Backend, val options: TesterOptionsManager) {
     // Implicit configuration options for backend
@@ -115,6 +122,7 @@ trait ChiselPokeTesterUtils extends Assertions {
 
 /** Basic peek-poke test system where failures are handled and reported within ScalaTest.
   */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 trait PokeTester extends ChiselPokeTesterUtils {
   def test[T <: Module](dutGen: => T, testerBackend: TesterBackend, options: TesterOptionsManager)(block: (InnerTester, T) => Unit) {
     runTester(dutGen, testerBackend, options) { (tester, dut) => block(tester, dut) }
@@ -131,6 +139,7 @@ trait PokeTester extends ChiselPokeTesterUtils {
   *
   * API very subject to change.
   */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 trait ImplicitPokeTester extends ChiselPokeTesterUtils {
   /** Pokes a value into the circuit.
     */

src/main/scala/chisel3/iotesters/ChiselSpec.scala

@@ -15,6 +15,7 @@ import sys.process.{stringSeqToProcess, BasicIO}
 import scala.util.Properties.envOrElse
 
 /** Common utility functions for Chisel unit tests. */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 trait ChiselRunners extends Assertions {
   val backends = envOrElse("TESTER_BACKENDS", "firrtl") split " "
   def runTester(t: => BasicTester, additionalVResources: Seq[String] = Seq()): Boolean = {
@@ -27,9 +28,11 @@ trait ChiselRunners extends Assertions {
 }
 
 /** Spec base class for BDD-style testers. */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 class ChiselFlatSpec extends AnyFlatSpec with ChiselRunners with Matchers
 
 /** Spec base class for property-based testers. */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 class ChiselPropSpec extends AnyPropSpec with ChiselRunners with ScalaCheckPropertyChecks {
 
   // Constrain the default number of instances generated for every use of forAll.

src/main/scala/chisel3/iotesters/Driver.scala

@@ -8,10 +8,11 @@ import java.io.File
 import chisel3.iotesters.DriverCompatibility._
 import firrtl.annotations.Annotation
 import firrtl_interpreter._
-import logger.Logger
+import logger.{LoggerCompatibility => Logger}
 
 import scala.util.DynamicVariable
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 object Driver {
   private val backendVar = new DynamicVariable[Option[Backend]](None)
   private[iotesters] def backend = backendVar.value
@@ -299,6 +300,7 @@ object Driver {
   }
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 class ReplOptionsManager
   extends InterpreterOptionsManager
     with HasChiselExecutionOptions

src/main/scala/chisel3/iotesters/DriverCompatibility.scala

@@ -10,6 +10,7 @@ import firrtl.options.Viewer.view
 import firrtl.options.phases.DeletedWrapper
 import firrtl.options.{Dependency, OptionsException, OptionsView, OutputAnnotationFileAnnotation, Phase, PhaseManager, StageError, Unserializable}
 import firrtl.stage.phases.DriverCompatibility.TopNameAnnotation
+import firrtl.stage.phases.DriverCompatibilityExtensions
 import firrtl.stage.{FirrtlCircuitAnnotation, RunFirrtlTransformAnnotation}
 import firrtl.{AnnotationSeq, ExecutionOptionsManager, FirrtlExecutionResult, HasFirrtlOptions}
 
@@ -18,6 +19,7 @@ import firrtl.{AnnotationSeq, ExecutionOptionsManager, FirrtlExecutionResult, Ha
   * Primarily, this object includes [[firrtl.options.Phase Phase]]s that generate [[firrtl.annotations.Annotation]]s
   * derived from the deprecated [[firrtl.stage.phases.DriverCompatibility.TopNameAnnotation]].
   */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 object DriverCompatibility {
 
   private[chisel3] implicit object ChiselExecutionResultView extends OptionsView[ChiselExecutionResult] {

src/main/scala/chisel3/iotesters/HWIOTester.scala

@@ -10,6 +10,7 @@ import scala.util.Random
 /**
   * provide common facilities for step based testing and decoupled interface testing
   */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 abstract class HWIOTester extends BasicTester {
   val device_under_test:     Module
   var io_info:               IOAccessor = null

src/main/scala/chisel3/iotesters/OrderedDecoupledHWIOTester.scala

@@ -39,6 +39,7 @@ import scala.collection.mutable.ArrayBuffer
   * likewise,
   * all outputs regardless of which interface are tested in the same order that they were created
   */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 abstract class OrderedDecoupledHWIOTester extends HWIOTester {
   val input_event_list  = new ArrayBuffer[Seq[(Data, BigInt)]]()
   val output_event_list = new ArrayBuffer[Seq[(Data, BigInt)]]()

src/main/scala/chisel3/iotesters/PeekPokeTester.scala

@@ -16,6 +16,7 @@ import scala.collection.mutable.ArrayBuffer
 import scala.language.implicitConversions
 
 // Provides a template to define tester transactions
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 trait PeekPokeTests {
   /** Get the actual step value (simTime)
     * @return simTime - number of steps since begining of simulation
@@ -73,6 +74,7 @@ trait PeekPokeTests {
   def finish: Boolean
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 object PeekPokeTester {
   /** Old "flatten" functionality.
     *
@@ -88,6 +90,7 @@ object PeekPokeTester {
   }
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 abstract class PeekPokeTester[+T <: Module](
     val dut: T,
     base: Int = 16,

src/main/scala/chisel3/iotesters/PeekPokeTesterUtils.scala

@@ -97,7 +97,7 @@ trait EditableBuildCSimulatorCommand {
     * @return sequence of strings (suitable for passing as arguments to the simulator builder) specifying a flag and the absolute path to the file.
     */
   def blackBoxVerilogList(dir: java.io.File): Seq[String] = {
-    val list_file = new File(dir, firrtl.transforms.BlackBoxSourceHelper.fileListName)
+    val list_file = new File(dir, firrtl.transforms.BlackBoxSourceHelper.defaultFileListName)
     if(list_file.exists()) {
       Seq("-f", list_file.getAbsolutePath)
     } else {

src/main/scala/chisel3/iotesters/SteppedHWIOTester.scala

@@ -39,6 +39,7 @@ import scala.collection.mutable.ArrayBuffer
   * }
   * }}}
   */
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 abstract class SteppedHWIOTester extends HWIOTester {
   case class Step(input_map: mutable.HashMap[Data,BigInt], output_map: mutable.HashMap[Data,BigInt])
 

src/main/scala/chisel3/iotesters/TesterOptions.scala

@@ -10,6 +10,7 @@ import firrtl_interpreter.HasInterpreterSuite
 
 import scala.util.matching.Regex
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 case class TesterOptions(
   isGenVerilog:         Boolean = false,
   isGenHarness:         Boolean = false,
@@ -42,6 +43,7 @@ object TesterOptions {
   val IvlFileCommands: Regex = """file:(.+)""".r
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 trait HasTesterOptions {
   self: ExecutionOptionsManager =>
 
@@ -186,6 +188,7 @@ trait HasTesterOptions {
     .text(s"""set this flag to "on" or "off", otherwise it defaults to off""")
 }
 
+@deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
 class TesterOptionsManager
   extends ExecutionOptionsManager("chisel-testers")
     with HasTesterOptions

src/main/scala/chisel3/iotesters/compatibility.scala

@@ -17,12 +17,14 @@ package object iotesters {
   type SteppedHWIOTester = ciot.SteppedHWIOTester
   type OrderedDecoupledHWIOTester = ciot.OrderedDecoupledHWIOTester
 
+  @deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
   object chiselMainTest {
     def apply[T <: Module](args: Array[String], dutGen: () => T)(testerGen: T => ciot.PeekPokeTester[T]) = {
       ciot.chiselMain(args, dutGen, testerGen)
     }
   }
 
+  @deprecated("chisel-iotesters is end-of-life. Use chiseltest instead, see https://www.chisel-lang.org/chiseltest/migrating-from-iotesters.", "chisel-iotesters 2.5.0")
   object Driver {
     /**
       * Runs the ClassicTester and returns a Boolean indicating test success or failure