Using Electric 11-3: The TCL Interface

Chapter 11: INTERPRETERS

| ## 11-3: The TCL Interface |

This section explains the TCL interpretive language interface in the Electric VLSI design system.

Throughout this section, examples of TCL code will appear underlined. For example, the "getarcproto" function takes the name of an arc prototype and returns a pointer to that object. This is coded as getarcproto Metal-1 which evaluates to the pointer of the form #arcproto15391808.

This section assumes that the reader is very familiar with the use of Electric, and somewhat familiar with the internals of the system. The Internals Manual (a document that is available from Static Free Software) provides a broad, C-oriented view of the information described here. For users of TCL, however, this section summarizes the relevant aspects of the Internals Manual. In general, the best way to understand this section is to try each command as it is explained.

### Session Control

To invoke the TCL interpreter, use the TCL... subcommand of the Language Interpreter command of the Tools menu. On some systems it may be necessary to move the cursor into the messages window (the text window) in order for the interpreter to "hear" you.

If you have a disk file with TCL code in it, you can read it into the interpreter by typing:
source FILENAME

To get back to Electric from TCL, type ^D (hold the Control key and type a "D"). On Windows, you must type the ESC key instead.

### Database Structure

The entire Electric database is a collection of objects, each of which has an arbitrary number of attributes. This section briefly outlines the object types and shows how they are related. Further detail can be found in the Internals Manual. See Section 11-5 for a list of attributes on these objects.

Individual components inside of circuits are described with nodeinst objects (instances of nodes), and individual wires are described with arcinst objects (instances of arcs). Connections between components and wires are described with portarcinst objects (instances of ports that connect to arcs). Because both components and wires have geometry, each one also has an associated geom object, and all of the geom objects in a cell are organized spatially into an R-tree with a collection of rtnode objects.

Class objects also exist to describe all individuals of a given type. The nodeproto object describes the prototypical component, which may have many individual nodeinst objects associated with it. For example, the CMOS P-Transistor is described with a single nodeproto object, and many nodeinst objects for each instance of such a transistor in any circuit. Hierarchy is implemented by having complex components, better known as cells, represented in the same way as the primitive components such as transistors. For example, the ALU circuit is described with a single nodeproto object, and each instance of that circuit higher up the hierarchy is described with a nodeinst object.

The cell object aggregates different views and versions of a circuit. Each of these is called a "cell" (represented with a nodeproto object) and a cell has both a view pointer and a version number.

In addition to component prototypes, the arcproto describes classes of wires and the portproto describes classes of component-wire connections. An additional object, the portexpinst, exists for exports. The network object describes electrically connected arcinst and portproto objects within a cell.

As a further aggregation of objects, the library is a collection of cells and cells. The technology is a collection of primitive components (nodeprotos) and all wire classes (arcprotos).

In addition to the above object pointers, there are some standard types of values that can be accessed through getval:

integer | 32-bit integer
string | null-terminated string of bytes
float | 32-bit floating point number
window | window partition object
windowframe | display window object
constraint | constraint system object
graphics | graphical attributes object

Also, there is the ability to have displayable variables (those whose values appear on the object) with the keyword: displayable.

### Database Examination

To begin a search through the database, it is important to know the current library. This is done with:
curlib
which returns a pointer to a library object (for example #library15464800). From here, the current cell can be obtained with:
getval [curlib] firstnodeproto

Essentially, any attribute can be examined with getval, and new attributes can be created with setval. Getval has the following format:
getval Object Attribute
where Object is the object being accessed and Attribute is the attribute being requested. A list of all existing attributes on the Electric objects is given at the end of this document.

New attributes can be created on any object with setval. In general, many of the existing attributes that are described at the end of this document cannot be set with setval, but rather are controlled with special database modification predicates. The format for setval is:
setval Object Attribute Value Options
Where the Options are either 0 or displayable to show this attribute when displaying the object. For example, to add a new attribute called "power-consumption" to the transistor component "t1", and give it the value 75, use:
setval $t1 power-consumption 75
To add a displayed name to node "t1", use:
setval $t1 NODE_name Q1 displayable
To set an array of values, use lists. For example, to set the shape of pure-layer node "metal" to be a diamond, use:
setval $metal trace {-1000 0 0 1000 1000 0 0 -1000}

Single entries in array attributes can be set, with:
setind Object Attribute Index Value
where Index is the 0-based entry in the array.

Finally, attributes can be deleted with:
delval Object Attribute
However, only those attributes that have been created with setval can be deleted in this way. The other attributes are protected.

### Basic Synthesis

To create a new cell in the current library, use:
newnodeproto CellName [curlib]
which returns a nodeproto pointer that can be used in subsequent calls which place components and wires in that cell.

To get the address of an existing nodeproto, use:
getnodeproto CellName
which returns the same type of value as newnodeproto. Thus, the code:
set mycell [newnodeproto "adder{lay}" [curlib]]
is the same as the code:
newnodeproto "adder{lay}" [curlib]
set mycell [getnodeproto "adder{lay}"]
and both deal with the "layout" view of the cell called "adder".

As an aside, the predicate getcell can be used to get a cell object, such that:
getcell adder
returns the same thing as:
getval $mycell cell

To create a component in a cell, use:
newnodeinst Proto LowX HighX LowY HighY Transpose Angle Cell
where Proto is a nodeproto of the component that is to be created, LowX, HighX, LowY, and HighY are the bounds of the component, Angle is the number of tenth-degrees of rotation for the component, Transpose is nonzero to transpose the component's orientation (after rotation), and Cell is the nodeproto in which to place the component.

The four bounds values are somewhat confusing to compute. For primitive components (such as Transistors), any value is acceptable and the component will scale. However, it is still nice to know the default value, which can be obtained from the nodeproto with getval as follows:
set tran [getnodeproto P-Transistor]
set lowx [getval $tran lowx]
set highx [getval $tran highx]
set lowy [getval $tran lowy]
set highy [getval $tran highy]
When complex components (cells) are placed, the bounds MUST be exactly the same as the bounding box of the cell's contents. This information is available in the above manner. As an example of newnodeinst, and given the above bounds calculations, a default size P-Transistor is created in cell "adder" with:
set t1 [newnodeinst $tran $lowx $highx $lowy $highy 0 0 $mycell]
The returned pointer to the transistor component will be used later when wiring.

To wire two components, it is necessary to know these four things:

- The component objects on the two ends, returned by newnodeinst
- The portproto values of the connection sites on the components
- The X and Y coordinates of the connection sites
- The type, width, and other characteristics of the wire being created

Connection sites are called portprotos and are associated with nodeprotos. To get the address, use:
getportproto NodeProto PortName
For example, to get the polysilicon port on the left side of the MOSIS CMOS P-Transistor, use:
set polyleft [getportproto $tran p-trans-poly-left]
Unfortunately, there is no good way to get a list of port names on the primitive components. There are, however, some simplifications. For example, if there is only one port (as is the case with most contacts and pins) then its name is not necessary:
set port [getval $tran firstportproto]
This will obtain the first port on the P-Transistor component. To obtain the coordinates of a port for wiring, use
portposition Node Port
This returns a list with the coordinates. For example:
set portpos [portposition $t1 $polyleft]
will obtain the coordinate of the "p-trans-poly-left" port on the newly created P-Transistor, t1. The X value will be lindex $portpos 0 and the Y value will be lindex $portpos 1.

The final piece of information necessary is the type of arc and the width of the arc. Given an arc name, the type can be obtained with:
getarcproto ArcName
Given an arcproto, its default width can be obtained with:
getval Arc nominalwidth
When all of the information is ready, the call:
newarcinst ArcType Width Bits NodeA PortA XA YA NodeB PortB XB YB Cell
places the wire. You can ignore the value of Bits and set it to zero.

Here is a complete example of placing a transistor, a contact, and running a wire between them (the result is shown here).

# create a cell called "tran-contact" in the current library set mycell [newnodeproto tran-contact [curlib]] # get pointers to primitives set tran [getnodeproto P-Transistor] set contact [getnodeproto Metal-1-Polysilicon-1-Con] # get default sizes of these primitives set tlowx [getval $tran lowx] set thighx [getval $tran highx] set tlowy [getval $tran lowy] set thighy [getval $tran highy] set clowx [getval $contact lowx] set chighx [getval $contact highx] set clowy [getval $contact lowy] set chighy [getval $contact highy] # get pointer to Polysilicon arc and its default width set arctype [getarcproto Polysilicon-1] set width [getval $arctype nominalwidth] # create the transistor and the contact to its left set c1 [newnodeinst $contact $clowx $chighx $clowy $chighy 0 0 $mycell] set t1 [newnodeinst $tran [expr $tlowx+8000] [expr $thighx+8000] $tlowy $thighy 0 0 $mycell] # get the transistor's left port coordinates set tport [getportproto $tran p-trans-poly-left] set tpos [portposition $t1 $tport] # get the contacts's only port coordinates set cport [getval $contact firstportproto] set cpos [portposition $c1 $cport] # run a wire between the primitives newarcinst $arctype $width 0 $t1 $tport [lindex $tpos 0] [lindex $tpos 1] $c1 $cport [lindex $cpos 0] [lindex $cpos 1] $mycell |

### Hierarchy

Cells, as created by newnodeproto, can be placed in other cells with newnodeinst. The instances simply use complex nodeproto fields rather than primitive nodeprotos as in the above example. For example, the following code creates a new cell called "two-trans" and places two instances of the above "tran-contact" cell, one above the other.

# create a cell called "two-trans" set highercell [newnodeproto two-trans [curlib]] # get pointer to the "tran-contact" cell set tc [getnodeproto tran-contact] # get size of this cell set lowx [getval $tc lowx] set highx [getval $tc highx] set lowy [getval $tc lowy] set highy [getval $tc highy] # create the two cell instances, one above the other set o1 [newnodeinst $tc $lowx $highx $lowy $highy 0 0 $highercell] set o2 [newnodeinst $tc $lowx $highx [expr $lowy+10000] [expr $highy+10000] 0 0 $highercell] |

Another necessary feature, when making hierarchy, is the ability to place wires between connection sites on cell instances. To do this, it is necessary to create exports. This takes a port on a primitive component (for example, the transistor or contact in the "tran-contact" cell) and makes it into an export on the current cell. This is done with:
newportproto Cell NodeInCell PortOnNode PortName
where Cell is the cell containing the component whose port is being exported, NodeInCell is that component, and PortOnNode is the particular port on that node being exported. For example, to export the top and bottom diffusion ports in the "tran-contact" cell (as shown here), the following code can be added:

newportproto $mycell $t1 [getportproto $tran p-trans-diff-top] topdiff newportproto $mycell $t1 [getportproto $tran p-trans-diff-bottom] botdiff |

And then, the components "o1" and "o2" in the cell "two-trans" can be wired, using the ports called "topdiff" and "botdiff":

# get pointer to P-Active arc and its default width set darctype [getarcproto P-Active] set dwidth [getval $darctype nominalwidth] # get the bottom cell's top port set lowport [getportproto $mycell topdiff] set lowpos [portposition $o1 $lowport] # get the top cell's bottom port set highport [getportproto $mycell botdiff] set highpos [portposition $o2 $highport] # run a wire between the primitives newarcinst $darctype $dwidth 0 $o1 $lowport [lindex $lowpos 0] [lindex $lowpos 1] $o2 $highport [lindex $highpos 0] [lindex $highpos 1] $highercell |

### Modification

Two types of modification can be done to existing objects: deletion and change. To delete a cell, use:
killnodeproto Cell

To make a copy of a cell (within the same library or from one library to another), use:
copynodeproto FromCell ToLibrary ToCellName
where FromCell is the original cell (nodeproto) and ToLibrary is the destination library. Use curlib to copy to the same library. The new cell name is the last parameter. The predicate returns the address of the new cell (nodeproto).

To delete a component, use:
killnodeinst Node
Before a component can be deleted, all wires and exports must be removed.

To change the size or orientation of a component, use:
modifynodeinst Node DLowX DLowY DHighX DHighY DRotation DTrans
where DLowX, DLowY, DHighX, and DHighY are the changes to position and size. DRotation and DTrans are changes to the orientation.

To change the prototype of a component, use:
replacenodeinst OldNode NewPrototype
where the old component is OldNode, and the new nodeproto that should be in its place is NewPrototype. This new prototype must be able to connect to all existing arcs. The predicate returns the address of the new component.

To delete a wire, use:
killarcinst Arc

To change the width or position of a wire, use:
modifyarcinst Arc DWidth DX1 DY1 DX2 DY2
where DWidth, DX1, DY1, DX2, and DY2 are the changes to the width, X/Y position of end 1, and X/Y position of end 2. Note that position changes cannot cause the connecting nodes to move, so the changes may only be small ones that work within the ports.

To change the prototype of a wire, use:
replacearcinst OldArc NewPrototype
where OldArc is the former wire and NewPrototype is the new arcproto to use. The nodes on either end must be able to accept this new type of wire. The predicate returns the address of the new wire.

To delete an export, use:
killportproto Cell Port
which will remove port Port on cell Cell.

To move an export from one component to another (keeping connected wires), use:
moveportproto Cell OldPort NewNode PortOnNewNode
where the old port is OldPort in cell Cell, and it is now moved to component NewNode (which is also in cell Cell), port PortOnNewNode of that component.

### Search

A common operation is a search of all components in a cell. The following code prints the name of all components in the cell "mycell":

for { set node [getval $mycell firstnodeinst] }
{ [string c $node #nodeinst-1] != 0 }
{ set node [getval $node nextnodeinst] }
{
puts stdout [format "Found %s node" [describenode $node]]
}

Where describenode is defined as follows (the name of a node is found in different places depending on whether it is a primitive or complex nodeproto):

proc describenode node
{
set proto [getval $node proto]
if { [getval $proto primindex] == 0}
{ return [getval [getval $proto cell] cellname] }
return [getval $proto primname]
}

And the following code prints the name of all wires in the cell "mycell":

for { set arc [getval $mycell firstarcinst] }
{ [string c $arc #arcinst-1] != 0 }
{ set arc [getval $arc nextarcinst] }
{
puts stdout [format "Found %s arc"
[getval [getval $arc proto] protoname]]
}

To do a search of all nodes and arcs in a rectangular area of a cell, first call:
initsearch LowX HighX LowY HighY Cell
where LowX, HighX, LowY, and HighY are the coordinates to search in cell Cell (a nodeproto). This predicate will return a search key that can then be passed repeatedly to:
nextobject SearchKey
which will return geom objects of each node and arc in the search area. When this predicate returns #geom-1, the search is complete. geom objects can point to either nodes or arcs, depending on their "entryisnode" attribute. Then, the "entryaddr" attribute will point to the actual nodeinst or arcinst. Here is an example of code that prints the names of all nodes and arcs in the area (2000 <= X <= 10000, -3000 <= Y <= 3000). The selected area is shown as a black box here.

set key [initsearch 2000 10000 -3000 3000 $mycell] for { set object [nextobject $key] } { [string c $object #geom-1] != 0 } { set object [nextobject $key] } { set isnode [getval $object entryisnode] if { $isnode } { puts stdout [format "Found %s node" [describenode [getval $object entryaddr]]] } else { puts stdout [format "Found %s arc" [getval [getval [ getval $object entryaddr] proto] protoname]] } } |

### Views

A view is an object that describes a cell. There are many standard views: Layout, Schematic, Icon, Simulation-snapshot, Skeleton, VHDL, Verilog, Document, Unknown, and many flavors of Netlist. In addition, new views can be created with "newview":
newview ViewName Abbreviation
and views can be deleted with killview (the standard views cannot be deleted):
killview View
To get a view object, use getview on its name.

To associate different views of a cell, the predicates iconview and contentsview obtain different cells. For example:
iconview Mycell
finds the associated icon cell of the cell in which "Mycell" resides.

### Libraries

In the above examples, the current library was always used. This is determined by calling:
curlib
However, there can be other libraries. To get a specific named library, use:
getlibrary LibName

To create a new library, use:
newlibrary LibraryName LibraryFile
where LibraryName is the name to use, and LibraryFile is the path name where this library will be saved. This predicate returns the address of a new library object that can then be used when creating cells.

Only one library is the current one, and to switch, you must use:
selectlibrary Lib

A library can be deleted with:
killlibrary Lib

A library can be erased (its cells deleted, but not the library) with:
eraselibrary Lib

### Technologies

A technology is an environment of design that includes primitive components and wire prototypes. The current technology can be obtained with:
curtech

A specific technology can be obtained from its name with:
gettechnology TechName

All technologies can be found by traversing a linked list, the head of which is a technology named "Generic".

### Tools

A tool is a piece of synthesis or analysis code that can operate upon the database. A particular tool object can be obtained with:
gettool ToolName
where the possible names of tools are:

compaction | circuit compaction
compensation | geometry compensation
drc | design-rule checking
erc | electrical-rule checking
io | input/output control
logeffort | logical effort analysis
network | network maintenance
pla | programmable logic array generator
project | project management
routing | automatic wire routing
silicon-compiler | netlist-to-layout silicon assembler
simulation | simulation
user | the user interface
vhdl-compiler | VHDL-to-netlist compiler

The number of tools is available with:
maxtool
And a particular tool, indexed from 0 to (maxtool)-1 can be obtained with:
indextool Index

A tool can be switched on with:
toolturnon Tool
where Tool is a tool object.

A tool can be turned off with:
toolturnoff Tool

A tool can be given a specific instruction with:
telltool Tool PARAMETERS
For example, to list all technologies, use this code:
telltool [getaid user] {show technologies}
These commands are from the low-level command interpreter, which is documented fully in the Internals Manual.

### Miscellaneous

Every change to the database is queued internally in a "batch" which includes the change and any constrained side-effects of that change. A new batch is created for each TCL session with the interpreter (also for each Electric command that is issued from the keyboard/mouse). To reverse the last batch of changes, use:
undoabatch

Multiple calls to this predicate in a single batch will undo multiple batches. To erase the list of change batches, use:
noundoallowed

If you are creating a wire that makes many bends, it is necessary to create special nodes called "pins" at each bend. To find out what kind of pin to use for a given wire type, use:
getpinproto Arc
where Arc is the wire type, and the predicate returns the component type (nodeproto) of the pin.

Network objects can be obtained by name with the predicate getnetwork which takes a name and a cell in which to search. For example, the code:
getnetwork insig Mycell
obtains the address of the network called "insig" in cell Mycell.

The generic function of a node instance can be determined with:
nodefunction Node
which returns a value from the list of constants in the C header file "efunction.h". This value is essentially the same one as would be obtained by looking at the "userbits" field of the node's prototype. However, certain components that have generic prototypes will be made more specific by this predicate.

To get an attribute value from an instance above this in the hierarchy, use:
getparentval Name Default Height
where Name is the attribute name, Default is the default value to return if the attribute is not found, and Height is the number of levels of hierarchy to climb when looking for the attribute (0 for infinite). As a shortcut for finding parameter values, there are four macros which use this routine:

- P xx obtains the value of parameter xx from the parent instance in the hierarchy.
- PD xx def obtains the value of parameter xx from the parent instance in the hierarchy and uses the value def if the parameter cannot be found.
- PAR xx obtains the value of parameter xx from any higher instance, anywhere in the hierarchy.
- PARD xx def obtains the value of parameter xx from any higher instance, anywhere in the hierarchy and uses the value def if the parameter cannot be found.

| Previous |  |  | Table of Contents |  | Next |