Bug fixes in e2e flow (#897)

* fixed spacing in makefile

* sram testcase

* moving sram confs to sram_wrapper confs

* improved setup docs, moved sky130/openroad tools to public spot on bwrc servers

* Update Hammer-Setup.md

* updated sky130/openroad install docs

* misc fixes, bumping bwrc tool versions

* Update openroad-sky130.md

* adder config and src files

* small typo

* RTL sim flags

* added macro defines input to synthesis/power

* improved joules report api

* final test

* removing redundant gitignore

* cleaned up experiments

* more small fixes

* fixes

* made width always a define param

* cleaned up using add8/add32

* improved flow

* reverting repo to remove experiment files, bumping some tool versions

* adding example hammer driver to demonstrate hooks

* report_stem is None bug

* adding sram_wrapper_sky130 testcase to e2e dir

* removing sram22_64x4m4w2 instance because its LEF is empty in sram22 files

* Update README.md

* Update openroad-sky130.md

* reverting default tool flow to nop

Author: nayiri-k

.gitignore

@@ -26,6 +26,9 @@ dist/
 /opendatabase.log
 
 # e2e outputs
+e2e/poetry.lock
 e2e/obj_dir
 e2e/build*
 e2e/output.json
+e2e/*.log
+e2e/experiments/tests/

doc/Examples/openroad-sky130.md

@@ -2,20 +2,21 @@
 
 The following directions will get a simple ``pass`` design from RTL to GDS using the [OpenROAD tools](https://theopenroadproject.org) and the [Skywater 130nm PDK](https://github.com/google/skywater-pdk). These directions are meant to provide the minimal set of steps to do so, please reference the next section, [Hammer End-to-End Integration Tests](https://hammer-vlsi.readthedocs.io/en/stable/Examples/e2e.html), for more detailed descriptions of all files and commands.
 
-## Instructions
+## Prerequisites Setup
 
-First, follow the [Hammer Developer Setup](https://hammer-vlsi.readthedocs.io/en/stable/Hammer-Basics/Hammer-Setup.html#developer-setup) to clone Hammer and install/activate the poetry virtual environment.
+First, follow the [Hammer Power User Setup](https://hammer-vlsi.readthedocs.io/en/stable/Hammer-Basics/Hammer-Setup.html#power-user-setup) to clone Hammer and install/activate the virtual environment.
 
-Next, run the setup script to install the OpenROAD tools using Conda, and Skywater 130nm PDK using the [Open-PDKs tool](https://github.com/RTimothyEdwards/open_pdks).
-This step will take a long time due to the amount and size of the required installs.
-You should supply a ``PREFIX`` path to a directory that will serve as the root of all PDK files and supporting tools (total size of all files is ~42GB),
+Next, run the setup script to install the OpenROAD tools and Skywater 130nm PDK using Conda.
+You should supply a ``PREFIX`` path to a directory that will serve as the root of all PDK files and supporting tools (total size of all files is ~4GB),
 otherwise the script will default to installing to your home directory (``~/``).
 
 ```shell
 cd hammer/e2e
 ./scripts/setup-sky130-openroad.sh [PREFIX]
 ```
 
+## Running Hammer
+
 You should now have a file ``configs-env/my-env.yml`` containing all required tool and technology paths for this tutorial.
 To point to your custom environment setup, set the Make variable ``env=my``.
 Additionally, we set the ``design``, ``pdk``, and ``tools`` Make variables to the appropriate RTL design, PDK, and tools flow, respecively.

doc/Hammer-Basics/Hammer-Setup.md

@@ -2,43 +2,50 @@
 
 Hammer depends on Python 3.9+.
 
-The default technology, ASAP7, has some extra requirements. See its [README](https://github.com/ucb-bar/hammer/blob/master/hammer/technology/asap7/README.md) for instructions.
+The Hammer setup is different based on its usecase, which are summarized as follows:
 
-## User Setup
+* [User Setup](#user-setup): Use Hammer with no modifications.
+* [Power User Setup](#power-user-setup): Modify Hammer and see these changes immediately reflected when calling Hammer [recommended].
+* [Developer Setup](#developer-setup): Developing major Hammer features, adding dependencies, running Hammer unit tests, etc.
 
-You can install Hammer from PyPI:
+Note that some tools and technologies have extra setup requirements:
+* [ASAP7 setup directions](https://github.com/ucb-bar/hammer/blob/master/hammer/technology/asap7/README.md)
+* [Sky130 & OpenROAD tools setup](https://hammer-vlsi.readthedocs.io/en/stable/Examples/openroad-sky130.html)
 
-```shell
-pip install hammer-vlsi
-```
+## User Setup
 
-If you are using ASAP7, you need to install hammer-vlsi with the asap7 extra dependency (gdspy or gdstk). By default, gdspy is installed:
+Install the hammer python package from PyPI.
 
 ```shell
-pip install hammer-vlsi[asap7]
-```
+pip install hammer-vlsi
 
-If instead, you want to install gdstk:
+# if using the ASAP7 PDK you need the gdspy or gdstk dependencies
+pip install hammer-vlsi[asap7]        # default: gdspy
+pip install hammer-vlsi[asap7-gdstk]  # install gdstk instead
 
-```shell
-pip install hammer-vlsi[asap7-gdstk]
+# verify that you can run the `hammer-vlsi` script from the command line
+hammer-vlsi -h
 ```
 
-After installation, verify that you can run the `hammer-vlsi` script from the command line.
+## Power User Setup
+Install Hammer as a source dependency to some target virtual environment, such as conda.
 
 ```shell
-hammer-vlsi -h
-```
+# clone Hammer somewhere on your disk
+git clone https://github.com/ucb-bar/hammer.git
 
-Note: certain tools and technologies will have additional system requirements. For example, LVS with Netgen requires Tcl/Tk 8.6, which is not installed for CentOS7/RHEL7 and below. Refer to each respective tool and technology's documentation for those requirements.
+# activate your target virtual environment, e.g. Chipyard
+#   commands vary for this based on your package/environment manager:
+#     conda activate <env name>
+#     source <path>/.venv/bin/activate
 
-### Installing Hammer as a Source Dependency
+# install hammer package in editable mode to your environment
+cd hammer
+pip install -e .  # run this after activating your target environment
 
-In some cases, it is useful to install Hammer as a source dependency.
-For instance, when developing tool or PDK plugins alongside a new feature or API changes in main Hammer, installing hammer as a source dependency will allow you to make changes in main hammer and see them reflected immediately when running code for your tool/PDK plugin.
+```
 
-(poetry_project)=
-#### From Another Poetry Project
+### Installing from Another Poetry Project
 
 Hammer tool (e.g. `hammer-cadence-plugins`) and PDK plugin repositories are poetry projects (with a `pyproject.toml` in their root).
 To depend on Hammer as a source dependency, first clone Hammer somewhere on your disk.
@@ -54,15 +61,6 @@ Run `poetry update` and `poetry install`.
 Do not commit the changes to `pyproject.toml` or `poetry.lock` without first removing the source dependency.
 You only need to specify `extras` if you need the `asap7` optional dependency (gdstk).
 
-#### From a Generic Python Project
-
-Other repos, such as Chipyard, are not poetry projects, but still depend on Hammer.
-To use Hammer as a source dependency:
-
-1. Remove the PyPI hammer-vlsi dependency from the project (e.g. by editing a conda env.yml file and rerunning dependency resolution)
-1. Clone Hammer somewhere on your disk
-1. Activate the virtualenv of the project (e.g. Chipyard)
-1. Run `pip install -e .` from the root of Hammer *within the project's virtualenv*
 
 ## Developer Setup
 

e2e/.gitignore

@@ -11,7 +11,7 @@ env                 ?= bwrc
 extra               ?=  # extra configs
 args                ?=  # command-line args (including step flow control)
 
-
+HAMMER_DRIVER		?= ./example-driver
 OBJ_DIR             ?= $(vlsi_dir)/build-$(pdk)-$(tools)/$(design)
 
 # non-overlapping default configs
@@ -28,9 +28,10 @@ SIM_CONF            ?= $(if $(findstring -rtl,$(MAKECMDGOALS)), configs-design/$
 POWER_CONF          ?= $(if $(findstring power-rtl,$(MAKECMDGOALS)), configs-design/$(design)/power-rtl-$(pdk).yml, \
                        $(if $(findstring power-syn,$(MAKECMDGOALS)), configs-design/$(design)/power-syn-$(pdk).yml, \
                        $(if $(findstring power-par,$(MAKECMDGOALS)), configs-design/$(design)/power-par-$(pdk).yml, )))
+SRAM_CONF           ?= $(OBJ_DIR)/sram_generator-output.json
 
 PROJ_YMLS           ?= $(PDK_CONF) $(TOOLS_CONF) $(DESIGN_CONF) $(DESIGN_PDK_CONF) $(SIM_CONF) $(POWER_CONF) $(extra)
-HAMMER_EXTRA_ARGS   ?= $(foreach conf, $(PROJ_YMLS), -p $(conf)) $(args)
+HAMMER_EXTRA_ARGS   ?= $(foreach conf, $(PROJ_YMLS), -p $(conf)) -p $(SRAM_CONF) $(args)
 
 
 
@@ -39,10 +40,14 @@ HAMMER_D_MK = $(OBJ_DIR)/hammer.d
 
 build: $(HAMMER_D_MK)
 
-$(HAMMER_D_MK):
-	hammer-vlsi --obj_dir $(OBJ_DIR) -e $(ENV_YML) $(HAMMER_EXTRA_ARGS) build
+$(HAMMER_D_MK): $(SRAM_CONF)
+	$(HAMMER_DRIVER) --obj_dir $(OBJ_DIR) -e $(ENV_YML) $(HAMMER_EXTRA_ARGS) build
 
 -include $(HAMMER_D_MK)
 
+$(SRAM_CONF) srams:
+	$(HAMMER_DRIVER) --obj_dir $(OBJ_DIR) -e $(ENV_YML) $(foreach conf, $(PROJ_YMLS), -p $(conf)) sram_generator
+	cp output.json $(SRAM_CONF)
+
 clean:
-    rm -rf $(OBJ_DIR) hammer-vlsi-*.log
+	rm -rf $(OBJ_DIR) hammer-vlsi-*.log

e2e/Makefile

@@ -1,15 +1,10 @@
 # Hammer End-to-End Integration Tests
 
-This folder contains an end-to-end (RTL -> GDS) smoketest flow using Hammer, using the Cadence toolchain, and the ASAP7 or Skywater 130 PDKs.
+The `hammer/e2e` folder contains an end-to-end (RTL -> GDS) smoketest flow using Hammer, either the Cadence or OpenROAD toolchain, and the ASAP7 or Skywater 130 PDKs.
 
 ## Setup
 
-The integration tests use Hammer as a source dependency, so create the e2e poetry environment.
-
-```shell
-poetry install
-poetry shell
-```
+First, follow the [Hammer Power User Setup](https://hammer-vlsi.readthedocs.io/en/stable/Hammer-Basics/Hammer-Setup.html#power-user-setup) to clone Hammer and install/activate the virtual environment.
 
 ## Overview
 
@@ -19,7 +14,7 @@ poetry shell
 The following variables in the Makefile select the target flow to run:
 
 - `design` - RTL name
-    - {`pass`, `gcd`}
+    - {`pass`, `gcd`, `sram_wrapper_sky130`}
 - `pdk` - PDK name
     - {`sky130`, `asap7`}
 - `tools` - CAD tool flow
@@ -86,6 +81,9 @@ make lvs
 
 These actions are summarized in more detail:
 
+- SRAM generation
+    - `make srams`
+    - Generated SRAM configs in `OBJ_DIR/sram_generator-output.json` (empty unless `vlsi.inputs.sram_parameters` is specified)
 - RTL simulation
     - `make sim-rtl`
     - Generated waveform in `OBJ_DIR/sim-rtl-rundir/output.fsdb`
@@ -151,3 +149,22 @@ Clone the [asap7 repo](https://github.com/The-OpenROAD-Project/asap7) somewhere
 
 Refer to the [Hammer Sky130 plugin README](https://hammer-vlsi.readthedocs.io/en/stable/Technology/Sky130.html)
 to install the Sky130 PDK, then reference the path in your `ENV_YML` config (only the `technology.sky130.sky130A` key is required).
+
+## Pipecleaning
+
+We have provided several reference designs of increasing complexity to aid with pipecleaning your Hammer VLSI flow setup. These are summarized as follows, in order of complexity:
+
+- `pass`: single register
+- `gcd`: computes greatest common denominator, good for testing more complex logic
+- `sram_wrapper_sky130`: example wrapper for an SRAM instance in Sky130, useful for ensuring correct SRAM integration into flow
+    - wraps any Sky130 SRAM instance available in `hammer/hammer/technology/sky130/sram-cache.json`
+    - SRAM instance specified via defines in `configs-design/sram_wrapper_sky130/common.yml`
+    - all SRAM configurations are loaded via these config fragments in `configs-design/sram_wrapper_sky130/sky130.yml`:
+        - ```yaml
+            # Compile all srams in our cache
+            vlsi.inputs.sram_parameters: "../../../hammer/technology/sky130/sram-cache.json"
+            vlsi.inputs.sram_parameters_meta: ["prependlocal", "transclude", "json2list"]
+            ```
+
+
+

e2e/README.md

@@ -11,21 +11,21 @@ power.inputs:
       levels: 1
       toggle_signal: /gcd/clk
       num_toggles: 1
-      report_name: levels-1
+      report_stem: levels-1
       output_formats:
       - all
     # the following two should produce equivalent results:
     - waveform_path: "build-sky130-cm/gcd/sim-rtl-rundir/output.fsdb"
       inst: /gcd/GCDctrl0
       toggle_signal: /gcd/clk
       num_toggles: 1
-      report_name: inst-GCDctrl0
+      report_stem: inst-GCDctrl0
       output_formats:
       - all
     - waveform_path: "build-sky130-cm/gcd/sim-rtl-rundir/output.fsdb"
       module: gcd_control
       interval_size: 5ns
-      report_name: module-gcd_control
+      report_stem: module-gcd_control
       output_formats:
       - all
 

e2e/configs-design/gcd/power-rtl-sky130.yml

@@ -0,0 +1,39 @@
+# Generate Make include to aid in flow
+vlsi.core.build_system: make
+
+vlsi.inputs.power_spec_type: "cpf"
+vlsi.inputs.power_spec_mode: "auto"
+
+design.defines: &DEFINES
+  - SRAM_NAME=sram22_64x32m4w8
+  - DATA_WIDTH=32
+  - ADDR_WIDTH=6
+  - WMASK_WIDTH=4
+
+synthesis.inputs:
+  top_module: "sram_wrapper_sky130"
+  input_files: ["src/sram_wrapper_sky130.v"]
+  defines: *DEFINES
+  defines_meta: append
+
+sim.inputs:
+  top_module: "sram_wrapper_sky130"
+  tb_name: "sram_wrapper_sky130_tb"
+  tb_dut: "sram_wrapper_sky130_dut"
+  defines: *DEFINES
+  defines_meta: append
+  
+power.inputs:
+  top_module: "sram_wrapper_sky130"
+  tb_name: "sram_wrapper_sky130_tb"
+  tb_dut: "sram_wrapper_sky130_dut"
+  defines: *DEFINES
+  defines_meta: append
+
+vlsi.inputs.delays: [
+  {name: "we", clock: "clock", delay: "1", direction: "input"},
+  {name: "wmask", clock: "clock", delay: "1", direction: "input"},
+  {name: "addr", clock: "clock", delay: "1", direction: "input"},
+  {name: "din", clock: "clock", delay: "1", direction: "input"},
+  {name: "dout", clock: "clock", delay: "1", direction: "output"}
+]

e2e/configs-design/sram_wrapper_sky130/common.yml

@@ -0,0 +1,20 @@
+# Test Joules Flow
+
+vlsi.core.power_tool: "hammer.power.joules"
+
+power.inputs:
+  level: "rtl"
+  input_files: ["src/sram_wrapper_sky130.v"]
+  waveforms: ["build-sky130-cm/sram_wrapper_sky130/sim-rtl-rundir/output.fsdb"]
+  report_configs:
+    - waveform_path: "build-sky130-cm/sram_wrapper_sky130/sim-rtl-rundir/output.fsdb"
+      inst: /sram_wrapper_sky130/mem0
+      # specify either interval_size or toggle_signal+num_toggles
+      # interval_size: 2.5ns
+      levels: 2
+      report_stem: sram22_64x32m4w8-write-din_13
+      toggle_signal: clock
+      num_toggles: 1
+      output_formats:
+      - report
+      - ppa

e2e/configs-design/sram_wrapper_sky130/power-rtl-sky130.yml

@@ -0,0 +1,13 @@
+# RTL Simulation
+
+sim.inputs:
+  level: "rtl"
+  input_files: ['src/sram_wrapper_sky130.v', 'src/sram_wrapper_sky130_tb.v']
+  options:
+    - "-notice"
+    - "-line"
+    - "+lint=all,noVCDE"
+    - "+v2k"
+    - "-debug"
+    - "-sverilog"
+    - "-lca"