From 33678ff6d93e158bfbc83e4215e4ec37477663b4 Mon Sep 17 00:00:00 2001 From: Matthias Koefferlein Date: Sat, 4 Jul 2026 23:28:21 +0200 Subject: [PATCH] Documentation --- src/doc/doc/about/drc_ref_global.xml | 229 ++++++++++++++++++++++++--- src/doc/doc/about/drc_ref_netter.xml | 23 ++- src/doc/doc/about/lvs_ref_global.xml | 17 ++ src/doc/doc/about/lvs_ref_netter.xml | 19 ++- src/doc/doc/manual/lvs_io.xml | 190 ++++++++++++++++++---- 5 files changed, 430 insertions(+), 48 deletions(-) diff --git a/src/doc/doc/about/drc_ref_global.xml b/src/doc/doc/about/drc_ref_global.xml index c10de75cf..e44fc040a 100644 --- a/src/doc/doc/about/drc_ref_global.xml +++ b/src/doc/doc/about/drc_ref_global.xml @@ -107,29 +107,59 @@ See Layer#drc, Usage:

Use this class with extract_devices to specify extraction of a -bipolar junction transistor +bipolar junction transistor without a substrate terminal. +If used with a name, the extractor will produce devices with device +class DeviceClassBJT3Transistor. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorBJT3Transistor for more details about this extractor.

+

"bjt3_class" - Supplies the device class for a 3-terminal bipolar junction transistor

+ +

Usage:

+
    +
  • bjt3_class(name)
    • +
+

+See DeviceClassBJT3Transistor for more details +about this device class. +

"bjt4" - Supplies the BJT4 transistor extractor class

Usage:

  • bjt4(name)
    • -
  • bjt4(name, class)
    • +
  • bjt4(device_class)

Use this class with extract_devices to specify extraction of a bipolar junction transistor with a substrate terminal +If used with a name, the extractor will produce devices with device +class DeviceClassBJT4Transistor. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorBJT4Transistor for more details about this extractor.

+

"bjt4_class" - Supplies the device class for a 4-terminal bipolar junction transistor

+ +

Usage:

+
    +
  • bjt4_class(name)
    • +
+

+See DeviceClassBJT4Transistor for more details +about this device class. +

"box" - Creates a box object

Usage:

@@ -145,30 +175,60 @@ This function creates a box object. The arguments are the same than for the

Usage:

  • capacitor(name, area_cap)
    • -
  • capacitor(name, area_cap, class)
    • +
  • capacitor(device_class, area_cap)

Use this class with extract_devices to specify extraction of a capacitor. The area_cap argument is the capacitance in Farad per square micrometer. +If used with a name, the extractor will produce devices with device +class DeviceClassCapacitor. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorCapacitor for more details about this extractor.

+

"capacitor_class" - Supplies the device class for a capacitor

+ +

Usage:

+
    +
  • capacitor_class(name)
    • +
+

+See DeviceClassCapacitor for more details +about this device class. +

"capacitor_with_bulk" - Supplies the capacitor extractor class that includes a bulk terminal

Usage:

  • capacitor_with_bulk(name, area_cap)
    • -
  • capacitor_with_bulk(name, area_cap, class)
    • +
  • capacitor_with_bulk(device_class, area_cap)

Use this class with extract_devices to specify extraction of a capacitor with a bulk terminal. The area_cap argument is the capacitance in Farad per square micrometer. +If used with a name, the extractor will produce devices with device +class DeviceClassCapacitorWithBulk. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorCapacitorWithBulk for more details about this extractor.

+

"capacitor_with_bulk_class" - Supplies the device class for a capacitor that includes a bulk terminal

+ +

Usage:

+
    +
  • capacitor_with_bulk_class(name)
    • +
+

+See DeviceClassCapacitorWithBulk for more details +about this device class. +

"cell" - Selects a cell for input on the default source

Usage:

@@ -470,47 +530,92 @@ See Netter#device_scaling

Usage:

Use this class with extract_devices to specify extraction of a planar diode +If used with a name, the extractor will produce devices with device +class DeviceClassDiode. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorDiode for more details about this extractor.

+

"diode_class" - Supplies the device class for a diode

+ +

Usage:

+
    +
  • diode_class(name)
    • +
+

+See DeviceClassDiode for more details +about this device class. +

"dmos3" - Supplies the DMOS3 transistor extractor class

Usage:

  • dmos3(name)
    • -
  • dmos3(name, class)
    • +
  • dmos3(device_class)

Use this class with extract_devices to specify extraction of a three-terminal DMOS transistor. A DMOS transistor is essentially the same than a MOS transistor, but source and drain are separated. +If used with a name, the extractor will produce devices with device +class DeviceClassMOS3Transistor. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorMOS3Transistor for more details about this extractor (strict mode applies for 'dmos3').

+

"dmos3_class" - Supplies the device class for a three-terminal DMOS transistor

+ +

Usage:

+
    +
  • dmos3_class(name)
    • +
+

+See DeviceClassMOS3Transistor for more details +about this device class. +

"dmos4" - Supplies the MOS4 transistor extractor class

Usage:

  • dmos4(name)
    • -
  • dmos4(name, class)
    • +
  • dmos4(device_class)

Use this class with extract_devices to specify extraction of a four-terminal DMOS transistor. A DMOS transistor is essentially the same than a MOS transistor, but source and drain are separated. +If used with a name, the extractor will produce devices with device +class DeviceClassMOS4Transistor. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorMOS4Transistor for more details about this extractor (strict mode applies for 'dmos4').

+

"dmos4_class" - Supplies the device class for a four-terminal DMOS transistor

+ +

Usage:

+
    +
  • dmos4_class(name)
    • +
+

+See DeviceClassMOS4Transistor for more details +about this device class. +

"edge" - Creates an edge object

Usage:

@@ -1201,29 +1306,59 @@ argument, "middle" represents the bounding box center marker generator on primar

Usage:

  • mos3(name)
    • -
  • mos3(name, class)
    • +
  • mos3(device_class)

Use this class with extract_devices to specify extraction of a three-terminal MOS transistor. +If used with a name, the extractor will produce devices with device +class DeviceClassMOS3Transistor. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorMOS3Transistor for more details about this extractor (non-strict mode applies for 'mos3').

+

"mos3_class" - Supplies the device class for a three-terminal symmetric MOS transistor

+ +

Usage:

+
    +
  • mos3_class(name)
    • +
+

+See DeviceClassMOS3Transistor for more details +about this device class. +

"mos4" - Supplies the MOS4 transistor extractor class

Usage:

  • mos4(name)
    • -
  • mos4(name, class)
    • +
  • mos4(device_class)

Use this class with extract_devices to specify extraction of a four-terminal MOS transistor. +If used with a name, the extractor will produce devices with device +class DeviceClassMOS4Transistor. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorMOS4Transistor for more details about this extractor (non-strict mode applies for 'mos4').

+

"mos4_class" - Supplies the device class for a four-terminal symmetric MOS transistor

+ +

Usage:

+
    +
  • mos4_class(name)
    • +
+

+See DeviceClassMOS4Transistor for more details +about this device class. +

"name" - Assigns a name to a layer for reference in the LVS database

Usage:

@@ -1666,6 +1801,26 @@ l1 = input(1, 0)

To remove this condition, call "region_touch" without any arguments.

+

"register_device_class" - Registers a device class for device extraction and netlisting

+ +

Usage:

+
    +
  • register_device_class(dc)
    • +
+

+Registers the device class for extraction and netlist input and output. +"dc" is an object of type DeviceClass. +

+Registers a device class for extraction and netlist output. +Registering a device class is optional. However, using registered +device classed simplify SPICE netlist writing, as device classes +can be configured with SPICE profiles to customize SPICE output. +In the LVS context, register_device_class also controls the way +schematic netlists are read from SPICE. +See Netter#register_device_class for a description of this function. +Also see Netter#extract_devices for how to use it with registered +device classes. +

"relative_height" - Selects primary shapes based on the ratio of height and width of their bounding boxes

Usage:

@@ -1718,37 +1873,65 @@ will also be written to the given file. If a file name is given and "long" is true, a verbose version of the L2N DB format will be used.

-

"resistor" - Supplies the resistor extractor class

+

"resistor" - Supplies the resistor extractor class.

Usage:

    -
  • resistor(name, sheet_rho)
    • -
  • resistor(name, sheet_rho, class)
    • +
  • resistor(name, rho)
    • +
  • resistor(device_class, rho)

Use this class with extract_devices to specify extraction of a resistor. -

-The sheet_rho value is the sheet resistance in ohms/square. It is used -to compute the resistance from the geometry. +"rho" is the sheet resistance in ohms/square. +If used with a name, the extractor will produce devices with device +class DeviceClassResistor. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorResistor for more details about this extractor.

+

"resistor_class" - Supplies the device class for a resistor

+ +

Usage:

+
    +
  • resistor_class(name)
    • +
+

+See DeviceClassResistor for more details +about this device class. +

"resistor_with_bulk" - Supplies the resistor extractor class that includes a bulk terminal

Usage:

    -
  • resistor_with_bulk(name, sheet_rho)
    • -
  • resistor_with_bulk(name, sheet_rho, class)
    • +
  • resistor_with_bulk(name, rho)
    • +
  • resistor_with_bulk(device_class, rho)

Use this class with extract_devices to specify extraction of a resistor with a bulk terminal. -The sheet_rho value is the sheet resistance in ohms/square. +"rho" is the sheet resistance in ohms/square. +If used with a name, the extractor will produce devices with device +class DeviceClassResistorWithBulk. If used with a specific device +class object, the extractor will produce devices with this class. +It is the responsibility of the user that this class is compatible with +the parameters and terminals the extractor will require.

See DeviceExtractorResistorWithBulk for more details about this extractor.

+

"resistor_with_bulk_class" - Supplies the device class for a resistor that includes a bulk terminal

+ +

Usage:

+
    +
  • resistor_with_bulk_class(name)
    • +
+

+See DeviceClassResistorWithBulk for more details +about this device class. +

"rounded_corners" - Applies corner rounding

Usage:

@@ -2318,6 +2501,7 @@ shape.
  • write_spice([ use_net_names [, with_comments ] ])
  • write_spice(writer_delegate [, use_net_names [, with_comments ] ])
    • +
  • write_spice(spice_profile [, use_net_names [, with_comments ] ])

Use this option in target_netlist for the format parameter to @@ -2328,5 +2512,12 @@ information comments such as instance coordinates or pin names.

"writer_delegate" allows using a NetlistSpiceWriterDelegate object to control the actual writing. +

+To provide the name of a SPICE profile to use, include it the following way: +

+

+# write SPICE files using profile "my_profile"
+write_spice(spice_profile("my-profile"))
+

diff --git a/src/doc/doc/about/drc_ref_netter.xml b/src/doc/doc/about/drc_ref_netter.xml index aca1a28e7..72ccafa48 100644 --- a/src/doc/doc/about/drc_ref_netter.xml +++ b/src/doc/doc/about/drc_ref_netter.xml @@ -468,7 +468,6 @@ either save to OASIS, or use integer numbers for the property names.

Usage:

Runs the device extraction for given device extractor class. In the first @@ -608,6 +607,28 @@ layout analysis. Hence, all connect, connect statements will clear the netlist and re-extract it again.

+

"register_device_class" - Registers a device class for device extraction and netlisting

+ +

Usage:

+
    +
  • register_device_class(dc)
    • +
+

+Registers the given device class object ("dc" is of type DeviceClass) +for use inside device extraction and for reading and writing netlists. +Registering a device class allows utilizing SPICE profiles for reading and +writing SPICE files. Device classes need to be registered before "schematic" +or "extract_devices" is used. +

+Registering device classes simplifies implementation of custom SPICE +representations for devices. Usually it is not required then to provide +SPICE reader or write delegates, as the SPICE format can be configured +inside the device class through SPICE profiles. +

+When creating custom device extractors, it is no longer required to +register a device class inside the device extractor. Instead, pre-registered device +classes are identified with a device extractor class by name. +

"soft_connect" - Specifies a soft connection between two layers

Usage:

diff --git a/src/doc/doc/about/lvs_ref_global.xml b/src/doc/doc/about/lvs_ref_global.xml index 494ef2f6e..9ed495891 100644 --- a/src/doc/doc/about/lvs_ref_global.xml +++ b/src/doc/doc/about/lvs_ref_global.xml @@ -172,6 +172,23 @@ See Netter for more details

See Netter#no_lvs_hints for a description of that feature.

+

"register_device_class" - Registers a device class for device extraction and netlisting

+ +

Usage:

+
    +
  • register_device_class(dc)
    • +
+

+Registers the device class for extraction and netlist input and output. +"dc" is an object of type DeviceClass. +

+Registering a device class is optional. However, using registered +device classed simplify SPICE netlist reading and writing, as device classes +can be configured with SPICE profiles to customize SPICE input and output. +See Netter#register_device_class for a description of this function. +Also see Netter#extract_devices for how to use it with registered +device classes. +

"report_lvs" - Specifies an LVS report for output

Usage:

diff --git a/src/doc/doc/about/lvs_ref_netter.xml b/src/doc/doc/about/lvs_ref_netter.xml index 2e1dbd89e..0bebc6e95 100644 --- a/src/doc/doc/about/lvs_ref_netter.xml +++ b/src/doc/doc/about/lvs_ref_netter.xml @@ -473,6 +473,8 @@ same_nets!("ND2", "A", "B")
  • schematic(filename)
  • schematic(filename, reader)
    • +
  • schematic(filename, spice_profile)
    • +
  • schematic(filename, spice_reader_delegate)
  • schematic(netlist)
  • schematic
@@ -480,9 +482,24 @@ same_nets!("ND2", "A", "B") If no argument is given, the current schematic netlist is returned. nil is returned if no schematic netlist is set yet.

-If a filename is given (first two forms), the netlist is read from the given file. +If a filename is given, 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. +Or you specify a NetlistSpiceReaderDelegate object to customize a SPICE reader +with a delegate. +

+Instead of a reader or delegate, a SPICE profile can be specified. In that case, the device +classes need to be registered with register_device_class before the schematic +method is called. To use a SPICE profile with name "my-profile" use this code: +

+

+# for a specific netter object
+netter.schematic("netlist.cir", spice_profile("my-profile"))
+
+# or globally
+schematic("netlist.cir", spice_profile("my-profile"))
+

Alternatively, a Netlist object can be given which is obtained from any other source. diff --git a/src/doc/doc/manual/lvs_io.xml b/src/doc/doc/manual/lvs_io.xml index 8cfd98cd7..b3b316a55 100644 --- a/src/doc/doc/manual/lvs_io.xml +++ b/src/doc/doc/manual/lvs_io.xml @@ -7,6 +7,7 @@ + @@ -40,6 +41,7 @@ You can write a netlist file to supply netlists for simulators for example. Within LVS scripts, the global "target_netlist" statement triggers writing of a netlist (see target_netlist for details). + For example, this writes the extracted netlist to "output.cir" in SPICE format: 

target_netlist("output.cir", write_spice, "Created by KLayout")
@@ -55,19 +57,33 @@

- The "write_spice" configuration function has two options: + The "write_spice" configuration function has these options:

- 
write_spice(use_net_names, with_comments)
+ 
write_spice(use_net_names, with_comments)
+write_spice(spice_profile(profile_name), use_net_names, with_comments)

- Both options are boolean values. If true and present, the first option will make + "use_net_names" and "with_comments" are optional, boolean values. If true and present, the first option will make the writer use the real net's names instead of numerical IDs. If true and present, "with_comments" will embed debug comments into the netlist showing instance locations, pin names etc.

+

+ For customizing SPICE output there are two possible + implementation paths: SPICE profiles and SPICE writer delegates. + While SPICE writer delegates are the most flexible way, SPICE + profiles are easier to use, but require a certain structure + in the LVS scripts. +

+ +

+ For documentation on SPICE profiles see the corresponding section below. +

+

SPICE writer delegates

+

Further customization can be achieved by providing an explicit SPICE writer @@ -145,30 +161,6 @@ X$2 VSS IN OUT SUBSTRATE NMOS PARAMS: L=0.25 W=0.9 AS=0.405 AD=0.405 PS=2.7 this way, a single netlist can be written to multiple files in different flavours.

-

SPICE profiles

- -

- An easier way to customize SPICE output is through "SPICE profiles". SPICE profiles are - pieces of data attached to "device class". Every device inside a netlist is associated with a - device class. The device class is a named entity inside the netlist. In a SPICE netlist, the - model name is the name of that device class. Device classes are objects of type . - Device classes, among other properties, carry "SPICE profiles". A SPICE profile declares: -

- - - -

- In most cases, the SPICE profiles will be enough to configure how devices are written - and read from SPICE files, so it is not required to implement a reader or writer delegate. - On the back side, it is required to declare and configure the device classes in the LVS - scripts. -

- -

Reading netlists

@@ -187,6 +179,21 @@ X$2 VSS IN OUT SUBSTRATE NMOS PARAMS: L=0.25 W=0.9 AS=0.405 AD=0.405 PS=2.7 Capacitor device classes) and "D" (gives diode device classes).

+

+ For customizing SPICE input there are two possible + implementation paths: SPICE profiles and SPICE reader delegates. + While SPICE reader delegates are the most flexible way, SPICE + profiles are easier to use, but require a certain structure + in the LVS scripts. +

+ +

+ For documentation on SPICE profiles see the corresponding section below. +

+ +

SPICE reader delegates

+ +

As for the SPICE reader, a delegate can be provided to customize the reader. For doing so, subclass the @@ -300,4 +307,133 @@ schematic("inv_xmodels.cir", reader) Hence exchange of LVS reports is possible.

+

SPICE profiles

+ + +

+ An easier way to customize SPICE output is through "SPICE profiles". SPICE profiles are + pieces of data attached to a "device class". Every device inside a netlist is associated with a + device class. The device class is a named entity inside the netlist. In a SPICE netlist, the + model name is the name of that device class. Device classes are objects of type . + Device classes carry, among other properties, "SPICE profiles". A SPICE profile declares: +

+ +
    +
  • The element to use for the device (e.g. "M" or "X")
    • +
  • How the parameters are written
    • +
  • How the parameters are read
    • +
+ +

+ In most cases, the SPICE profiles will be enough to configure how devices are written + and read from SPICE files, so it is not required to implement a reader or writer delegate. + On the back side, it is required to declare and configure the device classes in the LVS + scripts. +

+ +

+ To declare devices, you have to include their definitions before you use "schematic" to + read the schematic netlist and before you extract devices. + Definitions are made by creating a device class, either from the standard device classes + or using a custom one, and then configuring them. After you have configured them, they + need to be registered, so the SPICE reader and writer code knows they exist. +

+ +

+ Convenience helpers are provided to create an instance of the standard classes: + mos4_class, + dmos4_class, + mos3_class, + dmos3_class, + diode_class, + bjt3_class, + bjt4_class, + resistor_class, + resistor_with_bulk_class, + capacitor_class and + capacitor_with_bulk_class. + The helpers create device class objects which are pre-filled with the corresponding + parameters and terminals. Also, the device combination rules are configured already. +

+ +

+ Here is an example how to register custom device classes derived from the MOS4 class + () and which bind to SPICE "X" elements: +

+ + 
...
+
+# Creates a PMOS device derived from the MOS4 built-in type
+# and configure the default SPICE profile to use element type "X"
+pmos = mos4_class("PMOS")
+pmos.spice_profile().element = "X"
+
+# Same for NMOS
+nmos = mos4_class("NMOS")
+nmos.spice_profile().element = "X"
+
+# Registers the two new device classes
+# NOTE: this needs to come before the schematic netlist is read
+# or devices are extracted
+register_device_class(pmos)
+register_device_class(nmos)
+
+# Reads the schematic
+schematic("schematic.cir")
+
+...
+
+# PMOS transistor device extraction
+# NOTE: "mos4(pmos)" creates a device extractor for MOS4 devices which 
+# produces devices of "pmos" type.
+extract_devices(mos4(pmos), { "SD" => psd, "G" => pgate, "W" => nwell, 
+                              "tS" => psd, "tD" => psd, "tG" => poly, "tW" => nwell })
+
+# NMOS transistor device extraction
+extract_devices(mos4(nmos), { "SD" => nsd, "G" => ngate, "W" => bulk, 
+                              "tS" => nsd, "tD" => nsd, "tG" => poly, "tW" => bulk })
+
+...
+ +

+ For complete freedom of device configuration, you can also create + your own classes using the class. + Instead using the factories for pre-defined classes (such as "mos4_class" above), + you instantiate your own class. +

+ +

+ For more information about how SPICE reading and writing can be configured + with SPICE profiles, see here: . + Note that currently you can't modify the model name through SPICE profiles. +

+ +

+ There can be multiple SPICE profiles for different purposes (e.g. + SPICE reading and writing. SPICE profiles are named. For example, you + can declare two profiles - one for reading (called "READ") and one + for writing (called "WRITE") and use them separately: +

+ + 
...
+
+# Configures the target netlist to be written with SPICE profile "WRITE"
+target_netlist("extracted.cir", write_spice(spice_profile("WRITE")), "Extracted by KLayout")
+
+...
+
+# Creates a device class for "PMOS" with two SPICE
+# profiles. The one for reading uses the "X" element,
+# the one for writing uses the "M" element:
+pmos = mos4_class("PMOS")
+pmos.spice_profile("READ").element = "X"
+pmos.spice_profile("WRITE").element = "M"
+
+...
+
+# Reads the schematic using SPICE profile "READ"
+schematic("schematic.cir", spice_profile("READ"))
+
+...
+