From 69e27b2fd9e02d4e3a024eec0cafce5b4b46c10a Mon Sep 17 00:00:00 2001 From: Adam Izraelevitz Date: Mon, 14 Sep 2020 10:17:49 -0700 Subject: Documentation and minor plugin changes. (#1573) * Added documentation. Bugfix in plugin. Moved plugin APIs to separate package * Revert reg naming behavior (omit underscore) * Added documentation and a test * Addressed reviewer feedback.--- plugin/src/main/resources/scalac-plugin.xml | 2 +- .../chisel3/internal/plugin/ChiselPlugin.scala | 138 +++++++++++++++++++++ .../scala-2.12/chisel3/plugin/ChiselPlugin.scala | 138 --------------------- 3 files changed, 139 insertions(+), 139 deletions(-) create mode 100644 plugin/src/main/scala-2.12/chisel3/internal/plugin/ChiselPlugin.scala delete mode 100644 plugin/src/main/scala-2.12/chisel3/plugin/ChiselPlugin.scala (limited to 'plugin') diff --git a/plugin/src/main/resources/scalac-plugin.xml b/plugin/src/main/resources/scalac-plugin.xml index b2b44fc6..abe51d12 100644 --- a/plugin/src/main/resources/scalac-plugin.xml +++ b/plugin/src/main/resources/scalac-plugin.xml @@ -1,4 +1,4 @@ chiselplugin - chisel3.plugin.ChiselPlugin + chisel3.internal.plugin.ChiselPlugin diff --git a/plugin/src/main/scala-2.12/chisel3/internal/plugin/ChiselPlugin.scala b/plugin/src/main/scala-2.12/chisel3/internal/plugin/ChiselPlugin.scala new file mode 100644 index 00000000..2197430c --- /dev/null +++ b/plugin/src/main/scala-2.12/chisel3/internal/plugin/ChiselPlugin.scala @@ -0,0 +1,138 @@ +// See LICENSE for license details. + +package chisel3.internal.plugin + +import scala.tools.nsc +import nsc.{Global, Phase} +import nsc.plugins.Plugin +import nsc.plugins.PluginComponent +import scala.reflect.internal.Flags +import scala.tools.nsc.transform.TypingTransformers + +// The plugin to be run by the Scala compiler during compilation of Chisel code +class ChiselPlugin(val global: Global) extends Plugin { + val name = "chiselplugin" + val description = "Plugin for Chisel 3 Hardware Description Language" + val components: List[PluginComponent] = List[PluginComponent](new ChiselComponent(global)) +} + +// The component of the chisel plugin. Not sure exactly what the difference is between +// a Plugin and a PluginComponent. +class ChiselComponent(val global: Global) extends PluginComponent with TypingTransformers { + import global._ + val runsAfter: List[String] = List[String]("typer") + val phaseName: String = "chiselcomponent" + def newPhase(_prev: Phase): ChiselComponentPhase = new ChiselComponentPhase(_prev) + class ChiselComponentPhase(prev: Phase) extends StdPhase(prev) { + override def name: String = phaseName + def apply(unit: CompilationUnit): Unit = { + // This plugin doesn't work on Scala 2.11. Rather than complicate the sbt build flow, + // instead we just check the version and if its an early Scala version, the plugin does nothing + if(scala.util.Properties.versionNumberString.split('.')(1).toInt >= 12) { + unit.body = new MyTypingTransformer(unit).transform(unit.body) + } + } + } + + class MyTypingTransformer(unit: CompilationUnit) + extends TypingTransformer(unit) { + + // Determines if the chisel plugin should match on this type + def shouldMatch(q: Type, bases: Seq[Tree]): Boolean = { + + // If subtype of Data or BaseModule, its a match! + def terminate(t: Type): Boolean = bases.exists { base => t <:< inferType(base) } + + // Recurse through subtype hierarchy finding containers + // Seen is only updated when we recurse into type parameters, thus it is typically small + def recShouldMatch(s: Type, seen: Set[Type]): Boolean = { + def outerMatches(t: Type): Boolean = { + val str = t.toString + str.startsWith("Option[") || str.startsWith("Iterable[") + } + if (terminate(s)) { + true + } else if (seen.contains(s)) { + false + } else if (outerMatches(s)) { + // These are type parameters, loops *are* possible here + recShouldMatch(s.typeArgs.head, seen + s) + } else { + // This is the standard inheritance hierarchy, Scalac catches loops here + s.parents.exists( p => recShouldMatch(p, seen) ) + } + } + + // If doesn't match container pattern, exit early + def earlyExit(t: Type): Boolean = { + !(t.matchesPattern(inferType(tq"Iterable[_]")) || t.matchesPattern(inferType(tq"Option[_]"))) + } + + // First check if a match, then check early exit, then recurse + if(terminate(q)){ + true + } else if(earlyExit(q)) { + false + } else { + recShouldMatch(q, Set.empty) + } + } + + // Given a type tree, infer the type and return it + def inferType(t: Tree): Type = localTyper.typed(t, nsc.Mode.TYPEmode).tpe + + // Indicates whether a ValDef is properly formed to get name + def okVal(dd: ValDef, bases: Tree*): Boolean = { + + // These were found through trial and error + def okFlags(mods: Modifiers): Boolean = { + val badFlags = Set( + Flag.PARAM, + Flag.SYNTHETIC, + Flag.DEFERRED, + Flags.TRIEDCOOKING, + Flags.CASEACCESSOR, + Flags.PARAMACCESSOR + ) + badFlags.forall{ x => !mods.hasFlag(x)} + } + + // Ensure expression isn't null, as you can't call `null.autoName("myname")` + val isNull = dd.rhs match { + case Literal(Constant(null)) => true + case _ => false + } + okFlags(dd.mods) && shouldMatch(inferType(dd.tpt), bases) && !isNull && dd.rhs != EmptyTree + } + + // Whether this val is directly enclosed by a Bundle type + def inBundle(dd: ValDef): Boolean = { + dd.symbol.logicallyEnclosingMember.thisType <:< inferType(tq"chisel3.Bundle") + } + + // Method called by the compiler to modify source tree + override def transform(tree: Tree): Tree = tree match { + // If a Data and in a Bundle, just get the name but not a prefix + case dd @ ValDef(mods, name, tpt, rhs) if okVal(dd, tq"chisel3.Data") && inBundle(dd) => + val TermName(str: String) = name + val newRHS = transform(rhs) + val named = q"chisel3.internal.plugin.autoNameRecursively($str, $newRHS)" + treeCopy.ValDef(dd, mods, name, tpt, localTyper typed named) + // If a Data or a Memory, get the name and a prefix + case dd @ ValDef(mods, name, tpt, rhs) if okVal(dd, tq"chisel3.Data", tq"chisel3.MemBase[_]") => + val TermName(str: String) = name + val newRHS = transform(rhs) + val prefixed = q"chisel3.experimental.prefix.apply[$tpt](name=$str)(f=$newRHS)" + val named = q"chisel3.internal.plugin.autoNameRecursively($str, $prefixed)" + treeCopy.ValDef(dd, mods, name, tpt, localTyper typed named) + // If an instance, just get a name but no prefix + case dd @ ValDef(mods, name, tpt, rhs) if okVal(dd, tq"chisel3.experimental.BaseModule") => + val TermName(str: String) = name + val newRHS = transform(rhs) + val named = q"chisel3.internal.plugin.autoNameRecursively($str, $newRHS)" + treeCopy.ValDef(dd, mods, name, tpt, localTyper typed named) + // Otherwise, continue + case _ => super.transform(tree) + } + } +} diff --git a/plugin/src/main/scala-2.12/chisel3/plugin/ChiselPlugin.scala b/plugin/src/main/scala-2.12/chisel3/plugin/ChiselPlugin.scala deleted file mode 100644 index 3b3b52e9..00000000 --- a/plugin/src/main/scala-2.12/chisel3/plugin/ChiselPlugin.scala +++ /dev/null @@ -1,138 +0,0 @@ -// See LICENSE for license details. - -package chisel3.plugin - -import scala.tools.nsc -import nsc.{Global, Phase} -import nsc.plugins.Plugin -import nsc.plugins.PluginComponent -import scala.reflect.internal.Flags -import scala.tools.nsc.transform.TypingTransformers - -// The plugin to be run by the Scala compiler during compilation of Chisel code -class ChiselPlugin(val global: Global) extends Plugin { - val name = "chiselplugin" - val description = "Plugin for Chisel 3 Hardware Description Language" - val components = List[PluginComponent](new ChiselComponent(global)) -} - -// The component of the chisel plugin. Not sure exactly what the difference is between -// a Plugin and a PluginComponent. -class ChiselComponent(val global: Global) extends PluginComponent with TypingTransformers { - import global._ - val runsAfter = List[String]("typer") - val phaseName: String = "chiselcomponent" - def newPhase(_prev: Phase): ChiselComponentPhase = new ChiselComponentPhase(_prev) - class ChiselComponentPhase(prev: Phase) extends StdPhase(prev) { - override def name: String = phaseName - def apply(unit: CompilationUnit): Unit = { - // This plugin doesn't work on Scala 2.11. Rather than complicate the sbt build flow, - // instead we just check the version and if its an early Scala version, the plugin does nothing - if(scala.util.Properties.versionNumberString.split('.')(1).toInt >= 12) { - unit.body = new MyTypingTransformer(unit).transform(unit.body) - } - } - } - - class MyTypingTransformer(unit: CompilationUnit) - extends TypingTransformer(unit) { - - // Determines if the chisel plugin should match on this type - def shouldMatch(q: Type, bases: Seq[Tree]): Boolean = { - - // If subtype of Data or BaseModule, its a match! - def terminate(t: Type): Boolean = bases.exists { base => t <:< inferType(base) } - - // Recurse through subtype hierarchy finding containers - // Seen is only updated when we recurse into type parameters, thus it is typically small - def recShouldMatch(s: Type, seen: Set[Type]): Boolean = { - def outerMatches(t: Type): Boolean = { - val str = t.toString - str.startsWith("Option[") || str.startsWith("Iterable[") - } - if (terminate(s)) { - true - } else if (seen.contains(s)) { - false - } else if (outerMatches(s)) { - // These are type parameters, loops *are* possible here - recShouldMatch(s.typeArgs.head, seen + s) - } else { - // This is the standard inheritance hierarchy, Scalac catches loops here - s.parents.exists( p => recShouldMatch(p, seen) ) - } - } - - // If doesn't match container pattern, exit early - def earlyExit(t: Type): Boolean = { - !(t.matchesPattern(inferType(tq"Iterable[_]")) || t.matchesPattern(inferType(tq"Option[_]"))) - } - - // First check if a match, then check early exit, then recurse - if(terminate(q)){ - true - } else if(earlyExit(q)) { - false - } else { - recShouldMatch(q, Set.empty) - } - } - - // Given a type tree, infer the type and return it - def inferType(t: Tree): Type = localTyper.typed(t, nsc.Mode.TYPEmode).tpe - - // Indicates whether a ValDef is properly formed to get name - def okVal(dd: ValDef, bases: Tree*): Boolean = { - - // These were found through trial and error - def okFlags(mods: Modifiers): Boolean = { - val badFlags = Set( - Flag.PARAM, - Flag.SYNTHETIC, - Flag.DEFERRED, - Flags.TRIEDCOOKING, - Flags.CASEACCESSOR, - Flags.PARAMACCESSOR - ) - badFlags.forall{ x => !mods.hasFlag(x)} - } - - // Ensure expression isn't null, as you can't call `null.autoName("myname")` - val isNull = dd.rhs match { - case Literal(Constant(null)) => true - case _ => false - } - okFlags(dd.mods) && shouldMatch(inferType(dd.tpt), bases) && !isNull && dd.rhs != EmptyTree - } - - // Whether this val is directly enclosed by a Bundle type - def inBundle(dd: ValDef): Boolean = { - dd.symbol.logicallyEnclosingMember.thisType <:< inferType(tq"chisel3.Bundle") - } - - // Method called by the compiler to modify source tree - override def transform(tree: Tree): Tree = tree match { - // If a Data and in a Bundle, just get the name but not a prefix - case dd @ ValDef(mods, name, tpt, rhs) if okVal(dd, tq"chisel3.Data") && inBundle(dd) => - val TermName(str: String) = name - val newRHS = super.transform(rhs) - val named = q"chisel3.experimental.autoNameRecursively($str, $newRHS)" - treeCopy.ValDef(dd, mods, name, tpt, localTyper typed named) - // If a Data or a Memory, get the name and a prefix - case dd @ ValDef(mods, name, tpt, rhs) if okVal(dd, tq"chisel3.Data", tq"chisel3.MemBase[_]") => - val TermName(str: String) = name - val newRHS = super.transform(rhs) - val prefixed = q"chisel3.experimental.prefix.apply[$tpt](name=$str)(f=$newRHS)" - val named = q"chisel3.experimental.autoNameRecursively($str, $prefixed)" - treeCopy.ValDef(dd, mods, name, tpt, localTyper typed named) - // If an instance, just get a name but no prefix - case dd @ ValDef(mods, name, tpt, rhs) if okVal(dd, tq"chisel3.experimental.BaseModule") => - val TermName(str: String) = name - val newRHS = super.transform(rhs) - val named = q"chisel3.experimental.autoNameRecursively($str, $newRHS)" - treeCopy.ValDef(dd, mods, name, tpt, localTyper typed named) - // Otherwise, continue - case _ => super.transform(tree) - } - } -} -- cgit v1.2.3