From 1e49338fe93f9b540e977edebce5974d32723497 Mon Sep 17 00:00:00 2001 From: Matthias Koefferlein Date: Sun, 30 Jun 2019 23:36:51 +0200 Subject: [PATCH] WIP: doc. --- src/lay/lay/doc/about/lvs_ref.xml | 14 ++ src/lay/lay/doc/about/lvs_ref_global.xml | 126 +++++++++++++++++ src/lay/lay/doc/about/lvs_ref_netter.xml | 172 +++++++++++++++++++++++ src/lay/lay/doc/manual/index.xml | 1 + src/lay/lay/doc/manual/lvs.xml | 28 ++++ src/lay/lay/doc/manual/lvs_overview.xml | 109 ++++++++++++++ src/lay/lay/doc/manual/net_tracing.xml | 54 ++++++- 7 files changed, 503 insertions(+), 1 deletion(-) create mode 100644 src/lay/lay/doc/about/lvs_ref.xml create mode 100644 src/lay/lay/doc/about/lvs_ref_global.xml create mode 100644 src/lay/lay/doc/about/lvs_ref_netter.xml create mode 100644 src/lay/lay/doc/manual/lvs.xml create mode 100644 src/lay/lay/doc/manual/lvs_overview.xml diff --git a/src/lay/lay/doc/about/lvs_ref.xml b/src/lay/lay/doc/about/lvs_ref.xml new file mode 100644 index 000000000..1fcdb8ba6 --- /dev/null +++ b/src/lay/lay/doc/about/lvs_ref.xml @@ -0,0 +1,14 @@ + + + + + + + +LVS Reference + + + + + + diff --git a/src/lay/lay/doc/about/lvs_ref_global.xml b/src/lay/lay/doc/about/lvs_ref_global.xml new file mode 100644 index 000000000..d99c2fb74 --- /dev/null +++ b/src/lay/lay/doc/about/lvs_ref_global.xml @@ -0,0 +1,126 @@ + + + + + + + +LVS Reference: Global Functions + +

+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. +

+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. +

+For more details about the DRC functions see DRC::global. +

+ +

"compare" - Compares the extracted netlist vs. the schematic

+ +

Usage:

+
    +
  • compare
    • +
+

+See Netter#compare for a description of that function. +

+

"equivalent_pins" - Marks pins as equivalent

+ +

Usage:

+
    +
  • equivalent_pins(circuit, pins ...)
    • +
+

+See Netter#equivalent_pins for a description of that function. +

+

"max_res" - Ignores resistors with a resistance above a certain value

+ +

Usage:

+
    +
  • max_res(threshold)
    • +
+

+See Netter#max_res for a description of that function. +

+

"min_caps" - Ignores capacitors with a capacitance below a certain value

+ +

Usage:

+
    +
  • min_caps(threshold)
    • +
+

+See Netter#min_caps for a description of that function. +

+

"netter" - Creates a new netter object

+ +

Usage:

+
    +
  • netter
    • +
+

+See Netter for more details +

+

"report_lvs" - Specifies an LVS report for output

+ +

Usage:

+
    +
  • report_lvs([ filename ])
    • +
+

+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. +

+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. +

+report_lvs is only effective if a comparison step is included. +

+

"same_circuits" - Establishes an equivalence between the circuits

+ +

Usage:

+
    +
  • same_circuits(circuit_a, circuit_b)
    • +
+

+See Netter#same_circuits for a description of that function. +

+

"same_device_classes" - Establishes an equivalence between the device_classes

+ +

Usage:

+
    +
  • same_device_classes(class_a, class_b)
    • +
+

+See Netter#same_device_classes for a description of that function. +

+

"same_nets" - Establishes an equivalence between the nets

+ +

Usage:

+
    +
  • same_nets(circuit, net_a, net_b)
    • +
  • same_nets(circuit_a, net_a, circuit_b, net_b)
    • +
+

+See Netter#same_nets for a description of that function. +

+

"schematic" - Reads the reference netlist

+ +

Usage:

+
    +
  • schematic(filename)
    • +
  • schematic(filename, reader)
    • +
  • schematic(netlist)
    • +
+

+See Netter#schematic for a description of that function. +

+ diff --git a/src/lay/lay/doc/about/lvs_ref_netter.xml b/src/lay/lay/doc/about/lvs_ref_netter.xml new file mode 100644 index 000000000..98a3cd859 --- /dev/null +++ b/src/lay/lay/doc/about/lvs_ref_netter.xml @@ -0,0 +1,172 @@ + + + + + + + +LVS Reference: Netter object + +

+The Netter object provides services related to network extraction +from a layout plus comparison against a reference netlist. +Similar to the DRC DRC::Netter (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. +

+The LVS Netter object inherits all methods of the DRC::Netter. +

+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 global#netter function: +

+

+# 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
+
+

+ +

"compare" - Compares the extracted netlist vs. the schematic

+ +

Usage:

+
    +
  • compare
    • +
+

+Before using this method, a schematic netlist has to be loaded with schematic. +The compare can be configured in more details using same_nets, same_circuits, +same_device_classes and equivalent_pins. +

+This method will return true, if the netlists are equivalent and false +otherwise. +

+

"equivalent_pins" - Marks pins as equivalent

+ +

Usage:

+
    +
  • equivalent_pins(circuit, pins ...)
    • +
+

+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): +

+

+netter.equivalent_pins("NAND2", "A", "B")
+
+

+Before this method can be used, a schematic netlist needs to be loaded with +schematic. +

+

"lvs_data" - Gets the internal LayoutVsSchematic object

+ +

Usage:

+
    +
  • lvs_data
    • +
+

+The LayoutVsSchematic object provides access to the internal details of +the netter object. +

+

"max_res" - Ignores resistors with a resistance above a certain value

+ +

Usage:

+
    +
  • max_res(threshold)
    • +
+

+After using this method, the netlist compare will ignore resistor devices +with a resistance value above the given threshold (in Farad). +

+

"min_caps" - Ignores capacitors with a capacitance below a certain value

+ +

Usage:

+
    +
  • min_caps(threshold)
    • +
+

+After using this method, the netlist compare will ignore capacitance devices +with a capacitance values below the given threshold (in Farad). +

+

"same_circuits" - Establishes an equivalence between the circuits

+ +

Usage:

+
    +
  • same_circuits(circuit_a, circuit_b)
    • +
+

+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. +

+Before this method can be used, a schematic netlist needs to be loaded with +schematic. +

+

"same_device_classes" - Establishes an equivalence between the device classes

+ +

Usage:

+
    +
  • same_device_classes(class_a, class_b)
    • +
+

+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. +

+Before this method can be used, a schematic netlist needs to be loaded with +schematic. +

+

"same_nets" - Establishes an equivalence between the nets

+ +

Usage:

+
    +
  • same_nets(circuit, net_a, net_b)
    • +
  • same_nets(circuit_a, net_a, circuit_b, net_b)
    • +
+

+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. +

+Before this method can be used, a schematic netlist needs to be loaded with +schematic. +

+

"schematic" - Reads the reference netlist

+ +

Usage:

+
    +
  • schematic(filename)
    • +
  • schematic(filename, reader)
    • +
  • schematic(netlist)
    • +
+

+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 +NetlistReader object and allows detailed customization of the reader process. +

+Alternatively, a Netlist object can be given which is obtained from any other +source. +

+ diff --git a/src/lay/lay/doc/manual/index.xml b/src/lay/lay/doc/manual/index.xml index 5f7f6216e..9229a65e4 100644 --- a/src/lay/lay/doc/manual/index.xml +++ b/src/lay/lay/doc/manual/index.xml @@ -14,6 +14,7 @@ + diff --git a/src/lay/lay/doc/manual/lvs.xml b/src/lay/lay/doc/manual/lvs.xml new file mode 100644 index 000000000..f74fe09fd --- /dev/null +++ b/src/lay/lay/doc/manual/lvs.xml @@ -0,0 +1,28 @@ + + + + + + Layout vs. Schematic (LVS) + +

+ 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: +

+ + + + + + + + + + + + + +

A reference for the functions and objects available for LVS scripts can be found here: .

+ + + diff --git a/src/lay/lay/doc/manual/lvs_overview.xml b/src/lay/lay/doc/manual/lvs_overview.xml new file mode 100644 index 000000000..f5c1882e0 --- /dev/null +++ b/src/lay/lay/doc/manual/lvs_overview.xml @@ -0,0 +1,109 @@ + + + + + + Layout vs. Schematic (LVS) Overview + + + + +

Basic usage of LVS scripts

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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 . For + an introduction about how to work with DRC scripts see . +

+ +

+ 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 . +

+ +

KLayout's LVS implementation

+ +

+ 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: +

+ +
    +
  • Agnostic approach: 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. +
    • +
  • Hierarchical analysis: 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. +
    • +
  • Flexible engine: 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. +
    • +
  • Flexible I/O: 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. +
    • +
  • User interface integration: KLayout offers a browser for the netlist + extraction results and LVS reports (cross-reference, errors). +
    • + + + + + + + + diff --git a/src/lay/lay/doc/manual/net_tracing.xml b/src/lay/lay/doc/manual/net_tracing.xml index ee2180e3b..6c8b3a416 100644 --- a/src/lay/lay/doc/manual/net_tracing.xml +++ b/src/lay/lay/doc/manual/net_tracing.xml @@ -7,6 +7,8 @@ + +

    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.

    +

    Single net tracing

    +

    - 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.

    @@ -61,5 +65,53 @@ is changed to fit the net.

    +

    Tracing all nets

    + +

    + 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. +

    + +

    + 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. +

    + +

    + After the net tracer has finished, the netlist browser dialog opens. In this dialog you + can: +

    + +
      +
    • Browser the circuit hierarchy (taken from the cell hierarchy) in the left half of the central + view. +
      • +
    • Browse the nets of the circuits in the right half of the view. Clicking on a net + will highlight the net. +
      • +
    • Configure the net highlighting behavior. Use the "Configure" button. +
      • +
    • 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. +
      • +
    • Search for net names (if labelled) and circuits using the search edit box. +
      • +
    • Navigate through the history using the "back" and "forward" buttons at the top left. +
      • +
    + +

    + 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. +

    +