ExtModule's lacked support built in support for providing (#1154)

* ExtModule's lacked support built in support for providing
the verilog source. This changes creates traits that
can be used with ExtModule to provide the support currently found in
BlackBox

- Add support for ExtModule helpers
  - HasExtModuleResource to use addResource
  - HasExtModuleInline to use setInline
  - HasExtModulePath to use addPath
- Add tests of the above support.
  - Note: These tests use Stage instead of Driver
- Added ScalaDoc for HasBlackBoxInline#setInline

* Fix the danged trailing commas.

* Change to use `.transform` as the correct API for `ChiselStage`

2 files changed, 66 insertions, 0 deletions

diff --git a/src/main/scala/chisel3/util/BlackBoxUtils.scala b/src/main/scala/chisel3/util/BlackBoxUtils.scala
index 74d99ff8..21bd4dfa 100644
--- a/src/main/scala/chisel3/util/BlackBoxUtils.scala
+++ b/src/main/scala/chisel3/util/BlackBoxUtils.scala
@@ -32,6 +32,11 @@ trait HasBlackBoxResource extends BlackBox {
 trait HasBlackBoxInline extends BlackBox {
   self: BlackBox =>
 
+  /** Creates a black box verilog file, from the contents of a local string
+    *
+    * @param blackBoxName   The black box module name, to create filename
+    * @param blackBoxInline The black box contents
+    */
   def setInline(blackBoxName: String, blackBoxInline: String): Unit = {
     val anno = new ChiselAnnotation with RunFirrtlTransform {
       def toFirrtl = BlackBoxInlineAnno(self.toNamed, blackBoxName, blackBoxInline)
diff --git a/src/main/scala/chisel3/util/ExtModuleUtils.scala b/src/main/scala/chisel3/util/ExtModuleUtils.scala
new file mode 100644
index 00000000..831639be
--- /dev/null
+++ b/src/main/scala/chisel3/util/ExtModuleUtils.scala
@@ -0,0 +1,61 @@
+// See LICENSE for license details.
+
+package chisel3.util
+
+import chisel3.experimental.{ChiselAnnotation, ExtModule, RunFirrtlTransform}
+import firrtl.transforms.{BlackBoxPathAnno, BlackBoxResourceAnno, BlackBoxInlineAnno, BlackBoxSourceHelper}
+
+trait HasExtModuleResource extends ExtModule {
+  self: ExtModule =>
+
+  /** Copies a resource file to the target directory
+    *
+    * Resource files are located in project_root/src/main/resources/.
+    * Example of adding the resource file project_root/src/main/resources/blackbox.v:
+    * {{{
+    * addResource("/blackbox.v")
+    * }}}
+    */
+  def addResource(blackBoxResource: String): Unit = {
+    val anno = new ChiselAnnotation with RunFirrtlTransform {
+      def toFirrtl = BlackBoxResourceAnno(self.toNamed, blackBoxResource)
+      def transformClass = classOf[BlackBoxSourceHelper]
+    }
+    chisel3.experimental.annotate(anno)
+  }
+}
+
+trait HasExtModuleInline extends ExtModule {
+  self: ExtModule =>
+
+  /** Creates a black box verilog file, from the contents of a local string
+    *
+    * @param blackBoxName   The black box module name, to create filename
+    * @param blackBoxInline The black box contents
+    */
+  def setInline(blackBoxName: String, blackBoxInline: String): Unit = {
+    val anno = new ChiselAnnotation with RunFirrtlTransform {
+      def toFirrtl = BlackBoxInlineAnno(self.toNamed, blackBoxName, blackBoxInline)
+      def transformClass = classOf[BlackBoxSourceHelper]
+    }
+    chisel3.experimental.annotate(anno)
+  }
+}
+
+trait HasExtModulePath extends ExtModule {
+  self: ExtModule =>
+
+  /** Copies a file to the target directory
+    *
+    * This works with absolute and relative paths. Relative paths are relative
+    * to the current working directory, which is generally not the same as the
+    * target directory.
+    */
+  def addPath(blackBoxPath: String): Unit = {
+    val anno = new ChiselAnnotation with RunFirrtlTransform {
+      def toFirrtl = BlackBoxPathAnno(self.toNamed, blackBoxPath)
+      def transformClass = classOf[BlackBoxSourceHelper]
+    }
+    chisel3.experimental.annotate(anno)
+  }
+}