Merge pull request #2807 from Pinata-Consulting/asap7-minimal-readme

designs/asap7/minimal: getting started README.md

Author: vvbandeira

README.md

@@ -107,6 +107,13 @@ To build from your own git repository:
     cd /home/me/myproject
     make --file=~/OpenROAD-flow-scripts/flow/Makefile DESIGN_CONFIG=somefolder/config.mk ...
 
+## Running a quick smoke-test of ORFS on your own Verilog
+
+You can [run ORFS on your own Verilog files](./flow/designs/asap7/minimal/README.md)
+without setting up a project or moving your Verilog files and even learn
+a thing or two about floorplan, placement and routing
+before you create an .sdc file and a config.mk file.
+
 ## Citing this Work
 
 If you use this software in any published work, we would appreciate a citation!

flow/designs/asap7/minimal/README.md

@@ -0,0 +1,117 @@
+# Report on a design prior to setting up a configuration
+
+This configuration allows running synthesis and floorplan
+to extract some basic information useful when setting
+up a config.mk file from scratch.
+
+Below, instructions are given to run synthesis, floorplan, placement and
+global route, then examine the results in the GUI to see what a
+realistic floorplan and settings might be for your Verilog files.
+
+The example below uses the designs/src/aes/*.v Verilog files, but
+the Verilog files do not have to be located in the OpenROAD-flow-scripts
+git repository, adjust the VERILOG_FILES argument to point to your Verilog
+files:
+
+```
+make DESIGN_CONFIG=designs/asap7/minimal/config.mk DESIGN_NAME=aes_cipher_top VERILOG_FILES="$(ls designs/src/aes/*.v | xargs)" clean_synth synth gui_synth
+```
+
+Where, the exploratory config.mk file to be replaced
+by a design specific config.mk file is:
+
+```
+DESIGN_CONFIG=designs/asap7/minimal/config.mk
+```
+
+Verilog files that to be investigated are specified by:
+
+```
+VERILOG_FILES="$(ls designs/src/aes/*.v | xargs)"
+```
+
+The Verilog top module name is specified by:
+
+```
+DESIGN_NAME=aes_cipher_top
+```
+
+Synthesis cleaned and re-run by:
+
+```
+clean_synth synth
+```
+
+The GUI is opened by the makefile target:
+
+```
+gui_synth
+```
+
+## `make gui_synth` OpenROAD GUI information
+
+![Alt text](gui_synth.png)
+
+The module hierarchy can here be examined to give a sense of
+area required for the default placement density.
+
+## `make gui_floorplan` OpenROAD GUI information
+
+Next to iterate on floorplan settings:
+
+```
+make DESIGN_CONFIG=designs/asap7/minimal/config.mk DESIGN_NAME=aes_cipher_top VERILOG_FILES="$(ls designs/src/aes/*.v | xargs)" clean_floorplan floorplan gui_floorplan
+```
+
+A few more things can be learned from looking at this minimal floorplan:
+
+- The pins are placed randomly on the edges and at least there
+  is enough space on the edges to fit the top level pins
+- Check that the floorplan size is not completely unreasonable and
+  at least there is a chance that this design could go through
+  placement with this density.
+
+![Alt text](gui_floorplan.png)
+
+## `make gui_place` OpenROAD GUI information
+
+Next to iterate on placement settings:
+
+```
+make DESIGN_CONFIG=designs/asap7/minimal/config.mk DESIGN_NAME=aes_cipher_top VERILOG_FILES="$(ls designs/src/aes/*.v | xargs)" clean_place place gui_place
+```
+
+![Alt text](gui_place_heatmap.png)
+
+![Alt text](gui_place_module.png)
+
+From placement more information about how to set up the config.mk
+file can be learned:
+
+- Examine estimated routing congestion to get a sense if there
+  is a chance that the design can be routed.
+- Get a sense of size and location of modules
+
+## CTS(Clock tree Synthesis)
+
+After placement, CTS (clock tree synthesis is run). However the minimal design does
+not have a clock, so CTS runs quickly, but does nothing.
+
+## `make gui_grt` OpenROAD GUI information
+
+For non-trivial designs, some more work will need to be done in floorplan and
+placement before there is a chance that global routing will complete:
+
+```
+make DESIGN_CONFIG=designs/asap7/minimal/config.mk DESIGN_NAME=aes_cipher_top VERILOG_FILES="$(ls designs/src/aes/*.v | xargs)" clean_place place gui_place
+```
+
+![Alt text](gui_grt.png)
+
+Global routing congestion heatmap can be examined in the GUI.
+
+## Next steps
+
+Start creating a config.mk file for your design, write an .sdc file to
+examine timing and find reasonable values for the CORE_UTILIZATION
+and PLACE_DENSITY for your design considering routing congestion.

flow/designs/asap7/minimal/config.mk

@@ -0,0 +1,23 @@
+export DESIGN_NICKNAME = minimal
+export SDC_FILE = $(FLOW_HOME)/designs/asap7/minimal/empty.sdc
+export PLATFORM = asap7
+# Faster build and more information in GUI with hierarchical synthesis
+export SYNTH_HIERARCHICAL ?= 1
+# Keep all modules so we can examine the full hierarchy
+export MAX_UNGROUP_SIZE ?= 0
+
+# Set the core utilization to 10% for the minimal design to
+# maximize chances of getting an initial floorplan. This
+# provides a generous area, yet not so big as to make making
+# floorplan problematic
+export CORE_UTILIZATION ?= 10
+# Low placement density to maximize chances of getting a floorplan
+export PLACE_DENSITY ?= 0.20
+
+# This won't work with an empty .sdc file
+export SKIP_REPORT_METRICS = 1
+
+# Faster build, remove these in your own config.mk
+export SKIP_CTS_REPAIR_TIMING = 1
+export REMOVE_ABC_BUFFERS = 1
+export SKIP_INCREMENTAL_REPAIR = 1

flow/designs/asap7/minimal/empty.sdc

@@ -0,0 +1,2 @@
+# Creating a basic .sdc file is beyond the scope of
+# simple configuration, much as writing Verilog is.

flow/designs/asap7/minimal/gui_floorplan.png

@@ -0,0 +1,14 @@
+#!/bin/bash
+#
+# deltaDebug.py integration smoke-test, run from ORFS/flow folder.
+#
+# Exit with error if anything is amiss, including evaluation of
+# variable names such as $(false), unused variables, etc.
+set -x -ue -o pipefail
+
+cd "$(dirname "$0")/.."
+rm -rf results/outoftree/
+mkdir -p results/outoftree/
+cd results/outoftree/
+cp ../../designs/src/aes/* .
+make --file=../../Makefile DESIGN_CONFIG=../../designs/asap7/minimal/config.mk DESIGN_NAME=aes_cipher_top VERILOG_FILES="$(ls *.v | xargs)" grt