Add HasBlackBoxPath to BlackBoxUtils.scala (#903)

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

2 files changed, 67 insertions, 4 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)
+  }
+}
diff --git a/src/test/scala/chiselTests/BlackBoxImpl.scala b/src/test/scala/chiselTests/BlackBoxImpl.scala
index a6784909..fbfce58b 100644
--- a/src/test/scala/chiselTests/BlackBoxImpl.scala
+++ b/src/test/scala/chiselTests/BlackBoxImpl.scala
@@ -5,7 +5,7 @@ package chiselTests
 import java.io.File
 
 import chisel3._
-import chisel3.util.{HasBlackBoxInline, HasBlackBoxResource}
+import chisel3.util.{HasBlackBoxInline, HasBlackBoxResource, HasBlackBoxPath}
 import firrtl.FirrtlExecutionSuccess
 import org.scalacheck.Test.Failed
 import org.scalatest.{FreeSpec, Matchers, Succeeded}
@@ -47,7 +47,16 @@ class BlackBoxMinus extends HasBlackBoxResource {
     val in2 = Input(UInt(16.W))
     val out = Output(UInt(16.W))
   })
-  setResource("/chisel3/BlackBoxTest.v")
+  addResource("/chisel3/BlackBoxTest.v")
+}
+
+class BlackBoxMinusPath extends HasBlackBoxPath {
+  val io = IO(new Bundle {
+    val in1 = Input(UInt(16.W))
+    val in2 = Input(UInt(16.W))
+    val out = Output(UInt(16.W))
+  })
+  addPath(new File("src/test/resources/chisel3/BlackBoxTest.v").getCanonicalPath)
 }
 
 class UsesBlackBoxMinusViaResource extends Module {
@@ -64,6 +73,20 @@ class UsesBlackBoxMinusViaResource extends Module {
   io.out := mod0.io.out
 }
 
+class UsesBlackBoxMinusViaPath extends Module {
+  val io = IO(new Bundle {
+    val in1 = Input(UInt(16.W))
+    val in2 = Input(UInt(16.W))
+    val out = Output(UInt(16.W))
+  })
+
+  val mod0 = Module(new BlackBoxMinusPath)
+
+  mod0.io.in1 := io.in1
+  mod0.io.in2 := io.in2
+  io.out := mod0.io.out
+}
+
 class BlackBoxImplSpec extends FreeSpec with Matchers {
   val targetDir = "test_run_dir"
   "BlackBox can have verilator source implementation" - {
@@ -89,5 +112,16 @@ class BlackBoxImplSpec extends FreeSpec with Matchers {
           Failed
       }
     }
+    "Implementations can be contained in arbitrary files" in {
+      Driver.execute(Array("-X", "low", "--target-dir", targetDir), () => new UsesBlackBoxMinusViaPath) match {
+        case ChiselExecutionSuccess(_, _, Some(_: FirrtlExecutionSuccess)) =>
+          val verilogOutput = new File(targetDir, "BlackBoxTest.v")
+          verilogOutput.exists() should be (true)
+          verilogOutput.delete()
+          Succeeded
+        case _ =>
+          Failed
+      }
+    }
   }
 }