Add HasBlackBoxPath to BlackBoxUtils.scala (#903)

* Add HasBlackBoxPath trait
* Use 'setResource' instead of 'addResource'
* Add ScalaDoc

1 files changed, 31 insertions, 2 deletions

diff --git a/src/main/scala/chisel3/util/BlackBoxUtils.scala b/src/main/scala/chisel3/util/BlackBoxUtils.scala
index fa62184a..7f9c117f 100644
--- a/src/main/scala/chisel3/util/BlackBoxUtils.scala
+++ b/src/main/scala/chisel3/util/BlackBoxUtils.scala
@@ -4,12 +4,23 @@ package chisel3.util
 
 import chisel3._
 import chisel3.experimental.{ChiselAnnotation, RunFirrtlTransform}
-import firrtl.transforms.{BlackBoxResourceAnno, BlackBoxInlineAnno, BlackBoxSourceHelper}
+import firrtl.transforms.{BlackBoxPathAnno, BlackBoxResourceAnno, BlackBoxInlineAnno, BlackBoxSourceHelper}
 
 trait HasBlackBoxResource extends BlackBox {
   self: BlackBox =>
 
-  def setResource(blackBoxResource: String): Unit = {
+  @deprecated("Use addResource instead", "3.2")
+  def setResource(blackBoxResource: String): Unit = addResource(blackBoxResource)
+
+  /** 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]
@@ -29,3 +40,21 @@ trait HasBlackBoxInline extends BlackBox {
     chisel3.experimental.annotate(anno)
   }
 }
+
+trait HasBlackBoxPath extends BlackBox {
+  self: BlackBox =>
+
+  /** 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)
+  }
+}