The Flat View API

This Document describes the "Flat View" extension to the Database API and provides the commands listed below.

A Flat View is an instance-tree-based data structure linked to a top module. That data structure is created implicitly when needed, but can be compressed or freed explicitly. Each flat view can store flat attributes, flat flags and highlight colors. In addition it can be used for flat traversal.

Here is a reference list of the flat view commands:

The Flat View data is addressed by (usually tree-based) OIDs. Each OID’s root module must refer to a top module; more precisely, isTopRoot must return true for the OID - if not, then the OID cannot address a Flat View data structure and the commands will return an error.

The Flat View provides a "flat" view to a certain design tree; it is linked to a top module in the database. The Flat View data structure is created automatically when needed.

The free command deletes the Flat View at the given top or all Flat Views if $top is not specified. If a database is closed by $db close then all Flat Views are automatically freed.

The compress command frees unneeded data nodes from the Flat View data structure (saves memory space). If a $top is specified, then only the Flat View at the given top module is compressed (else all Flat Views are compressed).

The foreach hilight command loops over the flat view and executes the body for each object which has the hilight info set. A variable with the name of color is set with the current hilight value.

The foreach flagged command loops over the flat view and executes the body for each object which has a flat attribute with the given flagname set.

The foreach attr command loops over the flat view and executes the body for each object which has a attribute with the given attrname set. A variable with the name of value is set with the current attribute value.

The foreach obj command loops over the flat view and executes the body for each object which has attribute, flags or hilight info set. If a object in flat view does not match the database it is skipped. With the '-error' option set, unmatched objects generate an error.

The $top, if specified, must be an OID of a top module (it must not be tree-based and isTopRoot must be true). The database must not be modified while one or more Flat Views exists (or the Flat View data get invalid).

Here, the term "signal" is used to describe a set of interconnected nets (in the design hierarchy tree rooted at a top module). Technically, signal-OIDs are identical to the net-OIDs, but the different type name identifies that it is the top-most net of the interconnected nets. Most of the API functions that accept a net OID also accept a signal OID with the same meaning as the net OID.

In contrast to the $db functions, the flat functions are not local to a certain module, but traverse all instance paths below the top module (in other words: in the Flat View of the top module). The top module - and so the Flat View - is identified by the OID’s root module, that means, isTopRoot must be true for $top and $net below.

The 1st command loops over all signals in the flat-view (cur is set to the signal-OID of each signal in the design tree). If the optional argument -addHier is specified global nets are skipped. The 2nd command loops over all interconnected nets (of the given net or signal OID) and the 3rd command loops over all pins (and top-level ports) of all interconnected nets (identified by the given net or signal OID). If the net has the 'global' flag set, all nets with the same name in all hierarchies are visited. Keep in mind that this may be a large number for big designs. If the optional argument -addHier is specified then all intermediate hierarchical pins and ports are processed. If the optional argument -stopHier is specified then hierarchical pins which connect to nothing down the hierarchy are processed in addition. If the optional argument -skipConst is specified then connected constant nets are skipped. The 4th command "'foreach netseg'" executes $body for each netsegment, which lies on the path between $pin1 and $pin2. If there is no signal between $pin1 and $pin2 an error is generated. The 5th command "'signalOf'" returns the signal-OID that is the top-most net connected to $net (the top-most of all candidates that "'foreach net'" would traverse). For nets which have the 'global' flag set a net with the same name is searched in the top module.

The following commands exceptionally do not use the Flat View data structure:

The first command traverses the hierarchy tree, rooted at $mod (module OID, usually the top module) and loops over each instance of flagged Primitives or Modules (flagged with the given $flag. In each iteration, "cur" is set to an instance OID. The instance path of the "cur" OID starts with the path given to "$mod" and gets longer while the command dives down the hierarchy tree. If `$flag`is an empty string the command loops over all instances including all module instances. The second command traverses the hierarchy tree like the first command, but only one instance of each referenced cell is visited. The third command traverses the hierarchy tree rooted at $mod and loops over each instance of all modules. The fourth command traverses the hierarchy tree like the previous command, but only one instance of each referenced module is visited.

In addition to the module-based attributes, the database also supports "flat" attributes that are stored in an instance-tree-based data structure called Flat View. The Flat View is addressed by the $flag OID's root module as described above.

Both, add and set append one or more attributes to the given OID - however, set overwrites existing attributes (avoids duplicates) and add simply appends. The format of `$attr`is "name=value".

delete removes all or the named attributes from the given OID.

get returns a list of all attributes (list of name=value` elements). If the optional switch -sorted is given then a sorted list of all attributes is returned.

getValue returns just the attribute value (or an empty string if not found).

getMerged and getMergedValue have the same functionality as "get" and "getValue" but additionally merge the result with the module-based object attributes (module-based attributes have lower priority than flat attributes).

The flat-view’s attributes resist in the database and therefore also in the binfile. The number of attributes per OID is currently limited to 32.

With the deleteAll command, all flat attributes are removed. The '$name' arguments specify the attributes which should be removed. It may be omitted if all attributes should be removed. The "'$top'" is "*" or a module-based module OID; if "*" is used, then all trees are scanned otherwise only flat objects within the tree below the given '$top'. isTopRoot must return true for all OIDs.

In addition to the module-based flags, the database also supports "flat" flags that are stored in an instance-tree-based data structure called Flat View. The Flat View is addressed by the OID's root module as described above.

set or clear a flag at the specified object in the tree-based data structure. The is command returns a Boolean, is_set and is_clear do both, return the old flag (like is) and afterwards set or clear that flag. The get command returns a list of all set flags at the given object. The clearall command clears the given flag in the complete tree-based data structure, rooted at the given $oid’s top module. The general purpose flag name must be one of "orange", "cyan", "black", "white", "magenta" and "target".

The database also supports "flat" ids that are stored in an instance-tree-based data structure called Flat View. The Flat View is addressed by the $flag OID's root module as described above.

set the given numeric $id to the given OID. get returns the numeric id for the given OID. If there is none set 0 is returned. Currently only net, netBus or signal oids are supported.

The following commands can be used to highlight individual objects only in one specific instantiation path. An object inside a module that is instantiated multiple times will be highlighted with the given color only in the specified instantiation path of this module. The highlight API can be used to highlight objects in each instance of a module.

The set command set the flat highlight color for the object specified by $oid to $col. The get command returns the current flat highlight color or an empty list ( "{}" ) if nothing set. The getMerged command returns the flat highlight color, if not set it looks for the module based highlight color and if none found an empty list ( "{}" ) is returned. The delete command removes the highlight color from the object specified by $oid. With the deleteAll command, all highlights are removed. The '$col' argument specifies the color of the objects which should be removed. It may be omitted if all highlights should be removed. The "'$top'" is "*" or a module-based module OID; if "*" is used, then all trees are scanned otherwise only flat objects within the tree below the given '$top'. isTopRoot must return true for all OIDs.

A flathilight on a signal OID is supported but only stores the highlight information for the signal. It does not show the highlight color in the GUI. To do so the same color needs to be set at each net of the signal.

There are two sets of highlight colors for each object. 'normal' and '-permanent'. They can be set and deleted independent of each other. If both are set the 'normal' color has priority over the permanent color. '$col' may be in the range 0..48.

Using the option -both to get either the normal or permanent highlight color will return the permanent value as a negative number to be able to distinguish between normal highlight.

The following command can be used to add, get and loop over out of module references (OOMR).

Adding OOMR connectivity to a pin which has already a net connected in the module based world results in a warning. It is not fully supported and will be treated like disconnected in all hierarchies except the one defined by the OOMR commands.

To avoid these limitations (and the warning) use a singlized design (e.g. $db oper singlize) and disconnect the pins before adding OOMR connectivity.

Additionally, most of the operators are not aware of the OOMR connectivity and should be avoided.