3

---

CDBA Database Objects

---

Design data is stored as objects on the OpenAccess database. Each type of object represents a distinct concept in the world of electronic design automation. Examples of objects are rectangles, terminals, instances, and cellviews.

The OpenAccess database stores both physical and logical information about a design. Physical information is stored in objects such as geometrical shapes that directly correspond to their physical implementations. Logical information, on the other hand, is stored in objects such as nets that can exist without any corresponding physical realizations.

For more specific information on database objects, see these sections:

• Object Identifiers
• Object Types and Classes
• Attributes
• Properties
• Attributes and Properties Compared
• Property Bags
• Relationships among Objects
• Objects and IDs

Object Identifiers

To access an object in the database, you must first obtain a handle to the object known as the object identifier, or ID. IDs are data structures containing information that uniquely identifies the database objects the data structures refer to. The contents of IDs can only be created by database routines. End users cannot alter them directly. For all functions that operate on database objects, you need to specify the ID as a function argument.

This section discusses a generalized concept of database objects rather than the explicit CDBA data structures.

Object Types and Classes

Each object belongs to a type, and each type contains a number of attributes that describe the object. When a number of distinct object types share enough attributes to be more easily referred to as a single class, you create a data-type abstraction called an object class for these object types. The attributes of the object types, not the object types themselves, determine the grouping.

The different object types and classes form a class hierarchy. At the top of the hierarchy is the class of all database objects. At the bottom of the hierarchy are leaf nodes that represent an object type you can create, delete, and save on disk. Each node in the hierarchy has attributes that are common to all of its children. Geometrical shapes, for example, have the common attributes of layer, purpose, and bounding box.

The following table, Database Objects and IDs, shows a list of object classes, the names of the corresponding enumerated constants, and the names of corresponding IDs. The enumerated type dbType represents all enumerated constants representing object types.

Database Objects and IDs

Object class	Enumerated constant	Name for ID of object	Name for ID of enumerated constant
cellview	dbcCellViewType	dbCellViewId	dbcNullCellViewId
figure	-	dbFigId	dbcNullFigId
shape	-	dbShapeId	dbcNullShapeId
rectangle	dbcRectType	dbRectId	dbcNullRectId
polygon	dbcPolygonType	dbPolygonId	dbcNullPolygonId
line	dbcLineType	dbLineId	dbcNullLineId
path	dbcPathType	dbPathId	dbcNullPathId
arc	dbcArcType	dbArcId	dbcNullArcId
ellipse	dbcEllipseType	dbEllipseId	dbcNullEllipseId
donut	dbcDonutType	dbDonutId	dbcNullDonutId
dot	dbcDotType	dbDotId	dbcNullDotId
label	dbcLabelType	dbLabelId	dbcNullLabelId
any instance	-	dbAnyInstId	dbcNullAnyInstId
instance	dbcInstType	dbInstId	dbcNullInstId
mosaic instance	dbcMosaicInstType	dbMosaicInstId	dbcNullMosaicInstId
mosaic	dbcMosaicType	dbMosaicId	dbcNullMosaicId
signal	dbcSigType	dbSigId	dbcNullSigId
net	dbcNetType	dbNetId	dbcNullNetId
terminal	dbcTermType	dbTermId	dbcNullTermId
pin	dbcPinType	dbPinId	dbcNullPinId
instance header	dbcInstHeaderType	dbInstHeaderId	dbcNullInstHeaderId
instance terminal	dbcInstTermType	dbInstTermId	dbcNullInstTermId
instance pin	dbcInstPinType	dbInstPinId	dbcNullInstPinId
property	dbcPropType	dbPropId	dbcNullPropId
property bag	dbcBagType	dbBagId	dbcNullBagId
group	dbcGroupType	dbGroupId	dbcNullGroupId
group member	dbcGroupMemType	dbGroupMemId	dbcNullGroupMemId
layer	dbcLayerType	dbLayerId	dbcNullLayerId
display	dbcDisplayType	dbDisplayId	dbcNullDisplayId
text display	dbcTextDisplay	dbTextDisplayId	dbcNullTextDisplayId
zero value for generators			dbcNoMoreObj

Attributes

Each object type has a predefined set of attributes that can be set and retrieved using CDBA functions. The three types of attributes are

• Mandatory
• Optional
• Derived

Mandatory Attributes

Most attributes are mandatory. You must specify mandatory attributes at the time the object is created.

Optional Attributes

Some objects can have optional attributes. You can add optional attributes after an object is created.

Derived Attributes

Derived attributes are reconstructed from other object attributes. You have read-only access to derived attributes. Derived attributes are not stored in the database, but they play an important role in speeding up repetitive computation.

Properties

Properties store information about objects and serve as a mechanism for extending the basic framework of the database. A property has a name (which is a string) and a value. A property value can be a Boolean value, an integer, a floating-point number, a string, or an integer representing time. You can attach an arbitrary number of properties to an object.

Attributes and Properties Compared

The most important distinction between attributes and properties is that attributes are predefined and managed by the database, while properties are defined and managed by applications built on top of the database.

This distinction is often blurred because information currently stored as properties can be so essential to system operation that to ensure its robustness and speed, the database itself needs to manage this information directly. On the other hand, information currently stored as attributes can be so rarely used that the attributes should be moved out of the database layer into the application layer.

Mandatory attributes are stored directly in data structures that are optimized for storage efficiency and performance. Less frequently used optional attributes are better stored as “properties” instead of as part of the basic data structures, because properties take up storage space only when they are present. If you redefine optional attributes as properties, the optional attributes become visible to the user as normal properties.

Although properties are not mandatory for the database, some information currently stored as properties is essential to an application’s operations. Therefore, properties are mandatory for an application.

Because mandatory information stored as a property now might eventually be stored as an attribute later, some minor incompatibilities between different versions of CDBA are inevitable.

Currently, there is no solution to the problem, but the following coding conventions might minimize incompatibilities:

• Avoid name conflicts between attributes and properties that Cadence might introduce in the future. Adopt a naming convention that does not conflict with the Cadence naming convention.
  A simple convention is to make the names of all your properties begin with an uppercase letter (except “X,” which signifies the X Window System) because the Cadence convention is to begin names with a lowercase letter. An even safer convention, however, is to add to all your property names a unique three-letter prefix identifying your company.
• Although an attribute might be stored as a property, continue to treat it as you do other attributes. Always use the CDBA functions that are provided for manipulating that attribute.

Property Bags

Properties of OpenAccess objects can be accessed through property bags.

Storage Hierarchy Structure

Access to properties is handled through a concept called a property bag. The property bag is a virtual space that contains only properties and is managed by the procedural interface (PI). Each library, cell, or cellview can have an associated property bag. The PI keeps track of properties and manages interaction with properties.

Property Bag Access

You manipulate library, cell, and cellview properties externally through the same PI you use in DFII. When you create, access, and update a library, cell, or cellview property, this action causes an implicit I/O on the property bag, unless you call the property bag explicitly. The implicit I/O also supports transparent migration.

Opening a design cellview does not trigger the opening of the property bag. You open the property bag only when you need to. You can also open the property bag without also opening a design.

The following summarizes I/O implicit interaction with properties for both access and internal editing.

• When you access library, cell, or view properties without doing an explicit I/O on the property bag, the I/O implicitly does the following.
  • Opens the property bag for read.
  • Gets the property requested, if any.
• When you edit library, cell, or cellview properties without doing an explicit I/O on the property bag, the following occur implicitly.
  • The I/O opens the property bag for edit.
  • You edit the property.
  • You save and reopen the bag for read.

Therefore, each edit implies a pair of open and save operations. If you are editing more than one property in a given property bag, you can reduce the I/O overhead by opening the bag explicitly, making your edits, then saving and closing the bag.

A property bag residing in virtual memory (VM) might be out of date in a multiuser environment. Therefore, if you need to get the most current version, you must use dbMakeBagCurrent prior to any access or edit.

Explicit I/O Functions on Property Bags

If you open a property bag explicitly and access, create, and update properties in the property bag, the behavior enforced for the property bag is the same as the one for the design cellview. There is no I/O or locking overhead until you save, close, or purge the property bag.

Explicit I/O functions on property bags follow, along with brief explanations of their options.

dbOpenBag

dbBagId

dbOpenBag( ddId id, String mode 
);

Opens the library, cell, or view property bag in the given mode. Valid modes are r for read, and a or w for append. Locking and checking out policies are identical to dbOpenCellViewByType.

Opening the property bag for append or write locks out other users from updating the same property bag until the property bag is purged or reopened for read. Internally a reference count (refCount) is updated every time a property bag is opened and closed. A write count (wCount) is also updated every time a property bag is opened and closed for editing.

dbCloseBag

Boolean

dbCloseBag( dbBagId bagId, String mode 
);

Decrements the property bag refCount. If refCount becomes zero, the dbCloseBag function purges the property bag refCount from virtual memory and unlocks the property bag. Closing for edit decrements the write count. If the write count reaches zero but the refCount is still greater than zero, the property bag is downgraded to read mode and other users can edit it. Valid modes are r for read, and a or w for append.

dbGetRefCount

dbGetRefCount

dbGetRefCount( ddId id, String mode 
);

For DFII on OpenAccess, returns a value that is one less than the OpenAccess cellview refCount value that is returned by oaCellView::getRefCount(). This applies to cellviews that represent instance sub-masters. Exceptions are instance super-master cellviews.

dbPurgeBag

Boolean 

dbPurgeBag( dbBagId bagId 
);

Purges the property bag from virtual memory (VM) and releases the lock applied on the bag.

dbSaveBag

Boolean

dbSaveBag( dbBagId bagId 
);

Writes the VM image of the property bag.

dbRefreshBag

Boolean 

dbRefreshBag( dbBagId bagId 
);

Refreshes the VM image of the property bag with the stored image. If no stored image exists and the property bag is in append mode, it resets the property bag to empty (the VM image is truncated).

dbReOpenBag

Boolean

dbReOpenBag( dbBagId bagId, String mode 
);

Reopens the property bag for the given mode. Valid modes are r for read, and a or w for append.

dbGetBag

dbBagId

dbGetBag( ddId id 
);

Returns the property bag ID of the given ddId. Opens and reads the property bag if it is not yet in VM. If the property bag does not exist, it returns NULL ID. It does not increment the refCount if the property bag is already in VM.

dbMakeBagCurrent

Boolean

dbMakeBagCurrent( dbBagId bagId 
);

Refreshes the given property bag if it is out of date relative to the saved version. Returns FALSE only if it finds an error.

dbGetBagDdId

ddId

dbGetBagDdId( dbBagId bagId 
);

Returns the ddId associated with the property bag.

dbFindOpenBag

dbBagId

dbFindOpenBag( ddId id 
);

If the bag for the given ddId exists in VM, dbFindOpenBag returns it. Otherwise, it returns NULL.

Information Retrieval Functions on Property Bags

The following functions retrieve information about various characteristics of property bags.

dbIsBagId

Boolean

dbIsBagId( dbBagId bagId 
);

Returns TRUE if the given bagId is valid.

dbGetBagTimeStamp

time_t

dbGetBagTimeStamp( dbBagId bagId 
);

Returns the timeStamp of the property bag. The property bag timeStamp is not set or modified until you update the property bag.

dbIsBagCurrent

Boolean

dbIsBagCurrent( dbBagId bagId 
);

Returns TRUE if the property bag is current relative to the saved version.

dbIsBagReadable

Boolean

dbIsBagReadable( ddId id 
);

Returns TRUE if the property bag exists for the given ddId and the user has read access on the bag. The property bag must exist.

dbIsBagWritable

Boolean

dbIsBagWritable( ddId id 
);

Returns the UNIX file permission of the property bag regardless of the open mode of the property bag. For example, basic is a system owned library, dbIsBagWritable will always return FALSE on its bag. If you own a library, and its property bag has write permission, even if the bag is opened in r mode, dbIsBagWritable will still return TRUE. A new property bag that exists only in VM is not considered writable.

The following db functions

• Accept dbId, ddId and dbBagId
• Open, save, and reopen the property bag for an accepted ddId, if applicable

dbCreateProp(),

dbCreateHierProp(),

dbCreateRangeProp(),

dbCreateEnumProp();

dbReplaceProp(),

dbReplaceRangeProp(),

dbReplaceHierProp(),

dbReplaceEnumProp(),

dbReplacePropSpecial();

dbGetPropByName();

dbStartGenProp();

dbGenProp();

dbObjHasProp();

dbCopyProp();

dbMergeProp();

dbCopySingleProp();

dbMergeSingleProp();

Relationships among Objects

The OpenAccess database stores a large number of predefined relationships among different object types for efficiency and consistency. Such relationships are typically hidden from you, but you must explicitly create and maintain other object relationships. Some predefined relationships are

• Mandatory relationships
• Optional relationships
• Direct relationships
• Derived relationships
• One-to-one relationships
• Many-to-one relationships
• One-to-many relationships
• Relationships between logical and physical objects

Mandatory Relationships

Mandatory relationships are required relationships in the database. For example, every terminal must be attached to an electrical net. Therefore, you cannot create a terminal without specifying a net to which it connects.

Mandatory relationships are very often unidirectional. For example, you might have a net that does not connect to a terminal.

To maintain database consistency, when you delete an object belonging to a mandatory relationship, other objects belonging to that relationship are also deleted, because they cannot exist on their own. For example, if an electrical net is deleted, the terminal attached to that net is deleted as well because it cannot exist on its own.

Optional Relationships

Optional relationships in the database are those which are not required but which you create. You can create objects independently, then create the relationships among the objects.

Functions are provided for adding objects to and subtracting objects from the relationship. An example of a function expressing an optional relationship is

dbAddFigToNet( figId, netId )

Direct Relationships

Direct relationships have a one-to-one correspondence to linkage pointers within the database.

Derived Relationships

Derived relationships must be reconstructed each time their corresponding access functions are called, because derived attributes are not stored in the database. It is therefore usually much faster to access direct relationships than to access derived relationships.

One-to-One and Many-to-One Relationships

When a predefined relationship is a one-to-one or a many-to-one relationship, an access function allows the user to go from the source object to the related object. For example, the user can go from an instance to its master using the dbGetInstMaster function.

One-to-Many Relationships

When a predefined relationship is a one-to-many relationship, use the generator function to traverse the relationship and visit the related objects. For example, the user can go from a master to all its instances using the dbGenMasterToAnyInst generator function.

Relationships Between Logical and Physical Objects

When a logical object has a corresponding physical realization represented by one or more physical objects, the objects are linked together in the database. Access functions go from a logical object to its corresponding physical objects and vice versa.

An example of a function that accesses a physical object (a figure) from a logical object (a net) is

dbGenNetToFig(...)

Objects and IDs

The API is strongly typed so that the compiler catches as many semantic errors as possible at compile time. Compared to the alternative of a single generic C type for all database IDs, which performs type checking at execution, a strongly typed API facilitates error checking much earlier, is more efficient, and is inherently more robust. It does, however, occasionally require explicit typecasting among different types of IDs.

Conversions between IDs

All conversions between compatible ID types have to be explicit using the C typecasting mechanism. You must take special care not to cast a generic ID into a specific ID, until you know that the ID is indeed pointing to an object of that particular type. Casting an ID into an incompatible ID type creates a fatal programming error. You can reliably detect it only at run time, using the debug version of CDBA.

Functions to Retrieve Object and ID Information

Use the following functions to retrieve information about objects and IDs.

dbGetType

dbType

dbGetType( dbId id 
);

The dbGetType function returns an enumerated constant, which represents the object type referred to by the ID. For example, use dbcRectType if the object is a rectangle. dbGetType is currently implemented as a function but might be implemented as a macro in the future.

dbIsIdEqual

Boolean

dbIsIdEqual( dbId id1, dbId id2 
);

The dbIsIdEqual macro returns TRUE if id1 and id2 refer to the same database object. Always use this macro to test for the equality of two IDs instead of relying on the C operator “==”.

The following set of functions are fast, safe, and quiet. They never produce a core dump, no matter what arguments are passed to them, and they never generate error messages.

dbIsId

Boolean

dbIsId( dbId id 
);

The dbIsId function returns TRUE if the argument is a valid database object ID. If not, it returns FALSE.

dbIsCellViewId

Boolean

dbIsCellViewId( dbCellViewId id 
);

The dbIsCellViewId function returns TRUE if the argument is a valid cellview ID. If not, it returns FALSE.

dbIsFigId

The dbIsFigId function is documented in “CDBA Figure Functions”.

dbIsShapeId

The dbIsShapeId function is documented in “Shape Figure Functions”.

dbIsAnyInstId

Boolean

dbIsAnyInstId( dbAnyInstId id 
);

The dbIsAnyInstId function returns TRUE if the argument is a valid instance or mosaic instance ID. If not, it returns FALSE.

Return to top