The Operator API

The operators modify the Database.

It is not safe to run operators modifying the database while using a $db foreach …​ loop - especially if the body of the foreach loop modifies the current iteration type.

Here is an overview of the operator commands:

$db oper maketop $topCnt
$db oper guessTopModule ?-singleTop? ?-useAllUnreferencedCells? ?-ignoreLibcells?
$db oper sorttop
$db oper tsort
$db oper deftop $mod
$db oper deleteUnused
$db oper zombieUnused

$db oper validatePG

$db oper mergeNet $net $net2
$db oper mergeNetBus $netBus $netBus2
$db oper connect $pin $net
$db oper disconnect $pin

$db oper hiersep scan|get|wish
$db oper unused wish

$db oper singlize $inst
$db oper singlizePath $inst
$db oper singlizeTree $mod

$db oper addhier $mname $iname $instList
$db oper rmhier $inst ?$prefix? ?-delzombies?

$db oper createHier ?-doNotGuessPortDir? $top $hiersep ?$prefix?

$db oper collectSignalData ?-pg? ?-value? ?-spos? ?-attr? ?-hilight? ?-flatattr? ?-flathilight? ?$top?
$db oper flatdesign ?-spos? ?-keep? $top

$db oper flattenSubtree $inst

$db oper gate $mod ?-fold|-autofold? ?-noflat? …​
$db oper gateadd $type $key $stype $suffix $iorder
$db oper gateadd -clear
$db oper hierStart $top ?-fold|-autofold? ?-noflat? …​
$db oper hierAdd $cname $iname $iList $oList …​
$db oper hierFinish
$db oper hierFoldCount
$db oper hierFoldDupl foldkey
$db oper hierFoldList

$db oper hierPathCount
$db oper hierPathDupl $foldkey

$db oper rename ?-updateOIDs? ?-checkName? ?$oid $newname?
$db oper renameUniq ?-updateOIDs?
$db oper renameDigit

$db oper changecellref ?-updateOIDs? ?-similar? ?$inst $newcell?
$db oper setDirection $oid $dir ?-updatePins?

$db oper bulk wrong|all|none|nopg

$db oper guessPortBus $prim|$mod $open $close
$db oper guessNetBus ?-down? $mod $open $close
$db oper guessInstArray $mod $open $close ?-delzombies?
$db oper createPortBus $prim|$mod $busname $ports
$db oper sortPorts ?-down?
$db oper guessBusses ?-down? $open ?$close?
$db oper verilogBusses ?$cell?
$db oper distributeSubBits netBus attrName

$db oper removeBuf $mod|-all ?-delzombies?
$db oper removeInv $mod|-all ?-delzombies?
$db oper createConst $mod|-all ?-netstub? ?-bool? ?-delzombies?
$db oper guessWide $mod|-all ?-equal? ?-mux? ?-prio? ?-dlatch? ?-repeat? ?-delzombies?
$db oper guessWideBus $mod|-all ?-delzombies?
$db oper chain $mod|-all ?-mux? ?-bool? ?-inv? ?-delzombies?
$db oper reducePins $mod|-all ?-created? ?-modules? ?-delzombies?
$db oper removeDangle $mod|-all ?-delzombies?
$db oper instarray $mod|-all open close ?-delzombies?
$db oper bubbles $mod|-all ?-delzombies?
$db oper negedge $mod|-all ?-delzombies?
$db oper removeUnused ?-delzombies?
$db oper mergeRams ?-delzombies? ?$mod?
$db oper deletePort $cell $pname …​
$db oper guessDir

$db oper groupmultifinger $sep
$db oper weakflow ?-hspice? ?-reslimit limit?
$db oper poweranddirsettings ?-node m n t? ?-icase?
$db oper guesspower
$db oper poweranddirguess ?-icase? ?-avoidshorted? ?-evalvsrc2p? ?-evalvsrc2i? ?-addtopports? ?-pwrprop? ?-force?
$db oper hidepowerports
$db oper cleanup
$db oper expand ?-auto? ?-auto0? ?-icase? ?str …​..?
$db oper shortRes limit ?-hspice? ?-delzombies?
$db oper removeMOS ?-delzombies?
$db oper removeUseless ?-delzombies?
$db oper removeRes ?-delzombies?
$db oper removeCap ?-delzombies?
$db oper mergeParallelCap ?-hspice? ?-parasitic? ?-delzombies? ?mod?
$db oper mergeParallelRes ?-hspice? ?-parasitic? ?-delzombies? ?mod?
$db oper mergeParallelDiode ?-hspice? ?-parasitic? ?-delzombies? ?mod?
$db oper mergeParallelInst ?-hspice? ?-parasitic? ?-delzombies? ?-module mod? …​
$db oper reportParallelInst ?-parasitic? ?-module mod? …​
$db oper mergeSerialRes ?-hspice? ?-delzombies? ?mod?
$db oper mergeSerialCap ?-hspice? ?-delzombies? ?mod?
$db oper mergeParallel ?-hspice? ?-multi m? ?-delzombies?
$db oper mergeSerial ?-delzombies?
$db oper mergeSerialParallel ?-hspice? ?-multi m? ?-equality val? `?-delzombies?
$db oper removeEmptyModule ?-delzombies? ?-checkDanglingNets? ?-checkZombies?

$db oper analyzeCoupling
$db oper paraRmHier ?-delzombies? ?-prefix $pref? ?$inst|$mod?
$db oper paraRename $mod
$db oper paraMinMax $mod
$db oper paraNetCap $mod
$db oper paraFinish ?-deleteUnmatched?
$db oper paraInline ?-inlinemod? ?-delzombies?
$db oper paraRollback ?-delzombies?

The maketop command searches for up to $topCnt "top-level" modules and adds them to the list of top-modules; see the $db foreach top …​ loop.

The guessTopModule command flags modules as top which were most likely top modules. If only library cells are present then all of them become top module.

The sorttop command divides the list of top-modules into two sections and sorts each section (this affects the order of the $db foreach top …​ loop); the first section stores the "real tops" (modules that instantiate other modules) and the second section may store unreferenced library cells. The tsort command performs a topological sort to get a "declared before used" order of the modules. This re-orders the list of modules; see the $db foreach module …​ loop.

This operator validates the database for power and ground nets. If no power or ground net was found then an error will be raised. This operator is useful for databases with transistor devices.

The first command merges two nets by appending $net2's connectivity to $net. All connectivity (as e.g. specified by $db load net's -pin and -port) is moved from $net2 to $net. Net $net2 survives with no connections at all. Power/ground/negpower flags from $net2 are also merged into $net.

The second command merges all members of two netBuses with the same behavior as described above for mergeNet.

The third command disconnects a Pin or Port from a Net. The $pin must be a pin or port OID - if the pin/port already is unconnected then this command has no effect.

The fourth command connects a Pin or Port to a Net. The $pin must be a pin or port OID - if the pin/port is already connected to the given net then this command has no effect. If the pin/port is already connected to another net then this command throws an error.

The scan option scans all instance and net names in the database and returns a character that’s not used in any name - so it can be used as a separator character for path names.

The get option returns the previously scanned character - or if no "scan" was performed before, then it performs a scan exactly like the "scan" option do.

The wish option sets the desired hierarchy separator $character. If this character is not used in any name then it will be used as a separator character for path names.

The unused operator can be used to scan the database and return characters which are not used in the design. For each character in $wish an unused character is returned in the result.

In the zdb, each hierarchical module is either instantiated zero times (e.g. a top module) or one time (is "singlized") or multiple times, i.e. it is referred by more than one instance (is not "singlized"). We use the term "singlized module" if the module is only referred by one instance. The following commands clone modules if required to get a "singlized" hierarchy:

The singlize command checks only the one given instance $inst. If its down-module’s refcount is more than one (used by other instances also), then the module is cloned (same contents but the module name is extended by a unique number) and attached to that instance only. Then, the cloned module’s refcount is one - so it is private to that instance.

The singlizePath command walks down the instance path and performs singlize for each instance on the path as well as for the final $inst ($inst must be a tree-based OID).

The singlizeTree traverses the full sub-tree rooted at $mod and performs the "singlizing" for each hierarchy instance.

The singlize and singlizePath commands also "go to" the singlized module (exactly as reloadModule does), so that further load commands can add more objects to the singlized module. The singlize and singlizePath commands also accept tree-based module-OIDs (instead of instance-OIDs).

These commands update the native representation of all affected Tcl OID variables. That means that all existing Tcl OID variables stay at their objects. This kind of OID updates usually don’t change their textual representation, except for Module and Primitive OIDs, e.g. module top U2 U43 MUX will change to module top U2 U43 MUX#1 (if instance top.U2.U43 was singlized).

Split all instances and nets of a flat design at the given hierarchy separator and re-create the hierarchy.

Collect signal data from all connected nets. With the options -pg, -value, -spos, -attr, -hilight, -flatattr and -flathilight only selected data is copied to the main signal net. If no options are used all data is copied. If a top module is given, only this hierarchy is processed. Otherwise all hierarchies are processed.

The whole design get flattened into the given top module. If the -spos option is given, source file position are created for the flattened objects.

If the -keep option is given then the original hierarchical top will be preserved.

The addhier command adds a new level of hierarchy, grouping the given $instList (list of Instance OIDs). All elements in $instList must have the same root and path - meaning they must be located in the same parent module. The $mname is the name of the new Module (created to group the $instList) and $iname is the name of the new Instance of that Module. That new component is created within the parent module and its OID is returned. If the optional $prefix argument is given, then it specifies the prefix of characters removed from each inst/net/netBus name moved to the new Module. If the optional -usefirstinst argument is given, the first instance of $instList is used to determine the ports. If the optional -pwrgndtoo argument is given, power/ground nets create ports too.

The $instList may store tree-based and/or module-based OIDs, but they never singlize the path to the parent, meaning the command applies to all instantiations (if there are multi-instantiated Modules in the design).

The rmhier command removes the specified Module Instance and moves its contents up one level of hierarchy. The given $inst must be a tree-based Instance-OID (of the object to be removed). The optional $prefix argument specifies a prefix-string that is used to prefix all Instances, Nets and NetBuses names. If $prefix is not specified, then rmhier first checks if the existing names would create a name clash and if so, then it ties different prefixes until it finds one that will not create a name clash. As prefixes, it uses the $inst's name plus one of these single characters: _ - : <space> , # $ % & (but not the current hiersep). Like addhier, this command also never singlizes the path to the $inst, meaning if the path to $inst is multi-instantiated, then rmhier returns an error.

To remove the deleted objects the -delzombies options is needed. To optimize the performance for multiple rmhier commands this option can be omitted for all but the last commands.

The algorithm for addhier splits the crossing nets and routes them through the new module’s interface ($mname) - except for power/ground/negpower nets (those nets are split but not routed through the new module’s interface); rmhier is the undo-function to addhier and merges the split nets into a single net.

The subtree rooted at the specified hierarchical instance is flattened. All hierarchical instances in the subtree must be <<SINGLIZE,singlized>.

These oper functions are for internal use only.

Multiple calls to hierAdd need to be surrounded by one call to hierStart and hierFinish.

The other opers are useful for statistics.

The rename command changes the name of the given OID to $newname. The $db oid oname command will return $newname.

If the option -updateOIDs is specified, then all Tcl variables referring to object ids will be updated. The same effect can be achieved using the $db oid resetAllOIDs command.

The option -checkName will check if the rename would create a name clash and throws an error.

Please note that the rename operator works module based. If you rename an object with either flat attributes or flat highlight in a module that is instantiated multiple times, then the flat tree structure is not updated. To work around this limitation you can use the singlize operator to unfold the hierarchy.

The renameUniq command renames all Modules, Primitives, Ports and PortBusses such that they have a unique name (Modules and Primitives are renamed to C{number}, Ports are renamed to p{number}, and PortBusses are renamed to b{number}, where {number} is an increasing integer value).

The renameDigit command renames all Nets and Ports to avoid starting with a digit.

The changecellref command changes the referenced cell of the given instance OID to the cell specified as $newcell. The interface of $newcell must be identical to the original cell - unless the -similar option is specified.

If the option -similar is specified, then $newcell does not need to have the same interface as the original cell - instead, the instance’s connectivity is restored by port names: If $newcell is missing a port, the originally connected net will be disconnected, if $newcell has additional ports, the corresponding instance pins will not be connected to any net.

If the option -updateOIDs is specified, then all Tcl variables referring to object ids will be updated.

$dir may be on one of input, output, inout, or unknown.

The setDirection command may be used to change the direction of a given pin, port, pinBus or portBus. The direction can only be changed for cells without a function.

To get a valid database the direction of pins and ports must be in sync. The -updatePins option can be used to make this automatically. Because this is a relative costly operation it should be done once for all changes.

The bulk command toggles the visibility of the bulk pin(s) at NMOS, PMOS, NPN and PNP transistors. If devices with the functions CAP, RES, INDUCTOR, DIODE or ZDIODE are loaded with the optional bulk(s) pin then these devices are also processed by this operator.

If mode is wrong then only bulk connections at PMOS or PNP transistors are shown not connected to a power or negpower node and bulk connections at NMOS or NPN transistors are shown not connected to a ground node.

If mode is all then all bulk connections are shown.

If mode is none then no bulk connections are shown.

If mode is nopg then only bulks not connected to a power, negpower or ground node are shown.

Please note that not connected bulk pins are always hidden and that bulk hiding for symbol shapes coming from a symbol library is not supported.

Loops over all ports of a cell and tries to guess PortBuses. Sequential ports with same basename followed by a bit subscript will create a port bus. The bit subscript must consist of numerical digits prefixed by one character out of $open and ending with a character out of the optional $close argument. For the special case that $open contains 0, no character between base name and bit subscript is needed. If the ports with same basename are not in a sequential order they can be sorted by calling the sortPorts operator in advance.

Loops over all nets of a module and tries to guess NetBuses. Sequential net with same basename followed by a bit subscript will create a net bus. The bit subscript must consist of numerical digits prefixed by one character out of $open and ending with a character out of the optional $close argument. For the special case that $open contains 0, no character between base name and bit subscript is needed. Subscripts will get numerical sorted downwards if -down is specified.

Loops over all instances of a module and tries to guess arrayed instances. Instances with same basename followed by a bit subscript will create an arrayed instance. The bit subscript must consist of numerical digits prefixed by one character out of $open and ending with a character out of the optional $close argument. An optional suffix after the $close character will be appended to the generated base name. For the special case that $open contains 0, no character between base name and bit subscript is needed.

Create port bus from given ports.

Sorts all modules ports. Subscripts will get numerical sorted downwards if -down is specified.

The guessBusses command calls all bus guessing operators in the correct order to re-create bus structures from single bit ports.

The verilogBusses command only creates Verilog conform buses from single bit ports with consecutive numbering.

Distribute value of the given $netBus to all sub-bits.

Remove all BUF and WIDE_BUF instances and merge the connected nets.

Remove all INV instances if the input connects to a power or ground net. The net connected to the output is flagged with the inverted value of the input net.

Replace all power ground nets connected to input pins with a 'constant' net stub and annotate a 'value' attribute with the constant value.

The option -bool looks for AND/OR primitives with constant 0/1 at one input pin. If found, the constant is propagated to the output pin and the instance is removed. Nets connected to X and Z primitives are treated as a value of 'X' and 'Z'. These instances get removed if all connections can be replaced by a constant.

Replace multiple scalar primitives connected to same bus pin by corresponding wide function primitive.

The option -repeat may be used to recognize wide functions which are found only after the creation of some other wide functions.

The option -equal looks for equal/nequal/lessthan primitives connected to a bus pin and converts them to a hierarchical block.

The option -mux looks for mux primitives connected to a bus pin and converts them to a hierarchical block or a WIDE_MUX depending nets connected to the sel pins.

The option -prio looks for PRIO_SELECTOR primitives connected to a bus pin and converts them to a WIDE_PRIO_SELECTOR, but only if the sel pins or all connected in the same way.

The option -dlatch looks for DLATCH primitives connected to a bus pin and converts them to a hierarchical block.

The guessWideBus operator guesses buses from members connected to one output pinBus.

Replace chains of MUX/WIDE_MUX primitives by one PRIO_SELECTOR/WIDE_PRIO_SELECTOR instance (-mux).

Replace chains of AND/OR primitives by one reduced instance (REDUCE_AND/REDUCE_OR) (-bool).

Replace odd number of INVs in a chain by one INV and remove an even number of INVs in a chain.

Creates an extra hierarchy for primitive instances which have same nets connected to multiple pins.

The option -created extends the search to hierarchical instances created by one of the operators above.

The option -modules extends the search to module instances.

Remove nets connecting to nothing. Remove NetBuses with no subnets.

Remove all cell which not referenced anymore or only referenced by zombie flagged instances.

Merge ReadPort and WritePort instances to one RAM instance. If $mod is specified, only consider instances within this module, otherwise work on the whole DB.

Guess direction of unknown module ports.

Group instances which have digits enclosed in one of [<( brackets in their name.

Replace inverters by bubbles at connected input pins or change function for inverters at output pins.

Remove all inverter directly connected to a clock, set or reset pin of a flip-flop and add a bubble to the pin.

Delete named ports or portBuses from given cell. All instance pins and affected nets are updated. This is a relative costly operator, because Spos and OIDs need to be updated.

Remove spurious MOS transistors:

Operators related to transistor devices.

The mergeParallelInst operator can be used to merge parallel instances controlled by the following options:

<cell> controls the instances which will be processed by a given rule. It can be:

<attrs> is a comma separated list of attribute names followed by a equality value enclosed by round brackets, or * if the value is not compared. Each group of recognized parallel instances is divided into groups of instances which have equal attribute values and one group with the remaining instances. There is the special case ARRAYEDINST(str) where the instance names are used to cluster the parallel instances. str defines the open/close characters, separated by a blank, which are used to get the bit subscript.

The <eqfunc> describes how the equal instances should be processed. The <grpfunc> how the remaining group should be processed. Possible func names are:

<openSepClose> defines the characters needed to create bus range for arrayed instances.

Examples for rules:

The reportParallelInst operator can be used to get a list of parallel instances oid controlled by the following options:

<cell> and <attrs> are used like in mergeParallelInst. <eqfunc> and grpfunc are ignored and should be NOOP.

Operators related to parasitic modules.