Merge remote-tracking branch 'origin/main' into port_api

.github/scripts/defaults.sh

@@ -34,7 +34,7 @@ grouping["group-accels"]="chipyard-mempress chipyard-sha3 chipyard-hwacha chipya
 grouping["group-constellation"]="chipyard-constellation"
 grouping["group-tracegen"]="tracegen tracegen-boom"
 grouping["group-other"]="icenet testchipip constellation rocketchip-amba rocketchip-tlsimple rocketchip-tlwidth rocketchip-tlxbar"
-grouping["group-fpga"]="arty vcu118 vc707"
+grouping["group-fpga"]="arty arty100t nexysvideo vc707 vcu118"
 
 # key value store to get the build strings
 declare -A mapping
@@ -79,5 +79,7 @@ mapping["rocketchip-tlwidth"]="SUB_PROJECT=rocketchip CONFIG=TLWidthUnitTestConf
 mapping["rocketchip-tlxbar"]="SUB_PROJECT=rocketchip CONFIG=TLXbarUnitTestConfig"
 
 mapping["arty"]="SUB_PROJECT=arty verilog"
-mapping["vcu118"]="SUB_PROJECT=vcu118 verilog"
+mapping["arty100t"]="SUB_PROJECT=arty100t verilog"
+mapping["nexysvideo"]="SUB_PROJECT=nexysvideo verilog"
 mapping["vc707"]="SUB_PROJECT=vc707 verilog"
+mapping["vcu118"]="SUB_PROJECT=vcu118 verilog"

docs/Prototyping/Arty.rst

@@ -2,18 +2,18 @@ Running a Design on Arty
 ========================
 
 Arty100T Instructions
-----------------------
+---------------------
 
-The default Xilinx Arty 100T harness uses a TSI-over-UART adapter to bringup the FPGA.
-A user can connect to the Arty 100T target using a special ``uart_tsi`` program that opens a UART TTY.
+The default Digilent Arty A7-100T harness uses a TSI-over-UART adapter to bringup the FPGA.
+A user can connect to the Arty A7-100T target using a special ``uart_tsi`` program that opens a UART TTY.
 The interface for the ``uart_tsi`` program provides unique functionality that is useful for bringing up test chips.
 
-To build the design, run:
+To build the design (Vivado should be added to the ``PATH``), run:
 
 .. code-block:: shell
 
 		cd fpga/
-		make SUB_PROJECT=arty100t
+		make SUB_PROJECT=arty100t bitstream
 
 To build the UART-based frontend server, run:
 
@@ -58,7 +58,7 @@ Run a design at a higher baud rate than default (For example, if ``CONFIG=UART92
 Arty35T Legacy Instructions
 ---------------------------
 
-The default Xilinx Arty 35T harness is setup to have JTAG available over the board's PMOD pins, and UART available over its FTDI serial USB adapter. The pin mappings for JTAG signals are identical to those described in the `SiFive Freedom E310 Arty 35T Getting Started Guide <https://static.dev.sifive.com/SiFive-E310-arty-gettingstarted-v1.0.6.pdf>`__.
+The default Digilent Arty A7-35T harness is setup to have JTAG available over the board's PMOD pins, and UART available over its FTDI serial USB adapter. The pin mappings for JTAG signals are identical to those described in the `SiFive Freedom E310 Arty 35T Getting Started Guide <https://static.dev.sifive.com/SiFive-E310-arty-gettingstarted-v1.0.6.pdf>`__.
 The JTAG interface allows a user to connect to the core via OpenOCD, run bare-metal applications, and debug these applications with gdb. UART allows a user to communicate with the core over a USB connection and serial console running on a PC.
 To extend this design, a user may create their own Chipyard configuration and add the ``WithArtyTweaks`` located in ``fpga/src/main/scala/arty/Configs.scala``.
 Adding this config. fragment will enable and connect the JTAG and UART interfaces to your Chipyard design.
@@ -68,13 +68,13 @@ Adding this config. fragment will enable and connect the JTAG and UART interface
     :start-after: DOC include start: AbstractArty and Rocket
     :end-before: DOC include end: AbstractArty and Rocket
 
-Future peripherals to be supported include the Arty 35T SPI Flash EEPROM, and I2C/PWM/SPI over the Arty 35T GPIO pins. These peripherals are available as part of sifive-blocks.
+Future peripherals to be supported include the Arty A7-35T SPI Flash EEPROM, and I2C/PWM/SPI over the Arty A7-35T GPIO pins. These peripherals are available as part of sifive-blocks.
 
 Brief Implementation Description and Guidance for Adding/Changing Xilinx Collateral
 -----------------------------------------------------------------------------------
 
-Like the VCU118, the basis for the Arty 35T design is the creation of a special test harness that connects the external IO (which exist as Xilinx IP blackboxes) to the Chipyard design.
-This is done with the ``ArtyTestHarness`` in the basic default Arty 35T target. However, unlike the ``VCU118TestHarness``, the ``ArtyTestHarness`` uses no ``Overlays``, and instead directly connects chip top IO to the ports of the external IO blackboxes, using functions such as ``IOBUF`` provided by ``fpga-shells``.
-Unlike the VCU118 and other more complicated test harnesses, the Arty 35T Vivado collateral is not generated by ``Overlays``, but rather are a static collection of ``create_ip`` and ``set_properties`` statements located in the files within ``fpga/fpga-shells/xilinx/arty/tcl`` and ``fpga/fpga-shells/xilinx/arty/constraints``.
+Like the VCU118, the basis for the Arty A7-35T design is the creation of a special test harness that connects the external IO (which exist as Xilinx IP blackboxes) to the Chipyard design.
+This is done with the ``ArtyTestHarness`` in the basic default Arty A7-35T target. However, unlike the ``VCU118TestHarness``, the ``ArtyTestHarness`` uses no ``Overlays``, and instead directly connects chip top IO to the ports of the external IO blackboxes, using functions such as ``IOBUF`` provided by ``fpga-shells``.
+Unlike the VCU118 and other more complicated test harnesses, the Arty A7-35T Vivado collateral is not generated by ``Overlays``, but rather are a static collection of ``create_ip`` and ``set_properties`` statements located in the files within ``fpga/fpga-shells/xilinx/arty/tcl`` and ``fpga/fpga-shells/xilinx/arty/constraints``.
 If the user wishes to re-map FPGA package pins to different harness-level IO, this may be changed within ``fpga/fpga-shells/xilinx/arty/constraints/arty-master.xdc``. The addition of new Xilinx IP blocks may be done in ``fpga-shells/xilinx/arty/tcl/ip.tcl``, mapped to harness-level IOs in ``arty-master.xdc``, and wired through from the test harness to the chip top using ``HarnessBinders`` and ``IOBinders``.
 Examples of a simple ``IOBinder`` and ``HarnessBinder`` for routing signals (in this case the debug and JTAG resets) from the core to the test harness are the ``WithResetPassthrough`` and ``WithArtyResetHarnessBinder``.

docs/Prototyping/General.rst

@@ -2,7 +2,7 @@ General Setup and Usage
 ==============================
 
 Sources
----------------------------
+-------
 
 All FPGA prototyping-related collateral and sources are located in the ``fpga`` top-level Chipyard directory.
 This includes the ``fpga-shells`` submodule and the ``src`` directory that hold both Scala, TCL and other collateral.

docs/Prototyping/NexysVideo.rst

@@ -0,0 +1,49 @@
+Running a Design on Nexys Video
+===============================
+
+Nexys Video Instructions
+------------------------
+
+The default Digilent Nexys Video harness uses a TSI-over-UART adapter to bringup the FPGA.
+A user can connect to the Nexys Video target using a special ``uart_tsi`` program that opens a UART TTY.
+The interface for the ``uart_tsi`` program provides unique functionality that is useful for bringing up test chips.
+
+To build the design (Vivado should be added to the ``PATH``), run:
+
+.. code-block:: shell
+
+		cd fpga/
+		make SUB_PROJECT=nexysvideo bitstream
+
+To build the UART-based frontend server, run:
+
+.. code-block:: shell
+
+		cd generators/testchipip/uart_tsi
+		make
+
+After programming the bitstream, and connecting the Nexys Video's UART to a host PC via the USB cable, the ``uart_tsi`` program can be run to interact with the target.
+
+Running a program:
+
+.. code-block:: shell
+
+		./uart_tsi +tty=/dev/ttyUSBX dhrystone.riscv
+
+Probe an address on the target system:
+
+.. code-block:: shell
+
+		./uart_tsi +tty=/dev/ttyUSBX +init_read=0x10040 none
+
+Write some address before running a program:
+
+.. code-block:: shell
+
+		./uart_tsi +tty=/dev/ttyUSBX +init_write=0x80000000:0xdeadbeef none
+
+Self-check that binary loading proceeded correctly:
+
+.. code-block:: shell
+
+		./uart_tsi +tty=/dev/ttyUSBX +selfcheck dhrystone.riscv

docs/Prototyping/index.rst

@@ -2,10 +2,10 @@ Prototyping Flow
 ================
 
 Chipyard supports FPGA prototyping for local FPGAs supported by `fpga-shells <https://github.com/sifive/fpga-shells>`__.
-This includes popular FPGAs such as the Xilinx VCU118 and the Xilinx Arty 35T board.
+This includes popular FPGAs such as the Xilinx VCU118 and the Digilent Arty A7-35T/A7-100T board.
 
-.. Note:: While ``fpga-shells`` provides harnesses for other FPGA development boards such as the Xilinx VC707 and some MicroSemi PolarFire, only harnesses for the Xilinx VCU118 and Xilinx Arty 35T boards are currently supported in Chipyard.
-    However, the VCU118 and Arty 35T examples demonstrate how a user may implement support for other harnesses provided by fpga-shells.
+.. Note:: While ``fpga-shells`` provides harnesses for other FPGA development boards such as the Xilinx VC707 and some MicroSemi PolarFire, only harnesses for the Xilinx VCU118 and Digilent Arty A7-35T/A7-100T boards are currently supported in Chipyard.
+    However, the VCU118 and Arty A7-35T/A7-100T examples demonstrate how a user may implement support for other harnesses provided by fpga-shells.
 
 .. toctree::
    :maxdepth: 2
@@ -14,3 +14,4 @@ This includes popular FPGAs such as the Xilinx VCU118 and the Xilinx Arty 35T bo
    General
    VCU118
    Arty
+   NexysVideo

fpga/Makefile

@@ -57,6 +57,21 @@ ifeq ($(SUB_PROJECT),bringup)
 	BOARD             ?= vcu118
 	FPGA_BRAND        ?= xilinx
 endif
+
+ifeq ($(SUB_PROJECT),nexysvideo)
+	SBT_PROJECT       ?= fpga_platforms
+	MODEL             ?= NexysVideoHarness
+	VLOG_MODEL        ?= NexysVideoHarness
+	MODEL_PACKAGE     ?= chipyard.fpga.nexysvideo
+	CONFIG            ?= RocketNexysVideoConfig
+	CONFIG_PACKAGE    ?= chipyard.fpga.nexysvideo
+	GENERATOR_PACKAGE ?= chipyard
+	TB                ?= none # unused
+	TOP               ?= ChipTop
+	BOARD             ?= nexys_video
+	FPGA_BRAND        ?= xilinx
+endif
+
 ifeq ($(SUB_PROJECT),arty)
 	# TODO: Fix with Arty
 	SBT_PROJECT       ?= fpga_platforms

fpga/src/main/scala/arty100t/Harness.scala

@@ -54,6 +54,7 @@ class Arty100THarness(override implicit val p: Parameters) extends Arty100TShell
   override lazy val module = new HarnessLikeImpl
 
   class HarnessLikeImpl extends Impl with HasHarnessInstantiators {
+    all_leds.foreach(_ := DontCare)
     clockOverlay.overlayOutput.node.out(0)._1.reset := ~resetPin
 
     val clk_100mhz = clockOverlay.overlayOutput.node.out.head._1.clock

fpga/src/main/scala/nexysvideo/Configs.scala

@@ -0,0 +1,72 @@
+// See LICENSE for license details.
+package chipyard.fpga.nexysvideo
+
+import org.chipsalliance.cde.config._
+import freechips.rocketchip.subsystem._
+import freechips.rocketchip.devices.debug._
+import freechips.rocketchip.devices.tilelink._
+import freechips.rocketchip.diplomacy._
+import freechips.rocketchip.system._
+import freechips.rocketchip.tile._
+
+import sifive.blocks.devices.uart._
+import sifive.fpgashells.shell.{DesignKey}
+
+import testchipip.{SerialTLKey}
+
+import chipyard.{BuildSystem}
+
+// don't use FPGAShell's DesignKey
+class WithNoDesignKey extends Config((site, here, up) => {
+  case DesignKey => (p: Parameters) => new SimpleLazyModule()(p)
+})
+
+// DOC include start: WithNexysVideoTweaks and Rocket
+class WithNexysVideoTweaks extends Config(
+  new WithNexysVideoUARTTSI ++
+  new WithNexysVideoDDRTL ++
+  new WithNoDesignKey ++
+  new testchipip.WithUARTTSIClient ++
+  new chipyard.harness.WithSerialTLTiedOff ++
+  new chipyard.harness.WithHarnessBinderClockFreqMHz(50) ++
+  new chipyard.config.WithMemoryBusFrequency(50.0) ++
+  new chipyard.config.WithFrontBusFrequency(50.0) ++
+  new chipyard.config.WithSystemBusFrequency(50.0) ++
+  new chipyard.config.WithPeripheryBusFrequency(50.0) ++
+  new chipyard.harness.WithAllClocksFromHarnessClockInstantiator ++
+  new chipyard.clocking.WithPassthroughClockGenerator ++
+  new chipyard.config.WithNoDebug ++ // no jtag
+  new chipyard.config.WithNoUART ++ // use UART for the UART-TSI thing instad
+  new chipyard.config.WithTLBackingMemory ++ // FPGA-shells converts the AXI to TL for us
+  new freechips.rocketchip.subsystem.WithExtMemSize(BigInt(512) << 20) ++ // 512mb on Nexys Video
+  new freechips.rocketchip.subsystem.WithoutTLMonitors)
+
+class RocketNexysVideoConfig extends Config(
+  new WithNexysVideoTweaks ++
+  new chipyard.config.WithBroadcastManager ++ // no l2
+  new chipyard.RocketConfig)
+// DOC include end: WithNexysVideoTweaks and Rocket
+
+// DOC include start: WithTinyNexysVideoTweaks and Rocket
+class WithTinyNexysVideoTweaks extends Config(
+  new WithNexysVideoUARTTSI ++
+  new WithNoDesignKey ++
+  new sifive.fpgashells.shell.xilinx.WithNoNexysVideoShellDDR ++ // no DDR
+  new testchipip.WithUARTTSIClient ++
+  new chipyard.harness.WithSerialTLTiedOff ++
+  new chipyard.harness.WithHarnessBinderClockFreqMHz(50) ++
+  new chipyard.config.WithMemoryBusFrequency(50.0) ++
+  new chipyard.config.WithFrontBusFrequency(50.0) ++
+  new chipyard.config.WithSystemBusFrequency(50.0) ++
+  new chipyard.config.WithPeripheryBusFrequency(50.0) ++
+  new chipyard.harness.WithAllClocksFromHarnessClockInstantiator ++
+  new chipyard.clocking.WithPassthroughClockGenerator ++
+  new chipyard.config.WithNoDebug ++ // no jtag
+  new chipyard.config.WithNoUART ++ // use UART for the UART-TSI thing instad
+  new freechips.rocketchip.subsystem.WithoutTLMonitors)
+
+class TinyRocketNexysVideoConfig extends Config(
+  new WithTinyNexysVideoTweaks ++
+  new chipyard.config.WithBroadcastManager ++ // no l2
+  new chipyard.TinyRocketConfig)
+  // DOC include end: WithTinyNexysVideoTweaks and Rocket

fpga/src/main/scala/nexysvideo/Harness.scala

@@ -0,0 +1,92 @@
+// See LICENSE for license details.
+package chipyard.fpga.nexysvideo
+
+import chisel3._
+import chisel3.util._
+import freechips.rocketchip.diplomacy._
+import org.chipsalliance.cde.config.{Parameters}
+import freechips.rocketchip.tilelink._
+import freechips.rocketchip.subsystem.{SystemBusKey}
+
+import sifive.fpgashells.shell.xilinx._
+import sifive.fpgashells.shell._
+import sifive.fpgashells.clocks.{ClockGroup, ClockSinkNode, PLLFactoryKey, ResetWrangler}
+
+import sifive.blocks.devices.uart._
+
+import chipyard._
+import chipyard.harness._
+import chipyard.iobinders.{HasIOBinders}
+
+class NexysVideoHarness(override implicit val p: Parameters) extends NexysVideoShell {
+  def dp = designParameters
+
+  val clockOverlay = dp(ClockInputOverlayKey).map(_.place(ClockInputDesignInput())).head
+  val harnessSysPLL = dp(PLLFactoryKey)
+  val harnessSysPLLNode = harnessSysPLL()
+  val dutFreqMHz = (dp(SystemBusKey).dtsFrequency.get / (1000 * 1000)).toInt
+  val dutClock = ClockSinkNode(freqMHz = dutFreqMHz)
+  println(s"NexysVideo FPGA Base Clock Freq: ${dutFreqMHz} MHz")
+  val dutWrangler = LazyModule(new ResetWrangler())
+  val dutGroup = ClockGroup()
+  dutClock := dutWrangler.node := dutGroup := harnessSysPLLNode
+
+  harnessSysPLLNode := clockOverlay.overlayOutput.node
+
+  val io_uart_bb = BundleBridgeSource(() => new UARTPortIO(dp(PeripheryUARTKey).headOption.getOrElse(UARTParams(0))))
+  val uartOverlay = dp(UARTOverlayKey).head.place(UARTDesignInput(io_uart_bb))
+
+  // Optional DDR
+  val ddrOverlay = if (p(NexysVideoShellDDR)) Some(dp(DDROverlayKey).head.place(DDRDesignInput(dp(ExtTLMem).get.master.base, dutWrangler.node, harnessSysPLLNode)).asInstanceOf[DDRNexysVideoPlacedOverlay]) else None
+  val ddrClient = if (p(NexysVideoShellDDR)) Some(TLClientNode(Seq(TLMasterPortParameters.v1(Seq(TLMasterParameters.v1(
+    name = "chip_ddr",
+    sourceId = IdRange(0, 1 << dp(ExtTLMem).get.master.idBits)
+  )))))) else None
+  val ddrBlockDuringReset = if (p(NexysVideoShellDDR)) Some(LazyModule(new TLBlockDuringReset(4))) else None
+  if (p(NexysVideoShellDDR)) { ddrOverlay.get.overlayOutput.ddr := ddrBlockDuringReset.get.node := ddrClient.get }
+
+  val ledOverlays = dp(LEDOverlayKey).map(_.place(LEDDesignInput()))
+  val all_leds = ledOverlays.map(_.overlayOutput.led)
+  val status_leds = all_leds.take(2)
+  val other_leds = all_leds.drop(2)
+
+
+  override lazy val module = new HarnessLikeImpl
+
+  class HarnessLikeImpl extends Impl with HasHarnessInstantiators {
+    all_leds.foreach(_ := DontCare)
+    clockOverlay.overlayOutput.node.out(0)._1.reset := ~resetPin
+
+    val clk_100mhz = clockOverlay.overlayOutput.node.out.head._1.clock
+
+    // Blink the status LEDs for sanity
+    withClockAndReset(clk_100mhz, dutClock.in.head._1.reset) {
+      val period = (BigInt(100) << 20) / status_leds.size
+      val counter = RegInit(0.U(log2Ceil(period).W))
+      val on = RegInit(0.U(log2Ceil(status_leds.size).W))
+      status_leds.zipWithIndex.map { case (o,s) => o := on === s.U }
+      counter := Mux(counter === (period-1).U, 0.U, counter + 1.U)
+      when (counter === 0.U) {
+        on := Mux(on === (status_leds.size-1).U, 0.U, on + 1.U)
+      }
+    }
+
+    other_leds(0) := resetPin
+
+    harnessSysPLL.plls.foreach(_._1.getReset.get := pllReset)
+
+    def referenceClockFreqMHz = dutFreqMHz
+    def referenceClock = dutClock.in.head._1.clock
+    def referenceReset = dutClock.in.head._1.reset
+    def success = { require(false, "Unused"); false.B }
+
+    if (p(NexysVideoShellDDR)) { 
+      ddrOverlay.get.mig.module.clock := harnessBinderClock
+      ddrOverlay.get.mig.module.reset := harnessBinderReset
+      ddrBlockDuringReset.get.module.clock := harnessBinderClock
+      ddrBlockDuringReset.get.module.reset := harnessBinderReset.asBool || !ddrOverlay.get.mig.module.io.port.init_calib_complete
+    }
+
+    instantiateChipTops()
+  }
+}

fpga/src/main/scala/nexysvideo/HarnessBinders.scala

@@ -0,0 +1,43 @@
+// See LICENSE for license details.
+package chipyard.fpga.nexysvideo
+
+import chisel3._
+
+import freechips.rocketchip.subsystem.{PeripheryBusKey}
+import freechips.rocketchip.tilelink.{TLBundle}
+import freechips.rocketchip.util.{HeterogeneousBag}
+import freechips.rocketchip.diplomacy.{LazyRawModuleImp}
+
+import sifive.blocks.devices.uart.{UARTParams}
+
+import chipyard._
+import chipyard.harness._
+
+import testchipip._
+
+class WithNexysVideoUARTTSI(uartBaudRate: BigInt = 115200) extends OverrideHarnessBinder({
+  (system: CanHavePeripheryUARTTSI, th: HasHarnessInstantiators, ports: Seq[UARTTSIIO]) => {
+    implicit val p = chipyard.iobinders.GetSystemParameters(system)
+    require(ports.size <= 1)
+    val nexysvideoth = th.asInstanceOf[LazyRawModuleImp].wrapper.asInstanceOf[NexysVideoHarness]
+    ports.map({ port =>
+      nexysvideoth.io_uart_bb.bundle <> port.uart
+      nexysvideoth.other_leds(1) := port.dropped
+      nexysvideoth.other_leds(2) := port.tsi2tl_state(0)
+      nexysvideoth.other_leds(3) := port.tsi2tl_state(1)
+      nexysvideoth.other_leds(4) := port.tsi2tl_state(2)
+      nexysvideoth.other_leds(5) := port.tsi2tl_state(3)
+    })
+  }
+})
+
+class WithNexysVideoDDRTL extends OverrideHarnessBinder({
+  (system: CanHaveMasterTLMemPort, th: HasHarnessInstantiators, ports: Seq[HeterogeneousBag[TLBundle]]) => {
+    require(ports.size == 1)
+    val nexysTh = th.asInstanceOf[LazyRawModuleImp].wrapper.asInstanceOf[NexysVideoHarness]
+    val bundles = nexysTh.ddrClient.get.out.map(_._1)
+    val ddrClientBundle = Wire(new HeterogeneousBag(bundles.map(_.cloneType)))
+    bundles.zip(ddrClientBundle).foreach { case (bundle, io) => bundle <> io }
+    ddrClientBundle <> ports.head
+  }
+})

scripts/build-setup.sh

@@ -109,8 +109,31 @@ if [ $TOOLCHAIN_TYPE == "esp-tools" ]; then
     done
 fi
 
+
+#######################################
+###### BEGIN STEP-BY-STEP SETUP #######
+#######################################
+
+# In order to run code on error, we must handle errors manually
+set +e;
+
+function begin_step
+{
+    thisStepNum=$1;
+    thisStepDesc=$2;
+    echo " ========== BEGINNING STEP $thisStepNum: $thisStepDesc =========="
+}
+function exit_if_last_command_failed
+{
+    local exitcode=$?;
+    if [ $exitcode -ne 0 ]; then
+        die "Build script failed with exit code $exitcode at step $thisStepNum: $thisStepDesc" $exitcode;
+    fi
+}
+
 # setup and install conda environment
 if run_step "1"; then
+    begin_step "1" "Conda environment setup"
     # note: lock file must end in .conda-lock.yml - see https://github.com/conda-incubator/conda-lock/issues/154
     CONDA_REQS=$CYDIR/conda-reqs
     CONDA_LOCK_REQS=$CONDA_REQS/conda-lock-reqs
@@ -120,13 +143,15 @@ if run_step "1"; then
     if [ "$USE_UNPINNED_DEPS" = true ]; then
         # auto-gen the lockfiles
         $CYDIR/scripts/generate-conda-lockfiles.sh
+        exit_if_last_command_failed
     fi
 
     # use conda-lock to create env
-    conda-lock install --conda $(which conda) -p $CYDIR/.conda-env $LOCKFILE
+    conda-lock install --conda $(which conda) -p $CYDIR/.conda-env $LOCKFILE &&
 
-    source $CYDIR/.conda-env/etc/profile.d/conda.sh
+    source $CYDIR/.conda-env/etc/profile.d/conda.sh &&
     conda activate $CYDIR/.conda-env
+    exit_if_last_command_failed
 fi
 
 if [ -z "$FORCE_FLAG" ]; then
@@ -138,11 +163,14 @@ fi
 
 # initialize all submodules (without the toolchain submodules)
 if run_step "2"; then
+    begin_step "2" "Initializing Chipyard submodules"
     $CYDIR/scripts/init-submodules-no-riscv-tools.sh $FORCE_FLAG
+    exit_if_last_command_failed
 fi
 
 # build extra toolchain collateral (i.e. spike, pk, riscv-tests, libgloss)
 if run_step "3"; then
+    begin_step "3" "Building toolchain collateral"
     if run_step "1"; then
         PREFIX=$CONDA_PREFIX/$TOOLCHAIN_TYPE
     else
@@ -153,57 +181,73 @@ if run_step "3"; then
         PREFIX=$RISCV
     fi
     $CYDIR/scripts/build-toolchain-extra.sh $TOOLCHAIN_TYPE -p $PREFIX
+    exit_if_last_command_failed
 fi
 
 # run ctags for code navigation
 if run_step "4"; then
+    begin_step "4" "Running ctags for code navigation"
     $CYDIR/scripts/gen-tags.sh
+    exit_if_last_command_failed
 fi
 
 # precompile chipyard scala sources
 if run_step "5"; then
-    pushd $CYDIR/sims/verilator
-    make launch-sbt SBT_COMMAND=";project chipyard; compile"
-    make launch-sbt SBT_COMMAND=";project tapeout; compile"
+    begin_step "5" "Pre-compiling Chipyard Scala sources"
+    pushd $CYDIR/sims/verilator &&
+    make launch-sbt SBT_COMMAND=";project chipyard; compile" &&
+    make launch-sbt SBT_COMMAND=";project tapeout; compile" &&
     popd
+    exit_if_last_command_failed
 fi
 
 # setup firesim
 if run_step "6"; then
-    $CYDIR/scripts/firesim-setup.sh
+    begin_step "6" "Setting up FireSim"
+    $CYDIR/scripts/firesim-setup.sh &&
     $CYDIR/sims/firesim/gen-tags.sh
+    exit_if_last_command_failed
 
     # precompile firesim scala sources
     if run_step "7"; then
-        pushd $CYDIR/sims/firesim
+        begin_step "7" "Pre-compiling Firesim Scala sources"
+        pushd $CYDIR/sims/firesim &&
         (
+            set -e # Subshells un-set "set -e" so it must be re enabled
             echo $CYDIR
             source sourceme-manager.sh --skip-ssh-setup
             pushd sim
             make sbt SBT_COMMAND="project {file:$CYDIR}firechip; compile" TARGET_PROJECT=firesim
             popd
         )
+        exit_if_last_command_failed
         popd
     fi
 fi
 
 # setup firemarshal
 if run_step "8"; then
-    pushd $CYDIR/software/firemarshal
+    begin_step "8" "Setting up FireMarshal"
+    pushd $CYDIR/software/firemarshal &&
     ./init-submodules.sh
+    exit_if_last_command_failed
 
     # precompile firemarshal buildroot sources
     if run_step "9"; then
-        source $CYDIR/scripts/fix-open-files.sh
-        ./marshal $VERBOSE_FLAG build br-base.json
+        begin_step "9" "Pre-compiling FireMarshal buildroot sources"
+        source $CYDIR/scripts/fix-open-files.sh &&
+        ./marshal $VERBOSE_FLAG build br-base.json &&
         ./marshal $VERBOSE_FLAG clean br-base.json
+        exit_if_last_command_failed
     fi
     popd
 fi
 
 # do misc. cleanup for a "clean" git status
 if run_step "10"; then
+    begin_step "10" "Cleaning up repository"
     $CYDIR/scripts/repo-clean.sh
+    exit_if_last_command_failed
 fi
 
 cat <<EOT >> env.sh

scripts/insert-includes.py

@@ -1,4 +1,4 @@
-#!/usr/bin/python
+#!/usr/bin/env python
 
 # replaces a `include with the full include file
 #