Si2oaD/Overview

From oacwiki

Si2oaD is a library of functions that facilitate examination of OpenAccess Objects (and their attributes and relationships to other Objects) from

a persistent repository on disk
"live" RTM data in a running application

The Si2oaD API can be accessed

within a debugger (gdb, dbx) using program code variable names or addresses in a running application.
within an application by inserting oad() calls into the app source
via command-line front-end using si2dis that will display persistent data without the need of an application or debugger

Si2oaD can be configured to display any parts of a run-time model

managed Objects, like Nets, Constraints, OccInstTerms, etc.
entire containers (like Designs, DMDatas, Techs, Libs, etc.)
the whole Session, including Session-owned Def Objects
utility objects (like LookupTbls or Boxes) represented by variables in app source code (though this requires inserting oad() calls within application source, or stepping through it with the debugger)

The output of an oad() traversal and display call is

an XML output stream (to the console or a file), but can be transformed into
dynamic HTML for active rendition in an ordinary Web browser

Makefiles help automate build and setup functions. The Quick Start section contains instructions for unpacking and installing the code.

1 Prerequisites

Some OA knowledge will significantly aid use of Si2oaD and this manual. On the other hand, Si2oaD might just be the most effective tool to help a new OA user come up to speed quickly on the organization of the OA model.

OA data can be rich with Object relationships and attribute values. For both performance and readability, Si2oaD output is heavily abbreviated, yet reasonably intuitive. For example,

The CurrentDensity Layer attributes peakACCurrentDenisty and avgACCurrentDenisty are abbreviated as peakAC and avgAC, respectively.
A Design actually has three separate Lib, Cell, and View name attributes; however, they are displayed together, with path separator characters, as the value of a single attribute, such as lcv="LibChip/Top/abstract".

Familiarity with the names and types of attributes and associations of each OA class, and how to use the API class reference, will facilitate comprehension of oaD output. Hotlinks to OA API reference pages for the class names (in the interactive display) will help the user map display artifacts to specific Object semantics.

2 Motivation

The very object-oriented design features that facilitate code development with the OpenAccess API can really complicate debugging that code (or some hunk of design data) because it has been so carefully encapsulated.

2.1 Binary Format

Unlike common file interchange formats for netlist and other design information, the OA RTM and persistent representations are compressed, binary encodings. An engineer cannot just open up a design on disk with a text editor and look at the data to see what's there. The OA disk format is optimized for loading and storage via application tool – not for human readability. In fact, the only way to "look at the data" is with the API, one Object/relationship at a time.

2.2 Opaque Handles

Instead of public member variables, OA classes hide attribute and relationship information behind methods. This is a useful interface design strategy but can make accessing information about OA Objects inside a debugger awkward.

For example, requesting gdb to display a ModNet yields nothing except an "opaque" Object handle. While it is technically a pointer to an object instantiation, dereferencing it in the debugger produces little useful information:

Breakpoint 2, main (argc=4, argv=0xbfffcc84) at testcase.cpp:124
124 cout << "got ModNet" << modNet << endl;
(gdb) p modNet
$1 = (oaModNet *) 0xb75d0612
(gdb) p *modNet
$2 = { <oaModObject> = {<oaDesignObject> = {<oaObject> = {id = 4 '\004'},
       <No data fields>}, <No data fields>}, <No data fields>}

Accessing attribute information requires invocation of individual Object member functions one at a time. This quickly becomes tedious with interspersed console dialog that makes the output hard to read:

(gdb) p modNet->getSigType()
$3 = {value = oacSignalSigType, static names = 0x80ab1d8}
(gdb) call modNet->isImplicit()
$4 = 0
(gdb) call modNet->isEmpty()
$5 = 0
   ...

2.3 Return by Value

Many attributes are not return values of a function but are instead stored in one (or more!) of the function arguments, which must have been allocated by the caller and passed in by reference. This makes accessing such data complicated − even impossible − if there is no variable of the right type available in the source code (since most debuggers do not allow construction of temporary variables with user-defined class types). For example,

(gdb) call block->getBBox(box)
(gdb) p box
$6 = {lowerLeftVal = {xVal = -290, yVal = -187},
upperRightVal = {xVal = 707, yVal = 880}}
(gdb) call modNet->getName(ns,str)
No symbol "str" in current context.

2.4 One-to-Many Relationships

Displaying one-to-many relationships (such as the Shapes in an LPPHeader, the InstTerms connected to a Net or the Terms it owns) is important for understanding how parts of a design relate to each other. However, inside a debugger such information would require many function calls:

to obtain Collections of Objects,
iterate over them,
perhaps traverse to each one for a name or other significant attribute.

Moreover, bare handle references without a corresponding compile-time typed variable would need individual, explicit type-casting to be interpretable to the debugger. This is just too much work for the real-time console.

2.5 Readability

What Object information can be produced by such brute force methods ends up fragmented with hit-or-miss formatting (including user-fumbled inputs) scattered among multiple prompts on the console. A more coherently organized view of such data would significantly aid visualization of the design.

3 Implementation Approach

Si2oaD addresses the obstacles to easy access of model information by providing the algorithms for complete traversal of OA model Objects and mechanisms for displaying those Objects, their attributes, and associations to other Objects, generating data that can be displayed in a web browser as shown in Figure 1.

3.1 Interactive Display Output

Si2oaD symbols are made available to the debugger (8), which can be run on the target application in the usual way; e.g., using gdb or TCL (Figure 2). Breakpoints can be set at which, in addition to normal debugger analysis commands, the Si2oaD interface functions, all overloaded versions of oad(), can be invoked to display various portions of the RTM.

Figure 1: Browser Display of OA Model Data

The resulting XML output can be directed in-line to the console or to a browser. On the console, the raw XML will be displayed. When sent to a browser, however, an XSL transform will be applied to it (either via stand-alone XSLT processor or by the browser's native XSL capability), turning it into HTML with Javascript enhancements to provide various levels of active content. Figure 1 illustrates the interactions between the debugger and called Si2oaD functions, and the outputs generated and processes spawned as a result. A set of options controls various aspects of the processing and display.

Figure 2: Session Interactions

3.2 Operational Summary

When the debugger calls one of the oad() "display" entry points (as opposed to those that manipulate option settings), the traversal engine in si2oad.cpp starts at the supplied root object (or the entire RTM if no arguments are given) and performs a systematic, depth first traversal of the model. The si2oadutil.cpp module processes utility object data. Each object processed consists of some number of associations. Processing is sorted into two groups:

Association data that can be expressed as a simple name=value pair. These associations are all arranged together at the start of the containing object.
Data that has several such pairs, each of which must be associated together in a separate grouping.

3.2.1 Output Alternatives

The resulting model data can be rendered in two ways, depending on whether the “output” target option is set to

console, in which case the resulting XML is sent to stdout.
gui, in which case the output is sent to a file in the WWW server "root" directory that is set in the options.

3.2.2 GUI Output

If “gui” is selected, then a web "nanoserver" (si2oadwww.cpp) is started by creating a socket bound to a free port (selected by the OS) and then looping to accept connections on that port.

The accept loop is necessary both to handle the multiple file components (images, Javascript, etc.) on the main page, as well as subsequent requests for new XML traversals (as a result of clicks on the IDREF attribute of associations that reference objects not included on the data in the current page).

This internal web server's call to the accept() function blocks on the socket until a special "quit" request is made by the browser. This is normally accomplished by clicking a special button that displays at the top of the HTML produced by the XSL translation. However, no such button will exist if all browser instances were closed, or if raw XML was being displayed (i.e., no XSL conversion). In either case, a browser can be started manually (or the existing one used, if still open) to the URL, localhost:PORT#/quit. When the quit request is received, the socket and port are closed.

The browser set in the options is spawned via system() call and handed the URL of localhost plus the selected port, and the HTML file that was created (or the XML file if the options are set to use the browser's internal XSL processing, or if the external XSL processor failed).

3.2.3 XSL Transformation

If the xsltype option was set to

browser, then the XML output will be fed directly to the browser (set in the browser option).
processor, a system() call runs the tool specified by the xslexe option (adding the directory specified by the xsllib option to the library path) to create an HTML file in that same output directory. The si2oad.xsl fiile will be used to perform the transformation.

A suitable XSL "processor" is the freeware Xalan (which uses the freeware Xerces-C++ XML Parser). The latest versions are available directly from Apache:

Xalan (the XSL engine)
Apache XML (the Xerces parser)

Alternatively, a qualified set of these XML Tools (both Win and Linux binaries) is available as a convenience from Si2's Redistributed Components.

3.3 Traversal Side-Effects

Many OA calls have side-effects that can change the RTM or persistent store. Traversal under OAD is intended to be non-destructive to both these models. Side-effects are prevented entirely in Si2oaD, or controlled by an option setting; for example,

getConstraintGroup() is not called if !hasConstraintGroup()
getMaster(), getMasterTerm(), getMasterModule() are not called if !bound()
getMasterOccurrence() is not called if option expandocc is not set to t
ParasiticNetworks (and partitions) are not loaded unless the loadnetworks option is set to t
getBBox() will not be called unless dobbox() is set to t.
getCMap() will create a CMap in the Block if one does not exist already. There is no API to detect whether a CMap has been created without creating one as a side-effect. Si2oaD releases prior to 2.6.1 had no option to present this; hence, displaying a Block would always result in CMap creation if one had not already been created prior to the oad() call.

3.4 Dynamic RTM Elaboration

The interactive version of Si2oaD has a bit more flexibility when relationships are encountered that reference Objects not currently open in the RTM. Assuming options have not been set to cause automatic opening, an active “sentinel” of some kind is planted in the display output to provide a method for the user to cause the Object to open, if desired. These sentinels are represented as values in capital letters, as summarized by the following Table:

For example,

Object references display a master reference in an attribute group that includes the Lib, Cell, and View names, as well as a design attribute, which has either a
- handle, if the master is already open in the RTM
- sentinel – the keyword, BIND – if that master has not been bound yet

Clicking on BIND will cause a callback that binds the master and displays it in a separate window.

An unexpanded master Occurrence reference of an OccInst has the “value”, EXPANDOCC. Clicking on such a sentinel interactively will cause the Occurrence to be expanded and displayed in a separate window.
If the Tech for a Lib is not already open at the point in the application code where Si2oaD was invoked, then the Lib's tech attribute will show the sentinel, OPEN, instead of a handle to the Tech.
The reference to an unbound ViaDef for a Via will display as BIND, which when clicked, will cause on-demand binding of that Object in the RTM.
If a ParasiticNetwork is not loaded into the RTM, the sentinel, LOAD will appear, which when clicked, will cause on-demand loading of that Network into the RTM. (See the parasitics1 testcase.)

Each call that explicitly opens an Object that was not already in the RTM will add the handle of that Object to a list. When the oad() call is terminated and control returns to the command line, each Object on that list will be purged, unloaded (whatever is appropriate for that Type) to return the RTM to its original state before the Si2oaD call.

**Dynamic RTM Expansion Hooks**
Container Object	Attribute Group	Simple Attribute	Active Sentinel
Lib		tech=	OPEN
Inst, ModDesignInst, OccInst	master	design=	BIND
ModModuleInst	master	module	BIND
InstHeader, ModInstHeader, OccInstHeader	master	design=	BIND
ModInstHeader, ModModuleInstHeader	master	module	BIND
CustomVia, CustomViaDef	master	design=	BIND
CustomViaHeader	master	design=	BIND
Via		viaDef=	BIND_VIADEF
CellView	primary	design=	BIND
ParasiticNetwork, Partition		pn	LOAD
OccInst, OccModuleInstHeader	master	masterOcc	EXPAND
InstPropDisplay, OccInstPropDisplay	masterProp	masterProp	BIND
TextOverride	masterText	masterText	BIND
DMContainer		dmData	OPENDMDATA
DMFile		dmData	OPENDMDATALib OPENDMDATACell OPENDMDATAView OPENDMDATACellView