WIP: doc.

This commit is contained in:
Matthias Koefferlein 2019-06-30 23:36:51 +02:00
parent 2f66f3ee3b
commit 1e49338fe9
7 changed files with 503 additions and 1 deletions

View File

@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">
<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb -->
<!-- DO NOT EDIT! -->
<doc>
<title>LVS Reference</title>
<keyword name="LVS Reference"/>
<topics>
<topic href="/about/lvs_ref_netter.xml"/>
<topic href="/about/lvs_ref_global.xml"/>
</topics>
</doc>

View File

@ -0,0 +1,126 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">
<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb -->
<!-- DO NOT EDIT! -->
<doc>
<title>LVS Reference: Global Functions</title>
<keyword name="global"/>
<p>
Some functions are available on global level and can be used without any object.
Most of them are convenience functions that basically act on some default object
or provide function-like alternatives for the methods.
</p><p>
LVS is built upon DRC. So all functions available in DRC are also available
in LVS. In LVS, DRC functions are used to derive functional layers from original
layers or specification of the layout source.
</p><p>
For more details about the DRC functions see <a href="/about/drc_ref_global.xml">DRC::global</a>.
</p>
<h2-index/>
<h2>"compare" - Compares the extracted netlist vs. the schematic</h2>
<keyword name="compare"/>
<a name="compare"/><p>Usage:</p>
<ul>
<li><tt>compare</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml#compare">Netter#compare</a> for a description of that function.
</p>
<h2>"equivalent_pins" - Marks pins as equivalent</h2>
<keyword name="equivalent_pins"/>
<a name="equivalent_pins"/><p>Usage:</p>
<ul>
<li><tt>equivalent_pins(circuit, pins ...)</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml#equivalent_pins">Netter#equivalent_pins</a> for a description of that function.
</p>
<h2>"max_res" - Ignores resistors with a resistance above a certain value</h2>
<keyword name="max_res"/>
<a name="max_res"/><p>Usage:</p>
<ul>
<li><tt>max_res(threshold)</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml#max_res">Netter#max_res</a> for a description of that function.
</p>
<h2>"min_caps" - Ignores capacitors with a capacitance below a certain value</h2>
<keyword name="min_caps"/>
<a name="min_caps"/><p>Usage:</p>
<ul>
<li><tt>min_caps(threshold)</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml#min_caps">Netter#min_caps</a> for a description of that function.
</p>
<h2>"netter" - Creates a new netter object</h2>
<keyword name="netter"/>
<a name="netter"/><p>Usage:</p>
<ul>
<li><tt>netter</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml">Netter</a> for more details
</p>
<h2>"report_lvs" - Specifies an LVS report for output</h2>
<keyword name="report_lvs"/>
<a name="report_lvs"/><p>Usage:</p>
<ul>
<li><tt>report_lvs([ filename ])</tt></li>
</ul>
<p>
After the comparison step, the LVS database will be shown
in the netlist database browser in a cross-reference view.
If a filename is given, the LVS database is also written to
this file.
</p><p>
If this method is called together with report_netlist and two files each, two
files can be generated - one for the extracted netlist (L2N database) and one for the
LVS database. However, report_netlist will only write the extracted netlist
while report_lvs will write the LVS database which also includes the
extracted netlist.
</p><p>
report_lvs is only effective if a comparison step is included.
</p>
<h2>"same_circuits" - Establishes an equivalence between the circuits</h2>
<keyword name="same_circuits"/>
<a name="same_circuits"/><p>Usage:</p>
<ul>
<li><tt>same_circuits(circuit_a, circuit_b)</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml#same_circuits">Netter#same_circuits</a> for a description of that function.
</p>
<h2>"same_device_classes" - Establishes an equivalence between the device_classes</h2>
<keyword name="same_device_classes"/>
<a name="same_device_classes"/><p>Usage:</p>
<ul>
<li><tt>same_device_classes(class_a, class_b)</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml#same_device_classes">Netter#same_device_classes</a> for a description of that function.
</p>
<h2>"same_nets" - Establishes an equivalence between the nets</h2>
<keyword name="same_nets"/>
<a name="same_nets"/><p>Usage:</p>
<ul>
<li><tt>same_nets(circuit, net_a, net_b)</tt></li>
<li><tt>same_nets(circuit_a, net_a, circuit_b, net_b)</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml#same_nets">Netter#same_nets</a> for a description of that function.
</p>
<h2>"schematic" - Reads the reference netlist</h2>
<keyword name="schematic"/>
<a name="schematic"/><p>Usage:</p>
<ul>
<li><tt>schematic(filename)</tt></li>
<li><tt>schematic(filename, reader)</tt></li>
<li><tt>schematic(netlist)</tt></li>
</ul>
<p>
See <a href="/about/lvs_ref_netter.xml#schematic">Netter#schematic</a> for a description of that function.
</p>
</doc>

View File

@ -0,0 +1,172 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">
<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb -->
<!-- DO NOT EDIT! -->
<doc>
<title>LVS Reference: Netter object</title>
<keyword name="Netter"/>
<p>
The Netter object provides services related to network extraction
from a layout plus comparison against a reference netlist.
Similar to the DRC <a href="/about/drc_ref_netter.xml">DRC::Netter</a> (which lacks the compare ability), the
relevant method of this object are available as global functions too
where they act on a default incarnation. Usually it's not required
to instantiate a Netter object explicitly.
</p><p>
The LVS Netter object inherits all methods of the <a href="/about/drc_ref_netter.xml">DRC::Netter</a>.
</p><p>
An individual netter object can be created, if the netter results
need to be kept for multiple extractions. If you really need
a Netter object, use the global <a href="/about/lvs_ref_global.xml#netter">global#netter</a> function:
</p><p>
<pre>
# create a new Netter object:
nx = netter
# build connectivity
nx.connect(poly, contact)
...
# read the reference netlist
nx.schematic("reference.cir")
# configure the netlist compare
nx.same_circuits("A", "B")
...
# runs the compare
if ! nx.compare
puts("no equivalence!")
end
</pre>
</p>
<h2-index/>
<h2>"compare" - Compares the extracted netlist vs. the schematic</h2>
<keyword name="compare"/>
<a name="compare"/><p>Usage:</p>
<ul>
<li><tt>compare</tt></li>
</ul>
<p>
Before using this method, a schematic netlist has to be loaded with <a href="#schematic">schematic</a>.
The compare can be configured in more details using <a href="#same_nets">same_nets</a>, <a href="#same_circuits">same_circuits</a>,
<a href="#same_device_classes">same_device_classes</a> and <a href="#equivalent_pins">equivalent_pins</a>.
</p><p>
This method will return true, if the netlists are equivalent and false
otherwise.
</p>
<h2>"equivalent_pins" - Marks pins as equivalent</h2>
<keyword name="equivalent_pins"/>
<a name="equivalent_pins"/><p>Usage:</p>
<ul>
<li><tt>equivalent_pins(circuit, pins ...)</tt></li>
</ul>
<p>
This method will mark the given pins as equivalent. This gives the compare algorithm
more degrees of freedom when establishing net correspondence. Typically this method
is used to declare inputs from gates are equivalent where are are logically, but not
physically (e.g. in a CMOS NAND gate):
</p><p>
<pre>
netter.equivalent_pins("NAND2", "A", "B")
</pre>
</p><p>
Before this method can be used, a schematic netlist needs to be loaded with
<a href="#schematic">schematic</a>.
</p>
<h2>"lvs_data" - Gets the internal <class_doc href="LayoutVsSchematic">LayoutVsSchematic</class_doc> object</h2>
<keyword name="lvs_data"/>
<a name="lvs_data"/><p>Usage:</p>
<ul>
<li><tt>lvs_data</tt></li>
</ul>
<p>
The <class_doc href="LayoutVsSchematic">LayoutVsSchematic</class_doc> object provides access to the internal details of
the netter object.
</p>
<h2>"max_res" - Ignores resistors with a resistance above a certain value</h2>
<keyword name="max_res"/>
<a name="max_res"/><p>Usage:</p>
<ul>
<li><tt>max_res(threshold)</tt></li>
</ul>
<p>
After using this method, the netlist compare will ignore resistor devices
with a resistance value above the given threshold (in Farad).
</p>
<h2>"min_caps" - Ignores capacitors with a capacitance below a certain value</h2>
<keyword name="min_caps"/>
<a name="min_caps"/><p>Usage:</p>
<ul>
<li><tt>min_caps(threshold)</tt></li>
</ul>
<p>
After using this method, the netlist compare will ignore capacitance devices
with a capacitance values below the given threshold (in Farad).
</p>
<h2>"same_circuits" - Establishes an equivalence between the circuits</h2>
<keyword name="same_circuits"/>
<a name="same_circuits"/><p>Usage:</p>
<ul>
<li><tt>same_circuits(circuit_a, circuit_b)</tt></li>
</ul>
<p>
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>
Before this method can be used, a schematic netlist needs to be loaded with
<a href="#schematic">schematic</a>.
</p>
<h2>"same_device_classes" - Establishes an equivalence between the device classes</h2>
<keyword name="same_device_classes"/>
<a name="same_device_classes"/><p>Usage:</p>
<ul>
<li><tt>same_device_classes(class_a, class_b)</tt></li>
</ul>
<p>
This method will force an equivalence between the two device classes.
Device classes are also known as "models".
By default, device classes are identified by name. If names are different, this
method allows establishing an explicit correspondence.
</p><p>
Before this method can be used, a schematic netlist needs to be loaded with
<a href="#schematic">schematic</a>.
</p>
<h2>"same_nets" - Establishes an equivalence between the nets</h2>
<keyword name="same_nets"/>
<a name="same_nets"/><p>Usage:</p>
<ul>
<li><tt>same_nets(circuit, net_a, net_b)</tt></li>
<li><tt>same_nets(circuit_a, net_a, circuit_b, net_b)</tt></li>
</ul>
<p>
This method will force an equivalence between the net_a and net_b from circuit_a
and circuit_b (circuit in the three-argument form is for both circuit_a and circuit_b).
Circuit and nets are string giving a circuit and net by name.
After using this function, the compare algorithm will consider these nets equivalent.
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>.
</p>
<h2>"schematic" - Reads the reference netlist</h2>
<keyword name="schematic"/>
<a name="schematic"/><p>Usage:</p>
<ul>
<li><tt>schematic(filename)</tt></li>
<li><tt>schematic(filename, reader)</tt></li>
<li><tt>schematic(netlist)</tt></li>
</ul>
<p>
If a filename is given (first two forms), the netlist is read from the given file.
If no reader is provided, Spice format will be assumed. The reader object is a
<class_doc href="NetlistReader">NetlistReader</class_doc> object and allows detailed customization of the reader process.
</p><p>
Alternatively, a <class_doc href="Netlist">Netlist</class_doc> object can be given which is obtained from any other
source.
</p>
</doc>

View File

@ -14,6 +14,7 @@
<topic href="/manual/editor.xml"/>
<topic href="/manual/advanced.xml"/>
<topic href="/manual/drc.xml"/>
<topic href="/manual/lvs.xml"/>
</topics>
</doc>

View File

@ -0,0 +1,28 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">
<doc>
<title>Layout vs. Schematic (LVS)</title>
<p>
LVS is a verification step which checks whether a layout matches the circuit
from the schematic. The LVS feature is described in the following topic chapters:
</p>
<topics>
<topic href="/manual/lvs_overview.xml"/>
<topic href="/manual/lvs_intro.xml"/>
<topic href="/manual/lvs_hierarchy.xml"/>
<topic href="/manual/lvs_devices.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"/>
<topic href="/manual/lvs_browser.xml"/>
</topics>
<p>A reference for the functions and objects available for LVS scripts can be found here: <link href="/about/lvs_ref.xml"/>.</p>
</doc>

View File

@ -0,0 +1,109 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">
<doc>
<title>Layout vs. Schematic (LVS) Overview</title>
<keyword name="DRC"/>
<h2-index/>
<h2>Basic usage of LVS scripts</h2>
<p>
Starting with version 0.26, KLayout supports LVS as a built-in feature.
LVS is an important step in the verification of a layout: it ensures the
drawn circuit matches the desired schematic.
</p>
<p>
The basic functionality is simply to analyze the input layout and derive a netlist from this.
Then compare this netlist against a reference netlist (schematic). If both netlist are equivalent,
the circuit is likely to work in the intended fashion.
</p>
<p>
Beside the layout, a LVS script will also need a schematic netlist. Currently, KLayout
can read SPICE-format netlists. The reader can be configured to some extent, so the hope
is that a useful range of SPICE netlists can be digested.
</p>
<p>
While the basic idea is simple, the details become pretty complex. This documentation
tries to cover the solutions KLayout offers to implement LVS as well as the constraints
imposed by this process.
</p>
<p>
KLayout's LVS is integrated into the Macro Development IDE the same way as DRC scripts.
In fact, LVS is an add-on to DRC scripts. All DRC functions are available within LVS
scripts. Netlist extraction is performed in the DRC framework which was given the ability
to recognize devices and connections and turn them into a netlist. Although DRC does not
really benefit from these extension, they are still useful for implementing Antenna checks
for example.
</p>
<p>
LVS scripts are created, edited and debugged in the Macro Editor IDE. They are managed
in the "LVS" tab.
For more details about the IDE, see <link href="/about/macro_editor.xml"/>. For
an introduction about how to work with DRC scripts see <link href="/manual/drc_basic.xml"/>.
</p>
<p>
LVS scripts carry the ".lylvs" extension for the XML form (in analogy to ".lydrc" for DRC) and
".lvs" for the plain text form (same as ".drc"). Like DRC scripts, LVS scripts can be
executed standalone in batch mode like DRC scripts. See "Using KLayout as a standalone DRC engine"
in <link href="/manual/drc_basic.xml"/>.
</p>
<h2>KLayout's LVS implementation</h2>
<p>
The LVS implementation inside KLayout is designed to be highly flexible in terms of connectivity,
device recognition and input/output channels. Here are some highlights:
</p>
<ul>
<li><b>Agnostic approach:</b> KLayout tries to make as few assumptions as possible.
It does not require labels (although they are helpful), a specific hierarchy, specific
cell names or specific geometries. Netlist extraction is done purely from the polygons
of the layout. Labels and the cell hierarchy add merely useful hints which simplify debugging
and pin assignment, but no strict requirement.
</li>
<li><b>Hierarchical analysis:</b> KLayout got a hierarchical layout processing engine
to support hierarchical LVS. Hierarchical processing means that boolean operations happen inside
the local cell environment as far as possible. As a consequence, devices are recognized
inside their layout cell and layout cells are turned into respective subcircuits in the
netlist. The netlist compare will benefit as it is able follow the circuit hierarchy.
This is more efficient and gives better debugging information in case of mismatches.
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>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.
Second, the device recognition can be scripted to implement custom device extractors.
Five built-in device extractors are available for MOS and bipolar transistors, resistors, capacitors
and diodes.
</li>
<li><b>Flexible I/O:</b> Netlists are KLayout object trees and their components (nets, devices,
circuits, subcircuits ...) are fully mapped to script objects.
Netlists can therefore be analyzed and manipulated within LVS scripts or in other
contexts. It is possible to fully script readers and writers for custom formats.
Netlists plus the corresponding layout elements (sometimes called "annotated layout") can
be persisted in a KLayout-specific yet open format. SPICE format is available to read and
write pure netlist information. The SPICE reader and writer is customizable
through delegate classes which allow tailoring of the way devices are read and written.
</li>
<li><b>User interface integration:</b> KLayout offers a browser for the netlist
extraction results and LVS reports (cross-reference, errors).
</li>
</doc>

View File

@ -7,6 +7,8 @@
<keyword name="Net tracer"/>
<keyword name="Connectivity"/>
<h2-index/>
<p>
The net tracing function allows tracing of a net by detecting touching shapes that together form a conductive
region. It features specification of a stack of metal (or in general "conductive") layers optionally connected through
@ -16,8 +18,10 @@
active area region.
</p>
<h2>Single net tracing</h2>
<p>
The algorithm is intended for extracting single nets and employs an incremental extraction approach. Therefore
This algorithm is intended for extracting single nets and employs an incremental extraction approach. Therefore
extraction of a single small net is comparatively fast while extraction of large nets such as power nets is considerably
slower compared to hierarchical LVS tools currently.
</p>
@ -61,5 +65,53 @@
is changed to fit the net.
</p>
<h2>Tracing all nets</h2>
<p>
This algorithm is borrowed from the LVS feature, where the scenario is extended by device
recognition and netlist formation. In the context of the net tracer, nets consist of the
connected shapes but don't attach to devices. As LVS extracts all nets in one sweep, using
this feature in the net tracer will deliver all nets at once. Although this is a richer
information output, the tracing of all nets is typically faster then tracing a single, big
net such as power nets. The LVS net extractor also supports hierarchical processing which
gives a considerable performance improvement and more compact net representations.
</p>
<p>
To extract all nets, use "Trace All Nets" from the "Tools" menu. It will start extracting
the nets immediately. It will take the connectivity definition from the standard, single-net
net tracer. You can edit this layer stack either from the single net tracer UI, from the technology
manager or "Edit Layer Stack" from the "Tools" menu.
</p>
<p>
After the net tracer has finished, the netlist browser dialog opens. In this dialog you
can:
</p>
<ul>
<li>Browser the circuit hierarchy (taken from the cell hierarchy) in the left half of the central
view.
</li>
<li>Browse the nets of the circuits in the right half of the view. Clicking on a net
will highlight the net.
</li>
<li>Configure the net highlighting behavior. Use the "Configure" button.
</li>
<li>Export all or selected nets to layout, save the netlist (with shapes) to a file, load it back from a file and manage
the netlist database. Use the "File" menu button in the right upper corner.
</li>
<li>Search for net names (if labelled) and circuits using the search edit box.
</li>
<li>Navigate through the history using the "back" and "forward" buttons at the top left.
</li>
</ul>
<p>
Extracted nets are written and read in a KLayout-specific format called "L2N" ("layout to netlist").
This format contains both the nets and the shapes that make up a net. This way, the traced
nets can be saved and retrieved later.
</p>
</doc>