Added doc, added a warning about no pins found at top level.

src/db/db/dbLayoutVsSchematic.cc

@@ -100,6 +100,7 @@ LayoutVsSchematic::flag_missing_ports (const db::Circuit *circuit)
   }
 
   bool error = false;
+  bool any = false;
 
   for (auto n = pcd->nets.begin (); n != pcd->nets.end (); ++n) {
 
@@ -108,11 +109,12 @@ LayoutVsSchematic::flag_missing_ports (const db::Circuit *circuit)
 
     if (schem && layout && schem->begin_pins () != schem->end_pins ()) {
 
+      any = true;
+
       if (db::name_compare (layout, schem) != 0) {
 
         std::string msg = tl::sprintf (tl::to_string (tr ("Port mismatch '%s' vs. '%s'")), layout->expanded_name (), schem->expanded_name ());
         db::LogEntryData entry (db::Error, msg);
-
         pcd->log_entries.push_back (entry);
 
         error = true;
@@ -122,6 +124,14 @@ LayoutVsSchematic::flag_missing_ports (const db::Circuit *circuit)
 
   }
 
+  if (! any) {
+
+    std::string msg = tl::to_string (tr ("No pins found in circuit during 'flag_missing_ports'"));
+    db::LogEntryData entry (db::Warning, msg);
+    pcd->log_entries.push_back (entry);
+
+  }
+
   return !error;
 }
 

src/doc/doc/about/lvs_ref_global.xml

@@ -82,6 +82,15 @@ See <a href="/about/lvs_ref_netter.xml#enable_parameter">Netter#enable_parameter
 <p>
 See <a href="/about/lvs_ref_netter.xml#equivalent_pins">Netter#equivalent_pins</a> for a description of that function.
 </p>
+<a name="flag_missing_ports"/><h2>"flag_missing_ports" - Checks if all top level ports are properly labelled</h2>
+<keyword name="flag_missing_ports"/>
+<p>Usage:</p>
+<ul>
+<li><tt>flag_missing_ports</tt></li>
+</ul>
+<p>
+See <a href="/about/lvs_ref_netter.xml#flag_missing_ports">Netter#flag_missing_ports</a> for a description of that function.
+</p>
 <a name="ignore_parameter"/><h2>"ignore_parameter" - Specifies whether to ignore a parameter from a given device class for the compare</h2>
 <keyword name="ignore_parameter"/>
 <p>Usage:</p>

src/doc/doc/about/lvs_ref_netter.xml

@@ -186,6 +186,27 @@ case pin names for SPICE netlists.
 </p><p>
 Use this method andwhere in the script before the <a href="#compare">compare</a> call.
 </p>
+<a name="flag_missing_ports"/><h2>"flag_missing_ports" - Flags inconsistently labelled or missing ports in the current top circuit</h2>
+<keyword name="flag_missing_ports"/>
+<p>Usage:</p>
+<ul>
+<li><tt>flag_missing_ports</tt></li>
+</ul>
+<p>
+This method must be called after "compare" was executed successfully and will 
+report errors if pins in the current top circuit's schematic are not labelled 
+correspondingly in the layout. This prevents swapping of port labels or 
+pads.
+</p><p>
+<pre>
+success = compare
+success &amp;&amp; flag_missing_ports
+</pre>
+</p><p>
+Note that in order to use this method, the top circuit from the schematic netlist
+needs to have pins. This may not be always the case - for example, if the top 
+level circuit is not a subcircuit in a Spice netlist.
+</p>
 <a name="ignore_parameter"/><h2>"ignore_parameter" - Skip a specific parameter for a given device class name during device compare</h2>
 <keyword name="ignore_parameter"/>
 <p>Usage:</p>

src/doc/doc/manual/lvs_compare.xml

@@ -296,6 +296,69 @@ tolerance("NMOS", "L", :absolute => 0.05, :relative => 0.01)</pre>
 
   <pre>min_caps(1e-16)</pre>
 
+  <h2>Checking pin labels</h2>
+
+  <p>
+  LVS is basically name-agnostic, so except for resolving ambiguities, net names are
+  not considered. Topology matching has priority - if nets are not labelled
+  properly, LVS by default does not care.
+  </p>
+
+  <p>
+  This may have adverse effects in the case of outbound connections - for example
+  pads. It's a fatal error to connect the chip pads incorrectly. To mitigate this
+  issue, the "flag_missing_ports" function is provided.
+  </p>
+
+  <p>
+  You need to call this function after the compare step, i.e.
+  </p>
+
+  <pre>compare
+flag_missing_ports</pre>
+
+  <p>
+  Or, if you want to quench pseudo errors, only in case of successful compare:
+  </p>
+
+  <pre>success = compare
+success &amp;&amp; flag_missing_ports</pre>
+
+  <p>
+  This function takes the schematic top circuit and investigates all
+  nets that are connected to a pin. It will check the name (label) of the 
+  corresponding layout net and if names do not match, an error is written 
+  into the log section of the LVS report.
+  </p>
+
+  <p>
+  When you use this feature while working yourself bottom-up in the design,
+  it will make sure that all pins are properly labelled. If you use pins
+  in the top level circuit to describe the chip pads, this feature will make
+  sure that the correct nets are connected to the pads with the corresponding labels
+  on them.
+  </p>
+
+  <p>
+  Note that it is possible to have SPICE netlists which do not have pins 
+  at the top level circuit - e.g. if the top level circuit is not a SUBCKT.
+  In that case, the function will not report errors as there are not pin-carrying
+  nets. Only a warning is issues saying that no top level pins have been found.
+  </p>
+
+  <p>
+  You can use
+  </p>
+
+  <pre>schematic.make_top_level_pins</pre>
+
+  <p>
+  to create pins if none are provided. However, this method will turn every net into a pin
+  and force you to label every net in the top circuit then.
+  Hence, it is better to provide pins inside the schematic netlist.
+  Also note, that "make_top_level_pins" is implicitly included in "schematic.simplify".
+  </p>
+
   <h2>Compare and netlist hierarchy</h2>
 
   <p>