Merge remote-tracking branch 'origin/master' into HEAD

Author: oharboe

docs/conf.py

@@ -59,8 +59,6 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
 source_suffix = ['.md']
 
 # The master toctree document.
@@ -94,6 +92,10 @@
 html_theme_options = {
     "repository_url": "https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts",
     "repository_branch": "master",
+    "show_navbar_depth": 2,
+    "use_edit_page_button": True,
+    "use_source_button": True,
+    "use_issues_button": True,
     "use_download_button": True,
 
     # list for more fine-grained ordering of icons

docs/toc.yml

@@ -1,8 +1,8 @@
 root: index
 entries:
 
-- file: /dev/null
-  title: ORFS Documentation
+- file: user/UserGuide.md
+  title: User Guide
   entries:
   - file: user/BuildWithDocker
     title: Build With Docker
@@ -13,8 +13,8 @@ entries:
     title: Build With Pre-built Binaries
   - file: user/BuildLocally.md
     title: Build Locally
-  - file: user/UserGuide.md
-    title: User Guide
+  - file: user/BuildWithWSL.md
+    title: Build With WSL
   - file: user/FlowVariables.md
     title: Flow Variables
   - file: contrib/Metrics.md

docs/user/BuildWithPrebuilt.md

@@ -9,6 +9,7 @@ Instructions for installing:
 
 ```{tip} Unfortunately KLayout maintainers do not provide Debian 10/11 compatible packages. You can follow the build-from-sources instruction (Version >=0.25) and Ubuntu 22 instructions [here](https://www.klayout.de/build.html#:~:text=Building%20KLayout%20on%20Linux%20(Version%20%3E%3D%200.25)). 
 ```
+
 ## Install OpenROAD
 Download pre-built binaries with self-contained dependencies
 included from the Precision Innovations' Github releases
@@ -28,22 +29,30 @@ Step 2: Download the artifacts for your distribution.
 
 Step 3: Run the install command based on platform use package installer.
         For example Ubuntu 20.04 use:
+        
 ```shell
 sudo apt install ./openroad_2.0_amd64-ubuntu20.04.deb
 ```
+
 You can install these binaries within docker as well.
 
 
 ## Verify Installation
 You may clone the OpenROAD-flow-scripts repository non-recursively. 
+
 ```
 git clone https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts.git
 ```
+
 Export path variables accordingly.
+
 ```
-export PATH="<yosys_location>/bin:$PATH" 
-export PATH="<klayout_location>/bin:$PATH" # only if built from source
-export LD_LIBRARY_PATH="<klayout_location>/bin:$PATH" # only if built from source
+# these variables are used in flow/Makefile. Do make sure the yosys path is sourced.
+export OPENROAD_EXE=$(command -v openroad)
+export YOSYS_CMD=$(shell command -v yosys)
+
+# only if KLayout is built from source
+export LD_LIBRARY_PATH="<klayout_location>/bin:$PATH" 
 
 yosys -help
 openroad -help

flow/Makefile

@@ -267,21 +267,16 @@ endif
 
 # The following determine the executable location for each tool used by this flow.
 # Priority is given to
-#       1 user include path to the executable prior to running make
-#       2 user explicit set with variable in Makefile or command line
-export OPENROAD_EXE            ?= $(shell command -v openroad)
-ifeq ($(OPENROAD_EXE),)
-  export OPENROAD_EXE           = $(abspath $(FLOW_HOME)/../tools/install/OpenROAD/bin/openroad)
-endif
+#       1 user explicit set with variable in Makefile or command line, for instance setting OPENROAD_EXE
+#       2 ORFS compiled tools: openroad, yosys
+export OPENROAD_EXE      ?= $(abspath $(FLOW_HOME)/../tools/install/OpenROAD/bin/openroad)
+
 OPENROAD_ARGS            = -no_init $(OR_ARGS)
 OPENROAD_CMD             = $(OPENROAD_EXE) -exit $(OPENROAD_ARGS)
 OPENROAD_NO_EXIT_CMD     = $(OPENROAD_EXE) $(OPENROAD_ARGS)
 OPENROAD_GUI_CMD         = $(OPENROAD_EXE) -gui $(OR_ARGS)
 
-YOSYS_CMD               ?= $(shell command -v yosys)
-ifeq ($(YOSYS_CMD),)
-  YOSYS_CMD              = $(abspath $(FLOW_HOME)/../tools/install/yosys/bin/yosys)
-endif
+YOSYS_CMD               ?= $(abspath $(FLOW_HOME)/../tools/install/yosys/bin/yosys)
 
 KLAYOUT_CMD             ?= $(shell command -v klayout)
 
@@ -463,6 +458,18 @@ UNSET_AND_MAKE = @bash -c 'for var in $(UNSET_VARIABLES_NAMES); do unset $$var;
 #
 # A "do-synth" step would be welcomed, but it isn't strictly necessary
 # for the Bazel use-case.
+#
+# do-floorplan, do-place, do-cts, do-route, do-finish are the
+# supported interface to execute those stages without checking
+# for dependencies.
+#
+# The do- substeps of each of these stages are subject to change.
+#
+# $(1) stem, e.g. 2_1_floorplan
+# $(2) dependencies
+# $(3) tcl script step
+# $(4) extension of result, default .odb
+# $(5) folder of target, default $(RESULTS_DIR)
 define do-step
 $(if $(5),$(5),$(RESULTS_DIR))/$(1)$(if $(4),$(4),.odb): $(2)
 	$$(UNSET_AND_MAKE) do-$(1)
@@ -472,6 +479,25 @@ do-$(1):
 	($(TIME_CMD) $(OPENROAD_CMD) $(SCRIPTS_DIR)/$(3).tcl -metrics $(LOG_DIR)/$(1).json) 2>&1 | tee $(LOG_DIR)/$(1).log
 endef
 
+# generate make rules to copy a file, if a dependency change and
+# a do- sibling rule that copies the file unconditionally.
+#
+# The file is copied within the $(RESULTS_DIR)
+#
+# $(1) stem of target, e.g. 2_2_floorplan_io
+# $(2) basename of file to be copied
+# $(3) further dependencies
+# $(4) target extension, default .odb
+define do-copy
+$(RESULTS_DIR)/$(1)$(if $(4),$(4),.odb): $(RESULTS_DIR)/$(2) $(3)
+	$$(UNSET_AND_MAKE) do-$(1)$(if $(4),$(4),)
+
+.PHONY: do-$(1)$(if $(4),$(4),)
+do-$(1)$(if $(4),$(4),):
+	cp $(RESULTS_DIR)/$(2) $(RESULTS_DIR)/$(1)$(if $(4),$(4),.odb)
+endef
+
+
 # STEP 1: Translate verilog to odb
 #-------------------------------------------------------------------------------
 $(eval $(call do-step,2_1_floorplan,$(RESULTS_DIR)/1_synth.v $(RESULTS_DIR)/1_synth.sdc $(TECH_LEF) $(SC_LEF) $(ADDITIONAL_LEFS) $(FOOTPRINT) $(SIG_MAP_FILE) $(FOOTPRINT_TCL),floorplan))
@@ -481,18 +507,15 @@ $(eval $(call do-step,2_1_floorplan,$(RESULTS_DIR)/1_synth.v $(RESULTS_DIR)/1_sy
 ifndef IS_CHIP
 $(eval $(call do-step,2_2_floorplan_io,$(RESULTS_DIR)/2_1_floorplan.odb $(IO_CONSTRAINTS),io_placement_random))
 else
-$(RESULTS_DIR)/2_2_floorplan_io.odb: $(RESULTS_DIR)/2_1_floorplan.odb $(IO_CONSTRAINTS)
-	cp $< $@
+$(eval $(call do-copy,2_2_floorplan_io,2_1_floorplan.odb,$(IO_CONSTRAINTS)))
 endif
 
 # STEP 3: Timing Driven Mixed Sized Placement
 #-------------------------------------------------------------------------------
 ifeq ($(MACRO_PLACEMENT),)
 $(eval $(call do-step,2_3_floorplan_tdms,$(RESULTS_DIR)/2_2_floorplan_io.odb $(RESULTS_DIR)/1_synth.v $(RESULTS_DIR)/1_synth.sdc $(LIB_FILES),tdms_place))
 else
-$(RESULTS_DIR)/2_3_floorplan_tdms.odb: $(RESULTS_DIR)/2_2_floorplan_io.odb $(RESULTS_DIR)/1_synth.v $(RESULTS_DIR)/1_synth.sdc $(LIB_FILES)
-	$(info [INFO][FLOW] Using manual macro placement file $(MACRO_PLACEMENT))
-	cp $< $@
+$(eval $(call do-copy,2_3_floorplan_tdms,2_2_floorplan_io.odb,$(RESULTS_DIR)/1_synth.v $(RESULTS_DIR)/1_synth.sdc $(LIB_FILES)))
 endif
 
 # STEP 4: Macro Placement
@@ -507,11 +530,13 @@ $(eval $(call do-step,2_5_floorplan_tapcell,$(RESULTS_DIR)/2_4_floorplan_macro.o
 #-------------------------------------------------------------------------------
 $(eval $(call do-step,2_6_floorplan_pdn,$(RESULTS_DIR)/2_5_floorplan_tapcell.odb $(PDN_TCL),pdn))
 
-$(RESULTS_DIR)/2_floorplan.odb: $(RESULTS_DIR)/2_6_floorplan_pdn.odb
-	cp $< $@
+$(eval $(call do-copy,2_floorplan,2_6_floorplan_pdn.odb,))
 
 $(RESULTS_DIR)/2_floorplan.sdc: $(RESULTS_DIR)/2_1_floorplan.odb
 
+.PHONY: do-floorplan
+do-floorplan:
+	$(UNSET_AND_MAKE) do-2_1_floorplan do-2_2_floorplan_io do-2_3_floorplan_tdms do-2_4_floorplan_macro do-2_5_floorplan_tapcell do-2_6_floorplan_pdn do-2_floorplan
 
 .PHONY: clean_floorplan
 clean_floorplan:
@@ -539,8 +564,7 @@ $(eval $(call do-step,3_1_place_gp_skip_io,$(RESULTS_DIR)/2_floorplan.odb $(RESU
 ifndef IS_CHIP
 $(eval $(call do-step,3_2_place_iop,$(RESULTS_DIR)/3_1_place_gp_skip_io.odb $(IO_CONSTRAINTS),io_placement))
 else
-$(RESULTS_DIR)/3_2_place_iop.odb: $(RESULTS_DIR)/3_1_place_gp_skip_io.odb $(IO_CONSTRAINTS)
-	cp $< $@
+$(eval $(call do-copy,3_2_place_iop,3_1_place_gp_skip_io.odb,$(IO_CONSTRAINTS)))
 endif
 
 # STEP 3: Global placement with placed IOs, timing-driven, and routability-driven.
@@ -559,11 +583,13 @@ clean_resize:
 #-------------------------------------------------------------------------------
 $(eval $(call do-step,3_5_place_dp,$(RESULTS_DIR)/3_4_place_resized.odb,detail_place))
 
-$(RESULTS_DIR)/3_place.odb: $(RESULTS_DIR)/3_5_place_dp.odb
-	cp $< $@
+$(eval $(call do-copy,3_place,3_5_place_dp.odb,))
 
-$(RESULTS_DIR)/3_place.sdc: $(RESULTS_DIR)/2_floorplan.sdc
-	cp $< $@
+$(eval $(call do-copy,3_place,2_floorplan.sdc,,.sdc))
+
+.PHONY: do-place
+do-place:
+	$(UNSET_AND_MAKE) do-3_1_place_gp_skip_io do-3_2_place_iop do-3_3_place_gp do-3_4_place_resized do-3_5_place_dp do-3_place do-3_place.sdc
 
 # Clean Targets
 #-------------------------------------------------------------------------------
@@ -598,8 +624,11 @@ $(eval $(call do-step,4_2_cts_fillcell,$(RESULTS_DIR)/4_1_cts.odb,fillcell))
 
 $(RESULTS_DIR)/4_cts.sdc: $(RESULTS_DIR)/4_cts.odb
 
-$(RESULTS_DIR)/4_cts.odb: $(RESULTS_DIR)/4_2_cts_fillcell.odb
-	cp $< $@
+$(eval $(call do-copy,4_cts,4_2_cts_fillcell.odb))
+
+.PHONY: do-cts
+do-cts:
+	$(UNSET_AND_MAKE) do-4_1_cts do-4_2_cts_fillcell do-4_cts
 
 .PHONY: clean_cts
 clean_cts:
@@ -633,11 +662,13 @@ else
 $(eval $(call do-step,5_2_route,$(RESULTS_DIR)/4_cts.odb,detail_route))
 endif
 
-$(RESULTS_DIR)/5_route.odb: $(RESULTS_DIR)/5_2_route.odb
-	cp $< $@
+$(eval $(call do-copy,5_route,5_2_route.odb))
 
-$(RESULTS_DIR)/5_route.sdc: $(RESULTS_DIR)/4_cts.sdc
-	cp $< $@
+$(eval $(call do-copy,5_route,4_cts.sdc,,.sdc))
+
+.PHONY: do-route
+do-route:
+	$(UNSET_AND_MAKE) do-5_1_grt do-5_2_route do-5_route do-5_route.sdc
 
 $(RESULTS_DIR)/5_route.v:
 	@export OR_DB=5_route ;\
@@ -693,20 +724,21 @@ elapsed:
 ifneq ($(USE_FILL),)
 $(eval $(call do-step,6_1_fill,$(RESULTS_DIR)/5_route.odb $(FILL_CONFIG),density_fill))
 else
-$(RESULTS_DIR)/6_1_fill.odb: $(RESULTS_DIR)/5_route.odb
-	cp $< $@
+$(eval $(call do-copy,6_1_fill,5_route.odb))
 endif
 
-$(RESULTS_DIR)/6_1_fill.sdc: $(RESULTS_DIR)/5_route.sdc
-	cp $< $@
+$(eval $(call do-copy,6_1_fill,5_route.sdc,,.sdc))
 
-$(RESULTS_DIR)/6_final.sdc: $(RESULTS_DIR)/5_route.sdc
-	cp $< $@
+$(eval $(call do-copy,6_final,5_route.sdc,,.sdc))
 
 $(eval $(call do-step,6_report,$(RESULTS_DIR)/6_1_fill.odb $(RESULTS_DIR)/6_1_fill.sdc,final_report,.log,$(LOG_DIR)))
 
 $(RESULTS_DIR)/6_final.def: $(LOG_DIR)/6_report.log
 
+# NOTE! No GDS file for now
+.PHONY: do-finish
+do-finish:
+	$(UNSET_AND_MAKE) do-6_1_fill do-6_1_fill.sdc do-6_final.sdc do-6_report elapsed
 
 # Skipping resize can be useful for mock abstracts
 .PHONY: skip_resize
@@ -735,9 +767,17 @@ skip_route: $(RESULTS_DIR)/4_cts.odb $(RESULTS_DIR)/4_cts.sdc
 #
 # make skip_resize skip_cts skip_route generate_abstract
 .PHONY: generate_abstract
-generate_abstract: $(RESULTS_DIR)/6_final.gds $(RESULTS_DIR)/6_final.def  $(RESULTS_DIR)/6_final.v
+generate_abstract: $(RESULTS_DIR)/6_final.gds $(RESULTS_DIR)/6_final.def  $(RESULTS_DIR)/6_final.v $(RESULTS_DIR)/6_final.sdc
+	$(UNSET_AND_MAKE) do-generate_abstract
+
+.PHONY: do-generate_abstract
+do-generate_abstract:
 	($(TIME_CMD) $(OPENROAD_CMD) $(SCRIPTS_DIR)/generate_abstract.tcl -metrics $(LOG_DIR)/generate_abstract.json) 2>&1 | tee $(LOG_DIR)/generate_abstract.log
 
+.PHONY: clean_abstract
+clean_abstract:
+	rm -f $(RESULTS_DIR)/$(DESIGN_NAME).lib $(RESULTS_DIR)/$(DESIGN_NAME).lef
+
 # Merge wrapped macros using Klayout
 #-------------------------------------------------------------------------------
 $(WRAPPED_GDSOAS): $(OBJECTS_DIR)/klayout_wrap.lyt $(WRAPPED_LEFS)
@@ -837,7 +877,7 @@ clean:
 	@echo
 
 .PHONY: clean_all
-clean_all: clean_synth clean_floorplan clean_place clean_cts clean_route clean_finish clean_metadata
+clean_all: clean_synth clean_floorplan clean_place clean_cts clean_route clean_finish clean_metadata clean_abstract
 	rm -rf $(OBJECTS_DIR)
 
 .PHONY: nuke