API reference - Class GenericDeviceExtractor

Notation used in Ruby API documentation

Module: db

Description: The basic class for implementing custom device extractors.

Class hierarchy: GenericDeviceExtractor » DeviceExtractorBase

This class serves as a base class for implementing customized device extractors. This class does not provide any extraction functionality, so you have to implement every detail.

Device extraction requires a few definitions. The definitions are made in the reimplementation of the setup method. Required definitions to be made are:

When the device extraction is started, the device extraction algorithm will first ask the device extractor for the 'connectivity'. This is not a connectivity in a sense of electrical connections. The connectivity defines are logical compound that makes up the device. 'Connected' shapes are collected and presented to the device extractor. The connectivity is obtained by calling get_connectivity. This method must be implemented to produce the connectivity.

Finally, the individual devices need to be extracted. Each cluster of connected shapes is presented to the device extractor. A cluster may include more than one device. It's the device extractor's responsibility to extract the devices from this cluster and deliver the devices through create_device. In addition, terminals have to be defined, so the net extractor can connect to the devices. Terminal definitions are made through define_terminal. The device extraction is implemented in the extract_devices method.

If errors occur during device extraction, the error method may be used to issue such errors. Errors reported this way are kept in the error log.

This class has been introduced in version 0.26.

Public methods

void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
Device ptrcreate_deviceCreates a device.
[const]doubledbuGets the database unit
NetlistDeviceExtractorLayerDefinitiondefine_layer(string name,
string description)
Defines a layer.
NetlistDeviceExtractorLayerDefinitiondefine_opt_layer(string name,
unsigned long fallback,
string description)
Defines a layer with a fallback layer.
voiddefine_terminal(Device ptr device,
unsigned long terminal_id,
unsigned long layer_index,
const Polygon shape)
Defines a device terminal.
voiddefine_terminal(Device ptr device,
unsigned long terminal_id,
unsigned long layer_index,
const Box shape)
Defines a device terminal.
voiddefine_terminal(Device ptr device,
unsigned long terminal_id,
unsigned long layer_index,
const Point point)
Defines a device terminal.
voiderror(string message)Issues an error with the given message
voiderror(string message,
const DPolygon geometry)
Issues an error with the given message and micrometer-units polygon geometry
voiderror(string message,
const Polygon geometry)
Issues an error with the given message and database-unit polygon geometry
voiderror(string category_name,
string category_description,
string message)
Issues an error with the given category name and description, message
voiderror(string category_name,
string category_description,
string message,
const DPolygon geometry)
Issues an error with the given category name and description, message and micrometer-units polygon geometry
voiderror(string category_name,
string category_description,
string message,
const Polygon geometry)
Issues an error with the given category name and description, message and database-unit polygon geometry
[virtual]voidextract_devices(Region[] layer_geometry)Extracts the devices from the given shape cluster.
[virtual,const]Connectivityget_connectivity(const Layout layout,
unsigned int[] layers)
Gets the connectivity object used to extract the device geometry.
voidregister_device_class(DeviceClass ptr device_class)Registers a device class.
[const]doublesdbuGets the scaled database unit
[virtual]voidsetupSets up the extractor.

Detailed description

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

create_device

Signature: Device ptr create_device

Description: Creates a device.

The device object returned can be configured by the caller, e.g. set parameters. It will be owned by the netlist and must not be deleted by the caller.

dbu

Signature: [const] double dbu

Description: Gets the database unit

define_layer

Signature: NetlistDeviceExtractorLayerDefinition define_layer (string name, string description)

Description: Defines a layer.

Returns:The layer descriptor object created for this layer (use 'index' to get the layer's index)

Each call will define one more layer for the device extraction. This method shall be used inside the implementation of setup to define the device layers. The actual geometries are later available to extract_devices in the order the layers are defined.

define_opt_layer

Signature: NetlistDeviceExtractorLayerDefinition define_opt_layer (string name, unsigned long fallback, string description)

Description: Defines a layer with a fallback layer.

Returns:The layer descriptor object created for this layer (use 'index' to get the layer's index)

As define_layer, this method allows specification of device extraction layer. In addition to define_layout, it features a fallback layer. If in the device extraction statement, the primary layer is not given, the fallback layer will be used. Hence, this layer is optional. The fallback layer is given by it's index and must be defined before the layer using the fallback layer is defined. For the index, 0 is the first layer defined, 1 the second and so forth.

define_terminal

(1) Signature: void define_terminal (Device ptr device, unsigned long terminal_id, unsigned long layer_index, const Polygon shape)

Description: Defines a device terminal.

This method will define a terminal to the given device and the given terminal ID. The terminal will be placed on the layer given by "layer_index". The layer index is the index of the layer during layer definition. The first layer is 0, the second layer 1 etc.

This version produces a terminal with a shape given by the polygon. Note that the polygon is specified in database units.

(2) Signature: void define_terminal (Device ptr device, unsigned long terminal_id, unsigned long layer_index, const Box shape)

Description: Defines a device terminal.

This method will define a terminal to the given device and the given terminal ID. The terminal will be placed on the layer given by "layer_index". The layer index is the index of the layer during layer definition. The first layer is 0, the second layer 1 etc.

This version produces a terminal with a shape given by the box. Note that the box is specified in database units.

(3) Signature: void define_terminal (Device ptr device, unsigned long terminal_id, unsigned long layer_index, const Point point)

Description: Defines a device terminal.

This method will define a terminal to the given device and the given terminal ID. The terminal will be placed on the layer given by "layer_index". The layer index is the index of the layer during layer definition. The first layer is 0, the second layer 1 etc.

This version produces a point-like terminal. Note that the point is specified in database units.

error

(1) Signature: void error (string message)

Description: Issues an error with the given message

(2) Signature: void error (string message, const DPolygon geometry)

Description: Issues an error with the given message and micrometer-units polygon geometry

(3) Signature: void error (string message, const Polygon geometry)

Description: Issues an error with the given message and database-unit polygon geometry

(4) Signature: void error (string category_name, string category_description, string message)

Description: Issues an error with the given category name and description, message

(5) Signature: void error (string category_name, string category_description, string message, const DPolygon geometry)

Description: Issues an error with the given category name and description, message and micrometer-units polygon geometry

(6) Signature: void error (string category_name, string category_description, string message, const Polygon geometry)

Description: Issues an error with the given category name and description, message and database-unit polygon geometry

extract_devices

Signature: [virtual] void extract_devices (Region[] layer_geometry)

Description: Extracts the devices from the given shape cluster.

The shape cluster is a set of geometries belonging together in terms of the connectivity defined by "get_connectivity". The cluster might cover multiple devices, so the implementation needs to consider this case. The geometries are already merged.

The implementation of this method shall use "create_device" to create new devices based on the geometry found. It shall use "define_terminal" to define terminals by which the nets extracted in the network extraction step connect to the new devices.

get_connectivity

Signature: [virtual,const] Connectivity get_connectivity (const Layout layout, unsigned int[] layers)

Description: Gets the connectivity object used to extract the device geometry.

This method shall raise an error, if the input layer are not properly defined (e.g. too few etc.)

This is not a connectivity definition in the electrical sense, but defines the cluster of shapes which generates a specific device. In this case, 'connectivity' means 'definition of shapes that need to touch to form the device'.

The 'layers' argument specifies the actual layer layouts for the logical device layers (see define_layer). The list of layers corresponds to the number of layers defined. Use the layer indexes from this list to build the connectivity with Connectivity#connect. Note, that in order to capture a connected cluster of shapes on the same layer you'll need to include a self-connection like 'connectivity.connect(layers[0], layers[0])'.

register_device_class

Signature: void register_device_class (DeviceClass ptr device_class)

Description: Registers a device class.

The device class object will become owned by the netlist and must not be deleted by the caller. The name of the device class will be changed to the name given to the device extractor. This method shall be used inside the implementation of setup to register the device classes.

sdbu

Signature: [const] double sdbu

Description: Gets the scaled database unit

Use this unit to compute device properties. It is the database unit multiplied with the device scaling factor.

setup

Signature: [virtual] void setup

Description: Sets up the extractor.

This method is supposed to set up the device extractor. This involves three basic steps: defining the name, the device class and setting up the device layers.

Use name= to give the extractor and it's device class a name. Use register_device_class to register the device class you need. Defined the layers by calling define_layer once or several times.