add transforms to lint module name conflicts and override module names

.gitignore

@@ -4,3 +4,4 @@ project/target
 *~
 .addons-dont-touch
 /lib/
+/test_lib/

Makefrag

@@ -13,7 +13,7 @@ space := $() $()
 splitConfigs := $(subst $(comma), ,$(CONFIG))
 configBases := $(foreach config,$(splitConfigs),$(lastword $(subst ., ,$(config))))
 CONFIG_STR := $(subst $(space),_,$(configBases))
-long_name = $(PROJECT).$(CONFIG_STR)
+long_name ?= $(PROJECT).$(CONFIG_STR)
 
 VLSI_MEM_GEN ?= $(base_dir)/scripts/vlsi_mem_gen
 
@@ -39,14 +39,20 @@ ROCKET_CLASS_DIRS ?= \
 
 ROCKET_CLASSES ?= $(subst $(SPACE),:,$(ROCKET_CLASS_DIRS))
 FIRRTL_JAR ?= $(base_dir)/firrtl/utils/bin/firrtl.jar
+FIRRTL_TEST_JAR ?= $(base_dir)/firrtl/utils/bin/firrtl-test.jar
 FIRRTL ?= java -Xmx$(JVM_MEMORY) -Xss8M -XX:MaxPermSize=256M -cp "$(FIRRTL_JAR)":"$(ROCKET_CLASSES)" firrtl.Driver
 
 # Build firrtl.jar and put it where chisel3 can find it.
 $(FIRRTL_JAR): $(shell find $(base_dir)/firrtl/src/main/scala -iname "*.scala")
 	$(MAKE) -C $(base_dir)/firrtl SBT="$(SBT)" root_dir=$(base_dir)/firrtl build-scala
+	cd $(base_dir)/firrtl && $(SBT) "Test / assembly"
 	touch $(FIRRTL_JAR)
 	mkdir -p $(base_dir)/lib
 	cp -p $(FIRRTL_JAR) $(base_dir)/lib
+
+	mkdir -p $(base_dir)/test_lib
+	cp -p $(FIRRTL_JAR) $(base_dir)/test_lib
+	cp -p $(FIRRTL_TEST_JAR) $(base_dir)/test_lib
 # When chisel3 pr 448 is merged, the following extraneous copy may be removed.
 	mkdir -p $(base_dir)/chisel3/lib
 	cp -p $(FIRRTL_JAR) $(base_dir)/chisel3/lib

build.sbt

@@ -86,7 +86,8 @@ lazy val rocketchip = dependOnChisel(project in file("."))
       mappings in (Compile, packageSrc) ++= (mappings in (hardfloat, Compile, packageSrc)).value,
       mappings in (Compile, packageBin) ++= (mappings in (`rocket-macros`, Compile, packageBin)).value,
       mappings in (Compile, packageSrc) ++= (mappings in (`rocket-macros`, Compile, packageSrc)).value,
-      exportJars := true
+      exportJars := true,
+      Test / unmanagedBase := baseDirectory.value / "test_lib"
   )
 
 

src/main/resources/META-INF/services/firrtl.options.RegisteredLibrary

@@ -1,3 +1,4 @@
 freechips.rocketchip.linting.LintReporter
 freechips.rocketchip.linting.rule.LintAnonymousRegisters
 freechips.rocketchip.linting.rule.LintTruncatingWidths
+freechips.rocketchip.linting.rule.LintConflictingModuleNames

src/main/scala/aspects/RenameModulesAspect.scala

@@ -0,0 +1,46 @@
+// See LICENSE.SiFive for license details.
+
+package freechips.rocketchip.aspects
+
+import chisel3.aop.Aspect
+import chisel3.RawModule
+
+import firrtl.AnnotationSeq
+import firrtl.stage.RunFirrtlTransformAnnotation
+
+import freechips.rocketchip.transforms.naming.{OverrideDesiredNameAnnotation, RenameDesiredNames}
+
+/** An aspect that renames modules
+  *
+  * @example renaming all Queues in a design to "Queue_$bundleType_entries_$numEntries"
+  * {{{
+  * case object StabilizeQueueNames extends RenameModulesAspect({ top: RawModule =>
+  *   chisel3.aop.Select.collectDeep(top) {
+  *     case m: Queue[_] =>
+  *       m -> s"Queue_${m.genType.getClass.getSimpleName}_entries_${m.entries}"
+  *   }.toSeq
+  * })
+  * }}}
+  *
+  * @example renaming a specific instance of RocketCore in the design
+  * {{{
+  * case object RenameRocketCore0 extends RenameModulesAspect({ top: RawModule =>
+  *   chisel3.aop.Select.collectDeep(top) {
+  *     case th: TestHarness =>
+  *       val core = th.ldut.rocketTiles.head.module.core
+  *       core -> "Rocket_Core_0"
+  *   }.toSeq
+  * })
+  * }}}
+  *
+  * @param collectNameOverrides a function that takes the design top module and returns pairs of name overrides for the modules under the top module in the hierarchy
+  */
+abstract class RenameModulesAspect(
+  collectNameOverrides: RawModule => Seq[(RawModule, String)]
+  ) extends Aspect[RawModule] {
+  final def toAnnotation(top: RawModule): AnnotationSeq = {
+    RunFirrtlTransformAnnotation(new RenameDesiredNames) +: collectNameOverrides(top).map {
+      case (m, nameOverride) => OverrideDesiredNameAnnotation(nameOverride, m.toTarget)
+    }
+  }
+}

src/main/scala/linting/Linter.scala

@@ -24,7 +24,8 @@ object Linter {
   // Update list for any new lint rule
   private[linting] lazy val linters = Seq(
     new rule.LintAnonymousRegisters,
-    new rule.LintTruncatingWidths
+    new rule.LintTruncatingWidths,
+    new rule.LintConflictingModuleNames
   )
 
   private [linting] lazy val lintMap = linters.flatMap {

src/main/scala/linting/rule/LintConflictingModuleNames.scala

@@ -0,0 +1,104 @@
+// See LICENSE.SiFive for license details.
+
+package freechips.rocketchip.linting
+package rule
+
+import firrtl._
+import firrtl.annotations.{IsModule, SingleTargetAnnotation, Target}
+import firrtl.ir._
+import firrtl.options.Dependency
+
+import freechips.rocketchip.transforms.naming.RenameDesiredNames
+
+import chisel3.aop.{Aspect, Select}
+import chisel3.RawModule
+
+import scala.collection.mutable
+
+/** Captures the original desired name for a module
+  */
+case class DesiredNameAnnotation(
+  desiredName: String,
+  target: IsModule
+) extends SingleTargetAnnotation[IsModule] {
+  def duplicate(newTarget: IsModule): DesiredNameAnnotation = {
+    this.copy(target = newTarget)
+  }
+}
+
+/** Collects [[DesiredNameAnnotation]]s for [[LintConflictingModuleNames]] to lint
+  */
+case object LintConflictingModuleNamesAspect extends Aspect[RawModule] {
+  def toAnnotation(top: RawModule): AnnotationSeq = {
+    Select.collectDeep(top) {
+      case m: RawModule => DesiredNameAnnotation(m.desiredName, m.toTarget)
+    }.toSeq
+  }
+}
+
+/** This LintRule checks for module name collisions
+  *
+  * Module name collisions occur when different [[Module]]s are annotated with
+  * [[DesiredNameAnnotation]]s that have the same desiredName. Module name
+  * conflicts will cause a [[LintViolation]].
+  */
+final class LintConflictingModuleNames extends LintRule {
+  val recommendedFix: String = "override desiredName based on module parameters ('override def desiredName = \"...\"') or use RenameModulesAspect"
+
+  val lintName: String = "conflicting-module-names"
+
+  // depends on DedupModules which comes from super[LintRule].optionalPrerequisites
+  override def optionalPrerequisites: Seq[Dependency[Transform]] =
+    Dependency[RenameDesiredNames] +: super.optionalPrerequisites
+
+  override def execute(state: CircuitState): CircuitState = {
+    val violations = new Violations()
+
+    val modMap = state.circuit.modules.collect {
+      case m: Module => m.name -> m
+    }.toMap
+
+    val desiredNameAnnos = state.annotations.collect {
+      case a: DesiredNameAnnotation if a.target.circuit == state.circuit.main => a
+    }
+
+    val moduleToDesiredName: mutable.Map[String, mutable.Set[String]] = mutable.Map()
+
+    val nameMap = desiredNameAnnos.groupBy(_.desiredName).mapValues { annos =>
+      annos.map(a => Target.referringModule(a.target).module).distinct.map { referringModule =>
+        require(modMap.contains(referringModule), s"ModuleNameAnnotations may not refer to blackboxes: $referringModule")
+        val desiredNames = moduleToDesiredName.getOrElseUpdate(referringModule, mutable.Set())
+        desiredNames += annos.head.desiredName
+        modMap(referringModule)
+      }
+    }
+
+    val conflictingDesiredNames = moduleToDesiredName.collect {
+      case kv@ (moduleName, desiredName) if desiredName.size > 1 => kv
+    }
+
+    require(conflictingDesiredNames.size == 0, {
+      val explanation = conflictingDesiredNames.map {
+        case (modName, desiredNames) => s"  ${modName}: ${desiredNames.mkString(", ")}"
+      }.mkString("\n")
+      s"Modules may not have more than one desiredName:\n${explanation}"
+    })
+
+    nameMap.foreach {
+      case (desiredName, modules) if modules.size > 1 =>
+        val msg = s"Module conflicts for desired name $desiredName: ${modules.map(_.name).mkString(", ")}"
+        val info = MultiInfo(modules.map(_.info))
+        val mods = violations.getOrElse((info, msg), Set.empty)
+        violations((info, msg)) = mods ++ modules.map(_.name)
+      case _ =>
+    }
+
+    val whitelist = collectWhitelist(state.annotations)
+    val errorList = violations.collect {
+      case ((info, message), mods) if !isWhitelisted(info, whitelist) => Violation(this, info, message, mods)
+    }.toSeq.sortBy { _.toString }
+    val newAnnos = errorList ++ state.annotations
+
+    state.copy(annotations = newAnnos)
+  }
+}

src/main/scala/stage/RocketChipCli.scala

@@ -10,7 +10,7 @@ trait RocketChipCli { this: Shell =>
   Seq(
     TopModuleAnnotation,
     ConfigsAnnotation,
-    OutputBaseNameAnnotation,
+    OutputBaseNameAnnotation
   )
     .foreach(_.addOptions(parser))
 

src/main/scala/transforms/naming/RenameDesiredNames.scala

@@ -0,0 +1,131 @@
+// See LICENSE.SiFive for license details.
+
+package freechips.rocketchip.transforms.naming
+
+import firrtl._
+import firrtl.annotations.{CircuitTarget, HasSerializationHints, IsModule, SingleTargetAnnotation, Target}
+import firrtl.ir._
+import firrtl.options.Dependency
+import firrtl.transforms.DedupModules
+
+import freechips.rocketchip.linting.rule.DesiredNameAnnotation
+
+import scala.collection.mutable
+
+/** A helper to rename modules in a [[Circuit]]
+  */
+object RenameModules {
+  def onStmt(moduleNameMap: Map[String, String])(stmt: Statement): Statement = stmt match {
+    case inst: WDefInstance if moduleNameMap.contains(inst.module) => inst.copy(module = moduleNameMap(inst.module))
+    case inst: DefInstance if moduleNameMap.contains(inst.module) => inst.copy(module = moduleNameMap(inst.module))
+    case other => other.mapStmt(onStmt(moduleNameMap))
+  }
+
+  /** Renames the modules in a circuit given a mapping of old names to new names
+    *
+    * @param nameMappings mapping of old to new names
+    * @param circuit the circuit to rename
+    */
+  def apply(nameMappings: Map[String, String], circuit: Circuit): Circuit = {
+    val modules = circuit.modules.map {
+      case mod: Module => mod.mapStmt(onStmt(nameMappings)).mapString(m => nameMappings.getOrElse(m, m))
+      case ext: ExtModule => ext
+    }
+    val main = nameMappings.getOrElse(circuit.main, circuit.main)
+    circuit.copy(main = main, modules = modules)
+  }
+}
+
+/** Specifies the desired name to rename the module to, overriding the Module.desiredName
+  */
+case class OverrideDesiredNameAnnotation(
+  desiredName: String,
+  target: IsModule
+) extends SingleTargetAnnotation[IsModule] {
+  def duplicate(newTarget: IsModule): OverrideDesiredNameAnnotation = {
+    this.copy(target = newTarget)
+  }
+}
+
+/** Renames modules based on their overridden desired names
+  *
+  * Desired module name overrides are specified by
+  * [[OverrideDesiredNameAnnotation]].
+  */
+class RenameDesiredNames extends Transform with DependencyAPIMigration {
+
+  override def prerequisites = Seq(Dependency[DedupModules])
+  override def optionalPrerequisiteOf = Seq(Dependency[VerilogEmitter])
+
+  override def invalidates(transform: Transform) = false
+
+  def execute(state: CircuitState): CircuitState = {
+    val modMap = state.circuit.modules.collect {
+      case m: Module => m.name -> m
+    }.toMap
+
+    val overrideDesiredNameAnnos = state.annotations.collect {
+      case a: OverrideDesiredNameAnnotation if a.target.circuit == state.circuit.main => a
+    }
+
+    val moduleToDesiredName: mutable.Map[String, mutable.Set[String]] = mutable.Map()
+
+    val nameMap = overrideDesiredNameAnnos.groupBy(_.desiredName).mapValues { annos =>
+      annos.map(a => Target.referringModule(a.target).module).distinct.map { referringModule =>
+        require(modMap.contains(referringModule), "ModuleNameAnnotations may not refer to blackboxes")
+        val desiredNames = moduleToDesiredName.getOrElseUpdate(referringModule, mutable.Set())
+        desiredNames += annos.head.desiredName
+        modMap(referringModule)
+      }
+    }
+
+    val conflictingDesiredNames = moduleToDesiredName.collect {
+      case kv@ (moduleName, desiredName) if desiredName.size > 1 => kv
+    }
+
+    require(conflictingDesiredNames.size == 0, {
+      val explanation = conflictingDesiredNames.map {
+        case (modName, desiredNames) => s"  ${modName}: ${desiredNames.mkString(", ")}"
+      }.mkString("\n")
+      s"Modules may not have more than one desiredName:\n${explanation}"
+    })
+
+    val renamedDesiredNames = mutable.Set[String]()
+    val nameMappings = nameMap.flatMap { case (desiredName, modules) =>
+      if (modules.size == 1) {
+        renamedDesiredNames += desiredName
+        Some(modules.head.name -> desiredName)
+      } else {
+        None
+      }
+    }.toMap
+
+    val finalNames = state.circuit.modules.map {
+      case m: Module if nameMappings.contains(m.name) => nameMappings(m.name)
+      case m: DefModule => m.name
+    }
+    val renameConflicts = finalNames.groupBy(identity).collect {
+      case (_, conflicts) if conflicts.size > 1 => conflicts.head
+    }
+    require(renameConflicts.size == 0, s"desired names conflict with pre-existing module names: ${renameConflicts.mkString(", ")}")
+
+    val circuit = RenameModules(nameMappings, state.circuit)
+
+    val newMain = CircuitTarget(circuit.main)
+    val oldMain = CircuitTarget(state.circuit.main)
+    val renames = RenameMap()
+    nameMappings.foreach { case (from, to) =>
+      renames.record(oldMain.module(from), newMain.module(to))
+    }
+
+    // delete override annotations and rename desired name annotations for ones that were renamed
+    val newAnnos = state.annotations.flatMap {
+      case a: OverrideDesiredNameAnnotation if renamedDesiredNames(a.desiredName) => None
+      case a: DesiredNameAnnotation if nameMappings.contains(Target.referringModule(a.target).module) =>
+        Some(a.copy(desiredName = nameMappings(Target.referringModule(a.target).module)))
+      case a => Some(a)
+    }
+
+    state.copy(circuit = circuit, annotations = newAnnos, renames = Some(renames))
+  }
+}