Support for load memory annotations in chisel (#833)

* Support for load memory annotations in chisel
This PR
 * Delays the BlackBoxSourceHelper transformation to the Emitter stage of the VerilogCompiler
   * remove from VerilogCompiler
   * move to VerilogEmitter
 * Changes the verilog emitter to allow programmatic access to the verilog module declaration
   * Creating a bindable module requires headers to match
 * Provides a unit test that shows how to generate a bindable module.

* Binding support
Treadle needed LoadMemoryAnnotation to be in firrtl instead of chisel in order to recognize the annotations and use them for memory loading

* Binding support
- Fixed bug that handled suffixes on memory initializing files

* Binding support
- Add a bit more doc to the API provided by the VerilogRenderer

1 files changed, 65 insertions, 0 deletions

diff --git a/src/main/scala/firrtl/annotations/LoadMemoryAnnotation.scala b/src/main/scala/firrtl/annotations/LoadMemoryAnnotation.scala
new file mode 100644
index 00000000..a5ba22dd
--- /dev/null
+++ b/src/main/scala/firrtl/annotations/LoadMemoryAnnotation.scala
@@ -0,0 +1,65 @@
+// See LICENSE for license details.
+
+package firrtl.annotations
+
+/**
+  * Enumeration of the two types of readmem statements available in verilog
+  */
+object MemoryLoadFileType extends Enumeration {
+  type FileType = Value
+
+  val Hex:    Value = Value("h")
+  val Binary: Value = Value("b")
+}
+
+/**
+  * Firrtl implementation for load memory
+  * @param target        memory to load
+  * @param fileName      name of input file
+  * @param hexOrBinary   use $readmemh or $readmemb
+  */
+case class LoadMemoryAnnotation(
+  target: ComponentName,
+  fileName: String,
+  hexOrBinary: MemoryLoadFileType.FileType = MemoryLoadFileType.Hex,
+  originalMemoryNameOpt: Option[String] = None
+) extends SingleTargetAnnotation[Named] {
+
+  val (prefix, suffix) = {
+    fileName.split("""\.""").toList match {
+      case Nil =>
+        throw new Exception(s"empty filename not allowed in LoadMemoryAnnotation")
+      case name :: Nil =>
+        (name, "")
+      case other =>
+        (other.reverse.tail.reverse.mkString("."), "." + other.last)
+    }
+  }
+
+  def getFileName: String = {
+    originalMemoryNameOpt match {
+      case Some(originalMemoryName) =>
+        if(target.name == originalMemoryName) {
+          prefix + suffix
+        }
+        else {
+          prefix + target.name.drop(originalMemoryName.length) + suffix
+        }
+      case _ =>
+        fileName
+    }
+  }
+
+  def getSuffix: String = suffix
+
+  def duplicate(newNamed: Named): LoadMemoryAnnotation = {
+    newNamed match {
+      case componentName: ComponentName =>
+        this.copy(target = componentName, originalMemoryNameOpt = Some(target.name))
+      case _ =>
+        throw new Exception(s"Cannot annotate anything but a memory, invalid target ${newNamed.serialize}")
+    }
+  }
+}
+
+