Updated documentation

src/lay/lay/doc/about/drc_ref_drc.xml

@@ -887,10 +887,12 @@ The plain function is equivalent to "primary.sized".
 <keyword name="smoothed"/>
 <p>Usage:</p>
 <ul>
-<li><tt>expression.smoothed(d)</tt></li>
+<li><tt>expression.smoothed(d [, keep_hv ])</tt></li>
 </ul>
 <p>
-This operation acts on polygons and applies polygon smoothing with the tolerance d. See <a href="/about/drc_ref_layer.xml#smoothed">Layer#smoothed</a> for more details.
+This operation acts on polygons and applies polygon smoothing with the tolerance d. 'keep_hv' indicates
+whether horizontal and vertical edges are maintained. Default is 'no' which means such edges may be distorted.
+See <a href="/about/drc_ref_layer.xml#smoothed">Layer#smoothed</a> for more details.
 </p><p>
 The "smoothed" method is available as a plain function or as a method on <a href="/about/drc_ref_drc.xml">DRC</a> expressions.
 The plain function is equivalent to "primary.smoothed".

src/lay/lay/doc/about/drc_ref_global.xml

@@ -312,6 +312,17 @@ l1 = input(1, 0)
 <p>
 See <a href="/about/drc_ref_netter.xml#connect">Netter#connect</a> for a description of that function.
 </p>
+<a name="connect_explicit"/><h2>"connect_explicit" - Specifies explicit net connections</h2>
+<keyword name="connect_explicit"/>
+<p>Usage:</p>
+<ul>
+<li><tt>connect_explicit(net_names)</tt></li>
+<li><tt>connect_explicit(cell_pattern, net_names)</tt></li>
+</ul>
+<p>
+See <a href="/about/drc_ref_netter.xml#connect_explicit">Netter#connect_explicit</a> for a description of that function.
+Net names is an array (use square brackets to list the net names).
+</p>
 <a name="connect_global"/><h2>"connect_global" - Specifies a connection to a global net</h2>
 <keyword name="connect_global"/>
 <p>Usage:</p>

src/lay/lay/doc/about/drc_ref_netter.xml

@@ -219,6 +219,50 @@ joins.
 Connections are accumulated. The connections defined so far
 can be cleared with <a href="#clear_connections">clear_connections</a>.
 </p>
+<a name="connect_explicit"/><h2>"connect_explicit" - Specifies a list of net names for nets to connect explicitly</h2>
+<keyword name="connect_explicit"/>
+<p>Usage:</p>
+<ul>
+<li><tt>connect_explicit(net_names)</tt></li>
+<li><tt>connect_explicit(cell_pattern, net_names)</tt></li>
+</ul>
+<p>
+Use this method to explicitly connect nets even if there is no physical connection.
+As this breaks with the concept of physical verification, this feature should be used 
+with care. 
+</p><p>
+The first version of this function will connect all nets listed in the "net_names" array 
+in the top level cell. The second version takes a cell name pattern and connects all nets listed
+in "net_names" for cells matching this pattern.
+</p><p>
+A use case for this method is the following: consider a set of standard cells. These do not have a bulk
+or n-well pin in the schematics. They also do not have build in tie-down diodes for the 
+substrate connections. In this case there is a build-in discrepancy between the 
+schematics and the layout: bulk and VSS are separate nets within the layout, but the 
+schematic does not list them as separate. The solution is to make an explicit connection
+between VDD and n-well and VSS and bulk, provided VDD and VSS are properly labelled as "VDD" and "VSS"
+and n-well and bulk are accessible as named nets (for bulk you can use "connect_global").
+</p><p>
+The following code will establish an explicit connection for all cells called "INV.." between 
+BULK and VSS nets:
+</p><p>
+<pre>
+connect_global(bulk, "BULK")
+...
+connect_explicit("INV*", [ "BULK", "VSS" ])
+</pre>
+</p><p>
+Explicit connections also imply implicit connections between different parts of 
+one of the nets. In the example before, "VSS" pieces without a physical connection
+will also be connected.
+</p><p>
+When you use explicit connections you should make sure by other ways that the connection
+is made physically. For example, for the bulk/n-well pin example above, by enforcing at least one
+tie-down diode per n-well island and in the substrate by means of a DRC rule.
+</p><p>
+The explicit connections are applied on the next net extraction and cleared
+on "clear_connections".
+</p>
 <a name="connect_global"/><h2>"connect_global" - Connects a layer with a global net</h2>
 <keyword name="connect_global"/>
 <p>Usage:</p>

src/lay/lay/doc/about/lvs_ref_netter.xml

@@ -114,13 +114,15 @@ netter.equivalent_pins("NAND2", 0, 1)
 </pre>
 </p><p>
 The circuit argument is either a circuit name (a string) or a Circuit object
-from the schematic netlist.
+from the schematic netlist. 
+</p><p>
+Names are case sensitive for layout-derived netlists and case-insensitive for SPICE schematic netlists.
 </p><p>
 The pin arguments are zero-based pin numbers, where 0 is the first number, 1 the second etc.
-If the netlist provides named pins, names can be used instead of numbers.
+If the netlist provides named pins, names can be used instead of numbers. Again, use upper
+case pin names for SPICE netlists.
 </p><p>
-Before this method can be used, a schematic netlist needs to be loaded with
-<a href="#schematic">schematic</a>.
+Use this method andwhere in the script before the <a href="#compare">compare</a> call.
 </p>
 <a name="join_symmetric_nets"/><h2>"join_symmetric_nets" - Joins symmetric nets of selected circuits on the extracted netlist</h2>
 <keyword name="join_symmetric_nets"/>
@@ -174,6 +176,12 @@ with inherent ambiguity such as decoders, the complexity
 can be increased at the expense of potentially larger runtimes.
 The runtime penality is roughly proportional to the branch
 complexity.
+</p><p>
+By default, the branch complexity is unlimited, but it may
+be reduced in order to limit the compare runtimes at the cost
+of a less elaborate compare attempt. The preferred solution 
+however is to use labels for net name hints which also reduces
+the depth.
 </p>
 <a name="max_depth"/><h2>"max_depth" - Configures the maximum search depth for net match deduction</h2>
 <keyword name="max_depth"/>
@@ -191,6 +199,12 @@ the next net. With higher values for the depth, the algorithm
 pursues this "deduction path" in greater depth while with 
 smaller values, the algorithm prefers picking nets in a random fashion
 as the seeds for this deduction path. The default value is 8. 
+</p><p>
+By default, the depth is unlimited, but it may
+be reduced in order to limit the compare runtimes at the cost
+of a less elaborate compare attempt. The preferred solution 
+however is to use labels for net name hints which also reduces
+the branch complexity.
 </p>
 <a name="max_res"/><h2>"max_res" - Ignores resistors with a resistance above a certain value</h2>
 <keyword name="max_res"/>
@@ -223,11 +237,13 @@ This method will force an equivalence between the two circuits.
 By default, circuits are identified by name. If names are different, this
 method allows establishing an explicit correspondence.
 </p><p>
+circuit_a is for the layout netlist, circuit_b for the schematic netlist.
+Names are case sensitive for layout-derived netlists and case-insensitive for SPICE schematic netlists.
+</p><p>
 One of the circuits may be nil. In this case, the corresponding
 other circuit is mapped to "nothing", i.e. ignored.
 </p><p>
-Before this method can be used, a schematic netlist needs to be loaded with
-<a href="#schematic">schematic</a>.
+Use this method andwhere in the script before the <a href="#compare">compare</a> call.
 </p>
 <a name="same_device_classes"/><h2>"same_device_classes" - Establishes an equivalence between the device classes</h2>
 <keyword name="same_device_classes"/>
@@ -244,6 +260,9 @@ method allows establishing an explicit correspondence.
 Before this method can be used, a schematic netlist needs to be loaded with
 <a href="#schematic">schematic</a>.
 </p><p>
+class_a is for the layout netlist, class_b for the schematic netlist.
+Names are case sensitive for layout-derived netlists and case-insensitive for SPICE schematic netlists.
+</p><p>
 One of the device classes may be "nil". In this case, the corresponding
 other device class is mapped to "nothing", i.e. ignored.
 </p><p>
@@ -260,7 +279,11 @@ schematic side.
 </p><p>
 Once a device class is mentioned with "same_device_classes", matching by
 name is disabled for this class. So after using 'same_device_classes("A", "B")'
-"A" is no longer equivalent to "A" on the other side.
+"A" is no longer equivalent to "A" on the other side. If you want "A" to 
+stay equivalent to "A" too, you need to use 'same_device_classes("A", "A")' 
+in addition.
+</p><p>
+Use this method andwhere in the script before the <a href="#compare">compare</a> call.
 </p>
 <a name="same_nets"/><h2>"same_nets" - Establishes an equivalence between the nets</h2>
 <keyword name="same_nets"/>
@@ -281,8 +304,10 @@ After using this function, the compare algorithm will consider these nets equiva
 Use this method to provide hints for the comparer in cases which are difficult to
 resolve otherwise.
 </p><p>
-Before this method can be used, a schematic netlist needs to be loaded with
-<a href="#schematic">schematic</a>.
+circuit_a and net_a are for the layout netlist, circuit_b and net_b for the schematic netlist.
+Names are case sensitive for layout-derived netlists and case-insensitive for SPICE schematic netlists.
+</p><p>
+Use this method andwhere in the script before the <a href="#compare">compare</a> call.
 </p>
 <a name="schematic"/><h2>"schematic" - Gets, sets or reads the reference netlist</h2>
 <keyword name="schematic"/>

src/lay/lay/doc/manual/lvs_connect.xml

@@ -183,4 +183,76 @@ connect(metal2, metal2_labels)</pre>
   statements.
   </p>
 
+  <h2>Explicit connections</h2>
+
+  <p>
+  Explicit connections can be useful to enforce a connection in the layout 
+  which is made in the schematic, but not physically on the level of the cell.
+  For example consider the following layout for an inverter:
+  </p>
+
+  <p>
+  <img src="/manual/inv.png"/>
+  </p>
+
+  <p>
+  In the layout there are no tie-down diodes, hence there is no physical 
+  connection to the n-well region and no physical connection to the bulk
+  substrate. This saves space, but these diodes need to be added by other 
+  ways.
+  Usually this is done when the standard cells are combined into 
+  macros. Filler cells will be added which include these substrate and
+  well contacts.
+  </p>
+
+  <p>
+  On the inverter level however, there is no such connection. Therefore
+  the inverter has separate bulk and n-well pins. The schematic sometimes
+  is a simplified version which does not offer these pins. Hence there is
+  an intrinsic mismatch between layout and schematic.
+  </p>
+
+  <p>
+  <img src="/manual/inv_explicit.png"/>
+  </p>
+
+  <p>
+  To align layout and schematics, bulk and VSS pins can be connected
+  explicitly. Same for n-well and VDD.
+  There is a certain risk to forget making these connections later. 
+  But this risk can be mitigated by implementing DRC rules which
+  demand at least one tie-down diode for each isolated n-well island
+  or the bulk.
+  </p>
+
+  <p>
+  To establish an explicit connection, make sure that n-well and 
+  bulk have proper names. For the n-well this can be done by creating
+  labels on the n-well islands giving them a proper name - e.g. "NWELL".
+  The bulk isn't a real layout layer with polygons on it. Using "connect_global"
+  will both connect everthing on this layer and give it a name.
+  </p>
+
+  <p>
+  The following code will connect the bulk net with "VSS" inside the cell "INV":
+  </p>
+
+  <pre>connect_global(bulk, "BULK")
+...
+connect_explicit("INV", [ "BULK", "VSS" ])
+</pre>
+
+  <p>
+  The cell name can be a pattern. For example "INV*" will apply this rule on all 
+  cells starting with "INV".
+  The cell is not mandatory: if it is omitted, the rule is applied to top level only
+  to avoid introducing rules in subcells where they would mask layout errors.
+  </p>
+
+  <p>
+  An explicit connection will also imply implicit connections on the nets 
+  listed in the net names. So in the example above, different pieces of "VSS"
+  are connected even if they are not physically connected.
+  </p>
+
 </doc>

src/lay/lay/layHelpResources.qrc

@@ -92,6 +92,7 @@
         <file alias="lvs_symm_nodes.png">doc/manual/lvs_symm_nodes.png</file>
         <file alias="lvs_connect.xml">doc/manual/lvs_connect.xml</file>
         <file alias="inv.png">doc/manual/inv.png</file>
+        <file alias="inv_explicit.png">doc/manual/inv_explicit.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>
         <file alias="inv_with_diodes.png">doc/manual/inv_with_diodes.png</file>