Merge pull request #1639 from ucb-bar/bb-fixes

Rebuild `jar`s 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 \
@@ -246,9 +246,7 @@ $(SFC_MFC_TARGETS) &: $(TAPEOUT_CLASSPATH_TARGETS) $(FIRRTL_FILE) $(FINAL_ANNO_F
 	@if [ $(shell cat $(SFC_LEVEL)) = low ]; then cat $(TMP_DIR)/unnec-anno-deleted2.sfc.anno.json > $(SFC_ANNO_FILE) && rm $(TMP_DIR)/unnec-anno-deleted.sfc.anno.json && rm $(TMP_DIR)/unnec-anno-deleted2.sfc.anno.json; fi
 	firtool \
 		--format=fir \
-		--dedup \
 		--export-module-hierarchy \
-		--emit-metadata \
 		--verify-each=true \
 		--warn-on-unprocessed-annotations \
 		--disable-annotation-classless \
@@ -257,7 +255,6 @@ $(SFC_MFC_TARGETS) &: $(TAPEOUT_CLASSPATH_TARGETS) $(FIRRTL_FILE) $(FINAL_ANNO_F
 		--lowering-options=$(shell cat $(MFC_LOWERING_OPTIONS)) \
 		--repl-seq-mem \
 		--repl-seq-mem-file=$(MFC_SMEMS_CONF) \
-		--repl-seq-mem-circuit=$(MODEL) \
 		--annotation-file=$(SFC_ANNO_FILE) \
 		--split-verilog \
 		-o $(GEN_COLLATERAL_DIR) \

conda-reqs/chipyard.yaml

@@ -29,7 +29,7 @@ dependencies:
     - conda-gcc-specs
     - binutils
 
-    - firtool==1.30.0 # from ucb-bar channel - https://github.com/ucb-bar/firtool-feedstock
+    - firtool==1.58.0 # from ucb-bar channel - https://github.com/ucb-bar/firtool-feedstock
 
     # misc
     - autoconf

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

@@ -13,7 +13,7 @@ import freechips.rocketchip.util.UIntIsOneOf
 
 // DOC include start: GCD params
 case class GCDParams(
-  address: BigInt = 0x1000,
+  address: BigInt = 0x4000,
   width: Int = 32,
   useAXI4: Boolean = false,
   useBlackBox: Boolean = true)

scripts/generate-conda-lockfiles.sh

@@ -13,6 +13,13 @@ fi
 for TOOLCHAIN_TYPE in riscv-tools esp-tools; do
     # note: lock file must end in .conda-lock.yml - see https://github.com/conda-incubator/conda-lock/issues/154
     LOCKFILE=$REQS_DIR/conda-lock-reqs/conda-requirements-$TOOLCHAIN_TYPE-linux-64.conda-lock.yml
+    rm -rf $LOCKFILE
 
-    conda-lock -f "$REQS_DIR/chipyard.yaml" -f "$REQS_DIR/$TOOLCHAIN_TYPE.yaml" -p linux-64 --lockfile $LOCKFILE
+    conda-lock \
+	    --no-mamba \
+	    --no-micromamba \
+	    -f "$REQS_DIR/chipyard.yaml" \
+	    -f "$REQS_DIR/$TOOLCHAIN_TYPE.yaml" \
+	    -p linux-64 \
+	    --lockfile $LOCKFILE
 done

scripts/insert-includes.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python
 
-# replaces a `include with the full include file
+# replaces a `include with the full include file.
+# recursively replaces `include's until none are left
 #
 # args
 # $1 - file to remove includes from
@@ -12,6 +13,8 @@
 import sys
 import re
 import os
+import tempfile
+import shutil
 
 inVlog = sys.argv[1]
 outVlog = sys.argv[2]
@@ -24,28 +27,52 @@ if inVlog == outVlog:
 incDirs = sys.argv[3:]
 print("[INFO] Searching following dirs for includes: " + str(incDirs))
 
-# open file
+def process(inF, outF):
-with open(inVlog, 'r') as inFile:
+    # open file
-    with open(outVlog, 'w') as outFile:
+    with open(inF, 'r') as inFile:
-        # for each include found, search through all dirs and replace if found, error if not
+        with open(outF, 'w') as outFile:
-        for num, line in enumerate(inFile, 1):
+            # for each include found, search through all dirs and replace if found, error if not
+            for num, line in enumerate(inFile, 1):
+                match = re.match(r"^ *`include +\"(.*)\"", line)
+                if match:
+                    # search for include and replace
+                    found = False
+                    for d in incDirs:
+                        potentialIncFileName = d + "/" + match.group(1)
+                        if os.path.exists(potentialIncFileName):
+                            found = True
+                            with open(potentialIncFileName, 'r') as incFile:
+                                for iline in incFile:
+                                    outFile.write(iline)
+                            break
+
+                    # must find something to include with
+                    if not found:
+                        sys.exit("[ERROR] Couldn't replace include \"" + str(match.group(1)) + "\" found on line " + str(num))
+                else:
+                    outFile.write(line)
+
+inF = inVlog
+
+while True:
+    # create a copy of the input
+    fd, temp_path = tempfile.mkstemp()
+    shutil.copy2(inF, temp_path)
+
+    with open(temp_path, 'r') as inFile:
+        anyIncludes = False
+        for line in inFile:
             match = re.match(r"^ *`include +\"(.*)\"", line)
             if match:
-                # search for include and replace
+                anyIncludes = True
-                found = False
+                break
-                for d in incDirs:
-                    potentialIncFileName = d + "/" + match.group(1)
-                    if os.path.exists(potentialIncFileName):
-                        found = True
-                        with open(potentialIncFileName, 'r') as incFile:
-                            for iline in incFile:
-                                outFile.write(iline)
-                        break
 
-                # must find something to include with
+        if anyIncludes:
-                if not found:
+            process(temp_path, outVlog)
-                    sys.exit("[ERROR] Couldn't replace include \"" + str(match.group(1)) + "\" found on line " + str(num))
+            inF = outVlog
-            else:
+            os.remove(temp_path)
-                outFile.write(line)
+        else:
+            os.remove(temp_path)
+            break
 
 print("[INFO] Success. Writing output to: " + str(outVlog))

tests/gcd.c

@@ -1,9 +1,9 @@
 #include "mmio.h"
 
-#define GCD_STATUS 0x1000
+#define GCD_STATUS 0x4000
-#define GCD_X 0x1004
+#define GCD_X 0x4004
-#define GCD_Y 0x1008
+#define GCD_Y 0x4008
-#define GCD_GCD 0x100C
+#define GCD_GCD 0x400C
 
 unsigned int gcd_ref(unsigned int x, unsigned int y) {
   while (y != 0) {