From 153bfa9c52002e66e039fbbe5e479ef66f6bcdf8 Mon Sep 17 00:00:00 2001
From: Matthias Koefferlein <matthias@koefferlein.de>
Date: Thu, 4 Jul 2019 23:56:04 +0200
Subject: [PATCH] Updated doc.

---
 src/lay/lay/doc/manual/lvs.xml                |   2 +-
 src/lay/lay/doc/manual/lvs_compare.xml        |   6 +-
 src/lay/lay/doc/manual/lvs_connect.xml        | 119 ++++++++++++++++++
 .../lay/doc/manual/lvs_device_extractors.xml  |   4 +-
 src/lay/lay/doc/manual/lvs_overview.xml       |   8 ++
 src/lay/lay/doc/manual/lvs_tweaks.xml         |   6 +-
 src/lay/lay/layHelpResources.qrc              |   2 +
 7 files changed, 136 insertions(+), 11 deletions(-)

diff --git a/src/lay/lay/doc/manual/lvs.xml b/src/lay/lay/doc/manual/lvs.xml
index e39fb29d2..b0e658e33 100644
--- a/src/lay/lay/doc/manual/lvs.xml
+++ b/src/lay/lay/doc/manual/lvs.xml
@@ -17,10 +17,10 @@
     <topic href="/manual/lvs_device_classes.xml"/>
     <topic href="/manual/lvs_device_extractors.xml"/>
     <topic href="/manual/lvs_io.xml"/>
+    <topic href="/manual/lvs_connect.xml"/>
 
     <!--
     <topic href="/manual/lvs_hierarchy.xml"/>
-    <topic href="/manual/lvs_connect.xml"/>
     <topic href="/manual/lvs_reference.xml"/>
     <topic href="/manual/lvs_compare.xml"/>
     <topic href="/manual/lvs_tweaks.xml"/>
diff --git a/src/lay/lay/doc/manual/lvs_compare.xml b/src/lay/lay/doc/manual/lvs_compare.xml
index b23365003..96151e5f5 100644
--- a/src/lay/lay/doc/manual/lvs_compare.xml
+++ b/src/lay/lay/doc/manual/lvs_compare.xml
@@ -3,15 +3,13 @@
 
 <doc>
 
-  <title>LVS Device Classes</title>
+  <title>LVS Connectivity</title>
   <keyword name="LVS"/>
-  <keyword name="LVS Device Classes"/>
+  <keyword name="LVS Connectivity"/>
 
   <h2-index/>
 
   <p>
-  LVS (and also DRC as far as netlist extraction is concerned) provides 
-
   </p>
 
 </doc>
diff --git a/src/lay/lay/doc/manual/lvs_connect.xml b/src/lay/lay/doc/manual/lvs_connect.xml
index 96151e5f5..d05b817d7 100644
--- a/src/lay/lay/doc/manual/lvs_connect.xml
+++ b/src/lay/lay/doc/manual/lvs_connect.xml
@@ -9,7 +9,126 @@
 
   <h2-index/>
 
+  <h2>Intra- and inter-layer connections</h2>
+
   <p>
+  The connectivity setup of a LVS script determines how the connections are made.
+  Connections are usually made through conductive materials such as Aluminium or Copper.
+  The polygons representing such a material form a connection. Connections can be 
+  made across multiple polygons - touching polygons form connected islands of 
+  conductive material. This "intra-layer" connectivity is implicit: in LVS scripts
+  connections are always made between polygons on the same layer.
+  </p>
+
+  <p>
+  Connections often cross layers. A via for example is a hole in the insulator
+  sheet which connects two metal layers. This connection is modelled using
+  a "connect" statement (see <a href="/about/drc_ref_global.xml#connect">connect</a>):
+  </p>
+
+  <pre>connect(layer1, layer2)</pre>
+
+  <p>
+  A connect statement will specify an electrical connection when the polygons from layer1
+  and layer2 overlap. layer1 and layer2 are original or derived layers. "connect" statements
+  should appear in the script before the netlist is required - i.e. before "compare" 
+  or any other netlist-related statement inside the LVS script. The order of the connect
+  statements is not relevant. Neigther is the order of the arguments in "connect": 
+  connections are always bidirectional.
+  </p>
+
+  <p>
+  This is an example for a vertical cross section through a 
+  simple 3-metal layer stack with the corresponding "connect" statements:
+  </p>
+
+  <p>
+  <img src="/manual/metal_connections.png"/>
+  </p>
+
+  <p>
+  Labels can be included in the connectivity too. Typically labels are placed on
+  metal layers. If the labels are drawn on the same layer than the metal shapes
+  they are automatically included when using "input" to read the layer. If only
+  labels shall be read from a layer, use "labels" (see <a href="/about/drc_ref_global.xml#labels">labels</a>).
+  </p>
+
+  <p>
+  To attach labels to metal layers, simply connect the label and metal layers:
+  </p>
+
+  <pre>metal1_labels = labels(10, 0)
+metal1        = input(11, 0)
+via1          = input(12, 0)
+metal2_labels = labels(13, 0)
+metal2        = input(14, 0)
+
+connect(metal1, metal1_labels)
+connect(metal1, via1)
+connect(via1, metal2)
+connect(metal2, metal2_labels)</pre>
+
+  <p>
+  If labels are connected to metal layers, their text strings will be used to assign 
+  net names to the resulting nets. Ideally, one net is labelled with a single text 
+  or with texts with the same text string. In this case, the net name will 
+  be non-ambiguous. If multiple labels with different strings are present on a net, 
+  the net name will be made from a combination of these names.
+  </p>
+
+  <h2>Global connections</h2>
+
+  <p>
+  KLayout supports implicit connections made across all polygons on 
+  a layer, regardless whether they connect or not. A typical case for
+  such a connection is the substrate (aka "bulk"). This connection
+  represents the (lightly conductive) substrate material. There is no
+  polygon representing the wafer. Instead, a layer is defined which 
+  makes a global connection with "connect_global" (see <a href="/about/drc_ref_global.xml#connect_global">connect_global</a>):
+  </p>
+
+  <pre>connect_global(bulk, "VSS")</pre>
+
+  <p>
+  The arguments to "connect_global" is the globally connected layer and the 
+  name of the global net to create. The function will make all shapes on "bulk"
+  being connected to a single net "VSS". Every circuit will at least have 
+  the "VSS" net. In addition, each circuit will be 
+  given a pin called "VSS" which propagates this net to parent circuits.
+  </p>
+
+  <h2>Implicit connections</h2>
+
+  <p>
+  Implicit connections can be useful to supply preliminary connections
+  which are supposed to be created higher up in the hierarchy:
+  Imagine a circuit which a big power net for example. When the layout
+  is made, the power net may not be completely connected yet because the 
+  plan is to connect all parts of this power net later when the
+  cell is integrated. In this situation, the 
+  subcircuit cell itself won't be LVS clean because the power net is a single
+  net schematic-wise, but exist as multiple nets layout-wise. This prevents
+  bottom-up verification - a very useful technique to achieve LVS clean 
+  layouts.
+  </p>
+
+  <p>
+  To allow verification of such a cell, "implicit connections" can be
+  made by giving the net parts the same name through labels and assume
+  these parts are connected: 
+  for example to specify implicit connections between all parts of a "VDD" net,
+  place a label "VDD" on each part and include the following statement
+  in the script:
+  </p>
+
+  <pre>connect_implicit("VDD")</pre>
+
+  <p>
+  "connect_implicit" (see <a href="/about/drc_ref_global.xml#connect_implicit">connect_implicit</a>)
+  can be present multiple times to make many of such connections.
+  Implicit connections will only be made on the topmost circuit to prevent false verification results. 
+  Be careful not to use this option in a final verification of a full design as power net 
+  opens may pass unnoticed.
   </p>
 
 </doc>
diff --git a/src/lay/lay/doc/manual/lvs_device_extractors.xml b/src/lay/lay/doc/manual/lvs_device_extractors.xml
index afb0ad292..c3d07fd71 100644
--- a/src/lay/lay/doc/manual/lvs_device_extractors.xml
+++ b/src/lay/lay/doc/manual/lvs_device_extractors.xml
@@ -205,7 +205,7 @@ extract_devices(mos4(model_name), { "SD" => (active - poly) &amp; pplus, "G" =>
   </p>
 
   <p>
-  <img src="/manual/bjt_lateral.png"/> (lateral PNP transistor)
+  <img src="/manual/bjt_lateral.png"/> (lateral NPN transistor)
   </p>
 
   <p>
@@ -218,7 +218,7 @@ extract_devices(mos4(model_name), { "SD" => (active - poly) &amp; pplus, "G" =>
   </p>
 
   <p>
-  <img src="/manual/bjt_vertical.png"/> (vertical PNP transistor)
+  <img src="/manual/bjt_vertical.png"/> (vertical NPN transistor)
   </p>
 
   <p>
diff --git a/src/lay/lay/doc/manual/lvs_overview.xml b/src/lay/lay/doc/manual/lvs_overview.xml
index a4285c910..839f8a6d7 100644
--- a/src/lay/lay/doc/manual/lvs_overview.xml
+++ b/src/lay/lay/doc/manual/lvs_overview.xml
@@ -84,6 +84,14 @@
     As a positive side effect of hierarchical layout processing the runtimes for some boolean and 
     other operations is significantly reduced in most cases.
     </li>
+    <li><b>Hierarchically stable:</b> KLayout won't modify the layout's hierarchy nor 
+    will it introduce variants - at least for boolean and some other operations. 
+    This way, matching between layout and schematic hierarchy
+    is maintained even after hierarchical DRC operations.
+    Variants are introduced only for some anisotropic operations, the grid snap method
+    and some other features which require differentiation of cells in terms of location
+    and orientation.
+    </li>
     <li><b>Flexible engine:</b> The netlist formation engine is highly flexible with respect 
     to device recognition and connectivity extraction. First, almost all DRC features can 
     be used to derive intermediate layers for device formation and connectivity extraction.
diff --git a/src/lay/lay/doc/manual/lvs_tweaks.xml b/src/lay/lay/doc/manual/lvs_tweaks.xml
index b23365003..96151e5f5 100644
--- a/src/lay/lay/doc/manual/lvs_tweaks.xml
+++ b/src/lay/lay/doc/manual/lvs_tweaks.xml
@@ -3,15 +3,13 @@
 
 <doc>
 
-  <title>LVS Device Classes</title>
+  <title>LVS Connectivity</title>
   <keyword name="LVS"/>
-  <keyword name="LVS Device Classes"/>
+  <keyword name="LVS Connectivity"/>
 
   <h2-index/>
 
   <p>
-  LVS (and also DRC as far as netlist extraction is concerned) provides 
-
   </p>
 
 </doc>
diff --git a/src/lay/lay/layHelpResources.qrc b/src/lay/lay/layHelpResources.qrc
index 643c51236..0d977fed5 100644
--- a/src/lay/lay/layHelpResources.qrc
+++ b/src/lay/lay/layHelpResources.qrc
@@ -179,6 +179,7 @@
         <file alias="lvs_io.xml">doc/manual/lvs_io.xml</file>
         <file alias="lvs_compare.xml">doc/manual/lvs_compare.xml</file>
         <file alias="lvs_tweaks.xml">doc/manual/lvs_tweaks.xml</file>
+        <file alias="lvs_connect.xml">doc/manual/lvs_connect.xml</file>
         <file alias="inv.png">doc/manual/inv.png</file>
         <file alias="inv_no_transistors.png">doc/manual/inv_no_transistors.png</file>
         <file alias="inv_transistors.png">doc/manual/inv_transistors.png</file>
@@ -222,6 +223,7 @@
         <file alias="bjtlat_ex_tc.png">doc/manual/bjtlat_ex_tc.png</file>
         <file alias="bjtlat_ex_tb.png">doc/manual/bjtlat_ex_tb.png</file>
         <file alias="bjtlat_ex_ts.png">doc/manual/bjtlat_ex_ts.png</file>
+        <file alias="metal_connections.png">doc/manual/metal_connections.png</file>
         <file alias="edit_mode.xml">doc/manual/edit_mode.xml</file>
         <file alias="editor_advanced.xml">doc/manual/editor_advanced.xml</file>
         <file alias="editor_basics.xml">doc/manual/editor_basics.xml</file>