Add tutorial config and tutorial patches

.circleci/config.yml

@@ -143,6 +143,15 @@ jobs:
                 name: Check commits of each submodule
                 command: |
                     .circleci/check-commit.sh
+    tutorial-setup-check:
+        executor: main-env
+        steps:
+            - checkout
+            - run:
+                name: Check that the tutorial-setup patches apply
+                command: |
+                    scripts/tutorial-setup.sh
+
     install-riscv-toolchain:
         executor: main-env
         steps:
@@ -193,6 +202,11 @@ jobs:
         steps:
             - prepare-rtl:
                 project-key: "chipyard-rocket"
+    prepare-chipyard-sha3:
+        executor: main-env
+        steps:
+            - prepare-rtl:
+                project-key: "chipyard-sha3"
     prepare-chipyard-hetero:
         executor: main-env
         steps:
@@ -256,6 +270,11 @@ jobs:
         steps:
             - run-tests:
                 project-key: "chipyard-rocket"
+    chipyard-sha3-run-tests:
+        executor: main-env
+        steps:
+            - run-tests:
+                project-key: "chipyard-sha3"
     chipyard-hetero-run-tests:
         executor: main-env
         steps:
@@ -343,6 +362,9 @@ workflows:
 
             - commit-on-master-check
 
+            # Attempt to apply the tutorial patches
+            - tutorial-setup-check
+
             # Build extra tests
             - build-extra-tests:
                 requires:
@@ -354,6 +376,11 @@ workflows:
                     - install-riscv-toolchain
                     - install-verilator
 
+            - prepare-chipyard-sha3:
+                requires:
+                    - install-riscv-toolchain
+                    - install-verilator
+
             - prepare-chipyard-hetero:
                 requires:
                     - install-riscv-toolchain
@@ -417,6 +444,10 @@ workflows:
                 requires:
                     - prepare-chipyard-rocket
 
+            - chipyard-sha3-run-tests:
+                requires:
+                    - prepare-chipyard-sha3
+
             - chipyard-hetero-run-tests:
                 requires:
                     - prepare-chipyard-hetero

.circleci/defaults.sh

@@ -42,6 +42,7 @@ LOCAL_FIRESIM_DIR=$LOCAL_CHIPYARD_DIR/sims/firesim/sim
 # key value store to get the build strings
 declare -A mapping
 mapping["chipyard-rocket"]="SUB_PROJECT=chipyard"
+mapping["chipyard-sha3"]="SUB_PROJECT=chipyard CONFIG=Sha3RocketConfig"
 mapping["chipyard-hetero"]="SUB_PROJECT=chipyard CONFIG=LargeBoomAndRocketConfig"
 mapping["chipyard-boom"]="SUB_PROJECT=chipyard CONFIG=SmallBoomConfig"
 mapping["rocketchip"]="SUB_PROJECT=rocketchip"

.circleci/run-tests.sh

@@ -28,6 +28,8 @@ run_tracegen () {
     make tracegen -C $LOCAL_SIM_DIR VERILATOR_INSTALL_DIR=$LOCAL_VERILATOR_DIR $@
 }
 
+# TODO BUG: the run-binary command forces a rebuild of the simulator in CI
+#           instead, directly run the simulator binary
 case $1 in
     chipyard-rocket)
         run_bmark ${mapping[$1]}
@@ -58,6 +60,10 @@ case $1 in
         $LOCAL_SIM_DIR/simulator-chipyard-GemminiRocketConfig $GEMMINI_SOFTWARE_DIR/build/bareMetalC/raw_hazard-baremetal
         $LOCAL_SIM_DIR/simulator-chipyard-GemminiRocketConfig $GEMMINI_SOFTWARE_DIR/build/bareMetalC/mvin_mvout-baremetal
         ;;
+    chipyard-sha3)
+        (cd $LOCAL_CHIPYARD_DIR/generators/sha3/software && ./build.sh)
+        $LOCAL_SIM_DIR/simulator-chipyard-Sha3RocketConfig $LOCAL_CHIPYARD_DIR/generators/sha3/software/benchmarks/bare/sha3-rocc.riscv
+        ;;
     tracegen)
         run_tracegen ${mapping[$1]}
         ;;

build.sbt

@@ -123,7 +123,9 @@ lazy val testchipip = (project in file("generators/testchipip"))
   .settings(commonSettings)
 
 lazy val chipyard = conditionalDependsOn(project in file("generators/chipyard"))
-  .dependsOn(boom, hwacha, sifive_blocks, sifive_cache, utilities, sha3, gemmini, icenet, tracegen)
+  .dependsOn(boom, hwacha, sifive_blocks, sifive_cache, utilities,
+    sha3, // On separate line to allow for cleaner tutorial-setup patches
+    gemmini, icenet, tracegen)
   .settings(commonSettings)
 
 lazy val tracegen = conditionalDependsOn(project in file("generators/tracegen"))
@@ -195,7 +197,9 @@ lazy val midas      = ProjectRef(firesimDir, "midas")
 lazy val firesimLib = ProjectRef(firesimDir, "firesimLib")
 
 lazy val firechip = (project in file("generators/firechip"))
-  .dependsOn(boom, hwacha, chipyard, icenet, testchipip, sifive_blocks, sifive_cache, sha3, utilities, midasTargetUtils, midas, firesimLib % "test->test;compile->compile")
+  .dependsOn(boom, hwacha, chipyard, icenet, testchipip, sifive_blocks, sifive_cache,
+    sha3, // On separate line to allow for cleaner tutorial-setup patches
+    utilities, midasTargetUtils, midas, firesimLib % "test->test;compile->compile")
   .settings(
     commonSettings,
     testGrouping in Test := isolateAllTests( (definedTests in Test).value )

generators/chipyard/src/main/scala/ConfigFragments.scala

@@ -70,6 +70,18 @@ class WithTracegenTop extends Config((site, here, up) => {
 })
 
 
+class WithRenumberHarts(rocketFirst: Boolean = false) extends Config((site, here, up) => {
+  case RocketTilesKey => up(RocketTilesKey, site).zipWithIndex map { case (r, i) =>
+    r.copy(hartId = i + (if(rocketFirst) 0 else up(BoomTilesKey, site).length))
+  }
+  case BoomTilesKey => up(BoomTilesKey, site).zipWithIndex map { case (b, i) =>
+    b.copy(hartId = i + (if(rocketFirst) up(RocketTilesKey, site).length else 0))
+  }
+  case MaxHartIdBits => log2Up(up(BoomTilesKey, site).size + up(RocketTilesKey, site).size)
+})
+
+
+
 // ------------------
 // Multi-RoCC Support
 // ------------------

generators/chipyard/src/main/scala/config/BoomConfigs.scala

@@ -1,7 +1,5 @@
 package chipyard
 
-import chisel3._
-
 import freechips.rocketchip.config.{Config}
 
 // ---------------------
@@ -12,7 +10,7 @@ import freechips.rocketchip.config.{Config}
 class SmallBoomConfig extends Config(
   new chipyard.iobinders.WithUARTAdapter ++                      // display UART with a SimUARTAdapter
   new chipyard.iobinders.WithTieOffInterrupts ++                 // tie off top-level interrupts
-  new chipyard.iobinders.WithBlackBoxSimMem ++                        // drive the master AXI4 memory with a SimAXIMem
+  new chipyard.iobinders.WithBlackBoxSimMem ++                   // drive the master AXI4 memory with a SimAXIMem
   new chipyard.iobinders.WithTiedOffDebug ++                     // tie off debug (since we are using SimSerial for testing)
   new chipyard.iobinders.WithSimSerial ++                        // drive TSI with SimSerial for testing
   new testchipip.WithTSI ++                                      // use testchipip serial offchip link

generators/chipyard/src/main/scala/config/HeteroConfigs.scala

@@ -1,7 +1,5 @@
 package chipyard
 
-import chisel3._
-
 import freechips.rocketchip.config.{Config}
 
 // ---------------------
@@ -11,7 +9,7 @@ import freechips.rocketchip.config.{Config}
 class LargeBoomAndRocketConfig extends Config(
   new chipyard.iobinders.WithUARTAdapter ++                      // display UART with a SimUARTAdapter
   new chipyard.iobinders.WithTieOffInterrupts ++                 // tie off top-level interrupts
-  new chipyard.iobinders.WithBlackBoxSimMem ++                        // drive the master AXI4 memory with a SimAXIMem
+  new chipyard.iobinders.WithBlackBoxSimMem ++                   // drive the master AXI4 memory with a SimAXIMem
   new chipyard.iobinders.WithTiedOffDebug ++                     // tie off debug (since we are using SimSerial for testing)
   new chipyard.iobinders.WithSimSerial ++                        // drive TSI with SimSerial for testing
   new testchipip.WithTSI ++                                      // use testchipip serial offchip link
@@ -19,7 +17,7 @@ class LargeBoomAndRocketConfig extends Config(
   new chipyard.config.WithBootROM ++                             // use default bootrom
   new chipyard.config.WithUART ++                                // add a UART
   new chipyard.config.WithL2TLBs(1024) ++                        // use L2 TLBs
-  new boom.common.WithRenumberHarts ++                           // avoid hartid overlap
+  new chipyard.config.WithRenumberHarts ++                       // avoid hartid overlap
   new boom.common.WithLargeBooms ++                              // 3-wide boom
   new boom.common.WithNBoomCores(1) ++                           // single-core boom
   new freechips.rocketchip.subsystem.WithNoMMIOPort ++           // no top-level MMIO master port (overrides default set in rocketchip)
@@ -42,7 +40,7 @@ class HwachaLargeBoomAndHwachaRocketConfig extends Config(
   new chipyard.config.WithUART ++
   new chipyard.config.WithL2TLBs(1024) ++
   new hwacha.DefaultHwachaConfig ++                      // add hwacha to all harts
-  new boom.common.WithRenumberHarts ++
+  new chipyard.config.WithRenumberHarts ++
   new boom.common.WithLargeBooms ++
   new boom.common.WithNBoomCores(1) ++
   new freechips.rocketchip.subsystem.WithNoMMIOPort ++
@@ -64,7 +62,7 @@ class DualLargeBoomAndRocketConfig extends Config(
   new chipyard.config.WithBootROM ++
   new chipyard.config.WithUART ++
   new chipyard.config.WithL2TLBs(1024) ++
-  new boom.common.WithRenumberHarts ++
+  new chipyard.config.WithRenumberHarts ++
   new boom.common.WithLargeBooms ++
   new boom.common.WithNBoomCores(2) ++                       // 2 boom cores
   new freechips.rocketchip.subsystem.WithNoMMIOPort ++
@@ -89,7 +87,7 @@ class LargeBoomAndHwachaRocketConfig extends Config(
   new chipyard.config.WithMultiRoCC ++                                  // support heterogeneous rocc
   new chipyard.config.WithMultiRoCCHwacha(1) ++                         // put hwacha on hart-2 (rocket)
   new chipyard.config.WithL2TLBs(1024) ++
-  new boom.common.WithRenumberHarts ++
+  new chipyard.config.WithRenumberHarts ++
   new boom.common.WithLargeBooms ++
   new boom.common.WithNBoomCores(1) ++
   new freechips.rocketchip.subsystem.WithNoMMIOPort ++
@@ -113,7 +111,7 @@ class LargeBoomAndRV32RocketConfig extends Config(
   new chipyard.config.WithBootROM ++
   new chipyard.config.WithUART ++
   new chipyard.config.WithL2TLBs(1024) ++
-  new boom.common.WithRenumberHarts ++
+  new chipyard.config.WithRenumberHarts ++
   new boom.common.WithLargeBooms ++
   new boom.common.WithNBoomCores(1) ++
   new freechips.rocketchip.subsystem.WithNoMMIOPort ++
@@ -137,7 +135,7 @@ class DualLargeBoomAndDualRocketConfig extends Config(
   new chipyard.config.WithBootROM ++
   new chipyard.config.WithUART ++
   new chipyard.config.WithL2TLBs(1024) ++
-  new boom.common.WithRenumberHarts ++
+  new chipyard.config.WithRenumberHarts ++
   new boom.common.WithLargeBooms ++
   new boom.common.WithNBoomCores(2) ++                     // 2 boom cores
   new freechips.rocketchip.subsystem.WithNoMMIOPort ++
@@ -160,7 +158,7 @@ class LargeBoomAndRocketWithControlCoreConfig extends Config(
   new chipyard.config.WithUART ++
   new chipyard.config.WithControlCore ++  // add small control core to last hartid
   new chipyard.config.WithL2TLBs(1024) ++
-  new boom.common.WithRenumberHarts ++
+  new chipyard.config.WithRenumberHarts ++
   new boom.common.WithLargeBooms ++
   new boom.common.WithNBoomCores(1) ++
   new freechips.rocketchip.subsystem.WithNoMMIOPort ++

generators/chipyard/src/main/scala/config/RocketConfigs.scala

@@ -1,7 +1,5 @@
 package chipyard
 
-import chisel3._
-
 import freechips.rocketchip.config.{Config}
 
 // --------------
@@ -11,7 +9,7 @@ import freechips.rocketchip.config.{Config}
 class RocketConfig extends Config(
   new chipyard.iobinders.WithUARTAdapter ++                      // display UART with a SimUARTAdapter
   new chipyard.iobinders.WithTieOffInterrupts ++                 // tie off top-level interrupts
-  new chipyard.iobinders.WithBlackBoxSimMem ++                        // drive the master AXI4 memory with a SimAXIMem
+  new chipyard.iobinders.WithBlackBoxSimMem ++                   // drive the master AXI4 memory with a SimAXIMem
   new chipyard.iobinders.WithTiedOffDebug ++                     // tie off debug (since we are using SimSerial for testing)
   new chipyard.iobinders.WithSimSerial ++                        // drive TSI with SimSerial for testing
   new testchipip.WithTSI ++                                      // use testchipip serial offchip link

generators/chipyard/src/main/scala/config/TracegenConfigs.scala

@@ -1,7 +1,5 @@
 package chipyard
 
-import chisel3._
-
 import freechips.rocketchip.config.{Config}
 import freechips.rocketchip.rocket.{DCacheParams}
 

generators/chipyard/src/main/scala/config/TutorialConfigs.scala

@@ -0,0 +1,138 @@
+package chipyard
+
+import freechips.rocketchip.config.{Config}
+
+// This file is designed to accompany a live tutorial, with slides.
+// For each of 4 phases, participants will customize and build a
+// small demonstration config.
+
+// This file is designed to be used after running chipyard/scripts/tutorial-setup.sh,
+// which removes the SHA3 accelerator RTL, and provides participants
+// the experience of integrating external RTL.
+
+// This file was originally developed for the cancelled ASPLOS-2020
+// Chipyard tutorial. While the configs here work, the corresponding
+// slideware has not yet been created
+
+// NOTE: Configs should be read bottom-up, since they are applied bottom-up
+
+// Tutorial Phase 1: Configure the cores, caches
+class TutorialStarterConfig extends Config(
+  // IOBinders specify how to connect to IOs in our TestHarness
+  // These config fragments do not affect
+  new chipyard.iobinders.WithUARTAdapter ++       // Connect a SimUART adapter to display UART on stdout
+  new chipyard.iobinders.WithBlackBoxSimMem ++    // Connect simulated external memory
+  new chipyard.iobinders.WithTieOffInterrupts ++  // Do not simulate external interrupts
+  new chipyard.iobinders.WithTiedOffDebug ++      // Disconnect the debug module, since we use TSI for bring-up
+  new chipyard.iobinders.WithSimSerial ++         // Connect external SimSerial widget to drive TSI
+
+  // Config fragments below this line affect hardware generation
+  // of the Top
+  new testchipip.WithTSI ++                  // Add a TSI (Test Serial Interface)  widget to bring-up the core
+  new chipyard.config.WithNoGPIO ++          // Disable GPIOs.
+  new chipyard.config.WithBootROM ++         // Use the Chipyard BootROM
+  new chipyard.config.WithRenumberHarts ++   // WithRenumberHarts fixes hartids heterogeneous designs, if design is not heterogeneous, this is a no-op
+  new chipyard.config.WithUART ++            // Add a UART
+
+  // CUSTOMIZE THE CORE
+  // Uncomment out one (or multiple) of the lines below, and choose
+  // how many cores you want.
+  // new freechips.rocketchip.subsystem.WithNBigCores(1) ++ // Specify we want some number of Rocket cores
+  // new boom.common.WithSmallBooms ++                      // Specify all BOOM cores should be Small-sized (NOTE: other options are Medium/Large/Mega)
+  // new boom.common.WithNBoomCores(1) ++                   // Specify we want some number of BOOM cores
+
+  // CUSTOMIZE the L2
+  // Uncomment this line, and specify a size if you want to have a L2
+  // new freechips.rocketchip.subsystem.WithInclusiveCache(nBanks=1, nWays=4, capacityKB=128) ++
+
+  // For simpler designs, we want to minimize IOs on
+  // our Top. These config fragments remove unnecessary
+  // ports
+  new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+  new freechips.rocketchip.subsystem.WithNoSlavePort ++
+  new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
+  // BaseConfig configures "bare" rocketchip system
+  new freechips.rocketchip.system.BaseConfig
+)
+
+
+// Tutorial Phase 2: Integrate a TileLink or AXI4 MMIO device
+class TutorialMMIOConfig extends Config(
+  new chipyard.iobinders.WithUARTAdapter ++
+  new chipyard.iobinders.WithBlackBoxSimMem ++
+  new chipyard.iobinders.WithTieOffInterrupts ++
+  new chipyard.iobinders.WithTiedOffDebug ++
+  new chipyard.iobinders.WithSimSerial ++
+
+  new testchipip.WithTSI ++
+  new chipyard.config.WithNoGPIO ++
+  new chipyard.config.WithBootROM ++
+  new chipyard.config.WithRenumberHarts ++
+  new chipyard.config.WithUART ++
+
+  // Attach either a TileLink or AXI4 version of GCD
+  // Uncomment one of the below lines
+  // new chipyard.example.WithGCD(useAXI4=false) ++ // Use TileLink version
+  // new chipyard.example.WithGCD(useAXI4=true) ++  // Use AXI4 version
+
+  // For this demonstration we assume the base system is a single-core Rocket, for fast elaboration
+  new freechips.rocketchip.subsystem.WithNBigCores(1) ++
+  new freechips.rocketchip.subsystem.WithInclusiveCache ++
+  new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+  new freechips.rocketchip.subsystem.WithNoSlavePort ++
+  new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
+  new freechips.rocketchip.system.BaseConfig
+)
+
+// Tutorial Phase 3: Integrate a SHA3 RoCC accelerator
+class TutorialSha3Config extends Config(
+  new chipyard.iobinders.WithUARTAdapter ++
+  new chipyard.iobinders.WithBlackBoxSimMem ++
+  new chipyard.iobinders.WithTieOffInterrupts ++
+  new chipyard.iobinders.WithTiedOffDebug ++
+  new chipyard.iobinders.WithSimSerial ++
+
+  new testchipip.WithTSI ++
+  new chipyard.config.WithNoGPIO ++
+  new chipyard.config.WithBootROM ++
+  new chipyard.config.WithRenumberHarts ++
+  new chipyard.config.WithUART ++
+
+  // Uncomment this line once you added SHA3 to the build.sbt, and cloned the SHA3 repo
+  // new sha3.WithSha3Accel ++
+
+  // For this demonstration we assume the base system is a single-core Rocket, for fast elaboration
+  new freechips.rocketchip.subsystem.WithNBigCores(1) ++
+  new freechips.rocketchip.subsystem.WithInclusiveCache ++
+  new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+  new freechips.rocketchip.subsystem.WithNoSlavePort ++
+  new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
+  new freechips.rocketchip.system.BaseConfig
+)
+
+// Tutorial Phase 4: Integrate a Black-box verilog version of the SHA3 RoCC accelerator
+class TutorialSha3BlackBoxConfig extends Config(
+  new chipyard.iobinders.WithUARTAdapter ++
+  new chipyard.iobinders.WithBlackBoxSimMem ++
+  new chipyard.iobinders.WithTieOffInterrupts ++
+  new chipyard.iobinders.WithTiedOffDebug ++
+  new chipyard.iobinders.WithSimSerial ++
+
+  new testchipip.WithTSI ++
+  new chipyard.config.WithNoGPIO ++
+  new chipyard.config.WithBootROM ++
+  new chipyard.config.WithRenumberHarts ++
+  new chipyard.config.WithUART ++
+
+  // Uncomment these lines once SHA3 is integrated
+  // new sha3.WithSha3BlackBox ++ // Specify we want the Black-box verilog version of Sha3 Ctrl
+  // new sha3.WithSha3Accel ++
+
+  // For this demonstration we assume the base system is a single-core Rocket, for fast elaboration
+  new freechips.rocketchip.subsystem.WithNBigCores(1) ++
+  new freechips.rocketchip.subsystem.WithInclusiveCache ++
+  new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+  new freechips.rocketchip.subsystem.WithNoSlavePort ++
+  new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
+  new freechips.rocketchip.system.BaseConfig
+)

scripts/tutorial-patches/RocketConfigs.scala.patch

@@ -0,0 +1,13 @@
+diff --git a/generators/chipyard/src/main/scala/config/RocketConfigs.scala b/generators/chipyard/src/main/scala/config/RocketConfigs.scala
+index bc1dab6..1d84129 100644
+--- a/generators/chipyard/src/main/scala/config/RocketConfigs.scala
++++ b/generators/chipyard/src/main/scala/config/RocketConfigs.scala
+@@ -293,7 +293,7 @@ class Sha3RocketConfig extends Config(
+   new chipyard.config.WithBootROM ++
+   new chipyard.config.WithUART ++
+   new chipyard.config.WithL2TLBs(1024) ++
+-  new sha3.WithSha3Accel ++                                // add SHA3 rocc accelerator
++//  new sha3.WithSha3Accel ++                                // add SHA3 rocc accelerator
+   new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+   new freechips.rocketchip.subsystem.WithNoSlavePort ++
+   new freechips.rocketchip.subsystem.WithInclusiveCache ++

scripts/tutorial-patches/build.sbt.patch

@@ -0,0 +1,35 @@
+diff --git a/build.sbt b/build.sbt
+index 52fc3cb..875e3b4 100644
+--- a/build.sbt
++++ b/build.sbt
+@@ -124,7 +124,7 @@ lazy val testchipip = (project in file("generators/testchipip"))
+ 
+ lazy val chipyard = conditionalDependsOn(project in file("generators/chipyard"))
+   .dependsOn(boom, hwacha, sifive_blocks, sifive_cache, utilities,
+-    sha3, // On separate line to allow for cleaner tutorial-setup patches
++//    sha3, // On separate line to allow for cleaner tutorial-setup patches
+     gemmini, icenet, tracegen)
+   .settings(commonSettings)
+ 
+@@ -147,9 +147,9 @@ lazy val boom = (project in file("generators/boom"))
+   .dependsOn(rocketchip)
+   .settings(commonSettings)
+ 
+-lazy val sha3 = (project in file("generators/sha3"))
+-  .dependsOn(rocketchip, chisel_testers, midasTargetUtils)
+-  .settings(commonSettings)
++// lazy val sha3 = (project in file("generators/sha3"))
++//   .dependsOn(rocketchip, chisel_testers, midasTargetUtils)
++//   .settings(commonSettings)
+ 
+ lazy val gemmini = (project in file("generators/gemmini"))
+   .dependsOn(rocketchip, chisel_testers, testchipip)
+@@ -198,7 +198,7 @@ lazy val firesimLib = ProjectRef(firesimDir, "firesimLib")
+ 
+ lazy val firechip = (project in file("generators/firechip"))
+   .dependsOn(boom, hwacha, chipyard, icenet, testchipip, sifive_blocks, sifive_cache,
+-    sha3, // On separate line to allow for cleaner tutorial-setup patches
++//    sha3, // On separate line to allow for cleaner tutorial-setup patches
+     utilities, midasTargetUtils, midas, firesimLib % "test->test;compile->compile")
+   .settings(
+     commonSettings,

scripts/tutorial-setup.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -e -x
+
+rm -rf generators/sha3
+
+for p in scripts/tutorial-patches/*.patch
+do
+    echo "Applying tutorial patch $p"
+    git apply $p
+done