Rebuild jars when sv/v files are changed + Add documentation on blackboxes

common.mk

@@ -119,12 +119,12 @@ $(BOOTROM_TARGETS): $(build_dir)/bootrom.%.img: $(TESTCHIP_RSRCS_DIR)/testchipip
 #########################################################################################
 # compile scala jars
 #########################################################################################
-$(CHIPYARD_CLASSPATH_TARGETS) &: $(CHIPYARD_SCALA_SOURCES) $(SCALA_BUILDTOOL_DEPS)
+$(CHIPYARD_CLASSPATH_TARGETS) &: $(CHIPYARD_SCALA_SOURCES) $(SCALA_BUILDTOOL_DEPS) $(CHIPYARD_VLOG_SOURCES)
 	mkdir -p $(dir $@)
 	$(call run_sbt_assembly,$(SBT_PROJECT),$(CHIPYARD_CLASSPATH))
 
 # order only dependency between sbt runs needed to avoid concurrent sbt runs
-$(TAPEOUT_CLASSPATH_TARGETS) &: $(BARSTOOLS_SCALA_SOURCES) $(SCALA_BUILDTOOL_DEPS) | $(CHIPYARD_CLASSPATH_TARGETS)
+$(TAPEOUT_CLASSPATH_TARGETS) &: $(BARSTOOLS_SCALA_SOURCES) $(SCALA_BUILDTOOL_DEPS) $(BARSTOOLS_VLOG_SOURCES) | $(CHIPYARD_CLASSPATH_TARGETS)
 	mkdir -p $(dir $@)
 	$(call run_sbt_assembly,tapeout,$(TAPEOUT_CLASSPATH))
 
@@ -227,7 +227,7 @@ $(FINAL_ANNO_FILE): $(EXTRA_ANNO_FILE) $(SFC_EXTRA_ANNO_FILE) $(SFC_LEVEL)
 	touch $@
 
 $(SFC_MFC_TARGETS) &: private TMP_DIR := $(shell mktemp -d -t cy-XXXXXXXX)
-$(SFC_MFC_TARGETS) &: $(TAPEOUT_CLASSPATH_TARGETS) $(FIRRTL_FILE) $(FINAL_ANNO_FILE) $(SFC_LEVEL) $(EXTRA_FIRRTL_OPTIONS) $(MFC_LOWERING_OPTIONS) $(CHIPYARD_VLOG_SOURCES) $(BARSTOOLS_VLOG_SOURCES)
+$(SFC_MFC_TARGETS) &: $(TAPEOUT_CLASSPATH_TARGETS) $(FIRRTL_FILE) $(FINAL_ANNO_FILE) $(SFC_LEVEL) $(EXTRA_FIRRTL_OPTIONS) $(MFC_LOWERING_OPTIONS)
 	rm -rf $(GEN_COLLATERAL_DIR)
 	$(call run_jar_scala_main,$(TAPEOUT_CLASSPATH),barstools.tapeout.transforms.GenerateModelStageMain,\
 		--no-dedup \

docs/Customization/Incorporating-Verilog-Blocks.rst

@@ -161,4 +161,31 @@ transformed or augmented by any Chipyard FIRRTL transform.
 As mentioned earlier in this section, ``BlackBox`` resource files must
 be integrated into the build process, so any project providing
 ``BlackBox`` resources must be made visible to the ``tapeout`` project
-in ``build.sbt``
+in ``build.sbt``.
+
+Differences between ``HasBlackBoxPath`` and ``HasBlackBoxResource``
+-------------------------------------------------------------------
+
+Chisel provides two mechanisms for integrating blackbox files into a Chisel project that work slightly differently in Chipyard: ``HasBlackBoxPath`` and ``HasBlackBoxResource``.
+
+``HasBlackBoxResource`` incorporates extra files by looking up the relative path of the files within the ``src/main/resources`` area of project.
+This requires that the file added by ``addResource`` is present in the ``src/main/resources`` area and is **not** auto-generated (the file is static throughout the lifetime of generating RTL).
+This is due to the fact that when the Chisel sources are compiled they are put in a ``jar`` file, along with the ``src/main/resources`` area, and that ``jar`` is used to run the Chisel generator.
+Files referenced by the ``addResource`` must be located within this ``jar`` file during the Chisel elaboration.
+Thus if a file is generated during Chisel generation it will not be present in the ``jar`` file until the next time the Chisel sources are compiled.
+
+``HasBlackBoxPath`` differs in that it incorporates extra files by using an absolute path to them.
+Later in the build process, the FIRRTL compiler will copy the file from that location to the generated sources directory.
+Thus, the file must be present before the FIRRTL compiler is run (i.e. the file doesn't need to be in the ``src/main/resources`` or it can be auto-generated during Chisel elaboration).
+
+Additionally, both mechanisms do not enforce the order of files added.
+For example:
+
+.. code-block:: scala
+
+    addResource("fileA")
+    addResource("fileB")
+
+In this case, ``fileA`` is not guaranteed to be before ``fileB`` when passed to downstream tools.
+To bypass this, it is recommended to auto-generate a single file with the ordering needed by concatenating the files and using ``addPath`` given by ``HasBlackBoxPath``.
+An example of this is https://github.com/ucb-bar/ibex-wrapper/blob/main/src/main/scala/IbexCoreBlackbox.scala.

generators/chipyard/src/main/scala/example/GCD.scala

@@ -46,10 +46,11 @@ trait HasGCDIO extends BaseModule {
 }
 
 // DOC include start: GCD blackbox
-class GCDMMIOBlackBox(val w: Int) extends BlackBox(Map("WIDTH" -> IntParam(w))) with HasBlackBoxResource
+class GCDMMIOBlackBox(val w: Int) extends BlackBox(Map("WIDTH" -> IntParam(w))) with HasBlackBoxPath
   with HasGCDIO
 {
-  addResource("/vsrc/GCDMMIOBlackBox.v")
+  val chipyardDir = System.getProperty("user.dir")
+  addPath(s"$chipyardDir/generators/chipyard/src/main/resources/vsrc/GCDMMIOBlackBox.v")
 }
 // DOC include end: GCD blackbox
 
@@ -113,20 +114,36 @@ trait GCDModule extends HasRegMap {
     Module(new GCDMMIOChiselModule(params.width))
   }
 
+  val impl1 = if (params.useBlackBox) {
+    Module(new GCDMMIOBlackBox(params.width))
+  } else {
+    Module(new GCDMMIOChiselModule(params.width))
+  }
+
+
   impl.io.clock := clock
   impl.io.reset := reset.asBool
 
   impl.io.x := x
   impl.io.y := y.bits
   impl.io.input_valid := y.valid
-  y.ready := impl.io.input_ready
+  y.ready := impl.io.input_ready && impl1.io.input_ready
 
   gcd.bits := impl.io.gcd
-  gcd.valid := impl.io.output_valid
+  gcd.valid := impl.io.output_valid && impl1.io.output_valid
   impl.io.output_ready := gcd.ready
 
-  status := Cat(impl.io.input_ready, impl.io.output_valid)
-  io.gcd_busy := impl.io.busy
+  status := Cat(impl.io.input_ready, impl.io.output_valid, impl1.io.input_ready, impl1.io.output_valid)
+  io.gcd_busy := impl.io.busy && impl1.io.busy
+
+  impl1.io.clock := clock
+  impl1.io.reset := reset.asBool
+
+  impl1.io.x := x
+  impl1.io.y := y.bits
+  impl1.io.input_valid := y.valid
+
+  impl1.io.output_ready := gcd.ready
 
   regmap(
     0x00 -> Seq(