I NV E N TIV E

Database Access in EDI

with dbGet

Problem Statement
Robust and easy to use db access mechanisms play a
huge role in defining how productive users of design
systems can be
Historically, Encounters db access has been powerful
and fast, but a bit cryptic and difficult to learn
In 7.1, a new db access mechanism was introduced
which minimizes the need to peruse the 2000+ FE-TCL
commands and condenses them into 2 commands:
dbGet and dbSet

dbGet: Goals
Make it easy for a new user to explore a design interactively
Make it a self-documenting API
query which fields are available from any object
query fields for short description and legal enumerated values

Query all field values of an object at one time

Present the data in user units by default (or optionally in db units)

Make it easy to script common operations

common starting points built-in (top, head, selected)

general pattern matching for every field
object pointer direct from pattern match
unique objects from list with repeated objects

Approach
Use a methodology similar to what is available to DFII-SKILL with
the ~> operator
Enhance it with some new options not found in SKILL
3

Two main commands

(along with some helpers)
dbGet
dbSet
Related Commands:

setDbGetMode/getDbGetMode
dbSchema
dbTransform
dbQuery
dbShape (available in 10.1)

Getting Started with dbGet

What is this thing I have selected? Select an instance graphically and then:

Get a pointer to the selected object(s):

encounter 4> dbGet selected
0x2a9ef88578

Get a list of the attributes for that object:

encounter 5> dbGet selected.?
inst: box cell instTerms isDontTouch isHaloBlock isJtagElem isPhysOnly isSpareGate name
objType orient pHaloBot pHaloBox pHaloLeft pHaloRight pHaloTop pStatus pgCellTerms
pgTermNets pt rHaloBotLayer rHaloSideSize rHaloTopLayer

Get a list of the values of each attribute:

encounter 6> dbGet selected.??
box: {416.46 889.84 434.28 894.88}
cell: 0x2a9e734280
instTerms: 0x2a9ef8a4f0 0x2a9ef8a550 0x2a9ef8a5b0 0x2a9ef8a610 0x2a9ef8a670
0x2a9ef8a6d0 0x2a9ef8a730
isDontTouch: 0
isHaloBlock: 0
<etc>

dbGet Examples:

dbGet uses . as a separator for obj/attr traversal

Similar to DFII ~>

dbget top.insts.cell.name
AND2 OR2 INV1 AND2

top is a cell pointer for the top cell

insts is the list of inst pointers in top
cell is the master cell pointers for each inst
name is the master cell name

dbGet Examples:

.?h

Similar to .? but includes type, legal enum values, and a short description
For obj or objList includes objType
Note, objType field itself is suppressed as too long, with comment how to see it
Alphabetical

encounter 1> dbGet top.insts.?h

================================
inst: Instance - canonical (flat), equivalent to DEF COMPONENT. Points to a
libCell or ptnCell.
-------------------------------box: rect, Bounding box of the instance
pt(settable): pt, Location of the instance
instTerms: objList(instTerm), List of pointers to instance terminals

orient(settable): enum(MX MX90 MY MY90 R0 R180 R270 R90), Instance placement

orientation
pStatus(settable): enum(cover fixed placed unplaced), Instance placement
status

dbGet Examples: Pattern Matching

Can be used to match field names or values
Simple wildcard matching used by default (*, ?)
use regexp option for regular expression matching

Value matching
encounter 1> dbGet top.nets.name *clk*
a_clk1 clk2 clk3 clk[1] clk_2
encounter 2> dbGet top.nets.name *clk?
a_clk1 clk2 clk3

Field name matching (for .? .?? .?h) also useful to get just one field
encounter 1> dbGet top.insts.?h pstat*
pStatus(settable): enum(cover fixed placed unplaced), Instance
placement status

dbGet Examples: p with Pattern Matching

The p option returns the pointer of the object rather
than the field value, so pointers of objects that match a
field value can be returned
The p2 option goes back 2 levels of the . delimited
dbGet structure, -p3 goes back 3 levels, etc.
encounter 1> dbGet top.nets.name *clk*
a_clk1 clk2 clk3
# all nets matching *clk*
encounter 2> dbGet p top.nets.name *clk*
0x111111 0x222222
# ptrs to nets matching *clk*
encounter 3> dbGet [dbGet -p top.insts.cell.name INVX1].name
INVX1 INVX1 INVX1
# all INVX1 cells in design
encounter 4> dbGet [dbGet p2 top.insts.cell.name INVX1].name
i1/i2 i1/i3 i4/i5/i6
# all inst names of INVX1 in design

dbGet Examples: Expressions

dbGet [<expression>]
Specifies a Tcl expression where values of attributes or
objects can be accessed and utilized in Tcl "expr" style
comparisons
Example: Find all the high fanout nets that arent clocks
encounter 1> dbGet -p top.nets.numInputTerms 20
0x2aaab371adc8 0x2aaab371afc0
encounter 2> dbGet top.nets {.numInputTerms >= 20}
0x2aaab45257e8 0x2aaab4525890 0x2aaab4526460
encounter 3> dbGet top.nets {.numInputTerms >= 20 &&
.isClock == 0}
0x2aaab45257e8 0x2aaab4525890 0x2aaab4526460

10

dbGet Examples: Using u to Filter Lists

For some items, like cell names, the returned list may
have the same entry multiple times
encounter 1> dbGet top.insts.cell.name
INV AND2 INV OR2 INV

If the user only wanted the unique list of different cells

they can use u
encounter 2> dbGet -u top.insts.cell.name
INV AND2 OR2
encounter 3> dbGet u top.insts.cell
0x1111 0x2222 #one ptr to each cell used in design

11

dbGet Tcl Syntax

Usage: dbGet [-d] [-p#] [-u] [-regexp]
<obj|obj_list|head|top|selected>.[obj_type][{.attr_name|.?|.??|.?h} [pattern]]
p | -p1 | -p2 | -p3 levels for back traversal of objects (p or p1 = 1 level, p2 = 2 levels, etc.)
u
removes duplicate objects so that the resulting list has unique entries
-d
return dbu units rather than user units (by default coords are floats in um rather than ints)
-regexp
use regexp pattern matching rather than default Tcl glob matching
objList
list of 1 or more object pointers (can be a homogeneous or heterogeneous list)
head
used for technology info [dbgHead]
top
used for current top cell, [dbHeadTopCell]
selected list of objects in the selected set
.objName object or object list field name
.attrName attribute field name
.?
return list of available objects/fields available from the last object in the chain
.??
return list of available objects/fields and their values from the last object in the chain
.?h
return short help when available including list of enum choices
pattern
string expression to compare against attribute values (objName/attrName for .?, .??, .?h)

12

Smart Tab Completion

encounter 1> dbGet top.<tab>
<returns all valid objects associated with top>
encounter 2> dbGet top.i<tab>
<returns objects for top that start with i, and a trailing .>
dbGet top.insts.
encounter 3> selectInst i1
encounter 4> selectNet net1
encounter 5> dbGet selected.<tab>
<returns valid objects depending on selected set>
encounter 6> dbGet top.insts.cell.na<tab>
<returns unique completion and trailling space since theres
no objects to traverse to beyond name>
dbGet top.insts.cell.name
13

dbGet General Usage

dbGet is case insensitive
dbGet, dbget are both accepted
dbget top.fPlan, dbget TOP.FPlan, etc.

Empty fields return 0x0

Illegal field name gives Error msg but still return 0x0, so list of mixed
objects still ok
0x0 in objList is silently allowed, so list of mixed objects is still ok
>dbGet $n.allTerms.name
#$n is clk net attached to term
clk i1/i2/clkIn
#combo of terms and instTerms
>set i [dbGet $n.allTerms.inst]
ERROR: "inst" - Invalid obj/attribute for term
0x0 0x111111
#term has no inst field, so 0x0
>dbGet $i.name
0x0 i1/i2x
#no error msg from 0x0.name
>dbGet $i.name i1*
i1/i2x
>dbGet $i.name *x*
#0x0 is not a name, so *x* does
i1/i2x
>dbGet $i.name 0*
#no name was matched at all, so
0x0

14

and instTerm

returned

NOT match 0x0

empty list of 0x0 returned

dbGet Examples: Command Chaining

The following examples are the same:
>set pgnets [dbGet -p top.nets.isPwrOrGnd 1]
0x111111 0x222222
>dbGet $pgnets.name
VDD VSS
>dbGet [dbGet -p top.nets.isPwrOrGnd 1].name
VDD VSS

15

Changes from previous FE DB access

By default, all distance values in um rather than dbu (use d for dbu)
A few object names have been changed to align better with Virtuoso
and OpenAccess terminology. For example:
term in dbGet is FTerm in the FEDB (dbForEachCellFTerm)
instTerm in dbGet is Term in the FEDB (dbForEachInstTerm)

16

Compatibility with FE DB Access

dbGet pointers can be used by equivalent FE-TCL DB access
functions
FE-TCL DB pointers can be used by equivalent dbget object
although dbGet does not support all FE DB objects
>set a [dbget p top.insts.name i1/i2]
0x222222
>dbInstCellName $a
i1/i2
>set b [dbGetInstByName i1/i2]
0x222222
>dbget $b.name
i1/i2

17

Compatibility with FE DB Access

rect objType is a list with 4 values like {100.1 0.0 100.3 0.2}
use d for dbu values
use Tcl join if you need to flatten the list {1 2 3 4} to 1 2 3 4

> dbGet top.fplan.pblkgs.shapes.rect #returns list of lists

{100.1 0 100.3 0.2} {200.0 100.0 220.0 110.0}
>dbGet d top.fplan.pblkgs.shapes.rect
{100100 0 100300 200} {200000 100000 220000 110000}
>set b [lindex [dbGet top.fplan.pblkgs.shapes] 0]
0x222222
>set c [dbGet d $b.rect]
#still a list of lists
{100100 0 100300 200}
>join $c
#flatten the list
100100 0 100300 200

pt and ptList objTypes are similar, with ptList a list of lists of lists

pt: {100.1 100.2}

ptList: {{100.1 100.2} {100.1 100.4} }

18

setDbGetMode Tcl Syntax

setDbGetMode [-displayLimit value] [-displayFormat
(simple | table)]
The displayLimit controls the .?? output for both the number of
objects processed and for the length of objLists returned
As .?? is for interactive use, the goal is to not have thousands of
lines output that would not be useful
Default: 10

The displayFormat controls the .?h and .?? style outputs

Some users like a more tabular style
Similar to some timing reports

19

dbSet
dbSet allows editing of appropriate attribute fields, but
not pointers
Does not support creation or deletion of objects
Currently very limited: only a few attributes supported
placement status, halo values, gap values
dbget .?h descriptions show (settable) for attributes that can be
changed using dbSet

Syntax: dbset objList{.objName}*.attrName attrValue

>dbSet top.insts.pStatus placed
>dbSet [dbGet p top.insts.name *clk*].pStatus fixed

20

dbSchema
dbSchema provides a way to find the attributes available
for an object type when you dont have the pointer
already
dbSchema allows filtering to simplify output and look for
objects with a common attribute
Syntax: dbSchema [-help] [objNamePattern
[objAttrNamePattern]]
Example: Find out which objects contain object or attributes that
match the *ptn* pattern.
encounter> dbSchema * *ptn*
===================================================
hInst: Hierarchical instance (derived from netlist)
===================================================
ptn: obj(ptn), Pointer to the partition
===============================
head: Root/Head of the database
===============================
ptns: objList(ptn), List of pointers to partitions in the design

The hInst and head objects matched the query

21

dbTransform for Translating Global/Local

Coordinates
Usage: dbTransform [-help] [-d] {-inst <instPtr> | {-cell <cellPtr> -orient}
<orientEnum> -pt {x y}}} {-localPt <list> | -globalPt <list>}
-help
-d

# Prints out the command usage

# User specified values and return values are in database
# units: default is um (bool, optional)
-inst <instPtr>
# instance object (db object, required)
-cell <cellPtr>
# cell object (db object, optional)
-orient {R0|R90|R180|R270|MX|MX90|MY|MY90}
# orientation
# (enum, optional)
-pt {x y}
# location (point, optional)
-localPt <list>
# a pt {x y}, rect {xl yl xu yu} or list of pts and/or
# rects {{x1 y1} {x2 y2} {xl yl xu yu} ...} inside cell
# (string, required)
-globalPt <list>
# a pt {x y}, rect {xl yl xu yu} or list of pts and/or
# rects {{x1 y1} {x2 y2} {xl yl xu yu} ...} inside design
# (string, required)

22

dbShape for Geometric Operations

Usage: dbShape [-help] [-d] [-step <step>] [-output <polygon|rect>]
<shapeList> [AND <shapeList> | ANDNOT <shapeList> | OR <shapeList> | XOR <shapeList>
| SIZE <value>| BBOX | MOVE {<dx> <dy>}] ...
-help
-d

# Prints out the command usage

# User specified values and return values are in database units.
# Default: All values are in user units, in microns. (bool, optional)
-step <step>
# Specifies step size if output format is rect, required to convert
# non-orthogonal shapes into series of rectangles. Default: minwidth
# value of first routing layer (coord, optional).
-output <polygon|rect>
# Specifies the output format. default: rect (string, optional)
<shapeList>
# polygon or rect or list of polygon and rect. polygon:
# {{x y} {x y} {x y} ... }; rect: {x1 y1 x2 y2} (list, required)
AND <shapeList> # binary operator: intersection of shapeLists
ANDNOT <shapeList> # binary operator: initial shapeList minus <shapeList>
OR <shapelist>
# binary operator: union of shapelists
XOR <shapeList> # binary operator: OR minus AND of shapeList
# (string, optional)
SIZE <value>
# unary operator: increase the size of shapeList by <value>
MOVE {<dx> <dy>} # unary operator: move the shapeList by {<dx> <dy>}
BBOX
# unary operator: computes the bounding box of shapeList
# (string, optional)

23

dbQuery for Finding Objects by Area

Usage: dbQuery [-help] [-d] -area {llx lly urx ury} [-objType
<objTypeList>]
-help
-d

# Prints out the command usage

# User specified values and return values are in
# database units: default is um (bool, optional)
-area {llx lly urx ury} # Specifies the search area {llx
lly urx ury},
# where ll = lower left, ur = upper right.
# (box, required)
-objType <objTypeList>
# list of object types to
return. Legal values are:
# {inst special}, (special = union of sWire and
# sViaInst), default: inst (string, optional)

24

Summary
It would be impossible to provide native functionality to
suit every need that might arise, so db access
commands are useful in bridging the gap between tool
functionality and whats needed to get chips
implemented
dbGet and dbSet provide a simple, consistent way to
programmatically probe and tweak the database
We welcome your suggestions for improvement to
dbGet and hope you find it useful

25