Flow and step for opening designs in Magic (#463)

## Steps * New step, `Magic.OpenGUI`, which opens either DEF files or GDS files in magic * `Magic.*` * Fixed `magicrc` being `abspath`'d before command invocation (breaks reproducibles) * `_MAGIC_SCRIPT` is now set in `prepare_env` instead of `run_subprocess` (so it can be intercepted for reproducibles) * `KLayout.OpenGUI` * Renamed `KLAYOUT_PRIORITIZE_GDS` to `KLAYOUT_GUI_USE_GDS` to be consistent with the Magic steps ## Flows * New mono-step flow, `OpenInMagic`, which runs `Magic.OpenGUI` ## Tool Updates * OpenLane 2 now uses `nix-eda` for some of its derivations * Magic now uses tk with X11 on macOS, to prevent crashes when attempting to use the GUI * Updated Magic to `8.3.483`/`291ba96` ## Misc Bugfixes/Enhancements * `openlane.steps.Step.create_reproducible` * `PDK_ROOT` now included if the PDK is included but not flattened so Magic steps can work * `openlane.steps.TclStep` * **Internal**: Internal environment variables prefixed with `_` are no longer rerouted to `_env.tcl`, instead being passed raw (to help with creating reproducibles)
efabless · May 27, 2024 · 93e973f · 93e973f
1 parent a41330c
commit 93e973f
Show file tree

Hide file tree

Showing 32 changed files with 416 additions and 1,875 deletions.
diff --git a/default.nix b/default.nix
@@ -117,7 +117,7 @@ buildPythonPackage rec {
       libparse
       psutil
       klayout-pymod
-      
+
       # Ruby
       ruby
     ]

diff --git a/docs/source/usage/lvs/index.md b/docs/source/usage/lvs/index.md
@@ -0,0 +1,62 @@
+# Resolving LVS Mismatches in OpenLane
+
+This guide aims to document a number of common {term}`LVS` mismatches, their
+possible causes, and how to resolve them.
+
+This is a living document. We'll add more sections as we encounter more LVS
+
+## About LVS Mismatches
+
+LVS mismatches (alternately referred to simply as LVS errors) constitute a
+situation where the physical **layout** of the chip does not match the declared
+**schematic** thereof. Here is a non-exhaustive list of some common issues that
+are captured by LVS:
+
+1. An open circuit exists in the layout where it should be connected in the
+   schematic, i.e., a connection was not properly made.
+1. A bridge exists between two wires in the layout that are not connected in
+   the schematic, creating a short-circuit.
+1. A component (standard cell or macro) declared in the schematic is missing
+   or different in the layout.
+
+The first two are the most common class of LVS error. In OpenLane, the affected
+nets are more often than not power nets.
+
+These mismatches can occur either by user misconfiguration 
+
+## Identifying LVS mismatches
+
+When running the {flow}`Classic` flow, you may see this message at the end of
+the flow:
+
+```log
+ERROR   The following error was encountered while running the flow:
+        One or more deferred errors were encountered:
+        1 LVS errors found.
+```
+
+This indicates that both:
+* The {step}`Netgen.LVS` was run, comparing the final Verilog netlist with the
+  final {term}`SPICE` netlist, found one mismatch.
+* Another step, {step}`Checker.LVS`, reported it to the flow as an Error.
+
+We can find the specific LVS mismatches in the reports directory of
+{step}`Netgen.LVS`, which would be named something along the lines
+`runs/<run_tag>/<step number>-netgen-lvs/reports`. Inside, there is a report
+named `lvs.netgen.rpt`.
+
+You can find specific mismatches by searching `MISMATCH` in the report.
+
+## Pin postfixed with `_uqX`
+
+In some instance, the layout may contain a pin postfixed with `_uq` and then
+an integer.
+
+This typically indicates that there's a break in the net. During SPICE netlist
+extraction with Magic, Magic ensures every net has a unique name, meaning that
+if two nets exist with the same name (i.e. the same net has a break in it,)
+one will be renamed to `_uq`. This may be any number of things, including:
+
+
+
+
diff --git a/flake.lock b/flake.lock
diff --git a/flake.nix b/flake.nix
@@ -22,140 +22,116 @@
   };
 
   inputs = {
-    nixpkgs.url = github:nixos/nixpkgs/nixos-23.11;
+    nix-eda.url = github:efabless/nix-eda;
     libparse.url = github:efabless/libparse-python;
     ioplace-parser.url = github:efabless/ioplace_parser;
     volare.url = github:efabless/volare;
     flake-compat.url = "https://flakehub.com/f/edolstra/flake-compat/1.tar.gz";
   };
-  
-  inputs.libparse.inputs.nixpkgs.follows = "nixpkgs";
-  inputs.ioplace-parser.inputs.nixpkgs.follows = "nixpkgs";
-  inputs.volare.inputs.nixpkgs.follows = "nixpkgs";
+
+  inputs.libparse.inputs.nixpkgs.follows = "nix-eda/nixpkgs";
+  inputs.ioplace-parser.inputs.nixpkgs.follows = "nix-eda/nixpkgs";
+  inputs.volare.inputs.nixpkgs.follows = "nix-eda/nixpkgs";
 
   outputs = {
     self,
-    nixpkgs,
+    nix-eda,
     libparse,
     ioplace-parser,
     volare,
     ...
-  }: {
+  }: let
+    package-config = {
+      current = self;
+      withInputs = [nix-eda ioplace-parser libparse volare];
+      overlays = [(import ./nix/overlay.nix)];
+    };
+  in {
     # Helper functions
-    forAllSystems = function:
-      nixpkgs.lib.genAttrs [
-        "x86_64-linux"
-        "aarch64-linux"
-        "x86_64-darwin"
-        "aarch64-darwin"
-      ] (
-        system:
-          function (import nixpkgs {
-            inherit system;
-            overlays = [
-              (import ./nix/overlay.nix)
-            ];
-          })
-      );
-
     createOpenLaneShell = import ./nix/create-shell.nix;
-    createDockerImage = import ./nix/create-docker.nix;
 
     # Outputs
-    packages = self.forAllSystems (pkgs: let
-      callPackage = pkgs.lib.callPackageWith (pkgs // self.packages.${pkgs.system});
-      callPythonPackage = pkgs.lib.callPackageWith (pkgs // pkgs.python3.pkgs // ioplace-parser.packages."${pkgs.system}" // libparse.packages."${pkgs.system}" // volare.packages."${pkgs.system}" // self.packages.${pkgs.system});
-    in
-      rec {
-        colab-env = callPackage ./nix/colab-env.nix {};
-        netgen = callPackage ./nix/netgen.nix {};
-        magic = callPackage ./nix/magic.nix {};
-        klayout = callPackage ./nix/klayout.nix {};
-        klayout-pymod = callPackage ./nix/klayout-pymod.nix {};
-        opensta = callPackage ./nix/opensta.nix {};
-        openroad-abc = callPackage ./nix/openroad-abc.nix {};
-        openroad = callPythonPackage ./nix/openroad.nix {};
-        openlane = callPythonPackage ./default.nix {};
-        surelog = callPackage ./nix/surelog.nix {};
-        sphinx-tippy = callPythonPackage ./nix/sphinx-tippy.nix {};
-        sphinx-subfigure = callPythonPackage ./nix/sphinx-subfigure.nix {};
-        tclFull = callPackage ./nix/tclFull.nix {};
-        verilator = callPackage ./nix/verilator.nix {};
-        yosys-abc = callPackage ./nix/yosys-abc.nix {};
-        yosys = callPackage ./nix/yosys.nix {};
-        yosys-sby = callPackage ./nix/yosys-sby.nix {};
-        yosys-eqy = callPackage ./nix/yosys-eqy.nix {};
-        yosys-f4pga-sdc = callPackage ./nix/yosys-f4pga-sdc.nix {};
-        yosys-lighter = callPackage ./nix/yosys-lighter.nix {};
-        yosys-synlig-sv = callPackage ./nix/yosys-synlig-sv.nix {};
-        default = openlane;
-      }
-      // (pkgs.lib.optionalAttrs (pkgs.system == "x86_64-linux") {yosys-ghdl = callPackage ./nix/yosys-ghdl.nix {};})
-      // (pkgs.lib.optionalAttrs (pkgs.stdenv.isLinux) {openlane-docker = callPackage ./nix/docker.nix {};}));
+    packages = nix-eda.forAllSystems package-config (util:
+      with util;
+        rec {
+          # # Override Example
+          # magic = inputPkgs.magic.override {
+          #   rev = "291ba96285bcd7c2176f95229fc540bd88a25b88";
+          #   sha256 = "sha256-PE3mgjoe9kvEU/Ln++Dkpzag/7dAQBl7CBOxQJS/wk0=";
+          # };
+          colab-env = callPackage ./nix/colab-env.nix {};
+          opensta = callPackage ./nix/opensta.nix {};
+          openroad-abc = callPackage ./nix/openroad-abc.nix {};
+          openroad = callPythonPackage ./nix/openroad.nix {};
+          openlane = callPythonPackage ./default.nix {};
+          sphinx-tippy = callPythonPackage ./nix/sphinx-tippy.nix {};
+          sphinx-subfigure = callPythonPackage ./nix/sphinx-subfigure.nix {};
+          default = openlane;
+        }
+        // (pkgs.lib.optionalAttrs (pkgs.stdenv.isLinux) {openlane-docker = callPackage ./nix/docker.nix {createDockerImage = nix-eda.createDockerImage;};}));
 
-    devShells = self.forAllSystems (
-      pkgs: let
-        callPackage = pkgs.lib.callPackageWith (pkgs // self.packages.${pkgs.system});
-        callPythonPackage = pkgs.lib.callPackageWith (pkgs // pkgs.python3.pkgs // self.packages.${pkgs.system});
-      in rec {
-        default = callPackage (self.createOpenLaneShell {
-        }) {};
-        notebook = callPackage (self.createOpenLaneShell {
-          extra-packages = with pkgs; [
-            jupyter
-          ];
-        }) {};
-        dev = callPackage (self.createOpenLaneShell {
-          extra-packages = with pkgs; [
-            jdupes
-            alejandra
-            nbqa
-          ];
-          extra-python-packages = with pkgs.python3.pkgs; [
-            pyfakefs
-            pytest
-            pytest-xdist
-            pytest-cov
-            pillow
-            mdformat
-            black
-            flake8
-            mypy
-            types-deprecated
-            types-pyyaml
-            types-psutil
-            lxml-stubs
-          ];
-        }) {};
-        docs = callPackage (self.createOpenLaneShell {
-          extra-packages = with pkgs; [
-            jdupes
-            alejandra
-            imagemagick
-            nodejs.pkgs.nodemon
-          ];
-          extra-python-packages = with pkgs.python3.pkgs; [
-            pyfakefs
-            pytest
-            pytest-xdist
-            pillow
-            mdformat
-            furo
-            docutils
-            sphinx
-            sphinx-autobuild
-            sphinx-autodoc-typehints
-            sphinx-design
-            myst-parser
-            docstring-parser
-            sphinx-copybutton
-            self.packages.${pkgs.system}.sphinx-tippy
-            sphinxcontrib-spelling
-            sphinxcontrib-bibtex
-            self.packages.${pkgs.system}.sphinx-subfigure
-          ];
-        }) {};
-      }
+    devShells = nix-eda.forAllSystems package-config (
+      util:
+        with util; rec {
+          default =
+            callPackage (self.createOpenLaneShell {
+              }) {};
+          notebook = callPackage (self.createOpenLaneShell {
+            extra-packages = with pkgs; [
+              jupyter
+            ];
+          }) {};
+          dev = callPackage (self.createOpenLaneShell {
+            extra-packages = with pkgs; [
+              jdupes
+              alejandra
+              nbqa
+            ];
+            extra-python-packages = with pkgs.python3.pkgs; [
+              pyfakefs
+              pytest
+              pytest-xdist
+              pytest-cov
+              pillow
+              mdformat
+              black
+              flake8
+              mypy
+              types-deprecated
+              types-pyyaml
+              types-psutil
+              lxml-stubs
+            ];
+          }) {};
+          docs = callPackage (self.createOpenLaneShell {
+            extra-packages = with pkgs; [
+              jdupes
+              alejandra
+              imagemagick
+              nodejs.pkgs.nodemon
+            ];
+            extra-python-packages = with pkgs.python3.pkgs; [
+              pyfakefs
+              pytest
+              pytest-xdist
+              pillow
+              mdformat
+              furo
+              docutils
+              sphinx
+              sphinx-autobuild
+              sphinx-autodoc-typehints
+              sphinx-design
+              myst-parser
+              docstring-parser
+              sphinx-copybutton
+              self.packages.${pkgs.system}.sphinx-tippy
+              sphinxcontrib-spelling
+              sphinxcontrib-bibtex
+              self.packages.${pkgs.system}.sphinx-subfigure
+            ];
+          }) {};
+        }
     );
   };
 }