Using AEL Database Retrieval Functions

This chapter describes how you can extract design information from the Design Environment (DE) by using the AEL database retrieval (db) functions.

Database Overview

The database is structured around a hierarchy of objects, with the design object at the top. Every design contains two representations, a schematic and layout. In turn, these representations are composed of masks, nodes, pins, and instances. Masks contain shapes and text (data groups). Nodes, pins, and instances maintain connectivity. Instances can refer to another design and/or contain their own masks. Properties may be added to each of these database objects.

The following figure shows the design hierarchy and relationships among the design objects. For all objects, except representations, there can be a list of zero or more occurrences of the object. For example, a representation or instance may have a list of zero or more mask objects, a mask may have zero or more data groups. Each type of object is described briefly in the following sections.

Design

A design represents a complete Analog/RF or Digital Signal Processing design. Each design is stored in a separate file. Every design has two representations: a layout and a schematic. Either representation can be empty. Designs can reference other designs hierarchically through instances. There is no limit to the number of designs loaded in the program. When a hierarchical design is loaded, all the referenced designs are loaded as well.

Design Hierarchy and Relationships

Representation

Representations describe either the layout or the schematic of an Analog/RF or Digital Signal Processing design. The design synchronization engine (DSE) ensures or checks that the two are equivalent. Representations own masks (also called layers), instances, and nodes. Representations also own symbols (not shown on the chart). Symbols, used in schematics only, display a schematic in a hierarchy. A symbol owns pins and masks.

Mask

Masks (sometimes termed layers) group shapes and text. The only attribute of interest in a mask object is its number. The number is used as an index into a layer table, which in turn tells the program what color, name, fill pattern, etc. to use when displaying the objects grouped by the mask.

Node

A node, also known as net, represents an electrical connection between pins. Nodes are established by abutting pins of instances or creating a wire, naming a node, or trace that connects one or more pins. Nodes contain pointers to the pins they interconnect.

Instance

An instance represents either a primitive simulation element or a reference to another design. The term instance is also called component in the program and documentation. A resistor is represented as a primitive instance, while a subnetwork placed in another design is represented by a hierarchical instance. Regardless whether an instance is hierarchical or primitive, it can own a list of pins. Pins represent connection points for the instance. Interconnecting or abutting the pins of two instances forms an electrical connection (a node). Primitive instances can own masks. This is usually seen only in the layout representation. A microstrip transmission line instance owns the mask that describes its geometry. Instances can also own parameters. The type, name and number of parameters owned by an instance is dictated by an instance's component definition. Components are defined with the AEL create_item() and create_param() functions. When a new design is saved, a corresponding AEL definition is saved and used whenever an instance to the design is created.

Parameter

A parameter has a name and a value. The value of some parameters can be quite complex, so each value has a type. The simplest type is a single number, but some values are composed of a pair of numbers, a triple, a list of numbers, a string, etc. For example, the default value of a resistor's parameter R for resistance is the string "50 ohm." Stored with each parameter is a form name that was specified in the create_parm() function. The form name indicates how to interpret the type of a parameter's value. A number of AEL functions are supplied that simplify the extraction of parameters and their values.

Pin

A pin represents an electrical connection point on an instance. Abutting or wiring pins together forms an electrical connection (called a node). In hierarchical layout representations, a pin is created for the instance for each port on the referenced design. In hierarchical schematic representations, the symbol for the referenced design should have the same number of pins as the referenced design. The two are matched by pin number. Pins maintain a handle to any connecting wire or trace.

Data Group

A data group represents a shape or text. Shapes have a type that indicates whether the shape is a wire or trace, polygon, polyline, rectangle, circle, arc, construction line, or text. Polygons and polylines are composed of one or more segments.

Segment

A segment can be a list of points or an arc. Segments have the attribute of being filled or empty. An empty segment must be enclosed by a filled segment, since it represents a hole. Segments are composed of a list of one or more points.

Point

A point is an X,Y coordinate. These coordinates are integers in the range of roughly plus or minus 2 billion. Coordinates stored in the database are stored in database units. The number of database units to each user unit is controlled by a representation's precision. If mil is specified as the layout unit, the default is to store 1 mil as the integer 100, 0.5 mil would be stored as the integer 50.

Property

A property is a pair of a name and value. A property value type can be a long, double or string. An unlimited number of properties may be added to the following database objects: designs, representations, symbols, masks, nodes, instances, pins, data groups and segments.

Traversing a Design

For every object there is a traversal function that returns a handle to the object. Handles are like C pointers, in that they provide a way to uniquely identify an object and retrieve information about it. Generally these functions come in pairs, a get_first() and a get_next(). The get_first() function takes a handle to the object's parent, while the get_next() function takes a handle to the previous object in the list. This example uses these functions to traverse the list of data groups belonging to a mask object and count them.

decl cnt, maskHandle, dgHandle;
cnt = 0; 
dgHandle = db_first_dg( maskHandle ); 
while(  dgHandle )
{ 
   cnt = cnt + 1; 
   dgHandle = db_next_dg( dgHandle ); 
}

Besides traversal functions, each object has an attribute retrieval function. Attributes are the actual data, such as location, select status, bounding box, mask layer, pin number, etc.

The AEL function reference for an object's attribute function supplies a list of attributes that can be retrieved from each kind of object. After you have a handle to an object, you can retrieve any or all of its attributes. An attribute that is shared by both instances and data groups is the selected status attribute. By querying this attribute you can determine if an object has been selected.

Some objects, such as instances, have a large number of attributes. The example code segment demonstrates extracting information from an instance using the db_get_instance_attribute() query function.

instHandle = db_first_instance(repHandle);
while (instHandle) 
{
designName=db_get_instance_attribute(instHandle,INST_DESIGN_NAME); 
   instName   = db_get_instance_attribute(instHandle, INST_NAME);
   fputs( stderr, fmt_tokens( list( designName, " ", instName) ) );
   instHandle = db_next_instance( instHandle );

Using the database query functions can be complex. For a guide, you can use one of the examples supplied, such as de_bom.ael, which traverses the instances of a design. This file can be found in the installation sub-directory $HPEESOF_DIR/de/ael.

Note Be cautious when mixing query functions with database modification functions. As a design is modified, handles to the object in the database change and existing handles become invalid. After any modification, you should retraverse the database from the representation level on down to get new handles. Most modifications invalidate object handles.

Besides the list traversal functions, some functions retrieve design and instance information by name, rather than by handle. Examples are:

db_find_instance()
db_find_property()
db_get_instance_parm()

Details on these functions can be found in Database Query and Manipulation Functions.