KLayout section of Sky130+OpenROAD tutorial

docs/VLSI/Sky130-OpenROAD-Tutorial.rst

@@ -46,13 +46,14 @@ Prerequisites
 -------------
 
 * Python 3.9+
-* OpenROAD flow tools:
+* OpenROAD flow tools (NOTE: tutorial may break with different tool versions):
 
-  * Yosys (synthesis), install `using conda <https://anaconda.org/litex-hub/yosys>`__ or `from source <https://yosyshq.net/yosys/download.html>`__
-  * OpenROAD (place-and-route), install `using conda <https://anaconda.org/litex-hub/openroad>`__ (note that GUI is disabled in conda package) or `from source <https://openroad.readthedocs.io/en/latest/main/README.html#install-dependencies>`__
-  * KLayout (DEF to GDSII conversion), install `using conda <https://anaconda.org/litex-hub/klayout>`__ or `from source <https://www.klayout.de/build.html>`__
-  * Magic (DRC), , install `using conda <https://anaconda.org/litex-hub/magic>`__ or `from source <http://www.opencircuitdesign.com/magic/install.html>`__
-  * NetGen (LVS), , install `using conda <https://anaconda.org/litex-hub/netgen>`__ or `from source <http://www.opencircuitdesign.com/netgen/install.html>`__
+  * **Yosys 0.27+3** (synthesis), install `using conda <https://anaconda.org/litex-hub/yosys>`__ or `from source <https://yosyshq.net/yosys/download.html>`__
+  * **OpenROAD v2.0-7070-g0264023b6** (place-and-route), install `using conda <https://anaconda.org/litex-hub/openroad>`__ (note that GUI is disabled in conda package) or 
+    `from source <https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/docs/user/Build.md>`__ (git hash: 0264023b6c2a8ae803b8d440478d657387277d93)
+  * **KLayout 0.28.5** (DEF to GDSII conversion, DRC), install `using conda <https://anaconda.org/litex-hub/klayout>`__ or `from source <https://www.klayout.de/build.html>`__
+  * **Magic 8.3.376** (DRC), install `using conda <https://anaconda.org/litex-hub/magic>`__ or `from source <http://www.opencircuitdesign.com/magic/install.html>`__
+  * **NetGen 1.5.250** (LVS), install `using conda <https://anaconda.org/litex-hub/netgen>`__ or `from source <http://www.opencircuitdesign.com/netgen/install.html>`__
 
 * Sky130A PDK, install `using conda <https://anaconda.org/litex-hub/open_pdks.sky130a>`__ or `these directions  <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/sky130>`__
 * `Sram22 Sky130 SRAM macros  <https://github.com/rahulk29/sram22_sky130_macros>`__ 
@@ -67,6 +68,10 @@ Note that we create a new conda environment for each tool because some of them h
 
 .. code-block:: shell
 
+    # channel settings so openroad/klayout install properly
+    conda config --set channel_priority true
+    conda config --add channels defaults
+
     # download all files for Sky130A PDK
     conda create -c litex-hub --prefix ~/.conda-sky130 open_pdks.sky130a=1.0.399_0_g63dbde9
     # clone the SRAM22 Sky130 SRAM macros
@@ -78,6 +83,10 @@ Note that we create a new conda environment for each tool because some of them h
     conda create -c litex-hub --prefix ~/.conda-klayout klayout=0.28.5_98_g87e2def28
     conda create -c litex-hub --prefix ~/.conda-signoff magic=8.3.376_0_g5e5879c netgen=1.5.250_0_g178b172
 
+    # revert conda settings
+    conda config --set channel_priority strict
+    conda config --remove channels defaults
+
 Initial Setup
 -------------
 In the Chipyard root, ensure that you have the Chipyard conda environment activated. Then, run:
@@ -118,7 +127,7 @@ Add the following YAML keys to the top of this file to specify the location of t
 example-openroad.yml
 ^^^^^^^^^^^^^^^^^^^^
 This contains the Hammer configuration for the OpenROAD tool flow.
-It selects tools for synthesis (Yosys), place and route (OpenROAD), DRC (Magic), and LVS (NetGen).
+It selects tools for synthesis (Yosys), place and route (OpenROAD), DRC (KLayout or Magic), and LVS (NetGen).
 
 Add the following YAML keys to the top of this file to specify the locations of the tool binaries.
 Note that this is not required if the tools are already on your PATH.
@@ -129,7 +138,8 @@ Note that this is not required if the tools are already on your PATH.
     # tool binary paths
     synthesis.yosys.yosys_bin: ~/.conda-yosys/bin/yosys
     par.openroad.openroad_bin: ~/.conda-openroad/bin/openroad
-    par.openroad.klayout_bin: ~/.conda-klayout/bin/klayout
+    par.openroad.klayout_bin: ~/.conda-klayout/bin/klayout  # binary that OpenROAD calls for final GDS writeout
+    drc.klayout.klayout_bin: ~/.conda-klayout/bin/klayout   # binary that runs for DRC step
     drc.magic.magic_bin: ~/.conda-signoff/bin/magic
     lvs.netgen.netgen_bin: ~/.conda-signoff/bin/netgen
 
@@ -237,10 +247,14 @@ DRC & LVS
 
 As a note, this tutorial has been run extensively through commercial signoff tools,
 thus the open-source signoff flow is not stable or guaranteed to produce useful results.
-We welcome any contributions to improving both our `Magic tool plugin <https://github.com/ucb-bar/hammer/blob/master/hammer/drc/magic>`__
+We welcome any contributions to improving our  `KLayout tool plugin <https://github.com/ucb-bar/hammer/blob/master/hammer/drc/klayout>`__,
+`Magic tool plugin <https://github.com/ucb-bar/hammer/blob/master/hammer/drc/magic>`__,
 and `Netgen tool plugin <https://github.com/ucb-bar/hammer/blob/master/hammer/lvs/netgen>`__.
 
-To run DRC & LVS in Magic & Netgen, respectively:
+We recommend KLayout for DRC to produce readable results, but Magic may be selected in ``example-openroad.yml``
+by uncommenting the line ``vlsi.core.drc_tool: "hammer.drc.magic"``.
+
+To run DRC & LVS and view the results:
 
 .. code-block:: shell
 
@@ -259,7 +273,13 @@ Note that in ``sky130-openroad.yml`` we have set the following YAML keys:
 These keys cause the Hammer plugin to only generate all necessary scripts, without executing them with the respective tool.
 This is because Magic and Netgen, as of the writing of this tutorial, do not have a database format that may be loaded interactively,
 so to view the DRC/LVS results for debugging you must launch the tool interactively, then run DRC/LVS checks,
-which is done by the ``generated-scripts/view_[drc|lvs]`` scripts.
+which is done by the ``generated-scripts/view_[drc|lvs]`` scripts. This is not the case for KLayout, which does have a loadable database format.
+
+Below is the window you should see when loading the KLayout DRC results interactively. Note that most of these DRC errors are 
+from special rules relating to Sky130 SRAMs, which have been verified separately. In the future the KLayout tool plugin should blackbox these
+SRAM macros by default, but this feature does not exist yet.
+
+.. image:: ../_static/images/vlsi-openroad-klayout-drc.png
 
 
 VLSI Flow Control

vlsi/example-openroad.yml

@@ -1,10 +1,11 @@
 # Tool options. Replace with your tool plugin of choice.
 vlsi.core.build_system: make
-# Yosys
+# Synthesis: Yosys
 vlsi.core.synthesis_tool: "hammer.synthesis.yosys"
-# OpenROAD
+# Place-and-Route: OpenROAD
 vlsi.core.par_tool: "hammer.par.openroad"
-# Magic
-vlsi.core.drc_tool: "hammer.drc.magic"
-# Netgen
+# DRC: KLayout or Magic (comment other one out)
+vlsi.core.drc_tool: "hammer.drc.klayout"
+# vlsi.core.drc_tool: "hammer.drc.magic"
+# LVS: Netgen
 vlsi.core.lvs_tool: "hammer.lvs.netgen"