Refactor e2e & Joules Plugin

e2e/Makefile

@@ -1 +1,45 @@
-include obj_dir/hammer.d
+vlsi_dir=$(abspath .)
+
+
+
+# minimal flow configuration variables
+design              ?= test
+pdk                 ?= sky130
+tools               ?= cm
+env                 ?= bwrc
+
+extra               ?=  # extra configs
+args                ?=  # command-line args (including step flow control)
+
+
+OBJ_DIR             ?= $(vlsi_dir)/build-$(pdk)-$(tools)/$(design)
+
+# non-overlapping default configs
+ENV_YML             ?= configs-env/$(env)-env.yml
+PDK_CONF            ?= configs-pdk/$(pdk).yml
+TOOLS_CONF          ?= configs-tool/$(tools).yml
+
+# design-specific overrides of default configs
+DESIGN_CONF         ?= configs-design/$(design)/common.yml
+DESIGN_PDK_CONF     ?= configs-design/$(design)/$(pdk).yml
+SIM_CONF            ?= $(if $(findstring sim-rtl,$(MAKECMDGOALS)), configs-design/$(design)/sim-rtl.yml, \
+                       $(if $(findstring sim-syn,$(MAKECMDGOALS)), configs-design/$(design)/sim-syn.yml, \
+                       $(if $(findstring sim-par,$(MAKECMDGOALS)), configs-design/$(design)/sim-par.yml, )))
+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, )))
+
+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_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
+
+-include $(HAMMER_D_MK)

e2e/README.md

@@ -11,50 +11,142 @@ poetry install
 poetry shell
 ```
 
-We provide configs for Berkeley EECS compute nodes: BWRC (`-bwrc`), Millennium (`-a`), and instructional machines (`-inst`).
+## Overview
 
-- Environment configs (commercial CAD tool paths and license servers) are in `env`
-- PDK configs for ASAP7 and sky130 (pointers to PDK paths and CAD tool versions) are in `pdks`
-- The common design config (which CAD tool plugins to use and the design input files) in `configs/common.yml`
-- The PDK specific design config (clock, placement, and pin constraints, and which SRAM generator to use) in `configs/{asap7,sky130}.yml`
+
+### Flow Selection
+
+The following variables in the Makefile select the target flow to run:
+
+- `design` - RTL name
+    - {`test`, `gcd`}
+- `pdk` - PDK name
+    - {`sky130`, `asap7`}
+- `tools` - CAD tool flow
+    - {`cm` (commercial), `or` (OpenROAD)}
+- `env` - compute environment
+    - {`bwrc` (BWRC), `a` (Millenium), `inst` (instructional machines)}
+
+The outputs of the flow by default reside in `OBJ_DIR=build-<pdk>-<tools>/<design>/`
+
+### Configs
+
+The Hammer configuration files consist of environment (`ENV_YML`) and project (`PROJ_YMLS`) configurations.
+The environment configs take precedence over ALL project configs.
+The order of precedence for the project configs reads from right to left (i.e. each file overrides all files to its left).
+All configuration files are summarized below.
+
+```shell
+#         lowest precedence -------------------------------------------> highest precendence
+CONFS ?= $(PDK_CONF) $(TOOLS_CONF) $(DESIGN_CONF) $(DESIGN_PDK_CONF) $(SIM_CONF) $(POWER_CONF)
+```
+
+- `ENV_YML`- Environment configs that specify CAD tool license servers and paths are in `configs-env`.
+  This will take precedence over any other config file
+- `PDK_CONF` - PDK configs shared across all runs with this PDK are in `configs-pdk`
+- `TOOLS_CONF` - Tool configs to select which CAD tool flow to use are in `configs-tools`
+- Design-specific configs are located in `configs-design/<design>`, and are summarized below:
+    - `DESIGN_CONF` - the common design config (design input files, anything else design-specific)
+    - `DESIGN_PDK_CONF` - PDK-specific configs for this particular design (clock, placement, pin constraints)
+    - `SIM_CONF` - Simulation configs for post-RTL, Synthesis, or PnR simulation
+    - `POWER_CONF` - Power simulation configs for post-RTL, Synthesis, or PnR simulation
+      (NOTE: The Makefile expects the power config filename for each simulation level + PDK to be in the format `power-{rtl,syn,par}-<pdk>.yml`,
+      while the `joules.yml` and `voltus.yml` files serve as templates for the Cadence Joules/Voltus power tools)
+
+
+## Run the Flow
 
 First, use Hammer to construct a Makefile fragment with targets for all parts of the RTL -> GDS flow.
-Specify the configs according to which PDK and environment you are using.
+Specify the appropriate `env/tools/pdk/design` variables to select which configs will be used.
 
 ```shell
-hammer-vlsi -e env/a-env.yml -p pdks/asap7-a.yml -p configs/common.yml -p configs/asap7.yml build
+make build
+# same as: `make env=bwrc tools=cm pdk=sky130 design=test build`
 ```
 
-Hammer will generate a Makefile fragment in `obj_dir/hammer.d`.
+Hammer will generate a Makefile fragment in `OBJ_DIR/hammer.d`.
+
+Then run the rest of the flow, making sure to set the `env/tools/pdk/design` variables as needed:
+
+```shell
+make sim-rtl
+make power-rtl
+
+make syn
+make sim-syn
+make power-syn
+
+make par
+make sim-par
+make power-par
+
+make drc
+make lvs
+```
 
-### Run the Flow
+These actions are summarized in more detail:
 
 - RTL simulation
-    - `make sim-rtl HAMMER_EXTRA_ARGS="-p configs/sim.yml"`
-    - Generated waveform in `obj_dir/sim-rtl-rundir/output.fsdb`
+    - `make sim-rtl`
+    - Generated waveform in `OBJ_DIR/sim-rtl-rundir/output.fsdb`
+- Post-RTL Power simulation
+    - `make sim-rtl-to-power`
+    - `make power-rtl`
+    - Generated power reports in `OBJ_DIR/power-rtl-rundir/reports`
 - Synthesis
     - `make syn`
-    - Gate-level netlist in `obj_dir/syn-rundir/pass.mapped.v`
+    - Gate-level netlist in `OBJ_DIR/syn-rundir/pass.mapped.v`
 - Post-Synthesis simulation
-    - `make syn-to-sim HAMMER_EXTRA_ARGS="-p configs/syn-sim.yml"`
-    - `make sim-syn HAMMER_EXTRA_ARGS="-p configs/syn-sim.yml"`
-    - Generated waveform and register forcing ucli script in `obj_dir/sim-syn-rundir`
+    - `make syn-to-sim`
+    - `make sim-syn`
+    - Generated waveform and register forcing ucli script in `OBJ_DIR/sim-syn-rundir`
+- Post-Synthesis Power simulation
+    - `make syn-to-power`
+    - `make sim-syn-to-power`
+    - `make power-syn`
+    - Generated power reports in `OBJ_DIR/power-syn-rundir/reports`
 - PnR
     - `make syn-to-par`
     - `make par`
-    - LVS netlist (`pass.lvs.v`) and GDS (`pass.gds`) in `obj_dir/par-rundir`
+    - LVS netlist (`pass.lvs.v`) and GDS (`pass.gds`) in `OBJ_DIR/par-rundir`
 - Post-PnR simulation
-    - `make par-to-sim HAMMER_EXTRA_ARGS="-p configs/par-sim.yml"`
-    - `make sim-par HAMMER_EXTRA_ARGS="-p configs/par-sim.yml"`
+    - `make par-to-sim`
+    - `make sim-par`
+- Post-PnR Power simulation
+    - `make par-to-power`
+    - `make power-par`
+    - Generated power reports in `OBJ_DIR/power-par-rundir`
 
-### Custom Setups
+### Flow Customization
+
+If at any point you would like to use custom config files (that will override any previous configs), assign the `extra` Make variable to a space-separated list of these files.
+For example, to run the `test` design with `sky130` through the commercial flow, but run LVS with Cadence Pegasus instead of the default Siemens Calibre,
+simply run the following:
+
+```shell
+make extra="configs-tool/pegasus.yml" build
+```
+
+To use the [Hammer step flow control](https://hammer-vlsi.readthedocs.io/en/stable/Hammer-Use/Flow-Control.html), prepend `redo-` to any VLSI flow action,
+then assign the `args` Make variable to the appropriate Hammer command line args.
+For example, to only run the `report_power` step of the `power-rtl` action (i.e. bypass synthesis), run the following:
+
+```shell
+make args="--only_step report_power" redo-power-rtl
+```
+
+## Custom Setups
 
 If you're not using a Berkeley EECS compute node, you can create your own environment setup.
 
-- Create an environment config for your node to specify the location of the CAD tools, modeled after the yaml files in `env`
-- Create a PDK config for your node to specify the PDK paths and versions, modeled after the yaml files in `pdks`
-- Point to your custom configs when running `hammer-vlsi`. The rest of the flow should be identical
+- Create an environment config similar to those in `configs-env` for your node to specify the CAD tool license servers and paths/versions of CAD tools and the PDK, and set the `ENV_YML` variable to this file.
+- The rest of the flow should be identical
+
+### ASAP7 Install
+
+Clone the [asap7 repo](https://github.com/The-OpenROAD-Project/asap7) somewhere and reference the path in your `ENV_YML` config.
 
-#### ASAP7 Install
+### Sky130 Install
 
-Clone the [asap7 repo](https://github.com/The-OpenROAD-Project/asap7) somewhere and reference the path in your PDK yaml config.
+Refere to the [Hammer Sky130 plugin README](https://github.com/ucb-bar/hammer/tree/master/hammer/technology/sky130)
+to install the Sky130 PDK, then reference the path in your `ENV_YML` config (only the `technology.sky130.sky130A` key is required).

e2e/configs-design/gcd/asap7.yml

@@ -0,0 +1,28 @@
+# Specify clock signals
+vlsi.inputs.clocks: [
+  {name: "clk", period: "5ns", uncertainty: "0.1ns"}
+]
+
+sim.inputs:
+  defines: ['CLOCK_PERIOD=5']
+  defines_meta: 'append'
+
+# Placement Constraints
+vlsi.inputs.placement_constraints:
+  - path: "gcd"
+    type: toplevel
+    x: 0
+    y: 0
+    width: 100
+    height: 100
+    margins:
+      left: 0
+      right: 0
+      top: 0
+      bottom: 0
+
+vlsi.inputs.pin_mode: generated
+vlsi.inputs.pin.generate_mode: semi_auto
+vlsi.inputs.pin.assignments: [
+  {pins: "*", layers: ["M5"], side: "bottom"}
+]

e2e/configs-design/gcd/common.yml

@@ -0,0 +1,9 @@
+# Generate Make include to aid in tlow
+vlsi.core.build_system: make
+
+vlsi.inputs.power_spec_type: "cpf"
+vlsi.inputs.power_spec_mode: "auto"
+
+synthesis.inputs:
+  top_module: "gcd"
+  input_files: ["src/gcd.v"]

e2e/configs-design/gcd/joules.yml

@@ -0,0 +1,11 @@
+# Test Joules Flow
+
+vlsi.core.power_tool: "hammer.power.joules"
+
+power.inputs.input_files: ["src/gcd.v"]
+power.inputs.top_module: "gcd"
+power.inputs.tb_name: "gcd_tb"
+power.inputs.tb_dut: "gcd_dut"
+power.inputs.waveforms: ["build-asap7-cm/gcd/sim-rtl-rundir/output.fsdb"]
+
+power.inputs.power_spec: "auto"

e2e/configs-design/gcd/sim-par.yml

@@ -0,0 +1,13 @@
+# Post-PAR Simulation
+
+sim.inputs:
+  top_module: gcd
+  tb_dut: gcd_dut
+  tb_name: "gcd_tb"
+  input_files: ['src/gcd_tb.v']
+  input_files_meta: append
+  level: "par"
+  options: ['-timescale=1ns/10ps']
+  options_meta: append
+  timing_annotated: false
+

e2e/configs-design/gcd/sim-rtl.yml

@@ -0,0 +1,13 @@
+# RTL Simulation
+
+sim.inputs:
+  top_module: gcd
+  tb_dut: gcd_dut
+  tb_name: "gcd_tb"
+  input_files: ['src/gcd.v', 'src/gcd_tb.v']
+  defines: ['CLOCK_PERIOD=1']
+  defines_meta: 'append'
+  options: ['-timescale=1ns/10ps']
+  options_meta: append
+
+# sim.inputs.execute_sim: false

e2e/configs-design/gcd/sim-syn.yml

@@ -0,0 +1,13 @@
+# Post-Synthesis Simulation
+
+sim.inputs:
+  top_module: gcd
+  tb_dut: gcd_dut
+  tb_name: "gcd_tb"
+  input_files: ['src/gcd_tb.v']
+  input_files_meta: append
+  level: "syn"
+  options: ['-timescale=1ns/10ps']
+  options_meta: append
+  timing_annotated: true
+

e2e/configs/sky130.yml → e2e/configs-design/gcd/sky130.yml

@@ -1,20 +1,25 @@
 # Specify clock signals
 vlsi.inputs.clocks: [
-  {name: "clock", period: "10ns", uncertainty: "0.1ns"}
+  {name: "clk", period: "10ns", uncertainty: "0.1ns"}
 ]
 
+sim.inputs:
+  defines: ['CLOCK_PERIOD=10']
+  defines_meta: 'append'
+
+# Placement Constraints
 vlsi.inputs.placement_constraints:
-  - path: "pass"
+  - path: "gcd"
     type: toplevel
     x: 0
     y: 0
-    width: 100
-    height: 100
+    width: 1000
+    height: 1000
     margins:
-      left: 0
-      right: 0
-      top: 0
-      bottom: 0
+      left: 10
+      right: 10
+      top: 10
+      bottom: 10
 
 # Power Straps
 par.power_straps_mode: generate
@@ -46,11 +51,3 @@ vlsi.inputs.pin.generate_mode: semi_auto
 vlsi.inputs.pin.assignments: [
   {pins: "*", layers: ["met4"], side: "bottom"}
 ]
-
-vlsi.inputs.delays: [
-  {name: "in", clock: "clock", delay: "1", direction: "input"},
-  {name: "out", clock: "clock", delay: "2", direction: "output"}
-]
-
-# SRAM Compiler compiler options
-vlsi.core.sram_generator_tool: "hammer.technology.sky130.sram_compiler"

e2e/configs-design/gcd/voltus.yml

@@ -0,0 +1,8 @@
+# Voltus Power Analysis
+
+vlsi.core.power_tool: "hammer.power.voltus"
+power.inputs:
+  level: "par"
+  tb_name: "gcd_tb"
+  tb_dut: "gcd_dut"
+  database: "/path/to/database"

e2e/configs/asap7.yml → e2e/configs-design/test/asap7.yml

@@ -3,6 +3,10 @@ vlsi.inputs.clocks: [
   {name: "clock", period: "5ns", uncertainty: "0.1ns"}
 ]
 
+sim.inputs:
+  defines: ['CLOCK_PERIOD=5']
+  defines_meta: 'append'
+
 # Tool options.
 vlsi.inputs.placement_constraints:
   - path: "pass"
@@ -27,7 +31,3 @@ vlsi.inputs.delays: [
   {name: "in", clock: "clock", delay: "1", direction: "input"},
   {name: "out", clock: "clock", delay: "2", direction: "output"}
 ]
-
-
-# SRAM Compiler compiler options
-vlsi.core.sram_generator_tool: "hammer.technology.asap7.sram_compiler"

e2e/configs-design/test/common.yml

@@ -0,0 +1,9 @@
+# Generate Make include to aid in flow
+vlsi.core.build_system: make
+
+vlsi.inputs.power_spec_type: "cpf"
+vlsi.inputs.power_spec_mode: "auto"
+
+synthesis.inputs:
+  top_module: "pass"
+  input_files: ["src/pass.v"]

e2e/configs-design/test/power-par-sky130.yml

@@ -0,0 +1,8 @@
+# Voltus Power Analysis
+
+vlsi.core.power_tool: "hammer.power.voltus"
+power.inputs:
+  level: "par"
+  tb_name: "pass_tb"
+  tb_dut: "pass_0"
+  database: "build-sky130-cm/test/par-rundir/pass_FINAL"