Support for creating chisel annotations that are consumed by firrtl (#393)

* Support for creating chisel annotations that are consumed by firrtl
Update annotation serialization in Driver
Add DiamondAnnotation Spec that illustrates how to do simple annotations
frontEnd must have dependency on firrtl
Add annotation method to Module
Circuit has extra optional parameter that is Seq of Annotations
In Builder add annotation buffer to DynamicContext to store annotations created in modules
Added explicit types on naming api methods to avoid type confusion
Because some names are not available until elaboration create intermediate ChiselAnnotation that
gets turned into a firrtl Annotation after elaboration
In execute pass firrtl text and annotation to firrtl are now passed in through optionManager, though
intermediate file .fir and .anno files are still created for inspection and/or later use

* Somehow missed ChiselAnnotation

* fixes for Jack's review of PR

4 files changed, 45 insertions, 7 deletions

diff --git a/chiselFrontend/src/main/scala/chisel3/core/ChiselAnnotation.scala b/chiselFrontend/src/main/scala/chisel3/core/ChiselAnnotation.scala
new file mode 100644
index 00000000..73573bb1
--- /dev/null
+++ b/chiselFrontend/src/main/scala/chisel3/core/ChiselAnnotation.scala
@@ -0,0 +1,30 @@
+// See LICENSE for license details.
+
+package chisel3.core
+
+import chisel3.internal.InstanceId
+import firrtl.Transform
+import firrtl.annotations.{Annotation, CircuitName, ComponentName, ModuleName}
+
+/**
+  * This is a stand-in for the firrtl.Annotations.Annotation because at the time this annotation
+  * is created the component cannot be resolved, into a targetString.  Resolution can only
+  * happen after the circuit is elaborated
+  * @param component       A chisel thingy to be annotated, could be module, wire, reg, etc.
+  * @param transformClass  A fully-qualified class name of the transformation pass
+  * @param value           A string value to be used by the transformation pass
+  */
+case class ChiselAnnotation(component: InstanceId, transformClass: Class[_ <: Transform], value: String) {
+  def toFirrtl: Annotation = {
+    val circuitName = CircuitName(component.pathName.split("""\.""").head)
+    component match {
+      case m: Module =>
+        Annotation(
+          ModuleName(m.name, circuitName), transformClass, value)
+      case _ =>
+        Annotation(
+          ComponentName(
+            component.instanceName, ModuleName(component.parentModName, circuitName)), transformClass, value)
+    }
+  }
+}
diff --git a/chiselFrontend/src/main/scala/chisel3/core/Module.scala b/chiselFrontend/src/main/scala/chisel3/core/Module.scala
index bd406529..76a3b240 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/Module.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/Module.scala
@@ -14,7 +14,7 @@ object Module {
   /** A wrapper method that all Module instantiations must be wrapped in
     * (necessary to help Chisel track internal state).
     *
-    * @param m the Module being created
+    * @param bc the Module being created
     *
     * @return the input module `m` with Chisel metadata properly set
     */
@@ -85,6 +85,10 @@ extends HasId {
     iodef
   }
 
+  def annotate(annotation: ChiselAnnotation): Unit = {
+    Builder.annotations += annotation
+  }
+
   private[core] var ioDefined: Boolean = false
 
   /**
diff --git a/chiselFrontend/src/main/scala/chisel3/internal/Builder.scala b/chiselFrontend/src/main/scala/chisel3/internal/Builder.scala
index cf86b0e7..7a77763b 100644
--- a/chiselFrontend/src/main/scala/chisel3/internal/Builder.scala
+++ b/chiselFrontend/src/main/scala/chisel3/internal/Builder.scala
@@ -108,22 +108,22 @@ private[chisel3] trait HasId extends InstanceId {
   private[chisel3] def getRef: Arg = _ref.get
 
   // Implementation of public methods.
-  def instanceName = _parent match {
+  def instanceName: String = _parent match {
     case Some(p) => p._component match {
       case Some(c) => getRef fullName c
       case None => throwException("signalName/pathName should be called after circuit elaboration")
     }
     case None => throwException("this cannot happen")
   }
-  def pathName = _parent match {
+  def pathName: String = _parent match {
     case None => instanceName
     case Some(p) => s"${p.pathName}.$instanceName"
   }
-  def parentPathName = _parent match {
+  def parentPathName: String = _parent match {
     case Some(p) => p.pathName
     case None => throwException(s"$instanceName doesn't have a parent")
   }
-  def parentModName = _parent match {
+  def parentModName: String = _parent match {
     case Some(p) => p.name
     case None => throwException(s"$instanceName doesn't have a parent")
   }
@@ -145,6 +145,7 @@ private[chisel3] class DynamicContext() {
   val idGen = new IdGen
   val globalNamespace = new Namespace(None, Set())
   val components = ArrayBuffer[Component]()
+  val annotations = ArrayBuffer[ChiselAnnotation]()
   var currentModule: Option[Module] = None
   // Set by object Module.apply before calling class Module constructor
   // Used to distinguish between no Module() wrapping, multiple wrappings, and rewrapping
@@ -161,6 +162,7 @@ private[chisel3] object Builder {
   def idGen: IdGen = dynamicContext.idGen
   def globalNamespace: Namespace = dynamicContext.globalNamespace
   def components: ArrayBuffer[Component] = dynamicContext.components
+  def annotations: ArrayBuffer[ChiselAnnotation] = dynamicContext.annotations
 
   def currentModule: Option[Module] = dynamicContext.currentModule
   def currentModule_=(target: Option[Module]): Unit = {
@@ -206,7 +208,7 @@ private[chisel3] object Builder {
       errors.checkpoint()
       errors.info("Done elaborating.")
 
-      Circuit(components.last.name, components)
+      Circuit(components.last.name, components, annotations.map(_.toFirrtl))
     }
   }
 }
diff --git a/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala b/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
index 699cc13c..50400034 100644
--- a/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
+++ b/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
@@ -7,6 +7,8 @@ import core._
 import chisel3.internal._
 import chisel3.internal.sourceinfo.{SourceInfo, NoSourceInfo}
 
+import _root_.firrtl.annotations.Annotation
+
 case class PrimOp(val name: String) {
   override def toString: String = name
 }
@@ -273,4 +275,4 @@ abstract class Component extends Arg {
 case class DefModule(id: Module, name: String, ports: Seq[Port], commands: Seq[Command]) extends Component
 case class DefBlackBox(id: Module, name: String, ports: Seq[Port], params: Map[String, Param]) extends Component
 
-case class Circuit(name: String, components: Seq[Component])
+case class Circuit(name: String, components: Seq[Component], annotations: Seq[Annotation] = Seq.empty)