Merge remote-tracking branch 'origin/dev' into prep-for-main

.github/actions/run-tests/action.yml

@@ -17,7 +17,7 @@ runs:
   using: "composite"
   steps:
     - name: Init submodules (since only the RTL is cached)
-      run: ./scripts/init-submodules-no-riscv-tools.sh
+      run: ./scripts/init-submodules-no-riscv-tools.sh --skip-validate
       shell: bash
 
     # Note: You shouldn't need the other inputs since it shouldn't build RTL from scratch

.github/scripts/check-commit.sh

@@ -9,6 +9,7 @@ set -ex
 SCRIPT_DIR="$( cd "$( dirname "$0" )" && pwd )"
 source $SCRIPT_DIR/defaults.sh
 
+# enter bhd repo
 cd $LOCAL_CHIPYARD_DIR
 
 # ignore the private vlsi submodules
@@ -16,15 +17,16 @@ git config submodule.vlsi/hammer-cadence-plugins.update none
 git config submodule.vlsi/hammer-mentor-plugins.update none
 git config submodule.vlsi/hammer-synopsys-plugins.update none
 
-# initialize submodules and get the hashes
-git submodule update --init
-status=$(git submodule status)
-
 all_names=()
 
 
 search_submodule() {
     echo "Running check on submodule $submodule in $dir"
+    # Initialize submodule and get the hashes
+    git submodule update --init $dir/$submodule
+    git -C $dir/$submodule fetch --unshallow
+
+    status=$(git submodule status)
     hash=$(echo "$status" | grep "$dir.*$submodule " | awk '{print$1}' | grep -o "[[:alnum:]]*")
     for branch in "${branches[@]}"
     do
@@ -47,7 +49,7 @@ search () {
     done
 }
 
-submodules=("cva6" "ibex" "boom" "gemmini" "hwacha" "icenet" "nvdla" "rocket-chip" "sha3" "sifive-blocks" "sifive-cache" "testchipip" "riscv-sodor")
+submodules=("cva6" "boom" "ibex" "gemmini" "hwacha" "icenet" "nvdla" "rocket-chip" "sha3" "sifive-blocks" "sifive-cache" "testchipip" "riscv-sodor")
 dir="generators"
 branches=("master" "main" "dev")
 search

.github/scripts/defaults.sh

@@ -9,12 +9,11 @@ REMOTE_MAKE_NPROC=4
 VERILATOR_VERSION=v4.034
 
 HOME=$GITHUB_WORKSPACE
-CURRENT_BRANCH=$(git branch --show-current)
 
 # remote variables
 # CI_DIR is defined externally based on the GH repository secret BUILDDIR
 
-REMOTE_PREFIX=$CI_DIR/${GITHUB_REPOSITORY#*/}-$CURRENT_BRANCH
+REMOTE_PREFIX=$CI_DIR/${GITHUB_REPOSITORY#*/}-${GITHUB_REF_NAME//\//-}
 REMOTE_WORK_DIR=$GITHUB_WORKSPACE
 REMOTE_RISCV_DIR=$GITHUB_WORKSPACE/riscv-tools-install
 REMOTE_ESP_DIR=$GITHUB_WORKSPACE/esp-tools-install

.github/scripts/remote-do-rtl-build.sh

@@ -15,7 +15,7 @@ SCRIPT_DIR="$( cd "$( dirname "$0" )" && pwd )"
 source $SCRIPT_DIR/defaults.sh
 
 cd $REMOTE_CHIPYARD_DIR
-./scripts/init-submodules-no-riscv-tools.sh
+./scripts/init-submodules-no-riscv-tools.sh --skip-validate
 ./scripts/init-fpga.sh
 
 TOOLS_DIR=$REMOTE_RISCV_DIR

.github/scripts/remote-run-firesim-scala-tests.sh

@@ -18,7 +18,7 @@ export PATH="$RISCV/bin:$PATH"
 # This would generally be handled by build-setup.sh/firesim-setup.sh
 REMOTE_FIRESIM_SYSROOT=$REMOTE_FIRESIM_DIR/lib-install
 
-./scripts/init-submodules-no-riscv-tools.sh
+./scripts/init-submodules-no-riscv-tools.sh --skip-validate
 cd $REMOTE_CHIPYARD_DIR/sims/firesim/sim/firesim-lib/src/main/cc/lib
 git submodule update --init elfutils libdwarf
 cd $REMOTE_CHIPYARD_DIR/sims/firesim

.gitmodules

@@ -1,36 +1,47 @@
 [submodule "rocket-chip"]
 	path = generators/rocket-chip
 	url = https://github.com/chipsalliance/rocket-chip.git
+	shallow = true
 [submodule "testchipip"]
 	path = generators/testchipip
 	url = https://github.com/ucb-bar/testchipip.git
+	shallow = true
 [submodule "barstools"]
 	path = tools/barstools
 	url = https://github.com/ucb-bar/barstools.git
+	shallow = true
 [submodule "tools/torture"]
 	path = tools/torture
 	url = https://github.com/ucb-bar/riscv-torture.git
+	shallow = true
 [submodule "generators/boom"]
 	path = generators/boom
 	url = https://github.com/riscv-boom/riscv-boom.git
+	shallow = true
 [submodule "generators/sifive-blocks"]
 	path = generators/sifive-blocks
 	url = https://github.com/sifive/sifive-blocks.git
+	shallow = true
 [submodule "generators/hwacha"]
 	path = generators/hwacha
 	url = https://github.com/ucb-bar/hwacha.git
+	shallow = true
 [submodule "sims/firesim"]
 	path = sims/firesim
 	url = https://github.com/firesim/firesim.git
+	shallow = true
 [submodule "generators/icenet"]
 	path = generators/icenet
 	url = https://github.com/firesim/icenet.git
+	shallow = true
 [submodule "generators/block-inclusivecache-sifive"]
 	path = generators/sifive-cache
 	url = https://github.com/sifive/block-inclusivecache-sifive.git
+	shallow = true
 [submodule "toolchains/riscv-tools/riscv-gnu-toolchain"]
 	path = toolchains/riscv-tools/riscv-gnu-toolchain
 	url = https://github.com/riscv/riscv-gnu-toolchain.git
+	shallow = true
 [submodule "toolchains/riscv-tools/riscv-gnu-toolchain-prebuilt"]
 	path = toolchains/riscv-tools/riscv-gnu-toolchain-prebuilt
 	url = https://github.com/ucb-bar/chipyard-toolchain-prebuilt.git
@@ -38,99 +49,132 @@
 [submodule "toolchains/riscv-tools/riscv-isa-sim"]
 	path = toolchains/riscv-tools/riscv-isa-sim
 	url = https://github.com/riscv/riscv-isa-sim.git
+	shallow = true
 [submodule "toolchains/riscv-tools/riscv-pk"]
 	path = toolchains/riscv-tools/riscv-pk
 	url = https://github.com/riscv/riscv-pk.git
+	shallow = true
 [submodule "toolchains/riscv-tools/riscv-tests"]
 	path = toolchains/riscv-tools/riscv-tests
 	url = https://github.com/riscv/riscv-tests.git
+	shallow = true
 [submodule "toolchains/riscv-tools/riscv-openocd"]
 	path = toolchains/riscv-tools/riscv-openocd
 	url = https://github.com/riscv/riscv-openocd.git
+	shallow = true
 [submodule "toolchains/esp-tools/riscv-gnu-toolchain"]
 	path = toolchains/esp-tools/riscv-gnu-toolchain
 	url = https://github.com/ucb-bar/esp-gnu-toolchain.git
+	shallow = true
 [submodule "toolchains/esp-tools/riscv-isa-sim"]
 	path = toolchains/esp-tools/riscv-isa-sim
 	url = https://github.com/ucb-bar/esp-isa-sim.git
+	shallow = true
 [submodule "toolchains/esp-tools/riscv-pk"]
 	path = toolchains/esp-tools/riscv-pk
 	url = https://github.com/riscv/riscv-pk.git
+	shallow = true
 [submodule "toolchains/esp-tools/riscv-tests"]
 	path = toolchains/esp-tools/riscv-tests
 	url = https://github.com/ucb-bar/esp-tests.git
+	shallow = true
 [submodule "toolchains/libgloss"]
 	path = toolchains/libgloss
 	url = https://github.com/ucb-bar/libgloss-htif.git
+	shallow = true
 [submodule "vlsi/hammer"]
 	path = vlsi/hammer
 	url = https://github.com/ucb-bar/hammer.git
+	shallow = true
 [submodule "tools/dsptools"]
 	path = tools/dsptools
 	url = https://github.com/ucb-bar/dsptools.git
+	shallow = true
 [submodule "tools/chisel-testers"]
 	path = tools/chisel-testers
 	url = https://github.com/freechipsproject/chisel-testers.git
+	shallow = true
 [submodule "generators/sha3"]
 	path = generators/sha3
 	url = https://github.com/ucb-bar/sha3.git
+	shallow = true
 [submodule "vlsi/hammer-cadence-plugins"]
 	path = vlsi/hammer-cadence-plugins
 	url = https://github.com/ucb-bar/hammer-cadence-plugins.git
+	shallow = true
 [submodule "vlsi/hammer-synopsys-plugins"]
 	path = vlsi/hammer-synopsys-plugins
 	url = https://github.com/ucb-bar/hammer-synopsys-plugins.git
+	shallow = true
 [submodule "vlsi/hammer-mentor-plugins"]
 	path = vlsi/hammer-mentor-plugins
 	url = https://github.com/ucb-bar/hammer-mentor-plugins.git
+	shallow = true
 [submodule "toolchains/qemu"]
 	path = toolchains/qemu
 	url = https://github.com/qemu/qemu.git
+	shallow = true
 [submodule "tools/axe"]
 	path = tools/axe
 	url = https://github.com/CTSRD-CHERI/axe.git
+	shallow = true
 [submodule "software/spec2017"]
 	path = software/spec2017
 	url = https://github.com/ucb-bar/spec2017-workload.git
+	shallow = true
 [submodule "software/coremark"]
 	path = software/coremark
 	url = https://github.com/ucb-bar/coremark-workload.git
+	shallow = true
 [submodule "generators/gemmini"]
 	path = generators/gemmini
 	url = https://github.com/ucb-bar/gemmini
+	shallow = true
 [submodule "software/firemarshal"]
 	path = software/firemarshal
 	url = https://github.com/firesim/FireMarshal.git
+	shallow = true
 [submodule "generators/cva6"]
 	path = generators/cva6
 	url = https://github.com/ucb-bar/cva6-wrapper.git
+	shallow = true
 [submodule "tools/DRAMSim2"]
 	path = tools/DRAMSim2
 	url = https://github.com/firesim/DRAMSim2.git
+	shallow = true
 [submodule "generators/nvdla"]
 	path = generators/nvdla
 	url = https://github.com/ucb-bar/nvdla-wrapper.git
+	shallow = true
 [submodule "software/nvdla-workload"]
 	path = software/nvdla-workload
 	url = https://github.com/ucb-bar/nvdla-workload.git
+	shallow = true
 [submodule "tools/dromajo/dromajo-src"]
 	path = tools/dromajo/dromajo-src
 	url = https://github.com/riscv-boom/dromajo.git
+	shallow = true
 [submodule "generators/riscv-sodor"]
 	path = generators/riscv-sodor
 	url = https://github.com/ucb-bar/riscv-sodor.git
+	shallow = true
 [submodule "fpga/fpga-shells"]
 	path = fpga/fpga-shells
 	url = https://github.com/sifive/fpga-shells.git
+	shallow = true
 [submodule "tools/api-config-chipsalliance"]
 	path = tools/api-config-chipsalliance
 	url = https://github.com/chipsalliance/api-config-chipsalliance.git
+	shallow = true
 [submodule "tools/rocket-dsp-utils"]
 	path = tools/rocket-dsp-utils
 	url = https://github.com/ucb-bar/rocket-dsp-utils
+	shallow = true
 [submodule "generators/ibex"]
 	path = generators/ibex
 	url = https://github.com/ucb-bar/ibex-wrapper
+        shallow = true
 [submodule "generators/fft-generator"]
 	path = generators/fft-generator
 	url = https://github.com/ucb-bar/FFTGenerator.git
+	shallow = true

.readthedocs.yml

@@ -1,7 +1,16 @@
 version: 2
+
+build:
+    os: ubuntu-20.04
+    tools:
+        python: "3.6"
+
 formats: all
+
 sphinx:
-  configuration: docs/conf.py
+    configuration: docs/conf.py
+    fail_on_warning: true
+
 python:
-   install:
+    install:
-      - requirements: docs/requirements.txt
+        - requirements: docs/requirements.txt

CHANGELOG.md

@@ -2,6 +2,61 @@
 
 This changelog follows the format defined here: https://keepachangelog.com/en/1.0.0/
 
+## [1.6.0] - 2022-02-15
+
+A more detailed account of everything included is included in the dev to master PR for this release: https://github.com/ucb-bar/chipyard/pull/913
+
+### Added
+* Diplomatic IOBinder-like approach to setting up PRCI across different deployment targets (#900)
+* Default set of MMIO-controlled reset-setters and clock-gaters (#900)
+* Added simulation makefile options `torture` and `torture-overnight` for running Torture (#992)
+* FSDB waveform support (#1072, #1102)
+* Use GitHub Actions for CI (#1004, #999, #1090, #1092)
+* Add MAKE variable in `build-toolchains.sh` (#1021)
+* Cleanup GH issue and PR templates (#1029, #1032)
+* Add support for Ibex core (#979)
+* Add system bus width fragment (#1071)
+* Add support for FSDB waveform files (#1072, #1102)
+* Document simulator timeout settings (#1094)
+* Add FFT Generator (#1067)
+* Add waveforms for post-PNR and power (#1108)
+* Have PRCI control registers use clock of corresponding bus (#1109)
+* Add check to verify that user is running on tagged release (#1114)
+* Hammer tutorial in Sky130 (#1115)
+
+### Changed
+* Bump CVA6 (#909 )
+* Bump Hammer tutorial for ASAP7 r1p7 (#934)
+* Use Published Chisel, FIRRTL, Treadle, FIRRTLInterpreter packages instead of building from source. #1054
+* Change serialTL width to 32. Speeds up simulations (#1040)
+* Update how sbt flag is overridden (by using `SBT_BIN` variable) (#1041)
+* Use published dependencies for Chisel, FIRRTL, Treadle, and FIRRTLInterpreter (#1054)
+* Split `ConfigFragments.scala` into multiple files (with more organization) (#1061)
+* Avoid initializing nvdla software by default (#1063)
+* Update ASAP to 1.7 in Hammer (#934)
+* Shorten Gemmini docs and point to repo (#1078)
+* Bump Gemmini to 0.6.2 (#1083)
+* Use python2 for tracegen script (#1107)
+* Bump to Chisel/FIRRTL 3.5.1 (#1060, #1113)
+* Bump to FireMarshal 1.12.1 (#1116)
+* Bump to FireSim 1.13.0 (#1118 )
+
+### Fixed
+* Fix UART portmap for Arty (#968)
+* Support changing make variable `MODEL` from the cmdline (#1030)
+* Force FIRRTL to 1.4.1 (#1052)
+* Fix MMIO IOBinder (#1045)
+* Mask `fd` warning when running make (#1057)
+* Fix Sodor 5-stage hazard check (#1086)
+* Fix Sodor val io issue (#1089)
+* Fix BOOM reference in Readme (#1104)
+* Fix waveforms for post-P&R power analysis (#1108)
+
+### Removed
+* Remove duplicate `WithUARTIOCells` fragment (#1047)
+* Remove MaxPermSize in java variables (#1082)
+* Remove support for CircleCI (#1105)
+
 ## [1.5.0] - 2021-06-13
 
 A more detailed account of everything included is included in the dev to master PR for this release: https://github.com/ucb-bar/chipyard/pull/773
@@ -9,7 +64,7 @@ A more detailed account of everything included is included in the dev to master
 ### Added
 * FireMarshal support for FPGA prototypes (#849)
 * Hammer update to include power estimation flows, rail analysis, hierarchical sim support, and improved ASAP7 plugin with dummy SRAMs (#886)
-* Docker image 
+* Docker image
 * Support specifying architecture when building tools. (#802)
 * Add Config fragments: WithMultiRoCCFromBuildRoCC, PMP (#809, #821)
 * Add support for simulating an AXI memory interface over the default TL serial link (#812)
@@ -22,7 +77,7 @@ A more detailed account of everything included is included in the dev to master
 * FireSim bump to version 1.12
 * FireMarshal bump to version 1.12
 * Changes default FireSim frequency from 3.2 GHz (dual clock domains) to 1 GHz (single clock domain)
-* Bump pygments from 2.2.0 to 2.7.4 in docs 
+* Bump pygments from 2.2.0 to 2.7.4 in docs
 * Hammer tutorial example is now a TinyRocketConfig (#886)
 * Sha3 Spike model moved from sha3 repo to esp-isa-sim
 

docs/Chipyard-Basics/Initial-Repo-Setup.rst

@@ -29,13 +29,17 @@ Setting up the Chipyard Repo
 
 Start by fetching Chipyard's sources. Run:
 
-.. code-block:: shell
+.. parsed-literal::
 
     git clone https://github.com/ucb-bar/chipyard.git
     cd chipyard
+    # checkout latest official chipyard release
+    # note: this may not be the latest release if the documentation version != "stable"
+    git checkout |version|
     ./scripts/init-submodules-no-riscv-tools.sh
 
 This will initialize and checkout all of the necessary git submodules.
+This will also validate that you are on a tagged branch, otherwise it will prompt for confirmation.
 
 When updating Chipyard to a new version, you will also want to rerun this script to update the submodules.
 Using git directly will try to initialize all submodules; this is not recommended unless you expressly desire this behavior.

docs/VLSI/ASAP7-Tutorial.rst

@@ -9,40 +9,40 @@ Project Structure
 
 This example gives a suggested file structure and build system. The ``vlsi/`` folder will eventually contain the following files and folders:
 
-* Makefile, sim.mk, power.mk
+* ``Makefile``, ``sim.mk``, ``power.mk``
 
   * Integration of Hammer's build system into Chipyard and abstracts away some Hammer commands.
 
-* build
+* ``build``
 
   * Hammer output directory. Can be changed with the ``OBJ_DIR`` variable.
   * Will contain subdirectories such as ``syn-rundir`` and ``par-rundir`` and the ``inputs.yml`` denoting the top module and input Verilog files.
 
-* env.yml
+* ``env.yml``
 
   * A template file for tool environment configuration. Fill in the install and license server paths for your environment.
 
-* example-vlsi
+* ``example-vlsi``
 
   * Entry point to Hammer. Contains example placeholders for hooks.
 
-* example-asap7.yml, example-tools.yml
+* ``example-asap7.yml``, ``example-tools.yml``
 
   * Hammer IR for this tutorial.
 
-* example-design.yml, example-nangate45.yml, example-tech.yml
+* ``example-design.yml``, ``example-nangate45.yml``, ``example-tech.yml``
 
   * Hammer IR not used for this tutorial but provided as templates.
 
-* generated-src
+* ``generated-src``
 
   * All of the elaborated Chisel and FIRRTL.
 
-* hammer, hammer-<vendor>-plugins, hammer-<tech>-plugin
+* ``hammer``, ``hammer-<vendor>-plugins``, ``hammer-<tech>-plugin``
 
   * Core, tool, tech repositories.
 
-* view_gds.py
+* ``view_gds.py``
 
   * A convenience script to view a layout using gdstk or gdspy. Only use this for small layouts (i.e. smaller than the TinyRocketConfig example) since the gdstk-produced SVG will be too big and gdspy's GUI is very slow for large layouts!
 
@@ -65,7 +65,7 @@ In the Chipyard root, run:
 
     ./scripts/init-vlsi.sh asap7
     
-to pull the Hammer & plugin submodules. Note that for technologies other than ``asap7``, the tech submodule must be added in the ``vlsi`` folder first.
+to pull the Hammer & plugin submodules. Note that for technologies other than ``sky130`` or ``asap7``, the tech submodule must be added in the ``vlsi`` folder first.
 
 Pull the Hammer environment into the shell:
 
@@ -106,7 +106,7 @@ Synthesis
 
     make syn CONFIG=TinyRocketConfig
 
-Post-synthesis logs and collateral are in ``build/syn-rundir``. The raw QoR data is available at ``build/syn-rundir/reports``, and methods to extract this information for design space exploration are a WIP.
+Post-synthesis logs and collateral are in ``build/syn-rundir``. The raw quality of results data is available at ``build/syn-rundir/reports``, and methods to extract this information for design space exploration are a work in progress.
 
 Place-and-Route
 ^^^^^^^^^^^^^^^
@@ -144,15 +144,15 @@ Furthermore, the dummy SRAMs that are provided in this tutorial and PDK do not h
 
 Simulation
 ^^^^^^^^^^
-Simulation with VCS is supported, and can be run at the RTL- or gate-level (post-synthesis and P&R). The simulation infrastructure as included here is intended for running RISC-V binaries on a Chipyard config. For example, for an RTL-level simulation:
+Simulation with VCS is supported, and can be run at the RTL- or gate-level (post-synthesis and post-P&R). The simulation infrastructure as included here is intended for running RISC-V binaries on a Chipyard config. For example, for an RTL-level simulation:
 
 .. code-block:: shell
 
     make sim-rtl CONFIG=TinyRocketConfig BINARY=$RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv32ui-p-simple
 
-Post-synthesis and post-P&R simulations use the ``sim-syn`` and ``sim-par`` targets, respectively.
+Post-synthesis and post-P&R simulations use the ``sim-syn`` and ``sim-par`` make targets, respectively.
 
-You can also append ``-debug`` and ``-debug-timing`` to the above sim targets, which will instruct VCS to write a SAIF + VPD and do timing-annotated simulations, respectively. See the ``sim.mk`` file for all available targets.
+Appending ``-debug`` and ``-debug-timing`` to these make targets will instruct VCS to write a SAIF + VPD (or FSDB if the ``USE_FSDB`` flag is set) and do timing-annotated simulations, respectively. See the ``sim.mk`` file for all available targets.
 
 Power/Rail Analysis
 ^^^^^^^^^^^^^^^^^^^
@@ -164,4 +164,4 @@ Post-P&R power and rail (IR drop) analysis is supported with Voltus:
 
 If you append the ``BINARY`` variable to the command, it will use the activity file generated from a ``sim-<syn/par>-debug`` run and report dynamic power & IR drop from the toggles encoded in the waveform.
 
-Note that power and rail analysis can also be run without gate-level simulation, but you will need to run the power tool manually (see the generated commands in the generated ``hammer.d`` buildfile). Only static and active (vectorless) power & IR drop will be reported.
+To bypass gate-level simulation, you will need to run the power tool manually (see the generated commands in the generated ``hammer.d`` buildfile). Static and active (vectorless) power & IR drop will be reported.

docs/VLSI/Building-A-Chip.rst

@@ -49,6 +49,6 @@ Running the VLSI tool flow
 --------------------------
 
 For the full documentation on how to use the VLSI tool flow, see the `Hammer Documentation <https://hammer-vlsi.readthedocs.io/>`__.
-For an example of how to use the VLSI in the context of Chipyard, see :ref:`VLSI/Tutorial:ASAP7 Tutorial`.
+For an example of how to use the VLSI in the context of Chipyard, see :ref:`VLSI/ASAP7-Tutorial:ASAP7 Tutorial`.
 
 

docs/VLSI/Sky130-Tutorial.rst

@@ -0,0 +1,157 @@
+.. _sky130-tutorial:
+
+Sky130 Tutorial
+===============
+The ``vlsi`` folder of this repository contains an example Hammer flow with the SHA-3 accelerator and a dummy hard macro. This example tutorial uses the built-in Sky130 technology plugin and requires access to the included Cadence and Mentor tool plugin submodules. Cadence is necessary for synthesis & place-and-route, while Mentor is needed for DRC & LVS.
+
+Project Structure
+-----------------
+
+This example gives a suggested file structure and build system. The ``vlsi/`` folder will eventually contain the following files and folders:
+
+* ``Makefile``, ``sim.mk``, ``power.mk``
+
+  * Integration of Hammer's build system into Chipyard and abstracts away some Hammer commands.
+
+* ``build``
+
+  * Hammer output directory. Can be changed with the ``OBJ_DIR`` variable.
+  * Will contain subdirectories such as ``syn-rundir`` and ``par-rundir`` and the ``inputs.yml`` denoting the top module and input Verilog files.
+
+* ``env.yml``
+
+  * A template file for tool environment configuration. Fill in the install and license server paths for your environment.
+
+* ``example-vlsi-sky130``
+
+  * Entry point to Hammer. Contains example placeholders for hooks.
+
+* ``example-sky130.yml``, ``example-tools.yml``
+
+  * Hammer IR for this tutorial.
+
+* ``example-design.yml``, ``example-nangate45.yml``, ``example-tech.yml``
+
+  * Hammer IR not used for this tutorial but provided as templates.
+
+* ``generated-src``
+
+  * All of the elaborated Chisel and FIRRTL.
+
+* ``hammer``, ``hammer-<vendor>-plugins``, ``hammer-<tech>-plugin``
+
+  * Core, tool, tech repositories.
+
+Prerequisites
+-------------
+
+* Python 3.4+
+* numpy package
+* Genus, Innovus, Voltus, VCS, and Calibre licenses
+* Sky130 PDK, install using `these directions  <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__
+
+Initial Setup
+-------------
+In the Chipyard root, run:
+
+.. code-block:: shell
+
+    ./scripts/init-vlsi.sh sky130
+    
+to pull the Hammer & plugin submodules. Note that for technologies other than ``sky130`` or ``asap7``, the tech submodule must be added in the ``vlsi`` folder first.
+
+Pull the Hammer environment into the shell:
+
+.. code-block:: shell
+
+    cd vlsi
+    export HAMMER_HOME=$PWD/hammer
+    source $HAMMER_HOME/sourceme.sh
+
+Building the Design
+--------------------
+To elaborate the ``TinyRocketConfig`` and set up all prerequisites for the build system to push the design and SRAM macros through the flow:
+
+.. code-block:: shell
+
+    make buildfile tech_name=sky130 CONFIG=TinyRocketConfig
+
+The ``CONFIG=TinyRocketConfig`` selects the target generator config in the same manner as the rest of the Chipyard framework. This elaborates a stripped-down Rocket Chip in the interest of minimizing tool runtime.
+
+For the curious, ``make buildfile`` generates a set of Make targets in ``build/hammer.d``. It needs to be re-run if environment variables are changed. It is recommended that you edit these variables directly in the Makefile rather than exporting them to your shell environment.
+
+Running the VLSI Flow
+---------------------
+
+example-vlsi-sky130
+^^^^^^^^^^^^^^^^^^^
+This is the entry script with placeholders for hooks. In the ``ExampleDriver`` class, a list of hooks is passed in the ``get_extra_par_hooks``. Hooks are additional snippets of python and TCL (via ``x.append()``) to extend the Hammer APIs. Hooks can be inserted using the ``make_pre/post/replacement_hook`` methods as shown in this example. Refer to the Hammer documentation on hooks for a detailed description of how these are injected into the VLSI flow.
+
+
+example-sky130.yml
+^^^^^^^^^^^^^^^^^^
+This contains the Hammer configuration for this example project. Example clock constraints, power straps definitions, placement constraints, and pin constraints are given. Additional configuration for the extra libraries and tools are at the bottom.
+
+First, set ``technology.sky130.sky130A/sky130_nda/openram_lib`` to the absolute path of the respective directories containing the Sky130 PDK and SRAM files. See the 
+`Sky130 Hammer plugin README <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__
+for details about the PDK setup.
+
+
+Synthesis
+^^^^^^^^^
+.. code-block:: shell
+
+    make syn tech_name=sky130 CONFIG=TinyRocketConfig
+
+Post-synthesis logs and collateral are in ``build/syn-rundir``. The raw quality of results data is available at ``build/syn-rundir/reports``, and methods to extract this information for design space exploration are a work in progress.
+
+Place-and-Route
+^^^^^^^^^^^^^^^
+.. code-block:: shell
+
+    make par tech_name=sky130 CONFIG=TinyRocketConfig
+
+After completion, the final database can be opened in an interactive Innovus session via ``./build/par-rundir/generated-scripts/open_chip``.
+
+Intermediate database are written in ``build/par-rundir`` between each step of the ``par`` action, and can be restored in an interactive Innovus session as desired for debugging purposes. 
+
+Timing reports are found in ``build/par-rundir/timingReports``. They are gzipped text files.
+
+DRC & LVS
+^^^^^^^^^
+To run DRC & LVS, and view the results in Calibre:
+
+.. code-block:: shell
+
+    make drc tech_name=sky130 CONFIG=TinyRocketConfig
+    ./build/chipyard.TestHarness.TinyRocketConfig-ChipTop/drc-rundir/generated-scripts/view_drc
+    make lvs tech_name=sky130 CONFIG=TinyRocketConfig
+    ./build/chipyard.TestHarness.TinyRocketConfig-ChipTop/lvs-rundir/generated-scripts/view_lvs
+
+Some DRC errors are expected from this PDK, especially with regards to the SRAMs, as explained in the 
+`Sky130 Hammer plugin README  <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__.
+For this reason, the ``example-vlsi-sky130`` script black-boxes the SRAMs for DRC/LVS analysis. 
+
+Simulation
+^^^^^^^^^^
+Simulation with VCS is supported, and can be run at the RTL- or gate-level (post-synthesis and post-P&R). The simulation infrastructure as included here is intended for running RISC-V binaries on a Chipyard config. For example, for an RTL-level simulation:
+
+.. code-block:: shell
+
+    make sim-rtl CONFIG=TinyRocketConfig BINARY=$RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple
+
+Post-synthesis and post-P&R simulations use the ``sim-syn`` and ``sim-par`` make targets, respectively.
+
+Appending ``-debug`` and ``-debug-timing`` to these make targets will instruct VCS to write a SAIF + VPD (or FSDB if the ``USE_FSDB`` flag is set) and do timing-annotated simulations, respectively. See the ``sim.mk`` file for all available targets.
+
+Power/Rail Analysis
+^^^^^^^^^^^^^^^^^^^
+Post-P&R power and rail (IR drop) analysis is supported with Voltus:
+
+.. code-block:: shell
+
+    make power-par tech_name=sky130 CONFIG=TinyRocketConfig
+
+If you append the ``BINARY`` variable to the command, it will use the activity file generated from a ``sim-<syn/par>-debug`` run and report dynamic power & IR drop from the toggles encoded in the waveform.
+
+To bypass gate-level simulation, you will need to run the power tool manually (see the generated commands in the generated ``hammer.d`` buildfile). Static and active (vectorless) power & IR drop will be reported.

docs/VLSI/index.rst

@@ -11,5 +11,6 @@ In particular, we aim to support the Hammer physical design generator flow.
    Building-A-Chip
    Hammer
    Basic-Flow
-   Tutorial
+   ASAP7-Tutorial
+   Sky130-Tutorial
    Advanced-Usage

docs/conf.py

@@ -20,6 +20,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import os
+import subprocess
 
 # -- General configuration ------------------------------------------------
 
@@ -59,11 +61,32 @@ author = u'Berkeley Architecture Research'
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
+
-# The short X.Y version.
+on_rtd = os.environ.get("READTHEDOCS") == "True"
-version = u''
+if on_rtd:
-# The full version, including alpha/beta/rc tags.
+    for item, value in os.environ.items():
-release = u''
+        print("[READTHEDOCS] {} = {}".format(item, value))
+
+if on_rtd:
+    rtd_version = os.environ.get("READTHEDOCS_VERSION")
+    if rtd_version == "latest":
+        version = "main" # TODO: default to what "latest" points to
+    elif rtd_version == "stable":
+        # get the latest git tag (which is what rtd normally builds under "stable")
+        # this works since rtd builds things within the repo
+        process = subprocess.Popen(["git", "describe", "--exact-match", "--tags"], stdout=subprocess.PIPE)
+        output = process.communicate()[0].decode("utf-8").strip()
+        if process.returncode == 0:
+            version = output
+        else:
+            version = "v?.?.?" # this should not occur as "stable" is always pointing to tagged version
+    else:
+        version = rtd_version # name of a branch
+else:
+    version = "v?.?.?"
+
+# for now make these match
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -132,6 +155,17 @@ html_logo = '_static/images/chipyard-logo.png'
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Chipyarddoc'
 
+# -- Misc Options ---------------------------------------------------------
+
+html_context = {
+    "version": version
+}
+
+# add rst to end of each rst source file
+# can put custom strings here that are generated from this file
+rst_epilog = f"""
+.. |overall_version| replace:: {version}
+"""
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/index.rst

@@ -1,10 +1,5 @@
-.. Chipyard documentation master file, created by
+Welcome to Chipyard's documentation (version "|version|")!
-   sphinx-quickstart on Fri Mar  8 11:46:38 2019.
+==========================================================
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Chipyard's documentation!
-====================================
 
 .. image:: ./_static/images/chipyard-logo.svg
 

scripts/firesim-setup.sh

@@ -13,5 +13,5 @@ cd "${scripts_dir}/.."
 # Reenable the FireSim submodule
 git config --unset submodule.sims/firesim.update || true
 cd sims/firesim
-./build-setup.sh "$@" --library
+./build-setup.sh "$@" --library --skip-validate
 cd "$RDIR"

scripts/init-submodules-no-riscv-tools-nolog.sh

@@ -4,6 +4,34 @@
 set -e
 set -o pipefail
 
+SKIP_VALIDATE=false
+
+function usage
+{
+    echo "Usage: $0 [--skip-validate]"
+    echo "Initialize Chipyard submodules and setup initial env.sh script."
+    echo ""
+    echo "  --skip-validate    Skip prompt checking for tagged release"
+}
+
+while test $# -gt 0
+do
+   case "$1" in
+        --skip-validate)
+            SKIP_VALIDATE=true;
+            ;;
+        -h | -H | --help)
+            usage
+            exit 1
+            ;;
+        *) echo "ERROR: bad argument $1"
+            usage
+            exit 2
+            ;;
+    esac
+    shift
+done
+
 # Check that git version is at least 1.7.8
 MYGIT=$(git --version)
 MYGIT=${MYGIT#'git version '} # Strip prefix
@@ -17,6 +45,21 @@ if [ "$MINGIT" != "$(echo -e "$MINGIT\n$MYGIT" | sort -V | head -n1)" ]; then
   false
 fi
 
+# before doing anything verify that you are on a release branch/tag
+set +e
+tag=$(git describe --exact-match --tags)
+tag_ret_code=$?
+set -e
+if [ $tag_ret_code -ne 0 ]; then
+    if [ "$SKIP_VALIDATE" = false ]; then
+        read -p "WARNING: You are not on an official release of Chipyard."$'\n'"Type \"y\" to continue if this is intended, otherwise see https://chipyard.readthedocs.io/en/stable/Chipyard-Basics/Initial-Repo-Setup.html#setting-up-the-chipyard-repo: " validate
+        [[ $validate == [yY] ]] || exit 3
+        echo "Setting up non-official Chipyard release"
+    fi
+else
+    echo "Setting up official Chipyard release: $tag"
+fi
+
 # On macOS, use GNU readlink from 'coreutils' package in Homebrew/MacPorts
 if [ "$(uname -s)" = "Darwin" ] ; then
     READLINK=greadlink

scripts/init-vlsi.sh

@@ -10,6 +10,6 @@ git submodule update --init --recursive vlsi/hammer-synopsys-plugins
 git submodule update --init --recursive vlsi/hammer-mentor-plugins
 
 # Initialize HAMMER tech plugin
-if [[ $1 != *asap7* ]]; then
+if [[ $1 != *asap7* ]] && [[ $1 != *sky130* ]]; then
     git submodule update --init --recursive vlsi/hammer-$1-plugin
 fi

vlsi/Makefile

@@ -19,7 +19,7 @@ include $(base_dir)/variables.mk
 #########################################################################################
 sim_name           ?= vcs # needed for GenerateSimFiles, but is unused
 tech_name          ?= asap7
-tech_dir           ?= $(if $(filter $(tech_name),asap7 nangate45),\
+tech_dir           ?= $(if $(filter $(tech_name),sky130 asap7 nangate45),\
                         $(vlsi_dir)/hammer/src/hammer-vlsi/technology/$(tech_name), \
                         $(vlsi_dir)/hammer-$(tech_name)-plugin/$(tech_name))
 SMEMS_COMP         ?= $(tech_dir)/sram-compiler.json
@@ -36,8 +36,12 @@ ENV_YML            ?= $(vlsi_dir)/env.yml
 INPUT_CONFS        ?= example-tools.yml \
                       $(if $(filter $(tech_name),nangate45),\
                         example-nangate45.yml,\
-                        example-asap7.yml)
+                        $(if $(filter $(tech_name),asap7),\
-HAMMER_EXEC        ?= ./example-vlsi
+							example-asap7.yml,\
+							example-sky130.yml))
+HAMMER_EXEC        ?= $(if $(filter $(tech_name),sky130),\
+                        ./example-vlsi-sky130,\
+                        ./example-vlsi)
 VLSI_TOP           ?= $(TOP)
 VLSI_HARNESS_DUT_NAME ?= chiptop
 # If overriding, this should be relative to $(vlsi_dir)

vlsi/example-asap7.yml

@@ -17,7 +17,7 @@ vlsi.inputs.power_spec_type: "cpf"
 
 # Specify clock signals
 vlsi.inputs.clocks: [
-  {name: "clock", period: "1ns", uncertainty: "0.1ns"}
+  {name: "clock_clock", period: "1ns", uncertainty: "0.1ns"}
 ]
 
 # Generate Make include to aid in flow 

vlsi/example-design.yml

@@ -10,7 +10,7 @@ vlsi.inputs.power_spec_type: "cpf"
 
 # Specify clock signals
 vlsi.inputs.clocks: [
-  {name: "clock", period: "2ns", uncertainty: "0.1ns"}
+  {name: "clock_clock", period: "2ns", uncertainty: "0.1ns"}
 ]
 
 # Specify pin properties

vlsi/example-nangate45.yml

@@ -22,7 +22,7 @@ vlsi.inputs.power_spec_type: "cpf"
 
 # Specify clock signals
 vlsi.inputs.clocks: [
-  {name: "clock", period: "5ns", uncertainty: "0.5ns"}
+  {name: "clock_clock", period: "5ns", uncertainty: "0.5ns"}
 ]
 
 # Generate Make include to aid in flow 

vlsi/example-sky130.yml

@@ -0,0 +1,175 @@
+# Technology Setup
+# Technology used is Sky130
+vlsi.core.technology: sky130
+
+vlsi.core.max_threads: 12
+
+# Technology paths
+technology.sky130:
+  sky130_pdk: "path-to-skywater-pdk/"
+  sky130A: "path-to-sky130A/"
+  sky130_nda: "path-to-skywater-src-nda/"
+  openram_lib: "path-to-sky130_sram_macros/" 
+
+# General Hammer Inputs
+
+# Hammer will auto-generate a CPF for simple power designs; see hammer/src/hammer-vlsi/defaults.yml for more info
+vlsi.inputs.power_spec_mode: "auto"
+vlsi.inputs.power_spec_type: "cpf"
+
+# Specify clock signals
+vlsi.inputs.clocks: [
+  {name: "clock_clock", period: "130ns", uncertainty: "1ns"}
+]
+
+# Generate Make include to aid in flow 
+vlsi.core.build_system: make
+
+# Power Straps
+par.power_straps_mode: generate
+par.generate_power_straps_method: by_tracks
+par.blockage_spacing: 2.0
+par.blockage_spacing_top_layer: met4
+par.generate_power_straps_options:
+  by_tracks:
+    strap_layers:
+      - met4
+      - met5
+    pin_layers:
+      - met5
+    blockage_spacing_met2: 4.0
+    track_width: 6
+    track_width_met5: 2
+    track_spacing: 1
+    track_start: 10
+    track_start_met5: 1
+    power_utilization: 0.1
+    power_utilization_met4: 0.3
+    power_utilization_met5: 0.5
+
+# Placement Constraints
+vlsi.inputs.placement_constraints:
+  - path: "ChipTop"
+    type: toplevel
+    x: 0
+    y: 0
+    width: 4500
+    height: 2500
+    margins:
+      left: 0
+      right: 0
+      top: 0
+      bottom: 0
+
+  # Place data cache SRAM instances
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/dcache/data/data_arrays_0/data_arrays_0_ext/mem_0_0"
+    type: hardmacro
+    x: 50
+    y: 100
+    orientation: r0
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/dcache/data/data_arrays_0/data_arrays_0_ext/mem_1_0"
+    type: hardmacro
+    x: 50
+    y: 700
+    orientation: r0
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/dcache/data/data_arrays_0/data_arrays_0_ext/mem_2_0"
+    type: hardmacro
+    x: 50
+    y: 1300
+    orientation: r0
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/dcache/data/data_arrays_0/data_arrays_0_ext/mem_3_0"
+    type: hardmacro
+    x: 50
+    y: 1900
+    orientation: r0
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/dcache/data/data_arrays_0/data_arrays_0_ext/mem_4_0"
+    type: hardmacro
+    x: 1000
+    y: 1900
+    orientation: r0
+
+    
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/dcache/data/data_arrays_0/data_arrays_0_ext/mem_5_0"
+    type: hardmacro
+    x: 1000 
+    y: 1300
+    orientation: r0
+    
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/dcache/data/data_arrays_0/data_arrays_0_ext/mem_6_0"
+    type: hardmacro
+    x: 1000 
+    y: 700
+    orientation: r0
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/dcache/data/data_arrays_0/data_arrays_0_ext/mem_7_0"
+    type: hardmacro
+    x: 1000 
+    y: 100
+    orientation: r0
+
+  # Place instruction cache SRAM instances
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/frontend/icache/data_arrays_0/data_arrays_0_0_ext/mem_0_0"
+    type: hardmacro
+    x: 3700
+    y: 100
+    orientation: r0
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/frontend/icache/data_arrays_0/data_arrays_0_0_ext/mem_1_0"
+    type: hardmacro
+    x: 3700
+    y: 700
+    orientation: r0
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/frontend/icache/tag_array/tag_array_ext/mem_0_0"
+    type: hardmacro
+    x: 3000
+    y: 100
+    orientation: r0
+
+  # Place L2 TLB SRAM instances
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/ptw/l2_tlb_ram/l2_tlb_ram_ext/mem_0_0"
+    type: hardmacro
+    x: 1900
+    y: 1900
+    orientation: "r0"
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/ptw/l2_tlb_ram/l2_tlb_ram_ext/mem_0_1"
+    type: hardmacro
+    x: 2600
+    y: 1900
+    orientation: "r0"
+ 
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/ptw/l2_tlb_ram/l2_tlb_ram_ext/mem_0_2"
+    type: hardmacro
+    x: 3300
+    y: 1900
+    orientation: "r0"
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/ptw/l2_tlb_ram/l2_tlb_ram_ext/mem_0_3"
+    type: hardmacro
+    x: 3950
+    y: 1900
+    orientation: "r0"
+
+  - path: "ChipTop/system/tile_prci_domain/tile_reset_domain/tile/ptw/l2_tlb_ram/l2_tlb_ram_ext/mem_0_4"
+    type: hardmacro
+    x: 3950
+    y: 1300
+    orientation: "r0"
+
+# Pin placement constraints
+vlsi.inputs.pin_mode: generated
+vlsi.inputs.pin.generate_mode: semi_auto
+vlsi.inputs.pin.assignments: [
+  {pins: "*", layers: ["met2", "met4"], side: "bottom"}
+]
+
+# SRAM Compiler compiler options
+vlsi.core.sram_generator_tool: "sram_compiler"
+# You should specify a location for the SRAM generator in the tech plugin
+vlsi.core.sram_generator_tool_path: ["hammer/src/hammer-vlsi/technology/sky130"]
+vlsi.core.sram_generator_tool_path_meta: "append"

vlsi/example-vlsi

@@ -39,7 +39,6 @@ set_db route_design_top_routing_layer 7
 class ExampleDriver(CLIDriver):
     def get_extra_par_hooks(self) -> List[HammerToolHookAction]:
         extra_hooks = [
-
             # Default set of steps can be found in the CAD tool plugin's __init__.py
 
             # make_pre_insertion_hook will execute the custom hook before the specified step

vlsi/example-vlsi-sky130

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+#
+# NOTE: the custom hooks are only used for sky130.
+
+import os
+
+import hammer_vlsi
+from hammer_vlsi import CLIDriver, HammerToolHookAction
+
+from typing import Dict, Callable, Optional, List
+
+from technology.sky130 import SKY130Tech
+
+def example_place_tap_cells(x: hammer_vlsi.HammerTool) -> bool:
+    if x.get_setting("vlsi.core.technology") == "sky130":
+        x.append('''
+# TODO
+# Place custom TCL here
+''')
+    return True
+
+def example_add_fillers(x: hammer_vlsi.HammerTool) -> bool:
+    if x.get_setting("vlsi.core.technology") == "sky130":
+        x.append('''
+# TODO
+# Place custom TCL here
+''')
+    return True
+
+def example_tool_settings(x: hammer_vlsi.HammerTool) -> bool:
+    if x.get_setting("vlsi.core.technology") == "sky130":
+        x.append('''
+# TODO
+# Place custom TCL here
+# only route in met1 to met4 [metal layers: li1(1), met1(2), ..., met4(5), met5(6)]
+set_db route_design_bottom_routing_layer 2
+set_db route_design_top_routing_layer 5
+''')
+    return True
+
+class ExampleDriver(CLIDriver):
+    def get_extra_par_hooks(self) -> List[HammerToolHookAction]:
+        extra_hooks = [
+            # Default set of steps can be found in the CAD tool plugin's __init__.py
+
+            # make_pre_insertion_hook will execute the custom hook before the specified step
+            # SYNTAX: make_pre_insertion_hook("EXISTING_STEP", INSERTED_HOOK)
+            # hammer_vlsi.HammerTool.make_pre_insertion_hook("route_design", example_add_fillers),
+
+            # make_post_insertion_hook will execute the custom hook after the specified step
+            hammer_vlsi.HammerTool.make_post_insertion_hook("init_design", example_tool_settings),
+
+            # make_replacement_hook will replace the specified step with a custom hook
+            # hammer_vlsi.HammerTool.make_replacement_hook("place_tap_cells", example_place_tap_cells),
+
+            # make_removal_hook will remove the specified step from the flow
+            hammer_vlsi.HammerTool.make_removal_hook("place_bumps"),
+
+            # The target step in any of the above calls may be a default step or another one of your custom hooks
+        ]
+        return extra_hooks 
+
+if __name__ == '__main__':
+    ExampleDriver().main()